样本转歌曲
- 用一段音频样本扩展成完整歌曲，异步任务
- 源音轨必须来自上传接口
- 用
start_s与end_s框出采样区间
认证
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引用源音轨
产出源音轨的那次任务的 ID。必须是 uploadTask 上传任务，否则提交期返回 400。
引用源任务 data.result.music[] 中的第几首，默认 1，从 1 开始。一次生成通常 2 首。
The ID of the task that produced the source track. It must be an uploadTask upload task, or submission returns a 400.
Which track in the source task's data.result.music[], default 1, starting at 1. A single generation usually has 2.
采样区间
采样起点，单位秒。缺失即 400。
采样终点，单位秒。须满足 0 ≤ start_s < end_s，源时长已知时不能越界。
Sample start in seconds. Missing means a 400.
Sample end in seconds. Must satisfy 0 ≤ start_s < end_s, and mustn't exceed the source duration when it's known.
生成参数
true 为纯器乐、无人声，默认 false。
音频模型，默认 suno。
可选 v6（默认）、v6-wild、v6-mini。与 custom_model_id 互斥。
自建模型任务返回的完整 UUID，与 version 互斥。
true 为自定义模式（prompt 当歌词）；false 为灵感模式（用 gpt_description）。不传则后端按内容推断。
custom=true 且 instrumental=false 时必须给歌词。
灵感模式下不生效，但提交的值仍须满足长度要求。
灵感提示词。custom=false 时必填，缺失则提交期 400 且不扣费。
标题，仅 custom=true 生效。
风格标签，仅 custom=true 生效。
要排除的风格标签，仅 custom=true 生效。
true 表示对输入歌词二次创作，仅 custom=true 生效。
取值 0.00 到 1.00，越界直接 400，仅 custom=true 生效。
创意权重，0.00 到 1.00。兼容旧名 weirdness_constraint。
0.00 到 1.00，仅 custom=true 生效。
Male 或 Female，两种模式都生效。
风格变化程度：off、normal、high、extra、max。
Max 模式，默认 false。要求自定义模式，按普通售价 2 倍计费。
输出格式 mp3、m4a、wav。本接口无目标时长字段。
true for instrumental only, no vocals; defaults to false.
The audio model; defaults to suno.
v6 (default), v6-wild, or v6-mini. Mutually exclusive with custom_model_id.
The full UUID returned by a custom model creation task; mutually exclusive with version.
true is custom mode (prompt as lyrics); false is inspiration mode (using gpt_description). When omitted, the backend infers it from the content.
Lyrics are required when custom=true and instrumental=false.
Takes no effect in inspiration mode, but the submitted value must still meet length limits.
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.
true reworks the supplied lyrics; effective only with custom=true.
0.00 to 1.00; out of range returns a 400; effective only with custom=true.
Creativity weight, 0.00 to 1.00. The old name weirdness_constraint is supported.
0.00 to 1.00; effective only with custom=true.
Male or Female; effective in both modes.
Degree of style variation: off, normal, high, extra, max.
Max mode; defaults to false. Requires custom mode; billed at 2× the regular price.
Output format mp3, m4a, or wav. This endpoint has no target duration field.
响应
响应状态码。
任务状态，提交成功为 submitted。
任务唯一标识，用于轮询结果。
The response status code.
The task status; submitted on successful submission.
The unique task identifier, used to poll for the result.
取结果
轮询 GET /v1/music/tasks/{task_id}，间隔 3 到 5 秒，直到状态为 completed 或 failed。
取值 pending、processing、completed、failed。
0 到 100 的整数，不保证按固定节点变化。
完成后从中取生成的音频地址。
失败原因。预扣额度自动退回。
Poll GET /v1/music/tasks/{task_id} every 3 to 5 seconds until the status is completed or failed.
pending, processing, completed, or failed.
An integer from 0 to 100 that isn't guaranteed to change on fixed steps.
On completion, the generated audio URL.
The failure reason. The held balance is refunded automatically.
采样技巧
采样区间决定了模型能听到多少「素材」：
| 采样长度 | 效果 |
|---|---|
| 3 秒以内 | 只能抓到一小段动机，成品与原素材关联很弱 |
| 5 到 15 秒 | 最常用，能抓住旋律与音色特征 |
| 30 秒以上 | 更接近改编，成品会明显带有原曲影子 |
采样区间是从上传的源音频里取，不是从生成结果里取。所以 task_id 必须是 uploadTask 的产物。
The sample range determines how much "material" the model hears:
| Sample length | Effect |
|---|---|
| Under 3 seconds | Only a small motif is captured; the result barely relates to the source |
| 5 to 15 seconds | The most common choice; captures melody and timbre |
| Over 30 seconds | Closer to a remix; the result clearly bears the original's mark |
The sample range is taken from the uploaded source audio, not from a generation result. That's why task_id must be an uploadTask product.
错误码
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.