【推薦】複製音色 API

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

✅ 新接入推薦使用本鏈路。 依據大量使用者的實際評測，這條鏈路生成的歌曲原聲還原度較高，成品裡的人聲更接近你上傳樣本中的本人音色，因此作為目前對外推薦的首選鏈路。

對照：早期的人聲複製與指定人聲生成 API（不推薦） 仍然可用，但導覽裡已標註「不推薦」，不再推薦新接入。

• 文件日期：2026-09-26
• 涵蓋能力：建立自己的音色 → 用音色翻唱指定歌曲 / 用音色唱新歌 → 查詢進度 → 下載成品
• 全文介面、欄位與回應都經過真實呼叫驗證（下文標註「實測」的為重點驗證項目）

說明：本文件只描述你需要呼叫的介面。素材處理、任務排程、內容校驗等環節都由伺服器自動完成，客戶端無需實作。

0. 五分鐘上手

只要四步，就能從一段人聲樣本拿到兩首成品歌。

① 建立音色    POST /api/music/voice-profile/create      → 拿到 voice_id（status=ready）
② 用音色翻唱  POST /api/music/voice-profile/cover       → 立刻拿到 2 個 song_id
③ 查詢進度    POST /api/music/query                     → 輪詢到 status=completed
④ 下載成品    GET  /api/music/download?song_id=…&kind=mp3

最小可用範例（curl）：

API_KEY="sk-你的密鑰"
BASE="https://www.suno-api.io"

# ① 建立音色（上傳一段人聲樣本，建議 10 秒以上、10MB 以內）
curl -sS -X POST "$BASE/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./my-voice.mp3" \
  -F "title=我的音色" \
  -F "source_kind=upload"
# → {"success":true,"message":"","data":{"voice_id":"vp_2026…","status":"ready", …}}

# ② 用這個音色翻唱一首歌（song_clip_id = 要翻唱的那首歌的 clip id）
curl -sS -X POST "$BASE/api/music/voice-profile/cover" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Create-Ui-Client-Request-Id: cover-$(date +%s)" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "suno-v6",
        "voice_id": "vp_2026…",
        "song_clip_id": "5b773e9a-…",
        "lyrics": "[Verse 1]\n歌詞正文…",
        "style_requirements": "慢速民謠，木吉他",
        "audio_weight": 0.85,
        "max_mode": false
      }'
# → {"code":200,"message":"success","data":{"resolved_scene":"cover","clips":[{…},{…}]}}

# ③ 輪詢（一次傳多個 id，用半形逗號分隔）
curl -sS -X POST "$BASE/api/music/query" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"suno-v6","song_ids":"id1,id2"}'

# ④ 完成後下載 mp3（status=completed 才能拿到檔案）
curl -sS -L "$BASE/api/music/download?song_id=id1&kind=mp3" \
  -H "Authorization: Bearer $API_KEY" -o song1.mp3

1. 公共約定

1.1 網域與環境

下文所有路徑都相對於 Base URL，例如 POST /api/music/voice-profile/create 的完整位址是 https://www.suno-api.io/api/music/voice-profile/create。

1.2 驗證

所有介面都用同一個請求標頭，值就是你在主控台建立的 API Key：

Authorization: Bearer sk-xxxxxxxx

• Bearer 前綴可帶可不帶；sk- 前綴可帶可不帶（Authorization: sk-xxx 同樣有效）。
• Key 缺失或無效 → HTTP 401，回應主體形如 {"success":false,"message":"…"}（文案隨請求語言變化）。
• 每個 Key 只能看到、只能操作自己帳號的歌曲與音色。

1.3 請求主體格式

• 建立音色：推薦 multipart/form-data（上傳檔案），也支援 application/json（傳 URL 或 base64）。
• 其餘介面：application/json。

1.4 兩種回應外殼（對客只需認這兩種）

「音色管理」類介面（create / create-from-clip / list / detail / delete）用業務外殼：

{ "success": true, "message": "", "data": { } }

{ "success": false, "message": "voice_id is required" }

「音色翻唱」走生成通道，用生成外殼：成功是 code/message/data，失敗是 error 物件：

{ "code": 200, "message": "success", "data": { } }

