上傳來源音訊 API
介面說明
上傳來源音訊用於把本機音訊或遠端音訊上傳為後續翻唱、續寫、替換、分軌等能力可使用的來源 clip。
介面位址: POST /api/music/upload-source
計費: 免費。該介面只上傳來源音訊，不開始生成任務。
推薦用法：它是「兩步式翻唱」的第 1 步。 先用本介面把音訊傳上來（免費、失敗可隨時重試），拿到返回的
clip_id；確認上傳成功（status為完成態）後， 再呼叫基於來源 clip 翻唱 API 發起翻唱——那一步的請求體只有幾百位元組， 不會因為音訊太大而在傳輸中被截斷。相比一次性介面上傳後翻唱 API， 這種拆法在音訊較大、網路不穩定、或同一份素材要重複使用多次（續寫 / 替換 / 分軌）時更穩。
大檔案上傳建議
| 情況 | 建議做法 |
|---|---|
| 音訊已在公網（有 https 直鏈） | 用 file_url：請求體只有幾百位元組，最穩 |
| 臨時簽名 URL（ByteDance 等） | 僅在 URL 公開可存取且仍有效時使用 file_url；否則請用 multipart 或立即上傳 |
| 本機檔案（Node / Python / 桌面端） | 用 multipart 上傳（-F "file=@source.mp3"），並不要手動設定 Content-Type |
| 只能用 JSON + base64 | 注意 Content-Length 要用位元組數（Buffer.byteLength），否則請求體可能被截斷 |
上傳完成後，務必先確認回應裡的 status 已是完成態、並保存 clip_id，再進入第 2 步；
上傳失敗不會扣費、也不會產生生成任務，直接重試即可。
上傳前先檢查 file_url
file_url是由平台伺服器主動透過 HTTP 下載，不是瀏覽器跳轉。瀏覽器能開啟該網址，不代表生產伺服器也能下載。
本機檔案請優先使用 multipart，欄位名稱為 file。ByteDance 或其他臨時簽名 URL 除非公開可存取，且在送出請求時仍然有效，否則不要使用 file_url。
送出上傳請求前，請先從一般公網伺服器執行：
curl -L --max-time 30 -D - -o /dev/null "https://example.com/source.mp3"
GET 必須以 HTTP 200 結束，回傳音訊 MIME，且內容不可為空。登入頁、HTML 回應，以及 401、403、404、410 都無法供伺服器使用。
file_url download failed: HTTP 404 通常表示簽名過期、檔案已刪除，或 URL 參數不完整。
此上傳介面免費。file_url 下載失敗時不會建立 clip_id、歌曲任務或生成呼叫，也不會扣費，因此不需要退款。
請求參數
Headers
JSON 請求：
| 參數名 | 型別 | 必填 | 說明 |
|---|---|---|---|
| Authorization | string | 是 | Bearer YOUR_API_KEY |
| Content-Type | string | 是 | application/json |
multipart 請求不要手動指定 Content-Type，由用戶端自動生成。
請求主體參數
| 參數名 | 型別 | 必填 | 預設值 | 說明 |
|---|---|---|---|---|
| model | string | 否 | suno-v6 | 對客模型名：suno-v6、suno-v6-wild 或 suno-v6-mini |
| file_url | string | 否 | - | 遠端音訊 URL |
| file_base64 | string | 否 | - | Base64 音訊 |
| file | 檔案（multipart） | 否 | - | 要上傳的音訊檔案；欄位名稱必須是 file |
| file_name | string | 否 | - | 檔案名 |
| upload_type | string | 否 | file_upload | 上傳類型 |
JSON 請求範例
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 請求範例
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())
回應結果
{
"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": {}
}