強化上傳 API

2026-09-18 更新 · Suno-API 團隊

介面說明

強化上傳用於提交一首本機音訊檔案，由系統在後台執行增強處理，並生成可播放的完整歌曲結果。介面提交後會立即回傳任務資訊，用戶端需要透過查詢介面輪詢任務進度。

提交介面位址：POST /api/music/enhanced-upload

單一任務查詢位址：GET /api/music/enhanced-upload/:id

取消任務位址：POST /api/music/enhanced-upload/:id/cancel

列表查詢位址：GET /api/music/enhanced-upload

計費：10 元/次，按 suno-enhanced-upload 固定價格預扣費。任務失敗或在允許階段取消時會自動退回預扣費用，實際扣費以目前後台價格設定為準。

呼叫流程

1. 呼叫 POST /api/music/enhanced-upload 上傳音訊檔案。
2. 保存回傳的 task_id。
3. 呼叫 GET /api/music/enhanced-upload/:id 查詢進度與結果。
4. Suno 最終渲染完成後，服務使用該次任務綁定的 Suno 帳號呼叫 Studio 授權下載介面，將 MP3 寫入 CN2 媒體服務。
5. 只有 CN2 資產準備成功，任務才會變為 completed，此時從回應中的 audio_url 取得 CDN 音訊位址。

/api/forbidden 是 Suno Studio 中介資料可能出現的佔位位址，不是可播放或可下載資源。它不會回傳給客戶，也不會作為完成依據。若渲染已完成但 CN2 仍在準備，介面會繼續回傳 processing 且不回傳 audio_url；用戶端應繼續輪詢，不應將空位址視為失敗。

提交強化上傳

Headers

Form 參數

請求範例

下面範例使用的是生產驗證時相同的呼叫方式，但 API Key 已替換為佔位符。

curl.exe --http1.1 -s -S \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@source.aac" \
  -F "title=Enhanced upload demo" \
  "https://www.suno-api.io/api/music/enhanced-upload"

回應結果

{
  "success": true,
  "message": "",
  "data": {
    "task_id": 3209,
    "song_id": "pending:enhanced-upload:cu_20260611003241723483700xnCcQg",
    "client_request_id": "cu_20260611003241723483700xnCcQg",
    "title": "Enhanced upload demo",
    "file_name": "source.aac",
    "status": "queued",
    "created_at": 1781137961,
    "pre_consumed_quota": 5000000,
    "billing_source": "wallet"
  }
}

查詢單一任務

請求範例

curl.exe --http1.1 -s -S \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.suno-api.io/api/music/enhanced-upload/3209"

處理中回應範例

{
  "success": true,
  "message": "",
  "data": {
    "task": {
      "task_id": 3209,
      "song_id": "pending:enhanced-upload:cu_20260611003241723483700xnCcQg",
      "client_request_id": "cu_20260611003241723483700xnCcQg",
      "title": "Enhanced upload demo",
      "file_name": "source.aac",
      "status": "processing",
      "type": "enhanced_upload",
      "progress": {
        "stage": "media_preparing",
        "percent": 98,
        "label": "正在准备播放资源",
        "updated_at": 1781138500
      },
      "pre_consumed_quota": 5000000,
      "billing_source": "wallet",
      "created_at": 1781137961,
      "updated_at": 1781138500
    }
  }
}

完成回應範例

{
  "success": true,
  "message": "",
  "data": {
    "task": {
      "task_id": 3209,
      "song_id": "56cbd0bb-0e8c-4a34-8729-55d5c05d9c53",
      "client_request_id": "cu_20260611003241723483700xnCcQg",
      "title": "Enhanced upload demo",
      "file_name": "source.aac",
      "status": "completed",
      "type": "enhanced_upload",
      "audio_url": "https://media.code-go.com/assets/56cbd0bb-0e8c-4a34-8729-55d5c05d9c53-mp3.mp3",
      "duration": 217.74,
      "progress": {
        "stage": "completed",
        "percent": 100,
        "label": "已完成",
        "updated_at": 1781138943
      },
      "pre_consumed_quota": 5000000,
      "billing_source": "wallet",
      "created_at": 1781137961,
      "updated_at": 1781138943,
      "completed_at": 1781138943
    }
  }
}