{ "error": { "message": "voice not found: vp_xxx", "type": "bad_response_status_code", "param": "", "code": "bad_response_status_code" } }

判定建議：先看 HTTP 狀態碼，再看 success === false，最後看 code !== 200 或是否存在 error。 業務失敗不保證 HTTP 非 200（音色管理類介面出錯時 HTTP 仍是 200），所以不能只看 HTTP 狀態碼。

1.5 冪等

建立音色（含「從現有音訊建立」）是真正冪等的：同一個 Key 下，同一個 client_request_id 重複提交只會建一條音色，第二次直接回傳第一次的結果（success=true、同一個 voice_id）。用法是客戶端自己生成一個 id（例如 UUID），逾時重試時沿用同一個值。

翻唱提交不做請求級去重（它是一次計費生成），請注意兩點：

1. 提交標識放在請求標頭 X-Create-Ui-Client-Request-Id: <你的提交 id>。它會寫進伺服器任務記錄，便於事後排查；它不會阻止重複扣費。
2. 提交逾時 ≠ 失敗：請求可能已經被受理並在生成。重試前建議先 GET /api/music/songs?p=1&page_size=20（分頁參數是 p / page_size，也可用相容寫法 ps）看最近是否已經出現 generation_type=voice_profile_cover 的新歌，確認沒有再把同樣的請求重發一次。

create 與 create-from-clip 的 body 裡也用 client_request_id 欄位（見 §3、§4）。

1.6 計費總覽

價格隨時可透過公開介面讀取，不要寫死（見 §9）：

curl -sS https://www.suno-api.io/api/pricing/catalog | jq '.data.catalog.meta'
# {
#   "generation_price": "0.6",
#   "voice_generation_price": "1.2",      ← 音色翻唱基準價
#   "max_mode_factor": "2",
#   "enhanced_upload_price": "10",        ← 強化複製價
#   "voice_auto_verify_price": "5",
#   "voice_long_term_clone_price": "5"
# }

翻唱採用預扣費 + 失敗退款：

• 請求被拒絕（參數錯誤、平台 4xx/5xx、餘額不足本身）不會扣費——實測用不存在的音色提交後餘額完全沒變（delta = 0）；
• 已受理的任務最終失敗（含平台服務異常）會走伺服器退款鏈路退回預扣金額。

1.7 狀態字典

音色的 status：

歌曲的 status（查詢介面回傳值）：

2. 介面總覽

3. 建立音色

POST /api/music/voice-profile/create

把一段人聲音訊登記成「音色」，得到 voice_id。音色對平台而言就是「一段音訊 + 它在曲庫裡的 clip」，因此建立成功後這段來源音訊永久保留（用於後續翻唱）。

3.1 三種入參形態（任選其一）

形態 A：multipart 上傳檔案（推薦）

Content-Type: multipart/form-data

file=<音訊二進位>          # 必填
title=<音色名稱>            # 選填，空則取檔名去掉副檔名
file_name=<原始檔名>
source_file_name=<原始檔名>
source_kind=upload|record   # 選填，來源標記（上傳 / 錄製），預設 upload
enhanced=false|true         # 選填，true = 強化複製（見 §3.5）
client_request_id=<冪等鍵>   # 選填
voice_id=<自訂 ID>           # 選填，一般不用

curl -sS -X POST "https://www.suno-api.io/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./my-voice.mp3;type=audio/mpeg" \
  -F "file_name=my-voice.mp3" \
  -F "source_file_name=my-voice.mp3" \
  -F "title=我的音色" \
  -F "source_kind=upload"

形態 B：JSON + 公網音訊 URL

curl -sS -X POST "https://www.suno-api.io/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "file_url": "https://your-cdn.example.com/voice/my-voice.mp3",
        "file_name": "my-voice.mp3",
        "title": "我的音色"
      }'

• URL 必須是公網可存取的直鏈 HTTPS 位址，伺服器會下載一次並轉存到我們的物件儲存。
• 也可以把位址放在 audio_url 欄位，效果等價（兩者都傳時以 file_url 為準）。
• 已經是本平台物件儲存位址（*.myqcloud.com/create-ui/voice-source/...）時不會重複下載，直接登記。

