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

# Kling 4.0 与 Flash · 快速开始

> Kling 4.0 和 Flash 的文生、图生、Omni 参考与编辑，以及资源与计费说明

客户调用下文 `/kling/**` 时使用平台 Token。管理员在兼容渠道上配置需要使用的模型。官方北京渠道的地址为 `https://api-beijing.klingai.com`。4.0 使用 `kling-4.0`，Flash 使用 `kling-4.0-flash`，3.0 动作控制使用 `kling-3.0`。客户价格沿用 `kling-video-points`。

声线和主体创建使用 `kling-4.0` 检查令牌模型权限，请将其加入令牌白名单；标准主体请求无需额外填写 `model` 字段。

> [!WARNING]
>
> 主体创建（包括从视频自动抽取声线）的收费上界尚未确认，平台暂未开放付费主体创建。含新建主体的场景需等该费用条件解除。下方快速开始示例可直接使用提示词或素材 URL。

## 接口和默认值

| 入口 | 内容 | 画幅 |
| - | - | - |
| `POST /kling/text-to-video/kling-4.0` | 顶层 `prompt` | 21:9、16:9、9:16、1:1，默认16:9 |
| `POST /kling/image-to-video/kling-4.0` | `contents` 中的提示词、首中尾关键帧 | 不传独立 `aspect_ratio` |
| `POST /kling/omni-video/kling-4.0` | 关键帧、参考图、参考视频、待编辑视频及可用的主体和声线 | 支持 `adaptive`，默认 `adaptive` |

默认分辨率1080p，支持720p/1080p；显式 `settings.duration` 为3～30秒。省略时长时，上游先遵循提示词意图；Omni 没有时长意图时沿用基片，否则默认10秒。本地不会填入5秒，也不会解析提示词来决定扣款。

图片最多10张；视频和视频主体合计最多5项、累计时长最多30秒；主体最多7个，其中视频主体最多3个；声线最多3个；全部素材合计最多15项，待编辑视频最多1项。素材的 `id` 用于提示词中的 `@id`，同一任务内必须唯一；`element_id/voice_id` 使用资源查询返回的实际编号。

## 快速开始

使用有 `kling-4.0` 权限的 Kapon Token 提交请求。图片和视频 URL 需要能被上游访问，每次新建任务使用新的 `options.external_task_id`。

### 文生视频

向 `POST /kling/text-to-video/kling-4.0` 提交顶层 `prompt`。

```json theme={null}
{
  "prompt": "一只红色陶瓷杯放在木桌上，镜头缓慢推进",
  "settings": {"duration": 3, "resolution": "720p", "aspect_ratio": "16:9"},
  "options": {"external_task_id": "my-kling-text-001"}
}
```

### 关键帧图生视频

向 `POST /kling/image-to-video/kling-4.0` 提交 `contents`，其中至少有一张关键帧。图生请求省略 `settings.aspect_ratio`。

```json theme={null}
{
  "contents": [
    {"type": "prompt", "text": "镜头缓慢靠近杯子，保留杯子的形状和颜色"},
    {"type": "first_frame", "url": "https://example.com/first-frame.png"}
  ],
  "settings": {"duration": 3, "resolution": "1080p"},
  "options": {"external_task_id": "my-kling-image-001"}
}
```

### Omni 4.0 参考视频与编辑

向 `POST /kling/omni-video/kling-4.0` 提交 `contents`。用 `feature_video` 提供参考视频，用 `refer_image` 提供参考图。给需要在提示词中引用的素材设置唯一的 `id`，再用 `@id` 指明如何使用它。以下示例无需主体或声线。

```json theme={null}
{
  "contents": [
    {"type": "prompt", "text": "参考 @motion 的手部动作，生成一段在木桌上拿起红色杯子的视频"},
    {"type": "feature_video", "url": "https://example.com/reference-motion.mp4", "id": "motion"}
  ],
  "settings": {"duration": 3, "resolution": "720p"},
  "options": {"external_task_id": "my-kling-omni-001"}
}
```

要编辑一段已有视频，请在同一入口用 `base_video` 提交待编辑视频，并在提示词中写明要改动的内容。连续编辑时，将上一轮的实际成片 URL 作为本轮的 `base_video`，每次提交使用不同的业务编号。

标准版 Omni 的 `settings.audio` 默认是 `native`，上游会生成与画面匹配的声音。要保留输入视频的原声，请设置 `"audio": "original"`。此时必须提供 `base_video` 或 `feature_video`，且不能同时引用 `voice`。有 `base_video` 时保留基片原声，否则使用第一段 `feature_video` 的原声。

### Kling 4.0 Flash

使用有 `kling-4.0-flash` 权限的 Token 调用对应 Flash 路径。三个入口均只支持 `720p`，显式 `settings.duration` 为 3～20 秒的整数。省略时由上游按提示词确定时长。Omni 在提示词没有时长意图时采用基片时长四舍五入后的整数，无适用时长时默认 10 秒。

