# Kling

> 通过 UniAI 创建可灵文生、图生、参考、动作控制和视频编辑任务。

Canonical URL: https://docs.uniai.tv/models/video/kling
Locale: zh-CN

本页示例中的 `{BASE_URL}` 表示 `https://api.uniai.tv`。

## 概览

可灵视频能力统一使用稳定的版本级模型名。通过请求体顶层的 `resolution` 选择清晰度，通过 `operation` 选择生成方式；不要把清晰度、声音或上游路由写进模型名。

| 模型 | 视频能力 | 清晰度 |
| --- | --- | --- |
| `kling-v3-turbo` | 文生视频、单首帧图生视频 | `720p`、`1080p` |
| `kling-v3` | 文生视频、图生视频、首尾帧、动作控制、数字人 | `std`、`pro` |
| `kling-v3-omni` | 文生视频、图生视频、首尾帧、多模态参考、视频编辑 | `std`、`pro` |
| `kling-o1` | 文生视频、图生视频、首尾帧、多模态参考、视频编辑 | `std`、`pro` |

模型是否可用取决于模型广场、API Key 的模型权限和当前启用的路由。历史清晰度、声音、静音和数字人档位模型名不再接受，也不会自动转换。

## 适用场景

- 需要 `720p` 或 `1080p` 的快速文生、单图视频时使用 `kling-v3-turbo`。
- 需要首尾帧、动作控制或数字人时使用 `kling-v3`。
- 需要最多四张参考图的多模态参考或视频编辑时使用 `kling-v3-omni`。
- 需要相同的参考和编辑请求结构、且生成时长为 `3` 到 `10` 秒时使用 `kling-o1`。

## 接口

| 操作 | 方法 | 路径 |
| --- | --- | --- |
| 创建视频任务 | `POST` | `/v1/videos` |
| 查询视频任务 | `GET` | `/v1/videos/{task_id}` |
| 下载已完成的视频 | `GET` | `/v1/videos/{task_id}/content` |

`POST /v1/videos/generations` 和 `POST /v1/video/generations` 仍是兼容创建路径。新接入统一使用 `POST /v1/videos`。

## 鉴权

```http
Authorization: Bearer sk-***
Content-Type: application/json
```

## 清晰度与声音

在请求体顶层传入 `resolution`，不要使用 `size` 代替。未传时，Turbo 默认 `720p`，其他可灵视频模型默认 `std`。需要明确输出和计费记录时，建议显式传入。

可灵视频请求不接受 `sound` 开关。需要对白、音乐、环境声或静音效果时，直接写入 `prompt`。数字人任务使用的 `audio_url` 和 `voice_id` 是口型驱动输入，不属于声音开关。

## 生成方式

| `operation` | 支持模型 | 必要输入 |
| --- | --- | --- |
| `text_to_video` | Turbo、V3、Omni、O1 | `prompt` |
| `image_to_video` | Turbo、V3、Omni、O1 | `prompt` 和 `image` |
| `first_last_frame` | V3、Omni、O1 | `prompt`、`image` 和 `last_image` |
| `reference_to_video` | Omni、O1 | `prompt` 和图片或视频参考 |
| `edit_video` | Omni、O1 | `prompt` 和 `video_url`；参考图可选 |
| `motion_control` | V3 | `prompt`、`image`、`video` 和 `character_orientation` |
| `avatar` | V3 | 参见[数字人口播](/models/avatar/digital-human) |

时长规则：

- Turbo 和 V3 的生成 operation 支持 `3` 到 `15` 秒。
- Omni 的文生、图生和首尾帧支持 `3` 到 `15` 秒；`reference_to_video` 支持 `3` 到 `10` 秒。
- O1 的生成 operation 支持 `3` 到 `10` 秒。
- 动作控制、数字人和视频编辑按对应 operation 的结果时长规则处理；除非该 operation 明确支持，否则不要传 `duration`。
- Turbo 文生视频接受 `aspect_ratio`；Turbo 图生视频不接受。