形態 C：JSON + base64

{
  "file_base64": "data:audio/mpeg;base64,//uQxAAA…",
  "file_name": "my-voice.mp3",
  "title": "我的音色"
}

• 支援 data:audio/xxx;base64, 前綴，也支援純 base64。
• 體積受限（base64 會放大 1.33 倍），大檔案請用形態 A。

3.2 音訊要求

3.3 回應

{
  "success": true,
  "message": "",
  "data": {
    "voice_id": "vp_20260926080618509168500DXXrxe",
    "clip_id": "91cc5935-389f-4193-b56b-cc796c15562d",
    "song_id": "91cc5935-389f-4193-b56b-cc796c15562d",
    "account_id": "acc_1790085275308",
    "title": "我的音色",
    "source_file_name": "my-voice.mp3",
    "audio_url": "https://suno-api-p-1437223057.cos.ap-guangzhou.myqcloud.com/create-ui/voice-source/2026/09/26/xxx.mp3",
    "image_url": "https://cdn2.suno.ai/image_91cc5935-389f-4193-b56b-cc796c15562d.jpeg",
    "duration_s": 29.18,
    "enhanced": false,
    "source_kind": "upload",
    "status": "ready",
    "client_request_id": "",
    "created_at": 1790409978,
    "updated_at": 1790409998
  }
}

欄位說明（create / list / detail 三個介面共用同一套欄位）：

created_at / updated_at 是秒級時間戳（10 位），不是毫秒。

3.4 常見錯誤

3.5 強化複製（enhanced=true）

用於「音色樣本本身帶有版權歌詞 / 需要做加強上傳」的場景，價格依強化上傳價（預設 10 元/次，失敗自動退款）：

• 回應立刻是 status=processing + task_id（此時還沒有 clip_id），非同步執行；
• 處理期間用 GET /api/music/voice-profile/{voice_id} 查進度，會回傳 progress_percent / progress_stage / progress_message；
• 完成後 status 變 ready，clip_id、audio_url、image_url 補齊；
• 失敗則 status=failed，error_message 形如「強化上傳失敗，費用已自動退回，請稍後重試。」；
• 強化複製耗時明顯長於普通建立（分鐘級），請勿用同步逾時邏輯等待。

curl -sS -X POST "https://www.suno-api.io/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./my-voice.mp3" -F "title=我的音色" -F "enhanced=true"

4. 用已有音訊建立音色

如果你不想重新上傳：把自己已經上傳或已經生成的一段音訊直接複製成音色。免費、冪等。

POST /api/music/voice-profile/create-from-clip
Content-Type: application/json

{
  "source_song_id": "97ee62fe-56cd-473f-a2f5-c66ac0766a2e",
  "title": "徐清 強",
  "client_request_id": "vp-clip-1789…"
}

• source_song_id：你名下一段已完成音訊的 clip id（等同於歌曲的 song_id）。
• 同一個 clip 重複提交不會新建記錄，直接回傳已有音色並帶 reused: true（實測）。

回應 = §3.3 的全部欄位，另加兩個唯讀欄位：

{
  "success": true,
  "data": {
    "voice_id": "vp_20260926081712557959800Z5gvlt",
    "clip_id": "97ee62fe-56cd-473f-a2f5-c66ac0766a2e",
    "title": "徐清 強",
    "status": "ready",
    "enhanced": true,
    "reused": true,
    "source_type": "enhanced_upload"
  }
}

錯誤（message 原文，建議直接顯示或做本地化）：

5. 音色列表 / 詳情 / 刪除

5.1 列表

GET /api/music/voice-profile/list
GET /api/music/voice-profile/list?include_deleted=true

{
  "success": true,
  "message": "",
  "data": {
    "items": [ { "voice_id": "vp_…", "title": "我的音色", "status": "ready", "audio_url": "…", "image_url": "…" } ],
    "total": 1
  }
}

欄位與 §3.3 完全一致。預設不回傳已刪除的音色。

5.2 詳情

GET /api/music/voice-profile/{voice_id}

回傳單個音色物件（data 為物件本身，不是陣列）。強化複製在處理中時，會額外帶上：

5.3 刪除

