人聲複製與指定人聲生成 API（不推薦）

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

⛔ 舊鏈路，不推薦新接入。 本文件描述的是早期 persona（voice_task_id / generate-with-voice）鏈路，仍然可用，但不再對外推薦；左側導覽裡已標註「不推薦」。

新接入請用【推薦】複製音色 API：用一段人聲樣本建立音色（POST /api/music/voice-profile/create），再用它翻唱指定歌曲或演唱新歌。音色是一等資源，可以列表、查詢、刪除，且來源音訊永久保留。

如果你的產品需要「建立音色 → 長期複用 → 翻唱」的完整閉環，請優先接新鏈路。

重要提示：複製人聲可能過期。

人聲複製生成的 voice_id / voice_task_id 不是永久可用資源，可能因有效期限、帳號狀態或人聲狀態變化而失效。接入方不要只在首次複製成功後永久複用本地快取的人聲 ID。

推薦做法：

• 保存 voice_task_id、voice_id、is_available、updated_at 和最近一次生成成功時間。
• 每次使用已複製人聲生成前，先呼叫 GET /api/voice/clone/tasks/{voice_task_id} 或 POST /api/voice/clone/tasks/{voice_task_id}/check 確認 is_available=true。
• 如果介面回傳人聲不可用、任務不存在、selected voice is not ready 等錯誤，請提示使用者重新複製或重新選擇可用人聲。
• 不建議把複製人聲做成「永久資產」承諾給終端使用者；應在產品介面中提示「人聲可能過期，需要重新校驗或重新複製」。

介面說明

本組介面用於建立可複用的人聲，並使用該人聲生成歌曲。呼叫方只需要使用平台發放的 API Key，伺服器會統一處理任務提交、狀態同步、計費和下載。

認證方式: Authorization: Bearer YOUR_API_KEY

計費:

• 人聲校驗、人聲複製、狀態查詢、刪除、下載：免費。
• 工作台的一步式複製入口：固定 5 元/次，自動完成來源人聲校驗與二次驗證音訊，失敗會退款。
• 普通複製完成後繼續自動生成驗證音訊：固定 5 元/次；失敗按現有流程退款。
• 使用已複製人聲生成歌曲：收費，固定 1.2 元/次，每次通常回傳 2 個佔位任務。
• 開啟 Max Mode（POST /api/music/generate-with-voice 傳 max_mode: true）時， 上述 1.2 元/次按 2 倍計費，即 2.4 元/次；人聲生成也支援 variety（0-4， 不額外計費），取值規則見新版 API 總覽 的「進階參數」一節。

呼叫流程

1. 呼叫 POST /api/voice/clone/validate 上傳來源人聲，取得 voice_task_id。
2. 等待或輪詢 GET /api/voice/clone/tasks/{voice_task_id}，拿到 validate_info。
3. 使用者按 validate_info 朗讀並錄製驗證音訊。
4. 呼叫 POST /api/voice/clone/tasks/{voice_task_id}/generate 提交驗證音訊。
5. 呼叫 POST /api/voice/clone/tasks/{voice_task_id}/check 或繼續查詢任務，直到 is_available=true。
6. 呼叫 POST /api/music/generate-with-voice 使用該人聲生成歌曲。
7. 生成介面會先回傳佔位任務；歌曲生成完成並拿到實際 song_id 後，可用下載介面下載單一檔案或打包檔案。
8. （可選）不再需要這個人聲時，呼叫 DELETE /api/voice/clone/voices/{voice_task_id} 刪除，語意見第 6 節。

此外還有一步式複製：在工作台的首次錄音/上傳來源人聲頁面選擇一步完成，系統會一次完成校驗與音色生成，不需要你再錄第二段驗證音訊；按 5 元/次計費，失敗退款。

人聲任務欄位

1. 提交來源人聲校驗

介面位址: POST /api/voice/clone/validate

Body 參數

vocal_end_s - vocal_start_s 需要滿足最短人聲片段要求。建議上傳清晰、無明顯伴奏和雜訊的人聲錄音。

請求範例

curl -X POST https://www.suno-api.io/api/voice/clone/validate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_url": "https://example.com/source-voice.wav",
    "voice_name": "我的中文女聲",
    "description": "清亮自然的中文女聲",
    "style": "Mandopop",
    "singer_skill_level": "intermediate",
    "language": "zh",
    "vocal_start_s": 1.2,
    "vocal_end_s": 18.5,
    "source_duration_seconds": 20
  }'

回應範例

{
  "success": true,
  "message": "",
  "data": {
    "voice": {
      "voice_task_id": 123,
      "voice_name": "我的中文女聲",
      "language": "zh",
      "validate_status": "submitted",
      "is_available": false,
      "status": "validate_submitted",
      "stage": "validate_submitted",
      "created_at": 1780480000,
      "updated_at": 1780480000
    }
  }
}

2. 查詢人聲任務

介面位址: GET /api/voice/clone/tasks/{voice_task_id}

請求範例

curl https://www.suno-api.io/api/voice/clone/tasks/123 \
  -H "Authorization: Bearer YOUR_API_KEY"

