文档 / 音乐系列 / Suno / 辅助功能
裁剪音频片段
裁剪或移除已生成 clip 的指定时间区间。
用途#
提交一个 裁剪（CROP） 任务，对本服务已生成的 clip 做裁剪处理，生成一个新的 clip。接口为异步模式：服务在校验通过后立即返回公开 task_id，不会等待任务完成。后续通过 GET /v1/tasks/:id 轮询任务状态与结果。
CROP 基于源 clip_id 与裁剪区间 crop_start_s / crop_end_s 工作：它不重新生成音乐，而是对已有 clip 的音频按时间区间做裁剪。通过 is_crop_remove 可选择保留该区间或移除该区间。clip_id 必须来自本服务已生成的任务结果。
CROP 需要 clip_id、crop_start_s 和 crop_end_s；is_crop_remove、title 和 callback_url 为可选字段。
请求字段#
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
clip_id | string | 是 | — | 目标 Suno clip 的 UUID，须来自本服务已生成的任务结果 |
crop_start_s | number | 是 | — | 裁剪起点，单位秒，需 >= 0 |
crop_end_s | number | 是 | — | 裁剪终点，单位秒，需严格大于 crop_start_s |
is_crop_remove | bool | 否 | false | true 表示移除该区间；false 表示保留该区间 |
title | string | 否 | — | 新 clip 标题，留空时自动生成 |
callback_url | string | 否 | — | 任务到达终态时的回调通知地址 |
clip_id、crop_start_s、crop_end_s 均为必填：
- clip_id 为空返回 clip_id_empty。
- crop_start_s 或 crop_end_s 任一未传返回 crop_range_empty（显式传 0 视为已设置，保留显式零值语义）。
- crop_end_s 必须严格大于 crop_start_s，否则返回 crop_range_invalid。
callback_url 必须是公网可访问的 HTTPS 地址，长度不超过 2048 字符；禁止使用本机、内网、回环、链路本地地址，也禁止使用解析到这些地址的域名。
任务完成或失败后，服务会向该地址发送 POST JSON。回调接收端须在 10 秒内返回任意 2xx 状态码；超时、网络错误或非 2xx 响应均视为失败。
失败后会分别等待 1 秒、2 秒和 4 秒重试，连同首次请求最多发送 4 次。接收端应使用任务 ID 做幂等处理，避免重复处理。
请求示例#
curl --request POST \
--url https://api.apimax.ai/v1/music/crop \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"clip_id": "1f78f8de-4ca6-4375-ae79-46c33a2c97f7",
"crop_start_s": 10.0,
"crop_end_s": 45.0,
"is_crop_remove": false,
"title": "Edited Version"
}'成功响应#
{
"code": "success",
"message": "",
"data": "task_01HV7..."
}响应字段#
| 字段 | 类型 | 说明 |
|---|---|---|
code | string | 响应码，成功固定为 success |
message | string | 提示信息，成功时通常为空 |
data | string | 公开任务 ID（40 字符以内），用于后续查询 |
data 返回公开 task_id，所有后续查询均使用该 ID。
错误码#
| HTTP | code | 场景 |
|---|---|---|
| 400 | clip_id_empty | clip_id 为空，未指定目标 clip |
| 400 | crop_range_empty | crop_start_s 或 crop_end_s 未传 |
| 400 | crop_range_invalid | crop_end_s 未严格大于 crop_start_s |
| 400 | invalid_request | 请求体 JSON 解析失败 |
| 400 | invalid_action | action 不在支持列表内 |
| 503 | no_available_channel | 无可用渠道 |
| 502 | upstream_failed | 任务处理服务请求失败（网络错误等） |
源 clip 不存在或不可用时会返回对应错误。
查询任务结果#
提交成功后，使用返回的 task_id 轮询：
- 单个查询：
GET /v1/tasks/:id
status 枚举#
| 值 | 说明 |
|---|---|
queued | 任务已创建，等待处理 |
in_progress | 任务正在处理 |
completed | 任务处理完成，可读取 data |
failed | 任务处理失败，可读取 error |
completed 和 failed 为终态；其余状态请继续轮询。
查询结果中的 data 字段包含裁剪生成的新 clip，包括音频地址等信息。
{
"id": "task_BnZc0kcMPDFdSj8Gu3dwexpzFTbFbsKR",
"model": "suno_crop",
"object": "task",
"platform": "suno",
"type": "suno",
"status": "completed",
"progress": 100,
"created_at": 1783072521,
"started_at": 1783072522,
"finished_at": 1783072537,
"data": [
{
"id": "task_BnZc0kcMPDFdSj8Gu3dwexpzFTbFbsKR",
"status": "complete",
"title": "Journey's Call",
"audio_url": "https://cdn1.suno.ai/c130155f-f5e6-4c62-9eee-e0bc95ebc13f.mp3",
"image_url": "https://cdn2.suno.ai/image_c130155f-f5e6-4c62-9eee-e0bc95ebc13f.jpeg",
"created_at": "2026-07-03T09:55:29.362Z",
"metadata": {
"type": "edit_crop",
"duration": 100.8,
"edited_clip_id": "e30bf56e-f978-47ac-98b6-ef54cab07679",
"is_remix": true,
"tags": "mandopop, upbeat, acoustic guitar, light percussion",
"prompt": "[Verse]
背包装满梦想
...
[Chorus]
走吧走吧
世界那么大
..."
}
}
]
}data[] 为裁剪生成的新 clip 数组：audio_url / image_url 为结果音频与封面地址，metadata.type 为 edit_crop，metadata.edited_clip_id 指向源 clip，duration 为新片段时长（秒）。字段名与结构以实际响应为准。