取消任務

只有任務和後台 workflow 都仍處於 queued 階段時可以取消。任務進入 leasing、running、processing 或已完成後無法取消。

請求範例

curl.exe --http1.1 -s -S -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.suno-api.io/api/music/enhanced-upload/3209/cancel"

回應結果

{
  "success": true,
  "message": "",
  "data": {
    "task_id": 3209,
    "song_id": "pending:enhanced-upload:cu_20260611003241723483700xnCcQg",
    "client_request_id": "cu_20260611003241723483700xnCcQg",
    "status": "cancelled"
  }
}

如果任務已經開始處理，介面會回傳：

{
  "success": false,
  "message": "强化上传已开始处理，无法取消"
}

查詢任務列表

列表介面只回傳目前 API Key 所屬使用者的強化上傳任務，不會混入一般生成、翻唱、續寫等任務。

Query 參數

請求範例

curl.exe --http1.1 -s -S \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.suno-api.io/api/music/enhanced-upload?p=1&page_size=3"

回應結果

{
  "success": true,
  "message": "",
  "data": {
    "page": 1,
    "page_size": 3,
    "total": 1,
    "items": [
      {
        "task_id": 3209,
        "song_id": "56cbd0bb-0e8c-4a34-8729-55d5c05d9c53",
        "client_request_id": "cu_20260611003241723483700xnCcQg",
        "title": "Enhanced upload demo",
        "file_name": "source.aac",
        "status": "completed",
        "type": "enhanced_upload",
        "audio_url": "https://media.code-go.com/assets/56cbd0bb-0e8c-4a34-8729-55d5c05d9c53-mp3.mp3",
        "duration": 217.74,
        "progress": {
          "stage": "completed",
          "percent": 100,
          "label": "已完成",
          "updated_at": 1781138943
        },
        "pre_consumed_quota": 5000000,
        "billing_source": "wallet",
        "created_at": 1781137961,
        "updated_at": 1781138943,
        "completed_at": 1781138943
      }
    ]
  }
}

回傳欄位說明

注意事項

• 目前介面只支援 multipart 檔案上傳，不支援 JSON file_url 或 file_base64。
• 上傳檔案最大 80 MB。
• 提交介面是非同步介面，回傳 queued 表示任務已入列，不代表音訊已經完成。
• 取消只適用於尚未開始處理的任務；進入處理階段後不會中斷平台帳號工作流。
• 請不要在用戶端程式碼中暴露真實 API Key。

強化上傳完成後發起翻唱

強化上傳完成後，可以把完成結果作為來源 clip，呼叫 POST /api/music/generate-from-source 發起翻唱。

注意：翻唱是同步介面，回傳時才代表訂單已受理，實測最長可能等待約 230 秒。請把用戶端逾時設定為 300 秒以上，且逾時後不要立即重試。詳見 Suno API 介面文件總覽的「等待時間與逾時設定」。

請先輪詢 GET /api/music/enhanced-upload/:id，直到 task.status 為 completed。此時：

• task.song_id 是真實歌曲 ID，也是翻唱介面需要的 sourceClipId；
• task.audio_url 建議作為 sourceAudioUrl 一併傳入，便於伺服器處理來源 clip 與執行帳號不一致的情況；
• task.task_id 只是強化上傳任務 ID，不能作為 sourceClipId；
• pending:enhanced-upload:* 是處理階段的佔位 ID，不能用於翻唱。

發起翻唱時，請使用與強化上傳相同的 API Key，並按下面的欄位關係組裝請求：

其餘歌詞、風格、標題、模型等參數按照基於來源 clip 翻唱 API 填寫。翻唱介面回傳新的 clips[].song_id 後，使用 POST /api/music/query 查詢生成狀態與最終音訊。