# 音乐视频渲染
> 把 Flow Music 的音乐渲染成带画面的视频，异步任务
> 用 `clip_id` 引用源音频
> 三种预设模板可选
`POST /v1/music/generations/videoClipFlowMusic`
## 认证
- `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`。
- `preset` (string / 可选) — 视频模板预设，默认 `simple`。 - `simple` 简洁 - `modern` 现代风格 - `player` 播放器风格
## 三种预设怎么选
| 预设 | 视觉特征 | 适合 |
|---|---|---|
| `simple` | 大面积留白，元素最少 | 作为背景音乐视频，不抢注意力 |
| `modern` | 动态几何与渐变 | 社交媒体发布，观感更活跃 |
| `player` | 模拟播放器界面，含进度与封面 | 展示完整曲目信息 |
三种模板的差异主要在视觉呈现，音频内容完全一致。
## 提交响应
- `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` (integer) — 实际耗时，单位秒。
- `data.cost` (number) — 费用。
- `data.credits_cost` (number) — 消耗积分。
- `data.result.music[]` (array) — 生成结果列表。
- `data.result.music[].clip_id` (string) — 音频片段 ID。
- `data.result.music[].video_url` (string) — 视频地址。
- `data.result.music[].url` (string) — 与 `video_url` 相同的地址，两个字段指向同一份文件。
> **Note:** 
> 结果在 `result.music[0].video_url`。`url` 字段是它的别名，两者内容一致，读哪个都行。
## 错误
| HTTP | code | 场景 |
|---|---|---|
| 400 | `invalid_request` | 缺少 `clip_id` 等参数问题 |
| 429 | `rate_limit_error` | 当前分组容量饱和，需稍后重试 |
> **Note:** 
> 视频文件通常比音频大一个数量级，且地址可能有有效期。拿到后应尽快下载转存，不要直接把 CDN 地址嵌进长期使用的页面。
更多状态码与重试建议见[错误码与限流](../../../support/errors.html)，常见报错的排查步骤见[常见问题](../../../support/faq.html)。
## 使用示例
提交一个任务并拿到 `task_id`：
> **Note:** 
> 提交成功只表示任务已受理。真正的产物要拿返回的 `task_id` 去任务查询接口轮询，`status` 变成 `completed` 之后才有结果。
**音乐视频渲染{Render music video}::cURL**
```
curl -X POST https://api.oairoute.com/v1/music/generations/videoClipFlowMusic \
  -H 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  -H 'Content-Type: application/json' \
  --data '{
    "model": "flowmusic",
    "clip_id": "c_01KA",
    "preset": "modern"
  }'
```
**音乐视频渲染{Render music video}::Python**
```
import requests
res = requests.post(
    "https://api.oairoute.com/v1/music/generations/videoClipFlowMusic",
    headers={
        "Authorization": "Bearer YOUR_OAIRoute_KEY",
        "Content-Type": "application/json",
    },
    json={
        "model": "flowmusic",
        "clip_id": "c_01KA",
        "preset": "modern",
    },
)
print(res.json()["data"][0]["task_id"])
```
**音乐视频渲染{Render music video}::JavaScript**
```
const res = await fetch(
  "https://api.oairoute.com/v1/music/generations/videoClipFlowMusic",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_OAIRoute_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "flowmusic",
      clip_id: "c_01KA",
      preset: "player",
    }),
  }
);
const { data } = await res.json();
console.log(data[0].task_id);
```
**200 音乐视频渲染{Render music video}**
```
{
  "code": 200,
  "data": [
    { "status": "submitted", "task_id": "task_01K8F00M0HP1GJWBJYZMKX1XS1" }
  ]
}
```