POST /api/music/voice-profile/delete
Content-Type: application/json

{ "voice_id": "vp_2026…" }

{ "success": true, "message": "", "data": { "voice_id": "vp_2026…", "status": "deleted" } }

• 刪除後音色從列表裡消失，不能用於新的翻唱：繼續拿這個 voice_id 提交會回傳 400（見 §6.4）。
• 已經用它生成過的歌完全不受影響，播放、下載、續寫、替換、分軌照舊。
• 刪除不存在的音色、或不屬於本帳號的音色，回傳 {"success":false,"message":"voice not found"}。

6. 用音色翻唱（核心介面）

POST /api/music/voice-profile/cover
Content-Type: application/json

一次提交 生成 2 首（與普通生成一致）。

6.1 兩種場景

回應裡的 resolved_scene 會回顯 cover 或 sing，便於你確認走了哪條路。

6.2 請求欄位

建議同時帶上請求標頭 X-Create-Ui-Client-Request-Id: <同一個提交 id>：它才會寫進伺服器任務記錄，是事後排查的主鍵（詳見 §1.5）。

量綱提醒：audio_weight / style_weight / weirdness_constraint 是 0–1 小數，variety 是 0–4 整數，duration 是秒。混用會被拒絕或效果異常。

場景 B 的歌詞選填（模型會自行處理），但要唱指定內容時請務必傳 lyrics。

6.3 回應

{
  "code": 200,
  "message": "success",
  "data": {
    "voice_id": "vp_20260926081712557959800Z5gvlt",
    "voice_clip_id": "97ee62fe-56cd-473f-a2f5-c66ac0766a2e",
    "song_clip_id": "5b773e9a-a035-4134-a4a4-29c9961d3ccb",
    "resolved_scene": "cover",
    "model": "suno-v6",
    "audio_weight": 0.85,
    "clips": [
      {
        "song_id": "0f2a…",
        "status": "processing",
        "song_title": "",
        "model_version": "suno-v6",
        "audio_url": "",
        "play_url": "https://media.suno-api.io/play/0f2a…?expires=…&signature=…",
        "lyrics": "",
        "description": "【任務】這是一次翻唱。…（伺服器固定結構段 + 你填寫的翻唱/風格要求）"
      },
      {
        "song_id": "7c91…",
        "status": "processing",
        "model_version": "suno-v6",
        "audio_url": ""
      }
    ],
    "source_updates": []
  }
}

要點：

1. 成品標識用 clips[].song_id（本介面不回 id 欄位）。
2. 立刻拿到 2 個 song_id，此時 status 還是 processing（只代表已受理），audio_url 為空；要輪詢到 completed 才能下載。play_url 是平台試聽串流，提交階段就可能出現，會過期。
3. description 是伺服器最終上送的提示詞（固定結構段 + 你填寫的 cover_requirements / style_requirements），排查效果時很好用。
4. source_updates 是伺服器的素材處理結果，客戶端可忽略。
5. 你傳的 title 會寫進伺服器任務記錄，在後續查詢裡體現為 song_title；提交回包的 clips[].song_title 通常為空，屬正常。

6.4 錯誤

{ "error": { "message": "該音色不存在或已被刪除（voice_id=vp_xxx）…", "type": "new_api_error", "param": "", "code": "invalid_request" } }

餘額不足會在提交階段直接回傳計費錯誤，不會產生半成品任務。

6.5 可用模型（對客模型名）

請使用對客模型名（上面的名字）。chirp-* 是平台內部名稱，不要直接使用。

7. 查詢進度

7.1 批量查詢（推薦）

POST /api/music/query
Content-Type: application/json

{ "model": "suno-v6", "song_ids": "id1,id2" }

• song_ids 是半形逗號分隔的字串（不是陣列）。
• 回傳是裸陣列（直接 [...]，沒有 success / data 外殼）：

