裁剪音频
- 按时间区间裁剪已有歌曲，异步任务
- 只保留
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引用源音轨
产出源音轨那次任务的标识。缺失或无法解析源音轨时，提交阶段即返回 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 in the source task's data.result.music[], default 1. A single generation usually contains 2.
裁剪区间
裁剪起点，单位秒，不小于 0。支持小数。
裁剪终点，单位秒。须大于 start_s，且不超过已知源时长。支持小数。
音频模型，默认 suno，当前仅 suno。
本端点没有版本维度，传 version 会被丢弃，也不影响计费。
Crop start in seconds, no less than 0. Fractions allowed.
Crop end in seconds. Must be greater than start_s and no longer than the known source duration. Fractions allowed.
The audio model; defaults to suno, currently the only one.
This endpoint has no version dimension; passing version is discarded and doesn't affect billing.
响应
响应状态码。
任务状态，取值 submitted。
任务唯一标识，用于轮询结果查询接口。
轮询用 GET /v1/music/tasks/{task_id}，间隔 3 到 5 秒，直到 status 为 completed 或 failed。典型耗时 30 到 120 秒。
中间状态为 pending 与 processing。progress 是 0 到 100 的整数，变化节点不固定。
完成后音频地址在 data.result.music[].audio_url。失败原因见 data.error.message，预扣额度自动退回。
The response status code.
The task status: submitted.
The unique task identifier, used to poll the result query endpoint.
Poll with GET /v1/music/tasks/{task_id} every 3 to 5 seconds until status is completed or failed. Typical duration is 30 to 120 seconds.
Intermediate states are pending and processing. progress is an integer from 0 to 100 that doesn't change on fixed steps.
On completion the audio URL is at data.result.music[].audio_url. The failure reason is in data.error.message, and the held balance is refunded automatically.
典型用途
| 用途 | 区间写法 |
|---|---|
| 截取副歌做铃声 | start_s 到副歌起点，end_s 到副歌结束 |
| 去掉前奏 | start_s 设为前奏结束时间 |
| 去掉结尾静音 | end_s 设为最后一个音结束的时间 |
| 取 30 秒试听片段 | 起点任意，end_s = start_s + 30 |
end_s 的上界是源音频的实际时长。想让「一直裁到结尾」也做不到，必须给一个具体数值。先查一次源任务的 duration 再决定。
裁剪会重新编码，反复裁剪同一段会累积音质损失。需要多次调整时，每次都从原始版本重新裁，不要在前一次的输出上再裁。
| Use | How to set the range |
|---|---|
| Cut the chorus for a ringtone | start_s at the chorus start, end_s at its end |
| Drop the intro | Set start_s to where the intro ends |
| Drop trailing silence | Set end_s to where the last note ends |
| Take a 30-second preview | Any start, with end_s = start_s + 30 |
The upper bound of end_s is the source audio's actual duration. "Crop through to the end" isn't possible either — you must give a concrete value. Query the source task's duration first.
Cropping re-encodes, so repeated crops of the same segment accumulate quality loss. When adjusting several times, always crop from the original version, not from the previous output.
错误码
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.