# 裁剪音频
> 按时间区间裁剪已有歌曲，异步任务
> 只保留 `start_s` 到 `end_s` 之间的部分
> 支持小数秒，可精确到毫秒级
`POST /v1/music/generations/crop`
## 认证
- `Authorization` (string / 必填) — 所有接口均使用 Bearer Token 进行认证。 获取 API Key：[访问控制台](https://api.oairoute.com/keys) 创建。 请求时在请求头中添加： ```http Authorization: Bearer YOUR_OAIRoute_KEY ```
## 引用源音轨
- `task_id` (string / 必填) — 产出源音轨那次任务的标识。缺失或无法解析源音轨时，提交阶段即返回 400。
- `audio_index` (integer / 可选) — 指定源任务结果 `data.result.music[]` 中的第几首，默认 `1`。一次生成一般含 2 首。
## 裁剪区间
- `start_s` (number / 必填) — 裁剪起点，单位秒，不小于 0。支持小数。
- `end_s` (number / 必填) — 裁剪终点，单位秒。须大于 `start_s`，且不超过已知源时长。支持小数。
- `model` (string / 可选) — 音频模型，默认 `suno`，当前仅 `suno`。
本端点没有版本维度，传 `version` 会被丢弃，也不影响计费。
## 响应
- `code` (integer) — 响应状态码。
- `data[].status` (string) — 任务状态，取值 `submitted`。
- `data[].task_id` (string) — 任务唯一标识，用于轮询结果查询接口。
轮询用 `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`，预扣额度自动退回。
## 典型用途
| 用途 | 区间写法 |
|---|---|
| 截取副歌做铃声 | `start_s` 到副歌起点，`end_s` 到副歌结束 |
| 去掉前奏 | `start_s` 设为前奏结束时间 |
| 去掉结尾静音 | `end_s` 设为最后一个音结束的时间 |
| 取 30 秒试听片段 | 起点任意，`end_s = start_s + 30` |
> **Note:** 
> `end_s` 的上界是源音频的实际时长。想让「一直裁到结尾」也做不到，必须给一个具体数值。先查一次源任务的 `duration` 再决定。
> **Note:** 
> 裁剪会重新编码，反复裁剪同一段会累积音质损失。需要多次调整时，每次都从原始版本重新裁，不要在前一次的输出上再裁。
## 错误码
错误响应的格式、状态码与重试建议见[错误码与限流](../../../support/errors.html)，常见报错的排查步骤见[常见问题](../../../support/faq.html)。
## 使用示例
提交一个任务并拿到 `task_id`：
> **Note:** 
> 提交成功只表示任务已受理。真正的产物要拿返回的 `task_id` 去任务查询接口轮询，`status` 变成 `completed` 之后才有结果。
**裁剪音频{Crop audio}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/music/generations/crop' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "suno",
    "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K",
    "audio_index": 1,
    "start_s": 62.5,
    "end_s": 92.5
  }'
```
**裁剪音频{Crop audio}::Python**
```
import requests
res = requests.post(
    "https://api.oairoute.com/v1/music/generations/crop",
    headers={
        "Authorization": "Bearer YOUR_OAIRoute_KEY",
        "Content-Type": "application/json",
    },
    json={
        "model": "suno",
        "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K",
        "audio_index": 1,
        "start_s": 62.5,
        "end_s": 92.5,
    },
)
print(res.json()["data"][0]["task_id"])
```
**裁剪音频{Crop audio}::JavaScript**
```
const url = "https://api.oairoute.com/v1/music/generations/crop";
const options = {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "suno",
    "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K",
    "audio_index": 1,
    "start_s": 62.5,
    "end_s": 92.5
  }),
};
fetch(url, options)
  .then((res) => res.json())
  .then((json) => console.log(json))
  .catch((err) => console.error(err));
```
**200 裁剪音频{Crop audio}**
```
{
  "code": 200,
  "data": [
    { "status": "submitted", "task_id": "task_01K8D00M0HP1GJWBJYZMKX1XS1" }
  ]
}
```