# Cover 改编
> 用新的风格重新演绎已有音乐，异步任务
> 用 `clip_id` 引用源音频
> 产出的是**新的** clip_id，后续操作要用新值
`POST /v1/music/generations/coverFlowMusic`
## 认证
- `Authorization` (string / 必填) — 所有接口均使用 Bearer Token 进行认证。 获取 API Key：[访问控制台](https://api.oairoute.com/keys) 创建。 请求时在请求头中添加： ```http Authorization: Bearer YOUR_OAIRoute_KEY ```
## 请求参数
- `model` (string / 必填) — 模型名称固定为 `flowmusic`，不区分大小写。
- `clip_id` (string / 必填) — 源音频的唯一标识，取自此前成功任务的 `result.music[].clip_id`。 外部音频需要先上传，以换取 `clip_id`。
- `instruction` (string / 必填) — Cover 改编指令，例如「改成爵士三重奏的风格」。 这是本接口的核心，写清楚要变成什么样。只写「改成别的风格」模型会自己猜，结果不可控。
- `strength` (number / 必填) — 编辑强度，取值范围 0 到 1。**值越大改动越大**，超出范围会报错。
- `title` (string / 可选) — 改编后音乐的标题。
- `seed` (string / 可选) — 随机种子，用于复现结果。
## strength 怎么调
这是本接口最需要试的参数：
| 取值 | 效果 |
|---|---|
| 0 到 0.2 | 几乎听不出变化，只做了轻微调整 |
| 0.3 到 0.5 | 编曲变了，旋律骨架还在 |
| 0.6 到 0.8 | 明显是另一首歌，但能听出原曲影子 |
| 0.9 到 1 | 基本只剩歌词或结构，旋律几乎全新 |
建议从 0.5 起步，觉得不够就往上调，觉得面目全非就往下调。
> **Note:** 
> `strength` 是必填项，没有默认值。不传会直接报错，不会默默取中间值。
## 提交响应
- `code` (integer) — 状态码，成功时为 200。
- `data[].status` (string) — 任务状态，提交时初始为 `submitted`。
- `data[].task_id` (string) — 任务唯一标识，用于查询状态与结果。
## 任务查询响应
- `data.id` (string) — 任务 ID。
- `data.status` (string) — 任务状态，例如 `completed`。
- `data.progress` (integer) — 进度百分比。
- `data.created` (integer) — 创建时间戳。
- `data.completed` (integer) — 完成时间戳。
- `data.actual_time` (number) — 实际耗时。
- `data.cost` (number) — 费用。
- `data.credits_cost` (number) — 积分消耗。
- `data.result.music[]` (array) — 生成的音乐列表。
### music[] 元素字段
- `clip_id` (string) — 改编产物对应的**新** clip_id。后续操作需要改用这个新值，不是原来的。
- `title` (string) — 音乐标题。
- `duration_seconds` (string) — 时长，字符串形式的数值。
- `create_time` (string) — 创建时间，ISO 8601 格式。
- `lyrics` (string) — 歌词文本。
- `lyrics_id` (string) — 歌词标识。
- `lyrics_timing_markers` (array) — 歌词时间标记，二元组数组。
- `audio_url` (string) — 音频文件地址，m4a 格式。
- `wav_url` (string) — WAV 格式地址。
- `image_url` (string) — 封面图地址。
## 错误
- `error.message` (string) — 错误描述，例如参数越界或余额不足。
- `error.type` (string) — 错误类型，例如 `invalid_request`。
- `error.param` (string) — 出错参数，未指明时为空串。
- `error.code` (string) — 错误码，例如 `invalid_request`、`quota_not_enough`、`rate_limit_error`。
更多状态码与重试建议见[错误码与限流](../../../support/errors.html)，常见报错的排查步骤见[常见问题](../../../support/faq.html)。
## 使用示例
提交一个任务并拿到 `task_id`：
> **Note:** 
> 提交成功只表示任务已受理。真正的产物要拿返回的 `task_id` 去任务查询接口轮询，`status` 变成 `completed` 之后才有结果。
**Cover 改编{Cover remix}::cURL**
```
curl -X POST https://api.oairoute.com/v1/music/generations/coverFlowMusic \
  -H 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  -H 'Content-Type: application/json' \
  --data '{
    "model": "flowmusic",
    "clip_id": "c_01KA",
    "instruction": "改成爵士三重奏，钢琴贝斯鼓，慵懒",
    "strength": 0.6,
    "title": "窗边（爵士版）"
  }'
```
**Cover 改编{Cover remix}::Python**
```
import requests
res = requests.post(
    "https://api.oairoute.com/v1/music/generations/coverFlowMusic",
    headers={
        "Authorization": "Bearer YOUR_OAIRoute_KEY",
        "Content-Type": "application/json",
    },
    json={
        "model": "flowmusic",
        "clip_id": "c_01KA",
        "instruction": "改成爵士三重奏，钢琴贝斯鼓，慵懒",
        "strength": 0.6,
        "title": "窗边（爵士版）",
    },
)
print(res.json()["data"][0]["task_id"])
```
**Cover 改编{Cover remix}::JavaScript**
```
const url = "https://api.oairoute.com/v1/music/generations/coverFlowMusic";
const options = {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "flowmusic",
    "clip_id": "c_01KA",
    "instruction": "改成爵士三重奏，钢琴贝斯鼓，慵懒",
    "strength": 0.6,
    "title": "窗边（爵士版）"
  }),
};
fetch(url, options)
  .then((res) => res.json())
  .then((json) => console.log(json))
  .catch((err) => console.error(err));
```
**200 Cover 改编{Cover remix}**
```
{
  "code": 200,
  "data": [
    { "status": "submitted", "task_id": "task_01K8E88M0HP1GJWBJYZMKX1XS1" }
  ]
}
```
**改动力度小{Light modification}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/music/generations/coverFlowMusic' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "flowmusic",
  "clip_id": "c_01KA",
  "instruction": "只把钢琴换成电钢琴，其他保持",
  "strength": 0.25
}'
```
**改动力度小{Light modification}::Python**
```
import requests
url = "https://api.oairoute.com/v1/music/generations/coverFlowMusic"
headers = {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
}
payload = {
      "model": "flowmusic",
      "clip_id": "c_01KA",
      "instruction": "只把钢琴换成电钢琴，其他保持",
      "strength": 0.25
    }
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**改动力度小{Light modification}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/music/generations/coverFlowMusic", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "flowmusic",
    "clip_id": "c_01KA",
    "instruction": "只把钢琴换成电钢琴，其他保持",
    "strength": 0.25
  }),
});
console.log(await res.json());
```
**200 改动力度小{Light modification}**
```
{
  "code": 200,
  "data": [
    { "status": "submitted", "task_id": "task_01K8E88M0HP1GJWBJYZMKX1XS1" }
  ]
}
```