添加伴奏
- 在已有的人声或音轨上叠加伴奏，异步任务
- 源音轨必须来自上传接口
- 常用于清唱配伴奏的场景
认证
All endpoints authenticate with a Bearer token.
Get an API key: open the console and create one.
Add it to the request header:
Authorization: Bearer YOUR_OAIRoute_KEY引用源音轨
必须是由 uploadTask 上传接口返回的任务 ID。普通生成任务不能用。
缺失或无法解析源时，提交阶段直接返回 400。
指定 data.result.music[] 中第几首源音轨，默认 1，从 1 开始计数。一次生成通常有 2 首。
Must be the task ID returned by the uploadTask upload endpoint. Regular generation tasks won't work.
When it's missing or the source can't be resolved, submission returns a 400 straight away.
Which track in data.result.music[], default 1, counting from 1. A single generation usually has 2.
生成参数
音频模型，当前固定 suno。
公共版本，默认 v6，可选 v6-wild、v6-mini。如果使用 custom_model_id，不要传这个字段。
创建模型任务时返回的完整 UUID。与 version 互斥，二者只能选一个。
true 为自定义模式（prompt 作歌词）；false 为灵感模式（用 gpt_description）。
不传时按内容推断：有 prompt 则 true；无 prompt 但有 gpt_description 则 false；否则有 tags 或 title 就是 true。
歌词内容，仅 custom=true 时生效，灵感模式下被忽略。
灵感提示词。custom=false 时必填，缺失在提交阶段返回 400 且不扣费。
标题，仅 custom=true 时生效。
风格标签，仅 custom=true 时生效。
需排除的风格标签，仅 custom=true 时生效。
风格权重，0.00 到 1.00。越界在提交阶段返回 400，仅 custom=true 时生效。
创意权重，0.00 到 1.00。兼容旧名 weirdness_constraint，新请求建议用 weirdness。
音频权重，0.00 到 1.00，仅 custom=true 时生效。
人声性别，取值 Male 或 Female，两种模式都生效。
风格变化程度，取值 off、normal、high、extra、max。
启用 Max 模式，默认 false。要求同时使用自定义模式，按普通价格的 2 倍计费。
输出音频格式，mp3、m4a 或 wav。
The audio model; currently always suno.
The public version; defaults to v6, with v6-wild and v6-mini available. If you use custom_model_id, don't pass this field.
The full UUID returned by a model creation task. Mutually exclusive with version; pick one.
true is custom mode (prompt as lyrics); false is inspiration mode (using gpt_description).
When omitted it's inferred from the content: prompt present means true; no prompt but gpt_description present means false; otherwise tags or title present means true.
The lyrics content; effective only with custom=true, ignored in inspiration mode.
The inspiration prompt. Required when custom=false; missing returns a 400 at submission with no charge.
The title; effective only with custom=true.
Style tags; effective only with custom=true.
Style tags to exclude; effective only with custom=true.
Style weight, 0.00 to 1.00. Out of range returns a 400 at submission; effective only with custom=true.
Creativity weight, 0.00 to 1.00. The old name weirdness_constraint is supported, but new requests should use weirdness.
Audio weight, 0.00 to 1.00; effective only with custom=true.
Vocal gender, Male or Female; effective in both modes.
Degree of style variation: off, normal, high, extra, max.
Enables Max mode; defaults to false. Requires custom mode as well; billed at 2× the regular price.
Output audio format: mp3, m4a, or wav.
不支持的字段
auto_lyrics、persona_id、instrumental、目标时长字段都不支持。
auto_lyrics, persona_id, instrumental, and target duration fields are all unsupported.
响应
响应状态码。
提交成功时为 submitted。
任务唯一标识，用于轮询 GET /v1/music/tasks/{task_id}。
The response status code.
submitted on successful submission.
The unique task identifier, used to poll GET /v1/music/tasks/{task_id}.
取结果
轮询间隔 3 到 5 秒，status 变为 completed 或 failed 即结束，通常需要 30 到 120 秒。
轮询期间 status 可能为 pending 或 processing，progress 是 0 到 100 的整数且变化节点不固定。完成后从 data.result.music[].audio_url 取音频地址。失败原因见 data.error.message，预扣额度会自动退回。
Poll every 3 to 5 seconds; it ends when status becomes completed or failed, usually taking 30 to 120 seconds.
During polling status may be pending or processing, and progress is an integer from 0 to 100 that doesn't change on fixed steps. On completion, take the audio URL from data.result.music[].audio_url. The failure reason is in data.error.message, and the held balance is refunded automatically.
与「添加人声」的对照
| 项目 | 添加人声 | 添加伴奏 |
|---|---|---|
| 路径 | addVocals | addInstrumental |
| 输入 | 纯伴奏 | 清唱或人声轨 |
| 输出 | 带演唱的完整歌曲 | 带伴奏的完整歌曲 |
| 源音轨要求 | 必须来自上传接口 | 必须来自上传接口 |
两个接口互为镜像，参数表完全一致。都是「给一条不完整的音轨补上缺的另一半」。
instrumental 字段在这里也不支持。想控制输出是否含人声，本接口的输出天然是带伴奏的完整混音，不含额外选项。
| Item | Add vocals | Add instrumental |
|---|---|---|
| Path | addVocals | addInstrumental |
| Input | Instrumental only | A cappella or a vocal track |
| Output | A complete song with vocals | A complete song with backing |
| Source track requirement | Must come from the upload endpoint | Must come from the upload endpoint |
The two endpoints mirror each other and share an identical parameter table. Both "supply the missing half of an incomplete track".
The instrumental field is unsupported here too. To control whether the output has vocals — this endpoint's output is inherently a complete mix with backing, with no extra options.
错误码
For error response formats, status codes, and retry guidance see Error codes and rate limits; for troubleshooting steps on common errors see the FAQ.
使用示例
提交一个任务并拿到 task_id：
提交成功只表示任务已受理。真正的产物要拿返回的 task_id 去任务查询接口轮询，status 变成 completed 之后才有结果。
Submit a task and get a task_id:
A successful submission only means the task was accepted. To get the actual output, poll the task query endpoint with the returned task_id; results appear only after status becomes completed.