> ## 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 Flash 视频生成

> 使用同一个 kling-4.0-flash 模型进行文生视频, 参考素材生成和首帧生成

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

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

## 输入模式

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

## 请求参数

**Authorization** `string` *required*

使用 `Bearer YOUR_API_KEY` 认证.

**model** `string` *required*

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

**prompt** `string` *required*

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

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

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

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

仅支持 `720p`, 默认 `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 张 `first_frame` 图片, `keyframe` 和 `last_frame` 会被拒绝. 首帧由角色决定, 普通图片数组不会自动视为首帧.
* 首帧和参考素材互斥. 不使用旧 Kling 的 `mode`, `audio`, `video_list` 或 Omni 引用结构. `audio_with_roles`, `metadata.elements` 和 `metadata.voices` 不受本接入支持.
* 非法规格, 角色, URL, 数量或模式组合会被拒绝. 按返回的错误修正请求, 不要原样重试. 未在本页承诺素材大小, 编码或输入视频时长上限, 还需满足上传服务和上游媒体要求.

## 请求示例

### 文生视频

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

### 参考素材

```json theme={null}
{
  "model": "kling-4.0-flash",
  "prompt": "保持参考图片的人物外观, 参考视频中的镜头运动",
  "duration": 10,
  "resolution": "720p",
  "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-flash",
  "prompt": "以首帧为起点, 人物缓慢转向窗外",
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "image_with_roles": [
    {
      "url": "https://example.com/first.png",
      "role": "first_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-flash",
  "prompt": "海浪拍打海岸, 镜头缓慢推进, 日落光线",
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "16:9"
}'
```

```json theme={null}
{
  "id": "task_example",
  "object": "generation.task",
  "model": "kling-4.0-flash",
  "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.