Library

Upload a track or jingle from a link

POST
https://api.tunio.ai/v1/library/uploads/url

Give a direct https link to an audio file (for example the download link of a track generated in Suno) to add it to the caller's library as a music track or a jingle. The request only records the link and returns an upload in state pending; the download, the check that it is audio and the conversion happen in the background. Read the upload by its upload_id until the state is completed (track_id or jingle_id is then set) or failed (error says why). A completed track can then be added to a static playlist, a completed jingle to a jingle bundle. Only https on port 443 to public addresses is followed, with at most 3 redirects; the download must finish within 3 minutes. Formats: mp3, aac, m4a, wav, flac, ogg/opus, aiff, recognised by content. Music: up to 100 MB and 20 minutes, counts against the library storage limit. Jingle: up to 15 MB and 60 seconds, requires a plan with jingles; wma, webm/mkv and video files are taken too, only their first audio track is kept. Sending the same link again while its upload is unfinished returns that upload. Up to 20 uploads may be unfinished per account; 60 uploads per minute per account.

Request body

Link and target

NameTypeDescription
category_idstring
Music only: category of the caller's library the track is filed under.
genrestring
Music only: genre stored on the track, up to 64 characters.
kindRequiredstring
music (a track for playlists) or jingle (a jingle for bundles and the content schedule).
titlestring
Title, up to 255 characters. Music: "Artist - Title" is split into artist and track when the file has no tags. Defaults to the file name in the link.
urlRequiredstring
Direct https link to the audio file (port 443, no credentials). It is downloaded in the background; links to private or internal addresses are refused.
Request example
01{
02 "category_id": "0b3a59f4-8c3b-4c1e-9a1b-0d7c2e8f1a22",
03 "genre": "pop",
04 "kind": "music",
05 "title": "Tunio - Morning Drive",
06 "url": "https://cdn1.suno.ai/6f1526a5-405e-4447-8dc4-f4077b3f0f3c.mp3"
07}

Responses

NameTypeDescription
successboolean
Always true.
uploadobject
The upload.
completed_atstring
When it completed or failed.
created_atstring
When the upload was accepted.
durationinteger
Length in seconds, set once completed.
errorstring
Machine-readable failure code, set only when state is failed: url_not_allowed, download_failed, file_too_large, not_audio (not an audio file of a supported format), duration_out_of_range, storage_limit_exceeded, processing_failed or processing_timeout.
file_namestring
Name of the sent file, or the last segment of the link.
jingle_idstring
Jingle: the jingle in the caller's library, set once completed; add it to a bundle with POST /v1/jingle-bundles/{bundle_id}/items.
kindstring
music or jingle.
size_bytesinteger
Size of the source file in bytes, known once it is downloaded.
sourcestring
file (sent in the request) or url (downloaded from a link).
source_urlstring
The link the file is downloaded from; null for file uploads.
statestring
pending (waiting for a worker), downloading, processing (checking and converting), completed or failed.
titlestring
Title given in the request, null when none was.
track_idstring
Music: the track in the caller's library, set once completed; add it to a static playlist with POST /v1/playlists/{playlist_id}/items.
upload_idstring
Upload ID; poll GET /v1/library/uploads/{upload_id} with it.
NameTypeDescription
messagestring
Error code or human-readable error details.
successboolean
Always false for error payloads.
NameTypeDescription
messagestring
Error code or human-readable error details.
successboolean
Always false for error payloads.
NameTypeDescription
messagestring
Error code or human-readable error details.
successboolean
Always false for error payloads.
NameTypeDescription
messagestring
Error code or human-readable error details.
successboolean
Always false for error payloads.
NameTypeDescription
max_pendinginteger
Uploads allowed to be unfinished at once per account (20); sent with too_many_pending_uploads.
messagestring
too_many_pending_uploads or rate_limited.
successboolean
Always false.
NameTypeDescription
messagestring
Error code or human-readable error details.
successboolean
Always false for error payloads.