Kling 3.0 API 接入文档

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

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

Kling 3.0

POST/api/v1/jobs/createTask

模型标识： kling-3.0/video

参数	类型	说明与限制
`model` 必填	`string`	用于生成任务的模型名称。必填字段。 - 该接口必须使用 `kling-3.0/video` 模型可选值：`"kling-3.0/video"` 默认：`"kling-3.0/video"`
`callBackUrl` 可选	`string`	接收生成任务完成通知的回调 URL。可选配置，生产环境建议使用。 - 任务生成完成后，系统会向该 URL 以 POST 方式推送任务状态和结果 - 回调内容包含生成内容的 URL 及任务相关信息 - 你的回调接口需支持接收 POST 请求及 JSON 格式的请求体 - 也可选择调用任务详情接口，主动轮询任务状态 - 为确保回调安全性，请参阅 [Webhook 校验指南](/cn/common-api/webhook-verification) 了解签名验证实现方法
`input` 可选	`object`	生成任务的输入参数
`input.prompt` 可选	`string`	multi_shots 为 false 时必填，最长 2500 字符。
`input.image_urls` 可选	`array`	首尾帧图片链接。可选。当 multi_shots 为 false 时：长度为 2 时，索引 0 为首帧，索引 1 为尾帧；长度为 1 时，数组项作为首帧。当 multi_shots 为 true 时：只支持首帧。
`input.sound` 必填	`boolean`	必填。是否同时生成音频（对白、音效、环境声），影响价格。
`input.duration` 必填	`string`	必填。视频时长（秒），3–15（字符串，如 "5"）。多镜头模式下实际时长与计费按各镜头时长之和（3–15 秒），duration 请填同一合计值。可选值：`"3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15"`
`input.aspect_ratio` 可选	`string`	传了 image_urls 时可省略（输出比例跟随首帧）。文生视频请显式传入：16:9、9:16 或 1:1。可选值：`"16:9", "9:16", "1:1"`
`input.mode` 必填	`string`	必填。生成模式。std 为标准分辨率，pro 为高分辨率，4K 为 4K 分辨率。分辨率映射： - std 模式：16:9 (1280×720), 9:16 (720×1280), 1:1 (720×720) - pro 模式：16:9 (1920×1080), 9:16 (1080×1920), 1:1 (1080×1080) - 4K 模式：16:9 (3840×2160), 9:16 (2160×3840), 1:1 (2160×2160) 可选值：`"std", "pro", "4K"`
`input.multi_shots` 必填	`boolean`	必填。是否多镜头。true 时为多镜头，false 为单镜头。
`input.multi_prompt` 可选	`array`	镜头提示词。multi_shots 为 true 时生效。用来描述每一段镜头的文案和时长，最多支持 5 段，每段时长 1-12 秒，如果需要使用 element，则需加在 prompt 后。
`input.multi_prompt[].prompt` 必填	`string`	该镜头的提示词文本，单个镜头最多500字符，每个@element会占37个字符。 `maxLength: 500`
`input.multi_prompt[].duration` 必填	`integer`	该镜头的时长（单位：秒）。范围：1-12。 `minimum: 1` `maximum: 12`
`input.kling_elements` 可选	`array`	引用元素。prompt 中引用元素的详细信息。单个任务最多引用三个元素。 `maxItems: 3`
`input.kling_elements[].name` 必填	`string`	元素名称，在 prompt 中使用 @ 前缀引用（如 @element_dog）
`input.kling_elements[].description` 必填	`string`	元素描述
`input.kling_elements[].element_input_urls` 必填	`array`	2–4 张图片（JPG/PNG，单张不超过 10MB），或 1 个视频（MP4/MOV）。
`input.kling_elements[].element_input_audio_urls` 可选	`array`	可选。角色音频素材 URL 列表。音频时长必须为 5-30 秒
`input.kling_elements[].start_time` 可选	`integer`	视频角色素材截取开始时间，单位毫秒。仅 element_input_urls 上传视频时生效。未传时默认 0。默认：`0`
`input.kling_elements[].end_time` 可选	`integer`	视频角色素材截取结束时间，单位毫秒。仅 element_input_urls 上传视频时生效。必须大于 start_time，且 end_time - start_time 必须在 3000-8000ms。默认：`8000`

请求示例

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-3.0/video",
  "input": {
    "prompt": "In a bright rehearsal room, sunlight streams through the window@element_dog",
    "sound": true,
    "duration": "5",
    "aspect_ratio": "16:9",
    "mode": "pro",
    "multi_shots": false
  }
}'

返回值与错误

HTTP 200

请求成功

参数	类型	说明与限制
`data` 可选	`object`
`data.code` 必填	`string`	Response status code - 200: Success - Request has been processed successfully - 401: Unauthorized - Authentication credentials are missing or invalid - 402: Insufficient Credits - Account does not have enough credits to perform the operation - 404: Not Found - The requested resource or endpoint does not exist - 422: Validation Error - The request parameters failed validation checks - 429: Rate Limited - Request limit has been exceeded for this resource - 433: Request Limit - Sub-key Usage Exceeds Limit - 455: Service Unavailable - System is currently undergoing maintenance - 500: Server Error - An unexpected error occurred while processing the request - 501: Generation Failed - Content generation task failed - 505: Feature Disabled - The requested feature is currently disabled
`data.msg` 必填	`string`	Response message, error description when failed
`data.taskId` 可选	`string`	Task ID, can be used with Get Task Details endpoint to query task status

任务状态与回调

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

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

文件、日志与计费

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

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