[
  {
    "song_id": "0f2a…",
    "song_title": "兩隻老虎",
    "status": "completed",
    "audio_url": "https://suno-api-hk-1437223057.cos.ap-hongkong.myqcloud.com/assets/0f2a…-mp3.mp3",
    "cover_url": "https://cdn2.suno.ai/image_0f2a….jpeg",
    "duration": 115.15,
    "model_version": "suno-v6",
    "generation_type": "voice_profile_cover",
    "play_url": "https://media.suno-api.io/play/…?expires=…&signature=…",
    "lyrics": "[Verse 1]…",
    "prompt": "[Verse 1]…",
    "description": "【任務】這是一次翻唱。…（伺服器最終提示詞）",
    "style_tags": "…",
    "created_at": "2026-09-25T18:19:09.918Z",
    "video_url": ""
  }
]

輪詢建議：間隔 5–10 秒，總逾時 10–15 分鐘（冷帳號最慢實測約 4 分半；極少數更久）。不要用 audio_url 是否空來判斷完成，要用 status。

相容提示：本介面以 song_id 為標識；早期個別回應裡出現過 id 欄位，穩妥寫法是 row.song_id || row.id。

7.2 單首詳情

GET /api/music/songs/{song_id}

{
  "success": true,
  "data": {
    "song_id": "0f2a…",
    "title": "兩隻老虎",
    "status": "completed",
    "generation_type": "voice_profile_cover",
    "model": "suno-v6",
    "duration": 115.15,
    "audio_url": "https://…/assets/0f2a…-mp3.mp3",
    "image_url": "https://cdn2.suno.ai/image_0f2a….jpeg",
    "wav_url": "https://www.suno-api.io/api/music/download?song_id=0f2a…&kind=wav",
    "video_url": "https://www.suno-api.io/api/music/download?song_id=0f2a…&kind=video",
    "created_at": 1790411012,
    "completed_at": 1790411500,
    "parameters": {
      "prompt": "[Verse 1]…",
      "style_tags": "…",
      "title": "兩隻老虎",
      "model": "suno-v6",
      "generation_type": "voice_profile_cover",
      "source_song_id": "5b773e9a-…"
    },
    "parameter_retention": {
      "core_parameters_available": true,
      "extended_parameters_available": false,
      "sources": ["suno_tasks"],
      "unavailable_fields": ["negative_tags", "vocal_gender", "style_weight", "weirdness_constraint"]
    }
  }
}

• created_at / completed_at 這裡是 Unix 秒（與批量查詢的 ISO 字串不同，客戶端注意區分）。
• wav_url / video_url 是本平台的下載入口（相對當前網域），GET 即可取檔；平台沒有該產物時為空字串。
• parameter_retention 說明該歌曲能追溯哪些提交參數：core_parameters_available=true 表示歌詞 / 風格 / 來源等核心參數可查，extended_parameters_available=false 時上面列的擴充參數沒有留存（音色翻唱目前屬這一類）。

7.3 我的作品列表

GET /api/music/songs?p=1&page_size=20
GET /api/music/songs?status=completed&q=關鍵詞

分頁參數：p（頁碼，從 1 開始）/ page_size（每頁筆數，相容寫法 ps）。可選 status、q（標題關鍵詞）。預設按建立時間倒序。

{
  "success": true,
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 42,
    "items": [
      {
        "song_id": "0f2a…",
        "title": "兩隻老虎",
        "status": "completed",
        "generation_type": "voice_profile_cover",
        "model": "suno-v6",
        "duration": 115.15,
        "audio_url": "https://…/assets/0f2a…-mp3.mp3",
        "image_url": "https://cdn2.suno.ai/image_0f2a….jpeg",
        "created_at": 1790411012,
        "completed_at": 1790411500
      }
    ]
  }
}

用 generation_type=voice_profile_cover 可以把「用音色翻唱產出的歌」與其他生成結果區分開。

8. 下載成品

8.1 直接取 mp3（推薦，免費）

三種都可以，任選其一：

1. 用查詢結果裡的 audio_url（物件儲存直鏈，最省事）。
2. GET /api/music/download?song_id=<id>&kind=mp3 → 直接回傳音訊位元組流（Content-Disposition 已帶檔名）。
3. POST /api/music/download-url（拿帶簽名的臨時位址）。

curl -sS -L "https://www.suno-api.io/api/music/download?song_id=0f2a…&kind=mp3" \
  -H "Authorization: Bearer $API_KEY" -o song.mp3

