> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toapis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Kling v4 视频生成

> 使用同一个 kling-4.0 模型进行文生视频, 参考素材生成和首/中/尾关键帧控制

三种输入模式统一使用 `kling-4.0`, 根据实际素材自动选择生成方式. 这是异步任务接口, 提交后使用平台返回的任务 ID 查询结果.

> [!NOTE]
>
> 使用平台 API Key. 中国大陆用户可将示例中的 `https://toapis.com` 替换为 `https://toapis.cn`. 模型可用性以部署后的渠道配置和账户权限为准.

## 输入模式

| 模式 | 请求内容 |
| - | - |
| 文生视频 | 只传提示词和生成规格, 不传素材. |
| 参考素材 | 使用 `image_urls` / `video_urls`, 或带 reference 角色的素材. 图片和视频可以组合. |
| 关键帧 | 通过 `image_with_roles` 显式指定 `first_frame`, `keyframe`, `last_frame`. 不能同时传参考图片或参考视频. |

## 请求参数

**Authorization** `string` *required*

使用 `Bearer YOUR_API_KEY` 认证.

**model** `string` *required*

固定为 `kling-4.0`. 三种模式不需要切换模型 ID.

**prompt** `string` *required*

必填, 非空白, 最多 8000 个 Unicode 字符. 描述主体, 动作, 镜头和素材之间的关系.

**duration** `integer` (default: 5)

整数, 3-30 秒, 默认 5 秒.

**resolution** `string` (default: 720p)

支持 `720p` 和 `1080p`, 默认 `720p`. 使用本字段选择分辨率.

**aspect\_ratio** `string`

可选 `auto`, `16:9`, `9:16`, `1:1`, `21:9`. 省略时不覆盖上游默认值; 需要自动比例时可显式传 `auto`.

**image\_urls** `string[]`

参考图片 URL 数组, 最多 10 张. 不会自动解释为首帧或尾帧. 与 reference 图片角色合并计算数量, 建议同一素材只使用一种写法.

**video\_urls** `string[]`

参考视频 URL 数组, 最多 5 个. 与 `video_with_roles` 合并计算数量.

**image\_with\_roles** `object[]`

对象字段为 `url` 和 `role`. `reference` / `reference_image` 表示参考图片; `first_frame` 表示首帧; `keyframe` 表示中间帧; `last_frame` 表示尾帧.

**video\_with\_roles** `object[]`

对象字段为 `url` 和 `role`. role 支持 `reference` / `reference_video`, 表示参考视频.

**metadata** `object`

可通过 `keep_original_sound` 布尔值控制是否保留参考视频原声, 例如 `{"keep_original_sound": true}`. 仅用于参考视频; 关键帧模式不能携带此键, 即使值为 false.

**client\_business\_id** `string`

可选的客户业务 ID, 随任务保存, 可通过相同查询接口按业务 ID 查询.

## 素材规则与错误边界

* 素材使用公网可访问的 HTTP(S) URL, URL 不能携带用户名或密码. 本地文件先通过[上传图片](https://docs.toapis.com/docs/cn/api-reference/uploads/images.md)或[上传视频](https://docs.toapis.com/docs/cn/api-reference/uploads/videos.md)获取 URL. 不直接发送本地路径或 base64.
* 参考模式最多 10 张图片和 5 个视频. 普通图片数组与显式 reference 角色会合并, 不要重复提交同一素材.
* 关键帧至少 1 张. 首帧和尾帧各最多 1 张, 中间帧最多 8 张, 总数不超过 `min(duration + 1, 10)`. 例如 3 秒最多 4 张, 5 秒最多 6 张, 9-30 秒最多 10 张.
* 中间帧按数组中 `keyframe` 项的顺序排列. 首帧和尾帧由角色决定, 不是根据普通图片数组的位置推断. 仅首帧, 仅尾帧或仅中间帧也会进入关键帧模式.
* 关键帧和参考素材互斥. 不使用旧 Kling 的 `mode`, `audio`, `video_list` 或 Omni 引用结构. `audio_with_roles`, `metadata.elements` 和 `metadata.voices` 不受本接入支持.
* 非法规格, 角色, URL, 数量或模式组合会被拒绝. 按返回的错误修正请求, 不要原样重试. 未在本页承诺素材大小, 编码或输入视频时长上限, 还需满足上传服务和上游媒体要求.

## 请求示例

### 文生视频

```json theme={null}
{
  "model": "kling-4.0",
  "prompt": "海浪拍打海岸, 镜头缓慢推进, 日落光线",
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "16:9"
}
```

### 参考素材

```json theme={null}
{
  "model": "kling-4.0",
  "prompt": "保持参考图片的人物外观, 参考视频中的镜头运动",
  "duration": 10,
  "resolution": "1080p",
  "aspect_ratio": "16:9",
  "image_urls": [
    "https://example.com/character.png"
  ],
  "video_urls": [
    "https://example.com/motion.mp4"
  ],
  "metadata": {
    "keep_original_sound": true
  }
}
```

### 关键帧

```json theme={null}
{
  "model": "kling-4.0",
  "prompt": "从首帧经过中间场景平滑过渡至尾帧",
  "duration": 5,
  "resolution": "1080p",
  "aspect_ratio": "16:9",
  "image_with_roles": [
    {
      "url": "https://example.com/first.png",
      "role": "first_frame"
    },
    {
      "url": "https://example.com/middle-1.png",
      "role": "keyframe"
    },
    {
      "url": "https://example.com/middle-2.png",
      "role": "keyframe"
    },
    {
      "url": "https://example.com/last.png",
      "role": "last_frame"
    }
  ]
}
```

### 提交任务

```bash cURL theme={null}
curl --request POST \
  --url https://toapis.com/v1/videos/generations \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-4.0",
  "prompt": "海浪拍打海岸, 镜头缓慢推进, 日落光线",
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "16:9"
}'
```

```json theme={null}
{
  "id": "task_example",
  "object": "generation.task",
  "model": "kling-4.0",
  "status": "queued",
  "created_at": 1792713600
}
```

## 查询任务与计费

提交响应中的 `id` 是平台任务 ID. 使用下方接口查询, 不使用供应商 task\_id. 状态包括 `queued`, `in_progress`, `completed`, `failed`. 完整结果结构见[视频任务状态](https://docs.toapis.com/docs/cn/api-reference/tasks/video-status.md), 回调见[任务 Webhook](https://docs.toapis.com/docs/cn/api-reference/webhooks/task-webhooks.md).

```bash theme={null}
curl --request GET \
  --url https://toapis.com/v1/videos/generations/YOUR_TASK_ID \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

默认时长和分辨率为 5 秒 / 720p. 显式填写可让调用方清楚控制规格. 本页不提供固定价格或将原声开关等同于旧版 Sound 计费; 实际计费以账户报价及任务查询中的 usage / billing 为准.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.