Kling 4.0 API 接入文档

使用 VezAPI 密钥接入 Kling 4.0。下列操作共用同一个账号余额和鉴权方式。

服务地址： https://api.vezapi.com
请求头使用 Authorization: Bearer YOUR_VEZAPI_KEY。每次提交使用唯一的 Idempotency-Key，查询同一笔提交时才复用。

Kling 4.0 关键帧生成视频

POST/api/v1/jobs/createTask

模型标识： kling-4.0/keyframe-to-video

参数	类型	说明与限制
`model` 必填	`string`	用于生成任务的模型名称。必填字段。 - 该接口必须使用 `kling-4.0/keyframe-to-video` 模型可选值：`"kling-4.0/keyframe-to-video"` 默认：`"kling-4.0/keyframe-to-video"`
`callBackUrl` 可选	`string`	接收生成任务完成通知的回调 URL。可选配置，生产环境建议使用。 - 任务生成完成后，系统会向该 URL 以 POST 方式推送任务状态和结果 - 回调内容包含生成内容的 URL 及任务相关信息 - 你的回调接口需支持接收 POST 请求及 JSON 格式的请求体 - 也可选择调用任务详情接口，主动轮询任务状态 - 为确保回调安全性，请参阅 [Webhook 校验指南](/cn/common-api/webhook-verification) 了解签名验证实现方法
`input` 必填	`object`	生成任务的输入参数。
`input.prompt` 必填	`string`	视频描述，必填，最多 8000 个字符。用 `@first_frame`、`@keyframe_1`、`@keyframe_2`…、`@last_frame` 引用本次请求已传入的帧，只能引用实际提供的帧。每个 `@` 引用都必须能匹配到本次请求已传入的素材，否则请求会被拒绝。引用按已声明名称做最长匹配；若匹配到的名称以字母、数字或下划线结尾，紧跟的下一个字符不能再是字母、数字或下划线。 `minLength: 1` `maxLength: 8000`
`input.duration` 可选	`integer`	输出视频时长（秒），3–30 的整数，默认 `5`。同时限制总帧数（首帧 + 中间帧 + 尾帧）： - 3 秒 → 4 帧 - 4 秒 → 5 帧 - 5 秒 → 6 帧 - 6 秒 → 7 帧 - 7 秒 → 8 帧 - 8 秒 → 9 帧 - 9 秒及以上 → 10 帧默认：`5` `minimum: 3` `maximum: 30`
`input.resolution` 可选	`string`	输出分辨率：`720p` 或 `1080p`，默认 `720p`。可选值：`"720p", "1080p"` 默认：`"720p"`
`input.aspect_ratio` 可选	`string`	输出画面比例。只在一帧都不传时生效（纯文生视频），默认 `16:9`；传了任意帧时跟随首帧比例。可选值：`"auto", "16:9", "9:16", "1:1", "21:9"`
`input.first_frame_url` 可选	`string`	首帧图片地址。提示词里用 `@first_frame` 引用。
`input.keyframe_urls` 可选	`array`	中间帧图片地址，按时间顺序，最多 8 张（同时受 `duration` 限制）。提示词里用 `@keyframe_1`、`@keyframe_2`… 引用。默认：`[]` `maxItems: 8`
`input.last_frame_url` 可选	`string`	尾帧图片地址。提示词里用 `@last_frame` 引用。

请求示例

curl -X POST 'https://api.vezapi.com/api/v1/jobs/createTask' \
  -H 'Authorization: Bearer YOUR_VEZAPI_KEY' \
  -H 'Idempotency-Key: your-unique-request-id' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "kling-4.0/keyframe-to-video",
  "input": {
    "prompt": "The girl in @first_frame walks out, passes the street in @keyframe_1, and arrives at the party in @last_frame",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "auto"
  }
}'

返回值与错误

HTTP 200

请求成功

