Uploading

You can upload a file to the SourceAudio API by sending in an external URL. This is a per-track action, and needs to be called in series. Simultaneous uploads will be denied.

This endpoint can also be used to attach a new file to an existing upload or track to either add or replace a specific format.

/api/import/upload
Param Required Description
url yes The url to your externally hosted mp3, wav, or aiff
formats no Comma-separated mp3, wav, and/or aiff, indicating which formats to generate if not supplied
upload_id no The upload id to attach to if attaching to an uploaded but unpublished track
track_id no The track id to attach to if attaching to an already published track on the site
immediate no (1 or 0) Flag indicating whether to skip the publishing pipeline if it’s an update
format no The format of the uploaded file if you’re doing an immediate update to a track_id
autopublish no (1 or 0) Flag triggering autopublishing. Publishing automatically occurs if 10 minutes have passed without a new autopublish flag or 1000 tracks are in queue.
meta no Array of metadata; see Setting Metadata
oncomplete no An email or URL that will be called when this upload’s job is published. One per job, overwrites if already exists

Example Response

{
upload_id: 51223,
status: 'uploaded',
formats: ['mp3', 'wav'],
sources: [
'myfile.wav'
],
meta: {
Title: "My song! It's pretty good.",
Filename: "myfile.mp3",
Album: "My Album",
//...
}
}

Formats

SourceAudio supports 3 formats: mp3, aiff, and wav. If you upload one version, we can generate the others, or you can upload your own versions if you wish. Simply send in another upload action with the same filename other than the extension (e.g. wake-the-giant.mp3 and wake-the-giant.wav), or provide the upload_id of the first track when you upload the second and it’ll be attached as a secondary version. By default, we’ll generate an MP3 if you don’t upload one, but you can turn that off or generate the other formats with a formats call if you wish. The formats parameter can be added to an upload or setMetadata action, and should be comma separated.

Existing Tracks or Uploads

If you upload a file whose filename matches an already existing track, then it turns into an update to that track, and when you publish it will replace the filetype on that track if it exists or add it if it doesn’t.

You can also do this manually by passing in an upload_id that corresponds to the upload you want to attach the update to.

It’s also possible to update published tracks by using track_id with your upload. If you pass in immediate=1 and format=mp3 (insert your file type), then the published track’s format will automatically be replaced and it will not go into the queue. Neither the queued nor the immediate method will trigger generation of the other formats if you have that set up, so if you want to replace all the files, you either need to upload all types you supply, or delete and reupload.