段落替换
- 替换歌曲中的某一段，而不是删掉，异步任务
- 用新歌词填补指定区间，前后保持连贯
- 比「删除片段」更适合修补
认证
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。缺失或解析不到源时，提交阶段返回 400。
从源任务结果的 data.result.music[] 中选取第几首，默认 1，从 1 开始计数。一次生成通常为 1、2 两首。
The ID of the task the source track belongs to. Missing, or the source can't be resolved, returns a 400 at submission.
Which track to take from the source task's data.result.music[], default 1, counting from 1. A single generation usually yields tracks 1 and 2.
替换区间
替换起点，单位秒。缺失时返回 400。
替换终点，单位秒。需满足 0 ≤ start_s < end_s，且不能超出已知的源时长。
用于替换片段的新歌词。这是本接口的核心字段，写清楚这一段要唱什么。
Replacement start in seconds. Missing returns a 400.
Replacement end in seconds. Must satisfy 0 ≤ start_s < end_s and can't exceed the known source duration.
The new lyrics for the replaced stretch. This is the endpoint's core field — state clearly what this passage should sing.
生成参数
音频模型，默认 suno。
公共版本，默认 v6，可选 v6-wild、v6-mini。若使用 custom_model_id，则省略本字段。
创建自定义模型任务时返回的完整 UUID，不能与 version 同时使用。
原歌词上下文。把这一段前后各一句贴进来，模型能更好地衔接。
标题。
风格标签。
需要排除的风格标签。
风格变化程度，可选 off、normal、high、extra、max。
启用 Max 模式，默认 false。按普通售价的 2 倍计费。
输出格式，可选 mp3、m4a、wav。本接口没有目标时长字段。
The audio model; defaults to suno.
The public version; defaults to v6, with v6-wild and v6-mini available. Omit this field if using custom_model_id.
The full UUID returned by a custom model creation task; can't be used together with version.
The original lyrics context. Paste the line before and the line after, and the model joins up better.
The title.
Style tags.
Style tags to exclude.
Degree of style variation: off, normal, high, extra, max.
Enables Max mode; defaults to false. Billed at 2× the regular price.
Output format: mp3, m4a, or wav. This endpoint has no target duration field.
响应
响应状态码。
任务状态，提交成功时返回 submitted。
任务唯一标识，用于轮询 GET /v1/music/tasks/{task_id}。
The response status code.
The task status; submitted on successful submission.
The unique task identifier, used to poll GET /v1/music/tasks/{task_id}.
取结果
轮询时 status 可能为 pending、processing、completed 或 failed。progress 是 0 到 100 的整数，不保证按固定节点变化。
完成后从 data.result.music[].audio_url 取替换后的音频。失败时 data.error.message 给出原因，预扣额度自动退回。生成通常需要 30 到 120 秒。
During polling status may be pending, processing, completed, or failed. progress is an integer from 0 to 100 and isn't guaranteed to change on fixed steps.
On completion, take the replaced audio from data.result.music[].audio_url. On failure, data.error.message gives the reason and the held balance is refunded automatically. Generation usually takes 30 to 120 seconds.
与删除片段的对照
| 项目 | 删除片段 | 段落替换 |
|---|---|---|
| 路径 | removeSection | replaceMusic |
| 效果 | 区间被去掉，前后直接接 | 区间被新内容填上 |
| 接缝 | 可能突兀 | 相对自然 |
| 关键字段 | start_s、end_s | 再加 infill_lyrics |
修一段唱错的词、换掉一段不满意的副歌，用替换。整段多余的内容，用删除。
prompt 传的是原歌词上下文，不是新歌词。新歌词放 infill_lyrics。两个字段搞反是很常见的错误，表现为替换后唱的完全是另一段内容。
| Item | Remove section | Replace section |
|---|---|---|
| Path | removeSection | replaceMusic |
| Effect | The range is cut, the sides joined | The range is filled with new content |
| Seam | Possibly abrupt | Relatively natural |
| Key fields | start_s, end_s | Plus infill_lyrics |
Use replace to fix a mis-sung line or swap out a chorus you don't like. Use remove for a stretch that's simply excess.
prompt carries the original lyrics context, not the new lyrics. The new lyrics go in infill_lyrics. Mixing the two up is a common mistake, showing up as the replacement singing a completely different passage.
错误码
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.