kind 取值：mp3（等價於 song）/ playback（串流播放）/ wav / video / lyrics / timestamped_lyrics。 其中 timestamped_lyrics（.lrc）目前僅部分歌曲支援，失敗時請改用 時間軸歌詞 API 自行生成。 回應直接是檔案位元組流，Content-Type 與 Content-Disposition（檔名）都已帶好；GET /api/music/songs/{song_id} 回傳的 wav_url / video_url 就是帶上 kind=wav|video 的同一個入口。

8.2 轉 wav / 取歌詞 / 中繼資料（計費）

POST /api/music/free2
Content-Type: application/json

{ "song_ids": ["0f2a…"], "files": ["mp3", "wav", "lyrics"] }

{
  "success": true,
  "data": {
    "songs": [
      { "song_id": "0f2a…", "files": [ { "type": "mp3", "url": "https://…" }, { "type": "wav", "url": "https://…" } ] }
    ],
    "requested_songs": 1,
    "succeeded_songs": 1,
    "price": 0.2
  }
}

• files 支援：mp3 / wav / lyrics / metadata，一次最多 10 首。
• 按成功首數計費（0.2 元/首）；整首失敗不計費，某個格式失敗只出現在 songs[].errors。
• 重新下載之前已經取過的檔案，可以先用 免費 的 POST /api/music/free2/cached（同樣的 song_ids + files）取歸檔位址；回傳裡 songs[].missing_files 列出沒有快取、需要重新準備的格式。

9. 價格查詢

GET /api/pricing/catalog

公開介面，無需驗證。對客要顯示的單價都在 data.catalog.meta（字串）：

價格會在後台調整，請即時讀取，不要寫死在客戶端。翻唱實際扣費 = voice_generation_price ×（max_mode 為真時再 × max_mode_factor）。

10. 限制與注意事項

1. 上傳體積：≤ 10MB（伺服器可接受的上限更高，但入口閘道在 10MiB 處會截斷超大請求體，表現為「被 Suno 拒絕」，請自行先攔）。
2. 樣本時長：最少 6 秒，建議 10–60 秒；過短會被平台拒絕。
3. 樣本內容：乾淨人聲，避免與已有錄音高度相似（會被曲庫比對拒絕）。
4. 文字上限：lyrics ≤ 3000 字元，style_requirements / negative_tags / title 建議分別 ≤ 1000 / 1000 / 100 字元（風格與翻唱要求會拼進提示詞，合計請控制在 3000 字元內）。
5. 歌詞不做改寫：傳入什麼就唱什麼（逐字一致），不做本地截斷。
6. 每首歌固定 2 首產出，不要假設回傳 1 首。
7. 來源音訊永久保留：音色刪除了來源音訊也不清理；這是為了保證後續翻唱可用與合規追溯。
8. 音色必須 ready：processing 的音色不能用於翻唱。
9. 請求逾時：冷帳號首次提交最慢實測約 4 分半，客戶端逾時請設 ≥ 6 分鐘。翻唱不做請求級去重，逾時後請先核對是否已經產生新歌（§1.5），再決定是否重發。
10. 音色歸屬：音色按建立者歸屬管理；翻唱只接受已就緒（ready）且未刪除的音色。不存在、已刪除或不屬於本帳號，都會回傳 400：該音色不存在或已被刪除（voice_id=…）。

11. 常見問題（FAQ）

Q1. 建立音色會不會扣錢？ 普通建立與「從已有音訊建立」都免費；只有翻唱（1.2 元 / MAX 2.4 元）和強化複製（預設 10 元）計費。

Q2. 音色樣本能不能用帶伴奏的成品歌？ 不建議。帶音樂或與曲庫已有錄音高度相似會被平台拒絕（This audio matches an existing recording in our catalog.）。請用純人聲乾聲。

Q3. 為什麼提交翻唱後 audio_url 是空的？ 提交只代表已受理，status 還是 processing。輪詢 /api/music/query 到 status=completed 後才有可播 / 可下載位址。

Q4. 場景 B（不傳 song_clip_id）要不要傳歌詞？ 選填。要唱指定內容就傳 lyrics；不傳時模型會自行處理，但可控性較差。