| 入口 | 请求方式 |
| - | - |
| [Flash 文生](https://docs.kapon.cloud/kling/api2/text-to-video-4-0-flash.md) | `POST /kling/text-to-video/kling-4.0-flash`，填顶层 `prompt`，画幅默认 `16:9` |
| [Flash 图生](https://docs.kapon.cloud/kling/api2/image-to-video-4-0-flash.md) | `POST /kling/image-to-video/kling-4.0-flash`，`contents` 恰好包含一张 `first_frame`，可添加 `prompt`，省略 `settings.aspect_ratio` |
| [Flash Omni](https://docs.kapon.cloud/kling/api2/omni-video-4-0-flash.md) | `POST /kling/omni-video/kling-4.0-flash`，支持首帧、参考图、参考视频、待编辑视频和可验证的现有主体，画幅默认 `adaptive` |

文生和 Omni 支持 `21:9`、`16:9`、`9:16` 和 `1:1`，Omni 还支持 `adaptive`。Flash Omni 可提供一张 `first_frame`，使用 `refer_image` 引用参考图，`feature_video` 引用参考视频，`base_video` 提供待编辑视频。单段输入视频和输入视频总时长均为 3～20 秒，包含视频主体时长。图片最多 10 张，主体最多 7 个，其中视频主体最多 3 个。视频与视频主体合计最多 5 项，其中最多一段 `base_video`，全部素材合计最多 15 项。现有主体须能验证归属、参考类型及上游凭据，Flash Omni 不接受独立 `voice` 素材。

Flash Omni 的 `settings.audio` 默认为 `native`，生成与画面匹配的声音。使用 `original` 时需提供 `base_video` 或 `feature_video`，上游优先保留基片原声，其次使用第一段参考视频的原声。下面的 3 秒参考视频示例无需主体。

```json theme={null}
{
  "contents": [
    {"type": "prompt", "text": "参考 @motion 的摆臂动作，生成庭院人物短片"},
    {"type": "feature_video", "url": "https://example.com/reference-motion.mp4", "id": "motion"}
  ],
  "settings": {"duration": 3, "resolution": "720p"},
  "options": {"external_task_id": "my-kling-flash-omni-001"}
}
```

### 查询成片

使用 `GET /kling/tasks?task_ids=<platform_id>` 按平台任务 ID 查询，或用 `GET /kling/tasks?external_task_ids=<业务编号>` 按业务编号查询。任务状态为 `succeeded` 后，从 `outputs` 读取成片地址。

## 可选的声线与主体资源

用本账号合法单人音源调用 `POST /kling/v1/general/custom-voices`：

```json theme={null}
{
  "voice_name": "角色A",
  "voice_url": "https://example.com/replace-with-your-clean-voice.wav",
  "external_task_id": "my-voice-A"
}
```

`voice_url` 和 `video_id` 必须二选一。音源为5～30秒的干净单人人声；`video_id` 仅能引用本人已有的2.6有声、数字人或对口型作品，不能直接填写任意4.0成片编号。

用 `GET /kling/v1/general/custom-voices/{id}` 查询任务，成功后从 `task_result.voices` 取得声线编号。`GET /kling/v1/general/custom-voices` 只列出本人任务；`GET /kling/v1/general/presets-voices` 返回所选上游的官方预设声线。

图片主体A通过 `POST /kling/v1/general/advanced-custom-elements`，使用 `reference_type=image_refer`、一张正面图、1～3张参考图及 `element_voice_id`。视频主体B使用 `reference_type=video_refer` 和一段3～8秒、1080p、16:9或9:16的MP4/MOV；是否绑定自动声线，以实际查询返回为准。

主体创建当前仍会返回费用上界未确认的明确拒绝。开放后应查询到主体成功，再将实际 `element_id` 填入后续请求；平台会检查资源归属及上游凭据兼容性。

4.0 目前只接受平台能够确认归属和参考类型的自建主体。官方预设主体暂不用于4.0提交，避免无法区分图片主体、视频主体而错误计费；官方预设声线可以正常查询和使用。

## 六场景的请求顺序

下面的编号和URL都是占位符，必须替换为本次流程的实际结果。S1～S4 使用 `POST /kling/omni-video/kling-4.0`；S5/S6 使用 `POST /kling/motion-control/kling-3.0`。

**S1：30秒双人三镜头。**

```json theme={null}
{
  "contents": [
    {"type":"prompt","text":"30秒三镜头，依次为@A、@B、@A。保持人物与服装连续；A用@voiceA说第一句，B用@voiceB说第二句，A说第三句。"},
    {"type":"first_frame","url":"https://example.com/first.png","id":"first"},
    {"type":"middle_frame","url":"https://example.com/middle.png","id":"middle"},
    {"type":"last_frame","url":"https://example.com/last.png","id":"last"},
    {"type":"element","element_id":"A_ELEMENT_ID","id":"A"},
    {"type":"element","element_id":"B_ELEMENT_ID","id":"B"},
    {"type":"voice","voice_id":"A_VOICE_ID","id":"voiceA"},
    {"type":"voice","voice_id":"B_PRESET_VOICE_ID","id":"voiceB"}
  ],
  "settings":{"duration":30,"resolution":"1080p","aspect_ratio":"16:9"},
  "options":{"external_task_id":"my-S1"}
}
```

**S2：混合参考、自动时长画幅。** 省略 `duration`，在提示词中指定8秒和9:16。

```json theme={null}
{
  "contents":[
    {"type":"prompt","text":"生成8秒9:16竖屏视频。@A和@B在@yard中使用@cup中的红杯，动作参考@motion，用@narrator配旁白。"},
    {"type":"refer_image","url":"https://example.com/red-cup.png","id":"cup"},
    {"type":"refer_image","url":"https://example.com/yard.png","id":"yard"},
    {"type":"feature_video","url":"https://example.com/motion.mp4","id":"motion"},
    {"type":"element","element_id":"A_ELEMENT_ID","id":"A"},
    {"type":"element","element_id":"B_ELEMENT_ID","id":"B"},
    {"type":"voice","voice_id":"NARRATOR_PRESET_ID","id":"narrator"}
  ],
  "settings":{"resolution":"1080p","aspect_ratio":"adaptive"},
  "options":{"external_task_id":"my-S2"}
}
```

**S3/S4 连续编辑。** 两轮都设置 `settings.audio=original` 保留当前基片的原声，省略时长和画幅，并各用一个业务编号。

S3 使用 S2 的实际成片 URL。

```json theme={null}
{
  "contents":[
    {"type":"prompt","text":"编辑@base，只将红杯的杯身与把手改为蓝色。保留人物、动作、构图、镜头、时长和原声。"},
    {"type":"base_video","url":"S2_OUTPUT_VIDEO_URL","id":"base"}
  ],
  "settings":{"resolution":"1080p","audio":"original"},
  "options":{"external_task_id":"my-S3"}
}
```

S4 使用 S3 的实际成片 URL，保留上一轮已经改好的蓝杯。

```json theme={null}
{
  "contents":[
    {"type":"prompt","text":"编辑@base，只将背景墙改成浅黄色。保留蓝杯、人物、动作、构图、镜头、时长和原声。"},
    {"type":"base_video","url":"S3_OUTPUT_VIDEO_URL","id":"base"}
  ],
  "settings":{"resolution":"1080p","audio":"original"},
  "options":{"external_task_id":"my-S4"}
}
```

**S5/S6：3.0动作控制。** S5 使用 `character_orientation=image`、`audio=off`，参考视频最多10秒；S6 使用 `character_orientation=video`、`audio=original` 并增加主体A，参考视频最多30秒。使用主体时必须跟随视频朝向，成片可能因有效动作裁切变短，按实际输出时长结算。

```json theme={null}
{
  "contents":[
    {"type":"image","url":"https://example.com/character.png"},
    {"type":"video","url":"https://example.com/motion.mp4"},
    {"type":"element","element_id":"A_ELEMENT_ID","id":"A"}
  ],
  "settings":{"character_orientation":"video","audio":"original","resolution":"1080p"},
  "options":{"external_task_id":"my-S6"}
}
```

## 查询、结算与重试

重复查询同一任务不会重复扣费。

4.0 输入计费时长取 `usage.input_duration`，输出计费时长取 `usage.output_duration`。视频 `outputs[].duration` 是媒体时长，可能存在帧级尾差，例如3秒计量对应3.041秒媒体，不用于替代扣费依据。无输入视频按输出计量收费；有输入视频按 `max(输入计量,输出计量)+输出计量` 收费，包含视频主体。720p/1080p 无视频输入的单价为1.0/1.5积分，有视频输入为0.6/0.9积分，再乘冻结的客户积分单价。

Kling 4.0 省略时长时按 30 秒输出上界预留。有视频输入时还预留最多 30 秒输入。1080p 分别预留 45 和 54 积分，完成后释放差额。`billing[].amount` 可能是积分、现金或测试金，客户费用按平台计费规则计算。

Flash 无视频输入时按 `usage.output_duration × 0.6` 计算积分。有视频输入时按 `0.4 × (max(usage.input_duration, usage.output_duration) + usage.output_duration)` 计算积分。省略时长时按 20 秒输出上界预留，无视频输入预留 12 积分，有视频输入按额外 20 秒输入上界预留 16 积分。按提交时锁定的客户单价结算，完成后释放差额。

声线资源包支付使用最终正积分；若供应商返回积分扣减0但余额扣减为正，则按官方每次0.05视频积分归一这次成功调用，再乘冻结客户价。不会把余额扣减的折扣金额直接当客户价格，也不会把资源包扣减0误当成免费调用。

建议每次创建提供唯一 `external_task_id`。发生响应丢失时使用返回的 `platform_id` 或业务编号查询原任务；不要重新创建。声线和主体的回调、业务编号位于顶层，视频则位于 `options`。

任务成功但缺必需用量时，生成结果与账务待处理状态分别保留，平台等待官方用量后结算；不凭媒体帧级尾差猜扣款。


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