Kling 4.0 与 Flash · 快速开始

客户调用下文 /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 字段。

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

{
  "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。

{
  "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 指明如何使用它。以下示例无需主体或声线。

{
  "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 文生	`POST /kling/text-to-video/kling-4.0-flash`，填顶层 `prompt`，画幅默认 `16:9`
Flash 图生	`POST /kling/image-to-video/kling-4.0-flash`，`contents` 恰好包含一张 `first_frame`，可添加 `prompt`，省略 `settings.aspect_ratio`
Flash Omni	`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 秒参考视频示例无需主体。

{
  "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：

{
  "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秒双人三镜头。

{
  "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。

{
  "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。

{
  "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，保留上一轮已经改好的蓝杯。

{
  "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秒。使用主体时必须跟随视频朝向，成片可能因有效动作裁切变短，按实际输出时长结算。

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

概述

API 2.0

Legacy 视频生成

图像生成

视频编辑

任务管理

Kling 4.0 与 Flash · 快速开始

接口和默认值

快速开始

文生视频

关键帧图生视频

Omni 4.0 参考视频与编辑

Kling 4.0 Flash

查询成片

可选的声线与主体资源

六场景的请求顺序

查询、结算与重试