回應範例

{
  "success": true,
  "message": "",
  "data": {
    "voice": {
      "voice_task_id": 123,
      "voice_name": "我的中文女聲",
      "validate_info": "請朗讀這裡回傳的驗證文字",
      "validate_status": "success",
      "is_available": false,
      "status": "validate_ready",
      "stage": "validate_callback"
    }
  }
}

3. 重新生成驗證文字

介面位址: POST /api/voice/clone/tasks/{voice_task_id}/regenerate

當驗證文字不適合朗讀或需要重新校驗時可呼叫。

curl -X POST https://www.suno-api.io/api/voice/clone/tasks/123/regenerate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

4. 提交驗證音訊並建立人聲

介面位址: POST /api/voice/clone/tasks/{voice_task_id}/generate

Body 參數

請求範例

curl -X POST https://www.suno-api.io/api/voice/clone/tasks/123/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "verify_url": "https://example.com/verify-voice.wav",
    "voice_name": "我的中文女聲"
  }'

5. 檢查人聲是否可用

介面位址: POST /api/voice/clone/tasks/{voice_task_id}/check

curl -X POST https://www.suno-api.io/api/voice/clone/tasks/123/check \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

任務可用時回應中的 is_available 為 true，並回傳 voice_id。

6. 刪除人聲

介面位址: DELETE /api/voice/clone/voices/{voice_task_id}

計費: 免費。

curl -X DELETE https://www.suno-api.io/api/voice/clone/voices/123 \
  -H "Authorization: Bearer YOUR_API_KEY"

回應範例

{
  "success": true,
  "message": "",
  "data": {
    "voice_task_id": 123,
    "deleted": true
  }
}

刪除之後會怎樣

• 不能再拿來生成新歌：繼續拿這個 voice_task_id（或它的 voice_id）呼叫 POST /api/music/generate-with-voice 會被拒絕，錯誤訊息是 selected voice is not ready，不扣費。
• 已經用它生成的歌完全不受影響：播放、下載、續寫、替換、分軌都照舊。
• 這條人聲任務會從查詢裡消失：GET /api/voice/clone/tasks/{voice_task_id} 回傳 record not found。
• 來源音訊按平台的永久保留策略保留（2026-09-23 起，刪除不會再清理你上傳的那段人聲素材），但這不等於可以恢復：舊的這條任務已經終止，想繼續用同一個聲音，需要重新走一遍複製流程，會拿到新的 voice_task_id。
• 重複刪除：對同一條任務再刪一次回傳 record not found（它已經是刪除態，查不到了）。

7. 使用已複製人聲生成歌曲

介面位址: POST /api/music/generate-with-voice

計費: 1.2 元/次。

Body 參數

支援 suno-v6、suno-v6-wild 和 suno-v6-mini；空模型按 suno-v6 處理。舊的 V5/V5.5 模型已下線，但歷史任務可能仍顯示舊模型名。

共享請求結構還能解析 task、soundType、soundLoop、soundBpm、soundKey、voiceTaskId、voiceId 等 Create UI 相容欄位，但它們不是本介面的有效客戶參數：聲音任務必須傳 voice_task_id，可選聲音校驗必須傳 voice_id，聲音音樂生成不會讀取 sound 欄位。

生成參數填寫說明

• customMode=false 時，prompt 填歌曲描述；customMode=true 時，prompt 填完整歌詞，style 和 title 也必須填寫。不要把「歌詞」誤傳到靈感模式的描述欄位，或把歌曲描述當作進階模式歌詞。
• weirdnessConstraint 和 styleWeight 都是 0.0 到 1.0 的比例小數，不能填寫 50 或 50%。一般可用 0.5 作為均衡值；省略表示不指定，0 則是有效的顯式值。
• vocalGender 只能使用 m、male、f 或 female。instrumental 在本介面中僅為相容欄位，複製聲音生成固定按人聲歌曲處理。
• waitAudio 在本介面中不會改變行為，介面固定非同步回傳佔位任務。初始結果中的 audio_url 為空是正常現象，請使用 client_request_id 查詢，直到結果完成後再讀取音訊位址。

Header 參數

Idempotency-Key 行為：

• 首次請求在計費前寫入持久冪等記錄；
• 相同 Key、相同請求已完成時，重放第一次的接收回應，不重複計費或建任務；
• 相同 Key、不同請求體會被拒絕；
• 相同 Key 仍在處理中時回傳穩定的處理中錯誤，並且只在已生成時回傳安全的 client_request_id；
• 相同 Key 的首次請求失敗後保持失敗狀態，重試必須換新 Key。

sourceClipId 翻唱條件

客戶 API 的來源翻唱由伺服器統一處理來源歌曲存取，不需要客戶傳遞任何帳號資訊。是否可用以介面實際回應為準。

來源必須屬於當前 API 使用者，是已完成、非 pending: 的工作區歌曲，並有可用音訊。支援普通生成、普通上傳來源和強化上傳最終歌曲；強化上傳中間記錄會在計費前拒絕。伺服器只接受客戶提交的來源歌曲 ID，不接受客戶傳帳號 ID；來源不可用或未完成時會在計費前回傳錯誤。

