人声克隆与指定人声生成 API

更新于 2026-09-15 · Suno-API 团队

新接入请先看【推荐】克隆音色 API。

【推荐】克隆音色 API 是新的音色链路：用一段人声样本创建音色（POST /api/music/voice-profile/create），再用它翻唱指定歌曲或演唱新歌。音色是一等资源，可以列表、查询、删除，且源音频永久保留。

本篇描述的是早期 persona（voice_task_id / generate-with-voice）链路，仍然可用；如果你的产品需要"创建音色 → 长期复用 → 翻唱"的完整闭环，请优先接新链路。

重要提示：克隆人声可能过期。

人声克隆生成的 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

计费:

• 人声校验、人声克隆、状态查询、删除、下载：免费。
• Create UI 登录态入口 POST /api/create-ui/voice/clone-long-term：固定 5 元/次，走内部 Suno 人声 API，并通过 MiniMax 自动合成验证音频；失败会退款。
• Create UI 普通克隆后的 POST /api/create-ui/voice/tasks/{voice_task_id}/auto-generate-verify：固定 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 后，可用下载接口下载单文件或打包文件。

Create UI 另有自动克隆快捷流程：用户在首次录音/上传源人声页点击“自动克隆 5元/次”，前端提交同一组源人声字段到 POST /api/create-ui/voice/clone-long-term。该接口沿用原长期版克隆流程，一次性完成内部校验、MiniMax 自动验证音频合成和内部人声生成，不要求用户再录制二次验证音频。

Create UI 不再暴露单独的“内部克隆”按钮；普通“开始克隆”继续调用通用 validate 入口，由服务端 provider 配置决定实际链路。POST /api/create-ui/voice/validate-internal 仍作为受控测试和排障接口保留。内部克隆产生的 voice task 后续生成歌曲时应按该任务自身的 provider=internal 分派，不能再依赖全局 SUNO_VOICE_PROVIDER。

人声任务字段

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"

响应示例

{
  "code": 200,
  "message": "success",
  "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"

响应示例

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

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；如果某类资源暂未生成，则不会放入压缩包。

常见错误

Staging Internal Voice Clone Full-Chain Acceptance

Date: 2026-07-13

The staging manual internal-clone flow completed successfully for the first confirmed full-chain acceptance after the persona image payload fix.

Verified result:

• Layer 3 voice task: 57
• Layer 3 user: user_id=1
• Voice name: 555
• Provider: internal
• Staging Suno account-pool id: acc_1776666970012 (账号4)
• Validation task: 270fab46-3e33-4e54-8dda-9f589b48536c
• Validation phrase: 音乐海浪伴我歌声入耳此刻安宁
• Returned voice/persona id: 668753de-a77a-4653-9fcd-c46651f09631
• Final state: status=ready, is_available=true
• The later availability synchronization updated the stage to availability_checked; the initial successful generation stage was internal_voice_ready.

Acceptance meaning:

• Source recording upload succeeded.
• A fresh verification phrase was issued.
• The real second recording was approved by Suno.
• Persona image generation/download/data-URL conversion succeeded.
• Voice persona creation returned a non-empty id.
• Layer 3 retained the owning staging account id and exposed the voice as available.

Do not record the account cookie, token, login credential, or full phone number in this document.