【推荐】克隆音色 API

更新于 2026-09-15 · Suno-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" } }

• 删除是软删除：音色从列表消失、不能再用于新的翻唱，但源音频永久保留，也不影响已经用它生成过的歌。
• 删除不存在的音色（或不是你的）返回 {"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": "【任务】这是一次翻唱。…（服务端固定结构段 + 你填写的翻唱/风格要求）",
        "download_policy": { "download_disabled": false, "known": true }
      },
      {
        "song_id": "7c91…",
        "status": "processing",
        "model_version": "suno-v6",
        "audio_url": "",
        "download_policy": { "download_disabled": false, "known": true }
      }
    ],
    "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. download_policy.download_disabled === true 表示该成品禁止下载（翻唱素材含他人作品时上游会禁止下载与商用）。known=false 表示上游未表态，按不限制处理。
5. download_policy 只出现在提交响应里，不落库——需要持久化的话请客户端自己保存（按 song_id 记录）。
6. source_updates 是服务端的素材处理结果，客户端可忽略。
7. 你传的 title 会写进服务端任务记录，在后续查询里体现为 song_title；提交回包的 clips[].song_title 通常为空，属正常。

6.4 错误

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

余额不足会在提交阶段直接返回计费错误，不会产生半成品任务。

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。 响应直接是文件字节流，Content-Type 与 Content-Disposition（文件名）都已带好；GET /api/music/songs/{song_id} 返回的 wav_url / video_url 就是带上 kind=wav|video 的同一入口。

先检查 download_policy.download_disabled：为 true 时不要尝试下载（上游禁止），请给自己的用户展示对应提示。

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. 下载限制：翻唱素材含他人作品时，该成品可能被上游禁止下载（download_policy.download_disabled=true），请按此提示用户。
10. 请求超时：冷账号首次提交最慢实测约 4 分半，客户端超时请设 ≥ 6 分钟。翻唱不做请求级去重，超时后请先核对是否已经产生新歌（§1.5），再决定是否重发。
11. 音色归属：音色按创建者归属管理；翻唱只接受已就绪的音色（ready），不存在 / 已删除会直接报 voice not found。

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 秒；不传则由上游按原曲 / 素材自动决定。

附录 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, download_policy }] }
}

// ③ 轮询到完成（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：变更记录