# 片段替换
> 替换音乐中的某个时间片段，其余部分保持不变，异步任务
> 用 `clip_id` 引用源音频，用 `start_s` 与 `end_s` 框出区间
> 产出是新的 clip_id，整首重新输出
`POST /v1/music/generations/replaceFlowMusic`
## 认证
- `Authorization` (string / 必填) — 所有接口均使用 Bearer Token 进行认证。 获取 API Key：[访问控制台](https://api.oairoute.com/keys) 创建。 请求时在请求头中添加： ```http Authorization: Bearer YOUR_OAIRoute_KEY ```
## 请求参数
- `model` (string / 必填) — 模型名称，固定传 `flowmusic`，大小写不敏感。
- `clip_id` (string / 必填) — 源音乐 clip_id，取自成功任务的 `result.music[].clip_id`。
- `start_s` (number / 必填) — 替换开始时间，单位秒。
- `end_s` (number / 必填) — 替换结束时间，单位秒。须大于 `start_s`，且不超过源 clip 时长。
- `instruction` (string / 必填) — 替换片段的编辑指令，例如「替换为钢琴版本」。
- `title` (string / 可选) — 替换后音乐标题。
- `seed` (integer / 可选) — 随机种子，用于复现或控制生成结果。
## 与「删除片段」的区别
| 项目 | 删除 | 替换 |
|---|---|---|
| 区间处理 | 直接去掉，前后接上 | 用新内容填上 |
| 接缝 | 可能突兀 | 相对自然 |
| 需要指令 | 不需要 | `instruction` 必填 |
想换掉一段不满意的间奏，用替换。想整体缩短，用删除。
> **Note:** 
> 替换产物是**整首重新输出**，不是只吐出被替换的那一段。所以拿到的 `clip_id` 是一个新值，后续操作要用新的，不是原来的。
## 响应
- `code` (integer) — 状态码，成功为 200。
- `data[].status` (string) — 任务状态，初始提交时为 `submitted`。
- `data[].task_id` (string) — 任务唯一标识，用于查询状态与结果。
## 取结果
轮询 `GET /v1/music/tasks/{task_id}`，间隔 3 到 5 秒，直到状态变为 `completed` 或 `failed`。
完成后从 `data.result.music[]` 取新的 `clip_id` 与 `audio_url`。
## 错误
| HTTP | code | 说明 |
|---|---|---|
| 400 | invalid_request | 参数校验失败，例如 `end_s must be greater than start_s` |
| 429 | rate_limit_error | 当前分组容量饱和，需稍后重试 |
更多状态码与重试建议见[错误码与限流](../../../support/errors.html)，常见报错的排查步骤见[常见问题](../../../support/faq.html)。
## 使用示例
提交一个任务并拿到 `task_id`：
> **Note:** 
> 提交成功只表示任务已受理。真正的产物要拿返回的 `task_id` 去任务查询接口轮询，`status` 变成 `completed` 之后才有结果。
**片段替换{Replace segment}::cURL**
```
curl -X POST https://api.oairoute.com/v1/music/generations/replaceFlowMusic \
  -H 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  -H 'Content-Type: application/json' \
  --data '{
    "model": "flowmusic",
    "clip_id": "c_01KA",
    "start_s": 45,
    "end_s": 62.5,
    "instruction": "替换为纯钢琴独奏版本",
    "title": "窗边（间奏替换版）"
  }'
```
**片段替换{Replace segment}::Python**
```
import requests
res = requests.post(
    "https://api.oairoute.com/v1/music/generations/replaceFlowMusic",
    headers={
        "Authorization": "Bearer YOUR_OAIRoute_KEY",
        "Content-Type": "application/json",
    },
    json={
        "model": "flowmusic",
        "clip_id": "c_01KA",
        "start_s": 45,
        "end_s": 62.5,
        "instruction": "替换为纯钢琴独奏版本",
        "title": "窗边（间奏替换版）",
    },
)
print(res.json()["data"][0]["task_id"])
```
**片段替换{Replace segment}::JavaScript**
```
const url = "https://api.oairoute.com/v1/music/generations/replaceFlowMusic";
const options = {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "flowmusic",
    "clip_id": "c_01KA",
    "start_s": 45,
    "end_s": 62.5,
    "instruction": "替换为纯钢琴独奏版本",
    "title": "窗边（间奏替换版）"
  }),
};
fetch(url, options)
  .then((res) => res.json())
  .then((json) => console.log(json))
  .catch((err) => console.error(err));
```
**200 片段替换{Replace segment}**
```
{
  "code": 200,
  "data": [
    { "status": "submitted", "task_id": "task_01K8E99M0HP1GJWBJYZMKX1XS1" }
  ]
}
```