添加人声
- 给纯伴奏加上人声演唱，异步任务
- 源音轨必须来自上传接口，普通生成任务不能用
- 生成参数与「风格翻唱」同源
认证
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。普通生成任务的 ID 不可用。
缺失或无法解析源音轨时，提交阶段即失败。
引用源任务的第几首音轨，默认 1，从 1 开始。一次生成一般为 2 首。
这条限制与「添加伴奏」一致：源音轨必须先经过上传接口。直接拿生成任务的 task_id 过来会报错，因为人声叠加需要一条干净的伴奏作为基底。
Must be the ID returned by the uploadTask upload endpoint. IDs from regular generation tasks don't work.
When it's missing or the source track can't be resolved, submission fails immediately.
Which track of the source task, default 1, counting from 1. A single generation usually has 2.
The restriction matches "Add instrumental": the source track must first go through the upload endpoint. Handing over a generation task's task_id directly errors out, because layering vocals needs a clean instrumental as the base.
生成参数
音频模型，当前固定 suno。
公共版本，默认 v6，可选 v6-wild、v6-mini。与 custom_model_id 不能同时使用。
自定义模型的完整 UUID，与 version 互斥。
true 为自定义模式，false 为灵感模式。不传时按已提交字段推断。
歌词，仅自定义模式生效，灵感模式下忽略。
灵感提示词。custom 为 false 时必填，缺失在提交阶段返回 400 且不扣费。
标题，仅自定义模式生效。
风格标签，仅自定义模式生效。
要排除的风格标签，仅自定义模式生效。
风格权重，取值 0.00 到 1.00。越界返回 400，仅自定义模式生效。
创意度权重，取值 0.00 到 1.00。旧名 weirdness_constraint 仍兼容。
音频权重，取值 0.00 到 1.00，仅自定义模式生效。
人声性别，取值 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. Can't be used together with custom_model_id.
The custom model's full UUID; mutually exclusive with version.
true is custom mode, false is inspiration mode. When omitted, inferred from the submitted fields.
Lyrics; effective only in custom mode, ignored in inspiration mode.
The inspiration prompt. Required when custom is false; missing returns a 400 at submission with no charge.
The title; effective only in custom mode.
Style tags; effective only in custom mode.
Style tags to exclude; effective only in custom mode.
Style weight, 0.00 to 1.00. Out of range returns a 400; effective only in custom mode.
Creativity weight, 0.00 to 1.00. The old name weirdness_constraint is still supported.
Audio weight, 0.00 to 1.00; effective only in custom mode.
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; billed at 2× the regular price.
Output format: mp3, m4a, or wav.
不支持的字段
auto_lyrics、persona_id、instrumental、目标时长都不支持。
instrumental 在这里没有意义——本接口的目的就是加人声，传纯音乐标记会自相矛盾。
auto_lyrics, persona_id, instrumental, and target duration are all unsupported.
instrumental makes no sense here — this endpoint exists to add vocals, so passing the instrumental flag is self-contradictory.
响应
响应状态码。
提交成功为 submitted。
任务唯一标识，用于轮询任务详情。
轮询时 status 可能为 pending、processing、completed 或 failed。progress 是 0 到 100 的整数，变化节点不固定。完成后从 data.result.music[].audio_url 取音频。失败原因见 data.error.message，失败会自动退回预扣额度。
The response status code.
submitted on successful submission.
The unique task identifier, used to poll task details.
During polling, status may be pending, processing, completed, or failed. progress is an integer from 0 to 100 that doesn't change on fixed steps. On completion, take the audio from data.result.music[].audio_url. The failure reason is in data.error.message, and failures refund the held balance automatically.
完整流程
- 把伴奏放到公网可访问的地址
- 调「上传音频」拿
task_id - 等上传任务完成
- 用那个
task_id调本接口
- Host the instrumental at a publicly reachable address
- Call "Upload audio" to get a
task_id - Wait for the upload task to complete
- Call this endpoint with that
task_id
错误码
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.