Q5. 客戶自己上傳的音訊能直接當音色嗎？ 可以：create 的 file_url 形態，或先上傳成歌曲再呼叫 create-from-clip。

Q6. 失敗了會退錢嗎？ 被直接拒絕的請求（參數錯誤 / 平台報錯）實測不扣費；已受理但最終失敗的任務會退回預扣金額。終態失敗時任務回傳 status=failed 與 error_message。

Q7. 刪除音色後，之前用它生成的歌還能聽嗎？ 能。刪除只影響這個音色能否繼續用於新的翻唱。

Q8. 一次能翻唱多長的歌？ duration 傳 1–480 秒；不傳則由平台按原曲 / 素材自動決定。注意平台的成品最短約 30 秒：填小於 30 秒的值，實測出來仍是 29.96 / 29.76 秒。

附錄 A：完整呼叫範例（Node.js，含輪詢與下載）

const BASE = "https://www.suno-api.io";
const KEY = process.env.SUNO_API_KEY;
const H = { Authorization: `Bearer ${KEY}` };

// ① 建立音色（multipart）
async function createVoice(filePath, title) {
  const fd = new FormData();
  fd.set("file", new Blob([await (await import("node:fs/promises")).readFile(filePath)], { type: "audio/mpeg" }), "my-voice.mp3");
  fd.set("file_name", "my-voice.mp3");
  fd.set("source_file_name", "my-voice.mp3");
  fd.set("title", title);
  fd.set("client_request_id", `vp-create-${Date.now()}`);
  const res = await fetch(`${BASE}/api/music/voice-profile/create`, { method: "POST", headers: H, body: fd });
  const body = await res.json();
  if (!body.success) throw new Error(body.message);
  return body.data; // { voice_id, status, audio_url, ... }
}

// ② 翻唱
async function cover(voiceId, songClipId, lyrics) {
  const submissionId = `vp-cover-${Date.now()}`;
  const res = await fetch(`${BASE}/api/music/voice-profile/cover`, {
    method: "POST",
    headers: { ...H, "Content-Type": "application/json", "X-Create-Ui-Client-Request-Id": submissionId },
    body: JSON.stringify({
      model: "suno-v6",
      voice_id: voiceId,
      song_clip_id: songClipId || "",
      lyrics: lyrics || "",
      style_requirements: "慢速民謠，木吉他",
      audio_weight: 0.85,
      max_mode: false,
      client_request_id: submissionId,
    }),
  });
  const body = await res.json();
  if (body.error) throw new Error(body.error.message);
  return body.data; // { resolved_scene, clips: [{ song_id, status }] }
}

// ③ 輪詢到完成（5 秒一次，最多 15 分鐘）
async function waitUntilCompleted(songIds) {
  const deadline = Date.now() + 15 * 60 * 1000;
  while (Date.now() < deadline) {
    const res = await fetch(`${BASE}/api/music/query`, {
      method: "POST",
      headers: { ...H, "Content-Type": "application/json" },
      body: JSON.stringify({ model: "suno-v6", song_ids: songIds.join(",") }),
    });
    const songs = await res.json(); // 裸陣列
    if (songs.every((s) => s.status === "completed" || s.status === "failed")) return songs;
    await new Promise((r) => setTimeout(r, 5000));
  }
  throw new Error("timeout waiting for cover");
}

// ④ 下載
async function download(songId, outPath) {
  const res = await fetch(`${BASE}/api/music/download?song_id=${encodeURIComponent(songId)}&kind=mp3`, { headers: H });
  if (!res.ok) throw new Error(`download failed: ${res.status}`);
  (await import("node:fs/promises")).writeFile(outPath, Buffer.from(await res.arrayBuffer()));
}

const voice = await createVoice("./my-voice.mp3", "我的音色");
const result = await cover(voice.voice_id, "5b773e9a-a035-4134-a4a4-29c9961d3ccb", "[Verse 1]\n歌詞…");
const ids = result.clips.map((c) => c.song_id);
const songs = await waitUntilCompleted(ids);
for (const [i, s] of songs.entries()) {
  if (s.status === "completed") await download(s.song_id, `./out-${i}.mp3`);
}

附錄 B：變更記錄