Kling 系列
- 文生视频、图生视频、首尾帧、视频编辑与延长，统一一个模型入口
- 按传入的素材与 omni_reference_task_type 自动判定任务类型
- 每个输出都带立体声音轨
认证
All endpoints authenticate with a Bearer token.
Get an API key: open the console and create one.
Add it to the request header:
Authorization: Bearer YOUR_OAIRoute_KEY请求参数
提交成功只返回任务 ID，不含视频本身。拿成片用 task_id 轮询获取任务状态，成片地址在 result.videos[0].url，该地址约 24 小时后过期，请及时转存。
视频模型 ID，取值见下方模型列表。
画面描述。除纯图生视频外必填。
支持用 @Image1、@Video1、@Audio1 引用素材，编号按素材数组顺序从 1 开始。编辑模式下输入视频是 @Video1，参考图依次是 @Image1、@Image2。
时长，单位秒，默认 5。
取值 3 到 30。编辑任务省略时沿用输入视频长度；延长任务只计算新增片段的秒数。
输出分辨率，取值 720p、1080p，默认 720p。
V4 只认这个字段，不再支持 mode。
输出画幅，取值 16:9、9:16、1:1、21:9，参考生视频还可传 auto。
默认值随模式变化：文生视频 16:9，图生视频沿用首帧，参考生视频 auto，编辑沿用输入视频，延长不接受该字段。
图生视频最多 2 张，第一张是首帧、第二张是尾帧。
参考生视频与编辑最多 10 张，全部按参考图处理。地址必须公网可访问。
带角色的图片数组，每项含 url 与 role。
role 取值 first_frame、last_frame、keyframe（别名 middle_frame，按顺序最多 8 张）、reference_image。首尾帧与关键帧合计不超过 10 张。
首帧地址，等价于 image_with_roles 里的一条 first_frame，也等价于 image_urls 的第一项。
图生视频的尾帧，或延长任务的目标尾帧。
参考视频，最多 5 段，合计不超过 30 秒。
编辑与延长也可以改成在这里传 1 段，并配合 omni_reference_task_type。
编辑或延长任务的输入视频，必须同时把 omni_reference_task_type 设为 edit 或 extend。
编辑输入不得短于 3 秒，超过 30 秒会截取前 30 秒。
参考音频，最多 3 段，每段 5 到 30 秒。
任务类型，取值 auto、reference、edit、extend，默认 auto。
auto 由素材推断；reference 强制把 image_urls 里的图当参考图；edit 与 extend 必须配输入视频。
音轨处理方式，取值 origin 保留原始音轨、auto 重新生成。
编辑默认保留原音，带参考视频的参考生视频默认重新生成。延长任务不支持该字段。
A successful submission returns only the task ID, not the video itself. Poll Get task status with the task_id; the video URL is at result.videos[0].url, expires after about 24 hours, so copy it promptly.
The video model ID; see the model list below.
The scene description. Required except for pure image to video.
Reference assets with @Image1, @Video1, @Audio1; numbering starts at 1 in array order. In edit mode the input video is @Video1, and reference images are @Image1, @Image2, and so on.
Duration in seconds, default 5.
Range 3 to 30. Edit tasks inherit the input video's length when omitted; extension tasks count only the newly added seconds.
Output resolution: 720p or 1080p, default 720p.
V4 recognizes only this field and no longer supports mode.
Output framing: 16:9, 9:16, 1:1, 21:9; reference to video also accepts auto.
Defaults vary by mode: 16:9 for text to video, the first frame's ratio for image to video, auto for reference to video, the input video's ratio for editing, and extension doesn't accept this field.
For image to video, up to 2: the first is the opening frame and the second the closing frame.
For reference to video and editing, up to 10, all treated as reference images. Addresses must be publicly reachable.
An array of images with roles, each with url and role.
role is first_frame, last_frame, keyframe (alias middle_frame, up to 8 in order), or reference_image. First/last frames plus keyframes total no more than 10.
The first-frame address; equivalent to a first_frame entry in image_with_roles, and to the first item of image_urls.
The closing frame for image to video, or the target closing frame for extension tasks.
Reference videos, up to 5, totaling no more than 30 seconds.
Editing and extension can alternatively pass 1 here, together with omni_reference_task_type.
The input video for edit or extension tasks; omni_reference_task_type must be set to edit or extend at the same time.
Edit input must be at least 3 seconds; anything over 30 seconds is trimmed to the first 30.
Reference audio, up to 3, each 5 to 30 seconds.
The task type: auto, reference, edit, or extend, default auto.
auto infers from the media; reference forces images in image_urls to be treated as reference images; edit and extend require an input video.
Audio handling: origin keeps the original track, auto regenerates it.
Editing keeps the original audio by default; reference to video with a reference video regenerates by default. Extension doesn't support this field.
模式判定
不带任何图片或视频字段就是文生视频。
带 image_urls 或 image_with_roles 走图生视频：1 张是首帧，2 张是首尾帧，带 reference_image 角色则转为参考图。
带 video_urls 是参考视频；带 video_url 且 omni_reference_task_type 为 edit 或 extend 是视频编辑或延长。
参考图、参考视频、参考音频合计不超过 15 项。
No image or video fields means text to video.
With image_urls or image_with_roles it's image to video: 1 image is the first frame, 2 are the first and last frames, and a reference_image role turns them into reference images.
With video_urls it's reference video; with video_url and omni_reference_task_type set to edit or extend it's video editing or extension.
Reference images, reference videos, and reference audio together total no more than 15 items.
支持的模型列表
| 模型 ID | 定位 |
|---|---|
kling-v4 | 当前主力，五种任务类型共用一个模型名，由素材推断模式 |
kling-v3 | 上一代旗舰，支持 std / pro / 4k 三档与多镜头分镜 |
kling-v3-omni | v3 的全能版，额外支持视频编辑与主体参考 |
kling-v2-6 | 支持 5 秒与 10 秒两档，pro 档可自动生成音轨 |
kling-video-o1 | 面向镜头语言的版本 |
kling-3.0-turbo | 高速档，适合批量预览 |
v3 系列使用 mode 指定画质档位：std 对应 720P、pro 对应 1080P、4k 对应 4K。v4 不再支持 mode，改用 resolution。
| Model ID | Positioning |
|---|---|
kling-v4 | Current main model; five task types share one model name, with the mode inferred from media |
kling-v3 | Previous flagship; supports the std / pro / 4k tiers and multi-shot storyboarding |
kling-v3-omni | The all-round v3 variant, adding video editing and subject reference |
kling-v2-6 | Supports 5-second and 10-second tiers; the pro tier can auto-generate an audio track |
kling-video-o1 | A version oriented toward camera language |
kling-3.0-turbo | High-speed tier, suited to batch previews |
The v3 series uses mode for the quality tier: std maps to 720P, pro to 1080P, and 4k to 4K. V4 no longer supports mode and uses resolution instead.
使用限制
mode、negative_prompt、watermark: true、audio: false、multi_shot、multi_prompt、element_list、camera_control在 V4 上会被拒绝- 单独传
video_url而不指定edit或extend会返回 400，参考视频请用video_urls - 编辑任务输入不足 3 秒返回 400，探测输入时长失败也返回 400，且不扣费
- 失败任务全额退款
mode,negative_prompt,watermark: true,audio: false,multi_shot,multi_prompt,element_list, andcamera_controlare rejected on V4- Passing
video_urlalone withouteditorextendreturns a 400; usevideo_urlsfor reference video - Edit tasks with input under 3 seconds return a 400, as does failing to probe the input duration, and neither is billed
- Failed tasks are refunded in full
响应
提交成功返回统一的受理结构：
{
"code": 200,
"data": [
{
"status": "submitted",
"task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
}
]
}状态码，200 表示任务已受理。
本次提交的任务列表，逐项提交时按顺序排列。
受理状态，提交成功时为 submitted。
任务 ID，用它轮询结果。
A successful submission returns the standard accepted structure:
{
"code": 200,
"data": [
{
"status": "submitted",
"task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
}
]
}The status code; 200 means the task was accepted.
The list of tasks submitted this time, in order when submitting item by item.
The acceptance status; submitted on success.
The task ID; use it to poll for the result.
错误
| HTTP | type | 说明 |
|---|---|---|
| 400 | invalid_request_error | 请求参数无效，或参数组合冲突 |
| 401 | authentication_error | 身份验证失败，需检查 API Key |
| 402 | payment_required | 账户余额不足，需先充值 |
| 429 | rate_limit_error | 调用频率过高，稍后重试 |
参数错误在提交阶段同步返回，不创建任务、不扣费。
| HTTP | type | Notes |
|---|---|---|
| 400 | invalid_request_error | Invalid parameters, or a conflicting combination |
| 401 | authentication_error | Authentication failed; check the API key |
| 402 | payment_required | Insufficient account balance; top up first |
| 429 | rate_limit_error | Too many calls; retry later |
Parameter errors are returned synchronously at submission, creating no task and charging nothing.
For more status codes and retry guidance see Error codes and rate limits; for troubleshooting steps on common errors see the FAQ.
查询任务
GET /v1/tasks/{task_id} 返回任务进度与结果，status 为 completed 时成片地址在 result.videos[0].url，元素带 expires_at 过期时间戳。
建议每 5 到 10 秒轮询一次，客户端总超时设为 10 到 15 分钟。status 取值 pending、processing、completed、failed、cancelled，以状态判定完成，不要依赖 progress。
失败任务自动退回费用，error.message 给出原因。
GET /v1/tasks/{task_id} returns task progress and results; once status is completed, the video URL is at result.videos[0].url, with an expires_at timestamp on the element.
Poll every 5 to 10 seconds, with a 10 to 15 minute client timeout. status is one of pending, processing, completed, failed, cancelled; judge completion by status, not by progress.
Failed tasks are refunded automatically, with the reason in error.message.