# Kling 视频生成
> 文生视频、图生视频、首尾帧、视频编辑与延长，统一一个模型入口
> 按传入的素材与 omni_reference_task_type 自动判定任务类型
> 每个输出都带立体声音轨
`POST /v1/videos`
## 认证
- `Authorization` (string / 必填) — 所有接口均使用 Bearer Token 进行认证。 获取 API Key：[访问控制台](https://api.oairoute.com/keys) 创建。 请求时在请求头中添加： ```http Authorization: Bearer YOUR_OAIRoute_KEY ```
## 请求参数
> **Note:** 
> 提交成功只返回任务 ID，不含视频本身。拿成片用 `task_id` 轮询[获取任务状态](../tasks/status.html)，成片地址在 `result.videos[0].url`，该地址约 24 小时后过期，请及时转存。
- `model` (string / 必填) — 视频模型 ID，取值见下方模型列表。
- `prompt` (string / 条件必填) — 画面描述。除纯图生视频外必填。 支持用 `@Image1`、`@Video1`、`@Audio1` 引用素材，编号按素材数组顺序从 1 开始。编辑模式下输入视频是 `@Video1`，参考图依次是 `@Image1`、`@Image2`。
- `duration` (integer / 可选) — 时长，单位秒，默认 `5`。 取值 3 到 30。编辑任务省略时沿用输入视频长度；延长任务只计算新增片段的秒数。
- `resolution` (string / 可选) — 输出分辨率，取值 `720p`、`1080p`，默认 `720p`。 V4 只认这个字段，不再支持 `mode`。
- `aspect_ratio` (string / 可选) — 输出画幅，取值 `16:9`、`9:16`、`1:1`、`21:9`，参考生视频还可传 `auto`。 默认值随模式变化：文生视频 `16:9`，图生视频沿用首帧，参考生视频 `auto`，编辑沿用输入视频，延长不接受该字段。
- `image_urls` (string[] / 可选) — 图生视频最多 2 张，第一张是首帧、第二张是尾帧。 参考生视频与编辑最多 10 张，全部按参考图处理。地址必须公网可访问。
- `image_with_roles` (object[] / 可选) — 带角色的图片数组，每项含 `url` 与 `role`。 `role` 取值 `first_frame`、`last_frame`、`keyframe`（别名 `middle_frame`，按顺序最多 8 张）、`reference_image`。首尾帧与关键帧合计不超过 10 张。
- `first_frame_image` (string / 可选) — 首帧地址，等价于 `image_with_roles` 里的一条 `first_frame`，也等价于 `image_urls` 的第一项。
- `last_frame_image` (string / 可选) — 图生视频的尾帧，或延长任务的目标尾帧。
- `video_urls` (string[] / 可选) — 参考视频，最多 5 段，合计不超过 30 秒。 编辑与延长也可以改成在这里传 1 段，并配合 `omni_reference_task_type`。
- `video_url` (string / 可选) — 编辑或延长任务的输入视频，必须同时把 `omni_reference_task_type` 设为 `edit` 或 `extend`。 编辑输入不得短于 3 秒，超过 30 秒会截取前 30 秒。
- `audio_urls` (string[] / 可选) — 参考音频，最多 3 段，每段 5 到 30 秒。
- `omni_reference_task_type` (string / 可选) — 任务类型，取值 `auto`、`reference`、`edit`、`extend`，默认 `auto`。 `auto` 由素材推断；`reference` 强制把 `image_urls` 里的图当参考图；`edit` 与 `extend` 必须配输入视频。
- `audio_setting` (string / 可选) — 音轨处理方式，取值 `origin` 保留原始音轨、`auto` 重新生成。 编辑默认保留原音，带参考视频的参考生视频默认重新生成。延长任务不支持该字段。
## 模式判定
不带任何图片或视频字段就是文生视频。
带 `image_urls` 或 `image_with_roles` 走图生视频：1 张是首帧，2 张是首尾帧，带 `reference_image` 角色则转为参考图。
带 `video_urls` 是参考视频；带 `video_url` 且 `omni_reference_task_type` 为 `edit` 或 `extend` 是视频编辑或延长。
参考图、参考视频、参考音频合计不超过 15 项。
## 支持的模型列表
| 模型 ID | 定位 |
|---|---|
| `kling-v4` | 当前主力，五种任务类型共用一个模型名，由素材推断模式 |
| `kling-v3` | 上一代旗舰，支持 `std` / `pro` / `4k` 三档与多镜头分镜 |
| `kling-v3-omni` | v3 的全能版，额外支持视频编辑与主体参考 |
| `kling-v2-6` | 支持 5 秒与 10 秒两档，`pro` 档可自动生成音轨 |
| `kling-video-o1` | 面向镜头语言的版本 |
| `kling-3.0-turbo` | 高速档，适合批量预览 |
v3 系列使用 `mode` 指定画质档位：`std` 对应 720P、`pro` 对应 1080P、`4k` 对应 4K。v4 不再支持 `mode`，改用 `resolution`。
## 使用限制
- `mode`、`negative_prompt`、`watermark: true`、`audio: false`、`multi_shot`、`multi_prompt`、`element_list`、`camera_control` 在 V4 上会被拒绝
- 单独传 `video_url` 而不指定 `edit` 或 `extend` 会返回 400，参考视频请用 `video_urls`
- 编辑任务输入不足 3 秒返回 400，探测输入时长失败也返回 400，且不扣费
- 失败任务全额退款
## 响应
提交成功返回统一的受理结构：
```json
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
    }
  ]
}
```
- `code` (integer / 总是返回) — 状态码，`200` 表示任务已受理。
- `data` (array / 总是返回) — 本次提交的任务列表，逐项提交时按顺序排列。
- `data[].status` (string / 总是返回) — 受理状态，提交成功时为 `submitted`。
- `data[].task_id` (string / 总是返回) — 任务 ID，用它轮询结果。
## 错误
| HTTP | type | 说明 |
|---|---|---|
| 400 | invalid_request_error | 请求参数无效，或参数组合冲突 |
| 401 | authentication_error | 身份验证失败，需检查 API Key |
| 402 | payment_required | 账户余额不足，需先充值 |
| 429 | rate_limit_error | 调用频率过高，稍后重试 |
参数错误在提交阶段同步返回，不创建任务、不扣费。
更多状态码与重试建议见[错误码与限流](../../support/errors.html)，常见报错的排查步骤见[常见问题](../../support/faq.html)。
## 查询任务
`GET /v1/tasks/{task_id}` 返回任务进度与结果，`status` 为 `completed` 时成片地址在 `result.videos[0].url`，元素带 `expires_at` 过期时间戳。
建议每 5 到 10 秒轮询一次，客户端总超时设为 10 到 15 分钟。`status` 取值 `pending`、`processing`、`completed`、`failed`、`cancelled`，以状态判定完成，不要依赖 `progress`。
失败任务自动退回费用，`error.message` 给出原因。
**文生视频{Text to video}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/videos' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-v4",
  "prompt": "城市夜景延时，车流拉出光轨",
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "16:9"
}'
```
**文生视频{Text to video}::Python**
```
import requests
url = "https://api.oairoute.com/v1/videos"
headers = {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
}
payload = {
  "model": "kling-v4",
  "prompt": "城市夜景延时，车流拉出光轨",
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "16:9"
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**文生视频{Text to video}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/videos", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "kling-v4",
  "prompt": "城市夜景延时，车流拉出光轨",
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "16:9"
}),
});
console.log(await res.json());
```
**200 文生视频{Text to video}**
```
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
    }
  ]
}
```
**图生视频{Image to video}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/videos' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-v4",
  "prompt": "镜头缓慢推近，人物转头看向镜头",
  "image_urls": [
    "https://example.com/portrait.png"
  ],
  "duration": 5,
  "resolution": "1080p"
}'
```
**图生视频{Image to video}::Python**
```
import requests
url = "https://api.oairoute.com/v1/videos"
headers = {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
}
payload = {
  "model": "kling-v4",
  "prompt": "镜头缓慢推近，人物转头看向镜头",
  "image_urls": [
    "https://example.com/portrait.png"
  ],
  "duration": 5,
  "resolution": "1080p"
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**图生视频{Image to video}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/videos", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "kling-v4",
  "prompt": "镜头缓慢推近，人物转头看向镜头",
  "image_urls": [
    "https://example.com/portrait.png"
  ],
  "duration": 5,
  "resolution": "1080p"
}),
});
console.log(await res.json());
```
**200 图生视频{Image to video}**
```
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
    }
  ]
}
```
**首尾帧{First and last frame}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/videos' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-v4",
  "prompt": "画面从白天过渡到夜晚，灯光逐渐亮起",
  "image_with_roles": [
    {
      "url": "https://example.com/day.png",
      "role": "first_frame"
    },
    {
      "url": "https://example.com/night.png",
      "role": "last_frame"
    }
  ],
  "duration": 5
}'
```
**首尾帧{First and last frame}::Python**
```
import requests
url = "https://api.oairoute.com/v1/videos"
headers = {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
}
payload = {
  "model": "kling-v4",
  "prompt": "画面从白天过渡到夜晚，灯光逐渐亮起",
  "image_with_roles": [
    {
      "url": "https://example.com/day.png",
      "role": "first_frame"
    },
    {
      "url": "https://example.com/night.png",
      "role": "last_frame"
    }
  ],
  "duration": 5
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**首尾帧{First and last frame}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/videos", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "kling-v4",
  "prompt": "画面从白天过渡到夜晚，灯光逐渐亮起",
  "image_with_roles": [
    {
      "url": "https://example.com/day.png",
      "role": "first_frame"
    },
    {
      "url": "https://example.com/night.png",
      "role": "last_frame"
    }
  ],
  "duration": 5
}),
});
console.log(await res.json());
```
**200 首尾帧{First and last frame}**
```
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
    }
  ]
}
```
**参考生视频{Reference to video}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/videos' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-v4",
  "prompt": "@Image1 中的角色在 @Video1 的街道上行走",
  "image_urls": [
    "https://example.com/character.png"
  ],
  "video_urls": [
    "https://example.com/street.mp4"
  ],
  "omni_reference_task_type": "reference",
  "duration": 5
}'
```
**参考生视频{Reference to video}::Python**
```
import requests
url = "https://api.oairoute.com/v1/videos"
headers = {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
}
payload = {
  "model": "kling-v4",
  "prompt": "@Image1 中的角色在 @Video1 的街道上行走",
  "image_urls": [
    "https://example.com/character.png"
  ],
  "video_urls": [
    "https://example.com/street.mp4"
  ],
  "omni_reference_task_type": "reference",
  "duration": 5
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**参考生视频{Reference to video}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/videos", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "kling-v4",
  "prompt": "@Image1 中的角色在 @Video1 的街道上行走",
  "image_urls": [
    "https://example.com/character.png"
  ],
  "video_urls": [
    "https://example.com/street.mp4"
  ],
  "omni_reference_task_type": "reference",
  "duration": 5
}),
});
console.log(await res.json());
```
**200 参考生视频{Reference to video}**
```
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
    }
  ]
}
```
**视频编辑{Video edit}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/videos' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-v4",
  "prompt": "把画面色调改成黄昏暖光",
  "video_url": "https://example.com/source.mp4",
  "omni_reference_task_type": "edit"
}'
```
**视频编辑{Video edit}::Python**
```
import requests
url = "https://api.oairoute.com/v1/videos"
headers = {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
}
payload = {
  "model": "kling-v4",
  "prompt": "把画面色调改成黄昏暖光",
  "video_url": "https://example.com/source.mp4",
  "omni_reference_task_type": "edit"
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**视频编辑{Video edit}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/videos", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "kling-v4",
  "prompt": "把画面色调改成黄昏暖光",
  "video_url": "https://example.com/source.mp4",
  "omni_reference_task_type": "edit"
}),
});
console.log(await res.json());
```
**200 视频编辑{Video edit}**
```
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
    }
  ]
}
```
**延长视频{Extend video}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/videos' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-v4",
  "prompt": "镜头继续向前推进",
  "video_url": "https://example.com/source.mp4",
  "omni_reference_task_type": "extend",
  "duration": 5
}'
```
**延长视频{Extend video}::Python**
```
import requests
url = "https://api.oairoute.com/v1/videos"
headers = {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
}
payload = {
  "model": "kling-v4",
  "prompt": "镜头继续向前推进",
  "video_url": "https://example.com/source.mp4",
  "omni_reference_task_type": "extend",
  "duration": 5
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**延长视频{Extend video}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/videos", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "kling-v4",
  "prompt": "镜头继续向前推进",
  "video_url": "https://example.com/source.mp4",
  "omni_reference_task_type": "extend",
  "duration": 5
}),
});
console.log(await res.json());
```
**200 延长视频{Extend video}**
```
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
    }
  ]
}
```