請求範例

curl -X POST https://www.suno-api.io/api/music/generate-with-voice \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_task_id": 123,
    "customMode": true,
    "prompt": "寫一首關於夏夜海邊的中文流行歌曲",
    "style": "Mandopop, warm piano, emotional",
    "title": "夏夜海風",
    "negativeTags": "noise, low quality",
    "instrumental": false,
    "model": "suno-v6"
  }'

回應範例

{
  "success": true,
  "message": "",
  "data": {
    "client_request_id": "cu_1780480000_abcd1234",
    "items": [
      {
        "placeholder_id": "pending:cu_1780480000_abcd1234:0",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 0,
        "status": "submitted",
        "type": "voice_generate",
        "title": "夏夜海風",
        "prompt": "寫一首關於夏夜海邊的中文流行歌曲"
      },
      {
        "placeholder_id": "pending:cu_1780480000_abcd1234:1",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 1,
        "status": "submitted",
        "type": "voice_generate",
        "title": "夏夜海風",
        "prompt": "寫一首關於夏夜海邊的中文流行歌曲"
      }
    ],
    "pre_consumed_quota": 600000,
    "billing_source": "wallet"
  }
}

關於佔位任務和最終 song_id

generate-with-voice 是非同步生成介面。介面回傳成功只表示生成任務已經提交，不表示歌曲已經生成完成。

回應中的關鍵欄位含義：

注意：pending: 開頭的 placeholder_id 不能作為最終 song_id 使用，也不能直接用於 /api/music/query 或下載介面。只用 pending:* 呼叫 /api/music/query 時，可能會回傳空陣列 []，這是因為真實歌曲還沒有完成，或佔位任務還沒有替換成最終歌曲 ID。

錯誤範例：

{
  "song_ids": "pending:cu_1780480000_abcd1234:0"
}

正確流程：

1. 呼叫 POST /api/music/generate-with-voice 提交人聲生成音樂任務。
2. 保存回應裡的 client_request_id、items[].placeholder_id 和 items[].client_request_index。
3. 輪詢 GET /api/music/generate-with-voice/results?client_request_id=cu_xxx。
4. 等回應裡的 items[].song_id 有值且不以 pending: 開頭後，再呼叫 /api/music/query、/api/music/download-file 或 /api/music/download-all。

當前版本已新增公開查詢介面：

GET /api/music/generate-with-voice/results?client_request_id=cu_xxx

它回傳當前使用者下同一個 client_request_id 對應的任務結果，適合客戶自助查詢最終 song_id。回傳列表裡：

• song_id 是真實歌曲 ID；
• placeholder_id 僅在任務仍處於佔位狀態時出現；
• pending: 開頭的值不能用於 /api/music/query 或下載介面。

若你只保存了 client_request_id 或 pending:* 佔位 ID，可以先呼叫這個結果介面查詢；如果還沒查到真實 song_id，再把 client_request_id 發給技術支援協助定位。

查詢人聲生成音樂結果

介面位址: GET /api/music/generate-with-voice/results

計費: 免費。

Query 參數

請求範例

curl -X GET "https://www.suno-api.io/api/music/generate-with-voice/results?client_request_id=cu_1780480000_abcd1234" \
  -H "Authorization: Bearer YOUR_API_KEY"

生成中回應範例

{
  "success": true,
  "message": "",
  "data": {
    "client_request_id": "cu_1780480000_abcd1234",
    "status": "processing",
    "items": [
      {
        "song_id": "",
        "placeholder_id": "pending:cu_1780480000_abcd1234:0",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 0,
        "status": "processing",
        "type": "voice_generate",
        "title": "夏夜海風"
      }
    ]
  }
}

生成完成回應範例

{
  "success": true,
  "message": "",
  "data": {
    "client_request_id": "cu_1780480000_abcd1234",
    "status": "completed",
    "items": [
      {
        "song_id": "song_abc123",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 0,
        "status": "completed",
        "type": "voice_generate",
        "title": "夏夜海風",
        "audio_url": "https://...",
        "image_url": "https://...",
        "duration": 180.5
      }
    ]
  }
}

頂層 status 含義

8. 下載單一檔案

介面位址: POST /api/music/download-file

Body 參數

請求範例

curl -X POST https://www.suno-api.io/api/music/download-file \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "song_abc123",
    "kind": "audio"
  }' \
  --output song.mp3

回應為檔案串流，Content-Type 和檔名以後端回傳為準。

9. 打包下載歌曲資源

介面位址: POST /api/music/download-all

Body 參數

請求範例

curl -X POST https://www.suno-api.io/api/music/download-all \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "song_abc123"
  }' \
  --output song.zip

打包檔案通常包含音訊、封面和 metadata.json；如果某類資源暫未生成，則不會放入壓縮包。

常見錯誤

本組介面的錯誤統一回傳 HTTP 200：請以回應體裡的 success 欄位判斷成敗（false 即失敗，原因見 message），不要只看 HTTP 狀態碼。 刪除人聲的完整語意（刪除後還能不能用、能不能恢復）見第 6 節。