Library
Upload a track or jingle from a link
https://api.tunio.ai/ v1/ library/ uploads/ urlGive 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
| Name | Type | Description |
|---|---|---|
| category_id | string | Music only: category of the caller's library the track is filed under. |
| genre | string | Music only: genre stored on the track, up to 64 characters. |
| kindRequired | string | music (a track for playlists) or jingle (a jingle for bundles and the content schedule). |
| title | string | 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. |
| urlRequired | string | 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. |
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
| Name | Type | Description |
|---|---|---|
| success | boolean | Always true. |
| upload | object | The upload. |
| completed_at | string | When it completed or failed. |
| created_at | string | When the upload was accepted. |
| duration | integer | Length in seconds, set once completed. |
| error | string | 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_name | string | Name of the sent file, or the last segment of the link. |
| jingle_id | string | Jingle: the jingle in the caller's library, set once completed; add it to a bundle with POST /v1/jingle-bundles/{bundle_id}/items. |
| kind | string | music or jingle. |
| size_bytes | integer | Size of the source file in bytes, known once it is downloaded. |
| source | string | file (sent in the request) or url (downloaded from a link). |
| source_url | string | The link the file is downloaded from; null for file uploads. |
| state | string | pending (waiting for a worker), downloading, processing (checking and converting), completed or failed. |
| title | string | Title given in the request, null when none was. |
| track_id | string | 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_id | string | Upload ID; poll GET /v1/library/uploads/{upload_id} with it. |
| Name | Type | Description |
|---|---|---|
| message | string | Error code or human-readable error details. |
| success | boolean | Always false for error payloads. |
| Name | Type | Description |
|---|---|---|
| message | string | Error code or human-readable error details. |
| success | boolean | Always false for error payloads. |
| Name | Type | Description |
|---|---|---|
| message | string | Error code or human-readable error details. |
| success | boolean | Always false for error payloads. |
| Name | Type | Description |
|---|---|---|
| message | string | Error code or human-readable error details. |
| success | boolean | Always false for error payloads. |
| Name | Type | Description |
|---|---|---|
| max_pending | integer | Uploads allowed to be unfinished at once per account (20); sent with too_many_pending_uploads. |
| message | string | too_many_pending_uploads or rate_limited. |
| success | boolean | Always false. |
| Name | Type | Description |
|---|---|---|
| message | string | Error code or human-readable error details. |
| success | boolean | Always false for error payloads. |