参数	类型	说明与限制
`code` 可选	`integer`	响应状态码 - 200: 成功 - 请求已处理完成 - 401: 未授权 - 身份验证凭据缺失或无效 - 402: 积分不足 - 账户余额不足以执行该操作 - 404: 未找到 - 请求的资源或接口不存在 - 422: 参数验证错误 - 请求参数未通过校验 - 429: 调用频率超限 - 已超出该资源的请求限制 - 433: 子密钥使用超限 - 455: 服务不可用 - 系统正在维护中 - 500: 服务器内部错误 - 处理请求时发生意外故障 - 501: 生成失败 - 内容生成任务执行失败 - 505: 功能禁用 - 当前请求的功能已被禁用可选值：`200, 401, 402, 404, 422, 429, 433, 455, 500, 501, 505`
`msg` 可选	`string`	响应消息，请求失败时返回错误描述
`data` 必填	`object`
`data.taskId` 必填	`string`	任务 ID，可结合「获取任务详情」接口查询任务状态

Kling 4.0 全能参考生成视频

POST/api/v1/jobs/createTask

模型标识： kling-4.0/reference-to-video

参数	类型	说明与限制
`model` 必填	`string`	用于生成任务的模型名称。必填字段。 - 该接口必须使用 `kling-4.0/reference-to-video` 模型可选值：`"kling-4.0/reference-to-video"` 默认：`"kling-4.0/reference-to-video"`
`callBackUrl` 可选	`string`	接收生成任务完成通知的回调 URL。可选配置，生产环境建议使用。 - 任务生成完成后，系统会向该 URL 以 POST 方式推送任务状态和结果 - 回调内容包含生成内容的 URL 及任务相关信息 - 你的回调接口需支持接收 POST 请求及 JSON 格式的请求体 - 也可选择调用任务详情接口，主动轮询任务状态 - 为确保回调安全性，请参阅 [Webhook 校验指南](/cn/common-api/webhook-verification) 了解签名验证实现方法
`input` 必填	`object`	生成任务的输入参数。
`input.prompt` 必填	`string`	视频描述，必填，最多 8000个字符。用 `@` 引用本次请求里已上传的素材： - `@image_1`、`@image_2`… 按顺序对应 `image_urls`（从 1 开始） - `@video_1`、`@video_2`… 对应 `video_urls` - `@名称` 对应 `elements` 或 `voices` 中的 `name` 每个 `@` 引用都必须能匹配到本次请求已传入的素材，否则请求会被拒绝。引用按已声明名称做最长匹配；若匹配到的名称以字母、数字或下划线结尾，紧跟的下一个字符不能再是字母、数字或下划线。 `minLength: 1` `maxLength: 8000`
`input.duration` 可选	`integer`	输出视频时长（秒），3–30 的整数，默认 `5`。默认：`5` `minimum: 3` `maximum: 30`
`input.resolution` 可选	`string`	输出分辨率：`720p` 或 `1080p`，默认 `720p`。可选值：`"720p", "1080p"` 默认：`"720p"`
`input.aspect_ratio` 可选	`string`	输出画面比例，可选。 - 不传且提供了任意参考素材时，使用 `auto` - 不传且没有任何参考素材时，使用 `16:9` 可选值：`"auto", "16:9", "9:16", "1:1", "21:9"`
`input.image_urls` 可选	`array`	参考图，最多 10 张，需公网可访问。提示词里按数组顺序用 `@image_1`、`@image_2`… 引用。每边 300–65536 像素，宽高比 0.4–2.5。默认：`[]` `maxItems: 10`
`input.video_urls` 可选	`array`	参考视频，最多 5 个，每个 2–30 秒。提示词里用 `@video_1`、`@video_2`… 引用。参考视频与 `elements` 中的视频主体合计不超过 5 个。默认：`[]` `maxItems: 5`
`input.keep_original_sound` 可选	`boolean`	是否保留参考视频的原声。只在传了 `video_urls` 时生效，默认 `false`。不传参考视频时固定生成原生音频。默认：`false`
`input.elements` 可选	`array`	仅本次任务使用的主体，最多 7 个，其中视频主体最多 3 个。提示词里用 `@名称` 引用。`image_urls`、`video_urls`、`elements`、`voices` 四类按条数合计不超过 15。默认：`[]` `maxItems: 7`
`input.elements[].name` 必填	`string`	提示词里 `@名称` 引用用的名字。1–20 个字符，仅限中文、字母、数字、下划线。与 `elements`、`voices` 中的其它名称不能重复（不区分大小写）。不能使用保留名（不区分大小写，N 为数字）：`image_N`、`video_N`、`keyframe_N`、`object_N`、`audio_N`、`first_frame`、`last_frame`。
`input.elements[].image_urls` 可选	`array`	图片主体用的 2–4 张公网可访问图片，不能与 `video_url` 同时传。第 1 张是主图（正脸或主视角），其余是副图。 `minItems: 2` `maxItems: 4`
`input.elements[].video_url` 可选	`string`	视频主体用的人物视频地址，不能与 `image_urls` 同时传。1 个视频，3–8 秒，单镜头连续画面（不能有剪切），最短边不小于 700 像素。
`input.elements[].tag` 可选	`string`	主体分类。图片主体可选，不传时按主图自动识别；视频主体固定为 `character`，传其它值会被拒绝。可选值：`"character", "animal", "prop", "costume", "scene", "effect", "others"`
`input.elements[].description` 可选	`string`	可选的主体描述，最多 100 个字符。 `maxLength: 100`
`input.elements[].voice_url` 可选	`string`	可选，绑定在该主体上的参考音频。不能单独用 `@` 引用，也不占 `voices` 名额。只有人物主体能绑定：图片主体的 `tag` 须为 `character` 或不传；视频主体不传时，若视频里有人声则自动使用。
`input.voices` 可选	`array`	仅本次任务使用的独立声音参考，最多 3 个。提示词里用 `@名称` 引用。主体上通过 `voice_url` 绑定的声音与此无关，不占名额。默认：`[]` `maxItems: 3`
`input.voices[].name` 必填	`string`	提示词里 `@名称` 引用用的名字。1–20 个字符，仅限中文、字母、数字、下划线。与 `elements`、`voices` 中的其它名称不能重复（不区分大小写）。不能使用保留名（不区分大小写，N 为数字）：`image_N`、`video_N`、`keyframe_N`、`object_N`、`audio_N`、`first_frame`、`last_frame`。
`input.voices[].audio_url` 必填	`string`	公网可访问的参考音频地址，必填。识别不到可用声音时任务失败。