## 请求参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 稳定的可灵视频模型 ID。 |
| `prompt` | string | 是 | UniAI 视频任务接口要求提供的提示词。 |
| `operation` | string | 建议显式传入 | 上表中的生成方式。 |
| `resolution` | string | 否 | 模型对应的清晰度；默认值见上文。 |
| `duration` | integer | 条件必填 | 支持时长的 operation 的输出秒数。 |
| `aspect_ratio` | string | 条件必填 | `16:9`、`9:16` 或 `1:1`。 |
| `image` | string | 条件必填 | 图生视频图片或首帧的公开 HTTP(S) URL。 |
| `last_image` | string | 条件必填 | 尾帧图片 URL，需与 `image` 同时使用。 |
| `reference_image_urls` | string[] | 否 | 多模态参考或编辑使用的参考图 URL，最多四张。 |
| `video_url` | string | 条件必填 | 多模态参考或编辑使用的基础视频 URL。 |
| `video` | string | 条件必填 | `motion_control` 使用的动作参考视频 URL。 |
| `keep_original_sound` | string | 否 | 多模态参考和视频编辑可使用 `yes` 或 `no`。 |
| `character_orientation` | string | 条件必填 | `motion_control` 使用 `image` 或 `video`。 |
| `watermark` | boolean | 否 | 是否添加 AIGC 水印。 |

## 请求示例

### Turbo 文生视频

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3-turbo",
    "operation": "text_to_video",
    "prompt": "一架纸飞机穿过清晨的城市街道，电影感运镜，轻柔环境声。",
    "duration": 3,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "watermark": false
  }'
```

### Turbo 图生视频

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3-turbo",
    "operation": "image_to_video",
    "prompt": "纸飞机平稳向前滑翔，镜头缓慢跟随。",
    "image": "https://example.com/plane.png",
    "duration": 5,
    "resolution": "1080p"
  }'
```

Turbo 图生视频不要传 `aspect_ratio`。

### V3 首尾帧

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3",
    "operation": "first_last_frame",
    "prompt": "人物自然转身并看向镜头，过渡连续平滑。",
    "image": "https://example.com/first.png",
    "last_image": "https://example.com/last.png",
    "duration": 5,
    "resolution": "pro"
  }'
```

### V3 动作控制

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3",
    "operation": "motion_control",
    "prompt": "保持人物身份和服装，复现参考视频中的动作。",
    "image": "https://example.com/person.png",
    "video": "https://example.com/motion.mp4",
    "resolution": "pro",
    "character_orientation": "image"
  }'
```

### Omni 多模态参考

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3-omni",
    "operation": "reference_to_video",
    "prompt": "保持人物身份和服装，把参考动作应用到基础视频。",
    "reference_image_urls": [
      "https://example.com/person.png",
      "https://example.com/clothes.png"
    ],
    "video_url": "https://example.com/base.mp4",
    "duration": 8,
    "resolution": "pro",
    "keep_original_sound": "yes"
  }'
```

### Omni 视频编辑

```bash
curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3-omni",
    "operation": "edit_video",
    "prompt": "保持人物动作不变，把背景替换为夜晚城市街道。",
    "video_url": "https://example.com/source.mp4",
    "reference_image_urls": [
      "https://example.com/city-style.png"
    ],
    "resolution": "pro",
    "keep_original_sound": "yes"
  }'
```

`kling-o1` 使用相同的文生、图生、首尾帧、参考和编辑请求结构，其生成时长范围为 `3` 到 `10` 秒。

## 响应示例

```json
{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "video.generation.job",
  "model": "kling-v3",
  "status": "queued",
  "progress": 0
}
```

## 任务状态与结果

保存 `id` 或 `task_id`，然后按照[视频生成概览](/models/video/overview#视频任务生命周期)中的公共规则，每 3 到 10 秒轮询一次，并处理终态、结果字段、错误和带鉴权下载。

## 计费说明

视频通常结合公共模型、`operation`、`resolution` 和实际输出秒数计费。任务提交时可能预扣，最终以任务结算记录和模型广场当前价格为准。

## 常见错误

- 使用历史清晰度、声音、静音或数字人档位模型名，而不是上面的版本级模型。
- 使用 `size` 代替 `resolution`，或给视频请求传入 `sound`。
- Turbo 图生视频传入 `aspect_ratio`。
- 请求时长超出所选模型和 operation 的范围。
- 混用 `image`、`reference_image_urls` 和视频输入，重复提交同一个参考素材。
- 图片或视频 URL 无法由服务端公开访问。
- 一次轮询超时后重新提交付费任务，而不是继续查询原 `task_id`。

公共响应不会返回供应商名称、上游任务 ID、路由、凭证或上游原始请求。

## 相关页面

- [Kling 图片](/models/image/kling)
- [数字人口播](/models/avatar/digital-human)
- [视频生成概览](/models/video/overview)