风格翻唱
- 用另一种风格重新演绎已有歌曲，异步任务
- 保留原曲结构，换掉演唱与编曲风格
- 用
task_id加audio_index引用源曲
认证
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引用源曲
生成源音轨那次任务的标识。缺失或无法解析源音轨时，提交阶段直接返回 400。
指定源任务结果数组 data.result.music[] 中取第几首，默认 1。一次生成一般产出 2 首。
The identifier of the task that produced the source track. When it's missing or the source can't be resolved, submission returns a 400.
Which track to take from the source task's result array data.result.music[], default 1. A single generation usually produces 2.
模式推断规则
custom 不传时会按内容自动推断，规则如下：
| 情况 | 推断结果 |
|---|---|
有 prompt | true |
无 prompt 但有 gpt_description | false |
都没有，但有 tags 或 title | true |
传了 tags | 自动按 true 处理 |
custom: false 时如果没给 gpt_description，提交阶段就返回 400 且不扣费。灵感模式下这个字段是条件必填的。
When custom is omitted, it's inferred from the content:
| Situation | Inferred value |
|---|---|
prompt present | true |
No prompt but gpt_description present | false |
Neither, but tags or title present | true |
tags passed | Treated as true automatically |
With custom: false, if gpt_description isn't given, submission returns a 400 with no charge. In inspiration mode that field is conditionally required.
请求参数
音频模型，默认 suno，当前只有这一个取值。
公共模型版本，取值 v6（默认）、v6-wild、v6-mini。若使用 custom_model_id 则不要传本字段。
自定义模型标识，与 version、persona_id 互斥。
true 为自定义模式，用 prompt 作歌词；false 为灵感模式，用 gpt_description。不传时按上表推断。
歌词内容，仅在 custom: true 时生效。灵感模式下被忽略。
灵感提示词，custom: false 时必填。
歌曲标题，仅 custom: true 时生效。
目标风格标签，通常逗号分隔。仅 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。两种模式均生效。
Persona 风格标识，仅 custom: true 时生效，与 custom_model_id 互斥。
目标时长，取值 10 到 360 秒。仅 custom: true 可用，实际时长以结果为准。
风格变化程度，取值 off、normal、high、extra、max。可省略。
启用 Max 模式，默认 false。要求自定义模式，按普通售价的 2 倍计费。
输出音频格式，取值 mp3、m4a、wav。
The audio model; defaults to suno, currently the only value.
The public model version: v6 (default), v6-wild, or v6-mini. If using custom_model_id, don't pass this field.
The custom model identifier; mutually exclusive with version and persona_id.
true is custom mode, with prompt as lyrics; false is inspiration mode, using gpt_description. When omitted, inferred per the table above.
Lyrics content, effective only with custom: true. Ignored in inspiration mode.
The inspiration prompt; required when custom: false.
The song title; effective only with custom: true.
Target style tags, usually comma-separated. Effective only with custom: true. Passing them makes the system treat custom as true automatically.
Styles 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 field name was weirdness_constraint; 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.
The Persona style identifier; effective only with custom: true, and mutually exclusive with custom_model_id.
Target duration, 10 to 360 seconds. Available only with custom: true; the actual duration follows the result.
Degree of style variation: off, normal, high, extra, max. May be omitted.
Enables Max mode; defaults to false. Requires custom mode; billed at 2× the regular price.
Output audio format: mp3, m4a, or wav.
响应
响应状态码，成功为 200。
提交成功为 submitted。
任务唯一标识，用于轮询 GET /v1/music/tasks/{task_id}。
轮询时 status 取 pending、processing、completed、failed，progress 是 0 到 100 的整数但不保证按固定节点变化。完成后从 data.result.music[].audio_url 取音频地址。失败时 data.error.message 给出原因，并自动退回预扣额度。
The response status code; 200 on success.
submitted on successful submission.
The unique task identifier, used to poll GET /v1/music/tasks/{task_id}.
During polling status is pending, processing, completed, or failed, and progress is an integer from 0 to 100 that isn't guaranteed to change on fixed steps. On completion, take the audio URL from data.result.music[].audio_url. On failure, data.error.message gives the reason and the held balance is refunded automatically.
怎么描述目标风格
tags 传的是目标风格，不是原曲风格。写的时候按「乐器 + 人声 + 氛围」三层组合：
acoustic guitar, female vocal, intimate, slow比只写一个 folk 效果好得多。乐器定骨架，人声定呈现，氛围定情绪。
tags describes the target style, not the original's. Write it as a three-layer combination of "instruments + vocals + atmosphere":
acoustic guitar, female vocal, intimate, slowFar more effective than a single folk. Instruments set the skeleton, vocals set the delivery, atmosphere sets the mood.
错误
| HTTP | type | 说明 |
|---|---|---|
| 400 | invalid_request_error | 请求参数无效，或 custom: false 时缺 gpt_description |
| 401 | authentication_error | 身份验证失败 |
| 402 | payment_required | 账户余额不足 |
| 429 | rate_limit_error | 请求过于频繁 |
| HTTP | type | Notes |
|---|---|---|
| 400 | invalid_request_error | Invalid request parameters, or gpt_description missing with custom: false |
| 401 | authentication_error | Authentication failed |
| 402 | payment_required | Insufficient account balance |
| 429 | rate_limit_error | Too many requests |
For more 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.