请求示例

curl -X POST 'https://api.vezapi.com/api/v1/jobs/createTask' \
  -H 'Authorization: Bearer YOUR_VEZAPI_KEY' \
  -H 'Idempotency-Key: your-unique-request-id' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "kling-4.0/reference-to-video",
  "input": {
    "prompt": "@Hero sits at the desk in @video_1, picks up the doll from @image_1, and greets using @Narrator",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "auto"
  }
}'

返回值与错误

HTTP 200

请求成功

参数	类型	说明与限制
`code` 可选	`integer`	响应状态码 - 200: 成功 - 请求已处理完成 - 401: 未授权 - 身份验证凭据缺失或无效 - 402: 积分不足 - 账户余额不足以执行该操作 - 404: 未找到 - 请求的资源或接口不存在 - 422: 参数验证错误 - 请求参数未通过校验 - 429: 调用频率超限 - 已超出该资源的请求限制 - 433: 子密钥使用超限 - 455: 服务不可用 - 系统正在维护中 - 500: 服务器内部错误 - 处理请求时发生意外故障 - 501: 生成失败 - 内容生成任务执行失败 - 505: 功能禁用 - 当前请求的功能已被禁用可选值：`200, 401, 402, 404, 422, 429, 433, 455, 500, 501, 505`
`msg` 可选	`string`	响应消息，请求失败时返回错误描述
`data` 必填	`object`
`data.taskId` 必填	`string`	任务 ID，可结合「获取任务详情」接口查询任务状态

任务状态与回调

异步任务请保存返回的 taskId。调用 GET /api/v1/jobs/recordInfo?taskId=... 查询，或在创建时设置 callBackUrl。只有任务所属账号可以查询任务或基于任务创建派生资源。

超时可能表示请求已经受理。请在控制台查看原请求，不要自动新建任务。回调可能重试并重复到达，请使用 X-VezAPI-Event-Id 去重。

文件、日志与计费

生成媒体通常随上游保留 14 天，上传文件在 24 小时后失效。请在过期前保存所需文件。VezAPI 仅流式转发已登记资源，不提供永久作品库。请求日志保留两个自然月。

调用前预留积分，最终按实际优惠扣分 1:1 结算。用量不明时暂停新付费请求。若保护其他任务预留后余额不足以结算，会保留待结算记录，补足余额后再扣费；模型用量不会将钱包扣成负数。按时长计价的输入文件由服务端读取时长，读取失败时不提交模型任务。