Upload source audio API

Updated 2026-09-18 · Suno-API team

Endpoint description

Upload source audio turns a local or remote audio file into a source clip that later capabilities — cover, extend, replace-section, separation and so on — can use.

Endpoint: POST /api/music/upload-source

Billing: Free. This endpoint only uploads source audio; it does not start a generation task.

Recommended usage: this is step 1 of the "two-step cover". Upload the audio with this endpoint first (free, and you can retry whenever it fails) and keep the returned clip_id; once you have confirmed that the upload succeeded (status in a completed state), call the cover from a source clip API to start the cover — that request body is only a few hundred bytes, so it cannot be truncated in transit because the audio is too large. Compared with the one-shot upload-then-cover API, this split is more robust when the audio is large, the network is unstable, or the same material will be reused several times (extend / replace-section / separation).

Advice for large file uploads

After the upload finishes, always confirm that status in the response is already a completed state and save the clip_id before moving on to step 2; a failed upload is not charged and creates no generation task, so simply retry.

Check file_url before uploading

Our server downloads file_url itself; your browser does not. A URL that opens in your browser is not necessarily reachable from our production servers.

For local files, use multipart upload with the file field. Do not use file_url for ByteDance or other temporary signed URLs unless the URL is publicly reachable and is still valid when the upload request is sent.

Run this from a public server before sending the upload request:

curl -L --max-time 30 -D - -o /dev/null "https://example.com/source.mp3"

A GET request must end with HTTP 200, return an audio MIME type and contain non-empty data. Login pages, HTML responses, and HTTP 401, 403, 404 or 410 cannot be used by the server.

file_url download failed: HTTP 404 usually means the signed URL expired, the file was removed, or URL parameters were truncated.

This upload is free. If the file_url download fails, no clip_id, song task or generation call is created and no fee is charged, so no refund is required.

Request parameters

Headers

For JSON requests:

Do not set Content-Type manually for multipart requests; the client generates it automatically.

Body parameters

JSON request example

curl -X POST https://www.suno-api.io/api/music/upload-source \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "file_url": "https://example.com/source.mp3",
    "file_name": "source.mp3",
    "upload_type": "file_upload"
  }'

multipart request example

curl -X POST https://www.suno-api.io/api/music/upload-source \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@source.mp3" \
  -F "file_name=source.mp3" \
  -F "upload_type=file_upload" \
  -F "model=suno-v6"

import requests

with open("source.mp3", "rb") as audio:
    response = requests.post(
        "https://www.suno-api.io/api/music/upload-source",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
        data={
            "file_name": "source.mp3",
            "upload_type": "file_upload",
            "model": "suno-v6",
        },
        files={"file": ("source.mp3", audio, "audio/mpeg")},
        timeout=300,
    )

response.raise_for_status()
print(response.json())

Response

{
  "clip_id": "uploaded_clip_id",
  "status": "complete",
  "title": "source.mp3",
  "image_url": "https://...",
  "audio_url": "https://...",
  "display_tags": "pop, vocal",
  "inferred_description": "uploaded source audio",
  "clip_metadata": {}
}