跳至正文
EN
获取 API Key
☰

Kling O3 API 接入文档

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

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

Kling 3.0 Omni 图生视频

POST/api/v1/jobs/createTask

模型标识： kling-3.0-omni/image-to-video

参数类型说明与限制
model
必填		string

用于生成任务的模型名称。必填字段。 - 该接口必须使用 `kling-3.0-omni/image-to-video` 模型

可选值："kling-3.0-omni/image-to-video"

默认："kling-3.0-omni/image-to-video"

callBackUrl
可选		string

接收生成任务完成通知的回调 URL。可选配置，生产环境建议使用。 - 任务生成完成后，系统会向该 URL 以 POST 方式推送任务状态和结果 - 回调内容包含生成内容的 URL 及任务相关信息 - 你的回调接口需支持接收 POST 请求及 JSON 格式的请求体 - 也可选择调用任务详情接口，主动轮询任务状态 - 为确保回调安全性，请参阅 [Webhook 校验指南](/cn/common-api/webhook-verification) 了解签名验证实现方法

input
可选		object

生成任务的输入参数。规则：①customize_multi_shots 与 prefer_multi_shots 不能同为 true;②customize_multi_shots 为 true 时须传 1–6 个 multi_prompt 镜头（单镜头 1–12 秒，合计 ≤15 秒）;③否则不要传 multi_prompt;④aspect_ratio 默认且只能为 auto；仅 customize_multi_shots 为 true 时改为 16:9 / 9:16 / 1:1。

请求示例
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-omni/image-to-video",
  "callBackUrl": "https://example.com/input.png",
  "input": {
    "prompt": "A happy golden retriever running across a grassy field",
    "image_urls": [
      "https://example.com/input.png"
    ],
    "customize_multi_shots": false,
    "audio": false,
    "resolution": "720p",
    "aspect_ratio": "auto",
    "duration": 5,
    "elements": []
  }
}'
返回值与错误

HTTP 200

请求成功

参数类型说明与限制
code
可选		integer

Status code of the request. The HTTP status is 200 even when the request fails, so always check this field: 200 means success; any other value means the request failed and msg describes the reason. Common values: 401 invalid or missing API key; 402 insufficient credits; 429 rate limit exceeded; 422 or 500 the request could not be processed (read msg and check your parameters before retrying).

可选值：200, 401, 402, 404, 422, 429, 433, 455, 500, 501, 505

msg
可选		string

Response message, error description upon failure

data
必填		object
data.taskId
必填		string

The task ID can be used with the "Get Task Details" endpoint to query the task status.

Kling 3.0 Omni Reference-To-Video

POST/api/v1/jobs/createTask

模型标识： kling-3.0-omni/reference-to-video

参数类型说明与限制
model
必填		string

用于生成任务的模型名称。必填字段。 - 该接口必须使用 `kling-3.0-omni/reference-to-video` 模型

可选值："kling-3.0-omni/reference-to-video"

默认："kling-3.0-omni/reference-to-video"

callBackUrl
可选		string

接收生成任务完成通知的回调 URL。可选配置，生产环境建议使用。 - 任务生成完成后，系统会向该 URL 以 POST 方式推送任务状态和结果 - 回调内容包含生成内容的 URL 及任务相关信息 - 你的回调接口需支持接收 POST 请求及 JSON 格式的请求体 - 也可选择调用任务详情接口，主动轮询任务状态 - 为确保回调安全性，请参阅 [Webhook 校验指南](/cn/common-api/webhook-verification) 了解签名验证实现方法

input
必填		object

生成任务的输入参数。规则：①customize_multi_shots 与 prefer_multi_shots 不能同为 true;②customize_multi_shots 为 true 时须传 1–6 个 multi_prompt 镜头（单镜头 1–12 秒，合计 ≤15 秒）;③否则不要传 multi_prompt。

请求示例
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-omni/reference-to-video",
  "callBackUrl": "https://example.com/input.png",
  "input": {
    "prompt": "Generate a video of the character walking along a city street, using the character appearance in the reference images.",
    "image_urls": [
      "https://example.com/input.png"
    ],
    "customize_multi_shots": true,
    "multi_prompt": [
      {
        "prompt": "A wide shot of the character walking through the city.",
        "duration": 2
      },
      {
        "prompt": "A close-up of the character looking toward the camera.",
        "duration": 3
      }
    ],
    "audio": true,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "duration": 5,
    "elements": []
  }
}'
返回值与错误

HTTP 200

请求成功

参数类型说明与限制
code
可选		integer

Status code of the request. The HTTP status is 200 even when the request fails, so always check this field: 200 means success; any other value means the request failed and msg describes the reason. Common values: 401 invalid or missing API key; 402 insufficient credits; 429 rate limit exceeded; 422 or 500 the request could not be processed (read msg and check your parameters before retrying).

可选值：200, 401, 402, 404, 422, 429, 433, 455, 500, 501, 505

msg
可选		string

Response message, error description upon failure

data
必填		object
data.taskId
必填		string

The task ID can be used with the "Get Task Details" endpoint to query the task status.

Kling 3.0 Omni 文生视频

POST/api/v1/jobs/createTask

模型标识： kling-3.0-omni/text-to-video

参数类型说明与限制
model
必填		string

用于生成任务的模型名称。必填字段。 - 该接口必须使用 `kling-3.0-omni/text-to-video` 模型

可选值："kling-3.0-omni/text-to-video"

默认："kling-3.0-omni/text-to-video"

callBackUrl
可选		string

接收生成任务完成通知的回调 URL。可选配置，生产环境建议使用。 - 任务生成完成后，系统会向该 URL 以 POST 方式推送任务状态和结果 - 回调内容包含生成内容的 URL 及任务相关信息 - 你的回调接口需支持接收 POST 请求及 JSON 格式的请求体 - 也可选择调用任务详情接口，主动轮询任务状态 - 为确保回调安全性，请参阅 [Webhook 校验指南](/cn/common-api/webhook-verification) 了解签名验证实现方法

input
必填		object

生成任务的输入参数配置。规则：①customize_multi_shots 与 prefer_multi_shots 不能同为 true;②customize_multi_shots 为 true 时须传 1–6 个 multi_prompt 镜头（单镜头 1–12 秒，合计 ≤15 秒）;③否则不要传 multi_prompt。

input.prompt
必填		string

视频的文本描述。去除首尾空白字符后不能为空，且长度不得超过 3072 个字符。

minLength: 1

maxLength: 3072

input.customize_multi_shots
可选		boolean

可选，默认 false。设为 true 为自定义分镜（需传 multi_prompt）。

默认：false

input.prefer_multi_shots
可选		boolean

是否开启智能分镜模式。此字段与 `customize_multi_shots` 互斥。 两者可以同时为 `false`，但不能同时为 `true`。

input.multi_prompt
可选		array

自定义分镜列表。当 `customize_multi_shots` 为 `true` 时，该字段为必填且不能为空，最多支持 6 个分镜；当 `customize_multi_shots` 为 `false` 时，该字段必须为空数组或省略不传。

默认：[]

maxItems: 6

input.multi_prompt[].prompt
必填		string

当前分镜的视频描述，长度不得超过 512 个字符。

minLength: 1

maxLength: 512

input.multi_prompt[].duration
必填		integer

当前镜头时长（秒），1–12；所有镜头合计不超过 15 秒。

minimum: 1

maximum: 12

input.elements
可选		array

一次性主体素材列表，默认值为空数组。仅有多图主体时最多可以上传7个主体 仅有视频角色主体时，视频角色主体数量不得超过3。 同时有视频角色主体和多图主体时，视频角色主体数量不得超过3，多图主体不得超过4。

默认：[]

input.elements[].name
必填		string

主体名称。在同一个请求中必须唯一。可在 `prompt` 字段中通过 `@名称` 的方式进行引用。

minLength: 1

input.elements[].description
必填		string

主体素材的文本描述。

minLength: 1

input.elements[].element_input_urls
必填		array

多图主体的图片 URL 列表（需传入 2 至 4 张图片），或视频角色主体的视频 URL（仅需传入 1 个视频）。图片和视频不能混合传入。支持 HTTP、HTTPS 和 OSS 协议的地址。

minItems: 1

maxItems: 4

input.elements[].element_input_audio_urls
可选		array

主体音频素材的 URL 列表（可选配置）。支持 HTTP、HTTPS 和 OSS 协议的地址。

默认：[]

input.audio
可选		boolean

是否为生成的视频添加音频。`true` 表示开启音频，`false` 表示关闭音频。

默认：false

input.resolution
可选		string

生成视频的分辨率。可选值包括：`720p`（输出 720P 视频）、`1080p`（输出 1080P 视频）以及 `4k`（输出 4K 视频）。

可选值："720p", "1080p", "4k"

默认："720p"

input.aspect_ratio
可选		string

生成视频的画幅比例。支持的值为 `16:9`、`9:16` 和 `1:1`。

可选值："16:9", "9:16", "1:1"

默认："16:9"

input.duration
可选		integer

视频的总时长（单位：秒）。支持的范围为 3 至 15 秒，默认值为 5 秒。

可选值：3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15

默认：5

minimum: 3

maximum: 15

请求示例
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-omni/text-to-video",
  "callBackUrl": "https://example.com/input.png",
  "input": {
    "prompt": "A wide shot of the fox entering the snowy forest.",
    "customize_multi_shots": true,
    "multi_prompt": [
      {
        "prompt": "A wide shot of the fox entering the snowy forest.",
        "duration": 2
      },
      {
        "prompt": "A cinematic close-up of the fox looking toward the sunrise.",
        "duration": 3
      }
    ],
    "audio": false,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "duration": 5
  }
}'
返回值与错误

HTTP 200

请求成功

参数类型说明与限制
code
可选		integer

Status code of the request. The HTTP status is 200 even when the request fails, so always check this field: 200 means success; any other value means the request failed and msg describes the reason. Common values: 401 invalid or missing API key; 402 insufficient credits; 429 rate limit exceeded; 422 or 500 the request could not be processed (read msg and check your parameters before retrying).

可选值：200, 401, 402, 404, 422, 429, 433, 455, 500, 501, 505

msg
可选		string

Response message, error description upon failure

data
必填		object
data.taskId
必填		string

The task ID can be used with the "Get Task Details" endpoint to query the task status.

Kling 3.0 Omni Transformation

POST/api/v1/jobs/createTask

模型标识： kling-3.0-omni/transformation

参数类型说明与限制
model
必填		string

用于生成任务的模型名称。必填字段。 - 该接口必须使用 `kling-3.0-omni/transformation` 模型

可选值："kling-3.0-omni/transformation"

默认："kling-3.0-omni/transformation"

callBackUrl
可选		string

接收生成任务完成通知的回调 URL。可选配置，生产环境建议使用。 - 任务生成完成后，系统会向该 URL 以 POST 方式推送任务状态和结果 - 回调内容包含生成内容的 URL 及任务相关信息 - 你的回调接口需支持接收 POST 请求及 JSON 格式的请求体 - 也可选择调用任务详情接口，主动轮询任务状态 - 为确保回调安全性，请参阅 [Webhook 校验指南](/cn/common-api/webhook-verification) 了解签名验证实现方法

input
必填		object

生成任务的输入参数。

input.prompt
可选		string

视频描述。去除首尾空白后不能为空，最长 3072 字符。

minLength: 1

maxLength: 3072

input.video_urls
可选		array

视频地址数组，必须且只能传入 1 个视频。支持 HTTP、HTTPS 和 OSS 地址。视频支持 MP4、MOV 格式；单个文件不超过 200 MB；时长为 3 至 15.5 秒；宽高为 700 至 4553 px；总像素不超过 8,294,400；宽高比为 0.4 至 2；帧率为 24 至 60 fps。

minItems: 1

maxItems: 1

input.image_urls
可选		array

图片地址数组，图片数量上限与参考主体数量和参考主体类型有关，其中：仅有多图主体时，参考图片与多图主体数量之和不得超过4。 不同时支持视频角色主体和多图主体或参考图片。支持 HTTP、HTTPS 和 OSS 地址。图片支持 JPG、JPEG、PNG 格式；单个文件不超过 50 MB；宽高均不小于 300 px；宽高比为 0.4 至 2.5。

maxItems: 4

input.duration
可选		string

视频时长。视频加图片时可保留该字段配置。

input.resolution
可选		string

视频分辨率。`720p` 表示输出 720P 视频，`1080p` 表示输出 1080P 视频，`4k` 表示输出 4K 视频。

可选值："720p", "1080p", "4k"

默认："720p"

input.aspect_ratio
可选		string

视频画幅比例。仅视频输入时只能为 `auto`；视频加图片时支持 `16:9`、`9:16`、`1:1`，不支持 `auto`。

可选值："16:9", "9:16", "1:1", "auto"

默认："16:9"

input.audio
可选		boolean

有视频输入时不生成音频，请传 false。

可选值：false, true

input.elements
可选		array

一次性主体素材列表，默认值为空数组。仅有多图主体时最多可以上传7个主体 仅有视频角色主体时，视频角色主体数量不得超过3。 同时有视频角色主体和多图主体时，视频角色主体数量不得超过3，多图主体不得超过4。

默认：[]

input.elements[].name
必填		string

主体名称。在同一个请求中必须唯一。可在 `prompt` 字段中通过 `@名称` 的方式进行引用。

minLength: 1

input.elements[].description
必填		string

主体素材的文本描述。

minLength: 1

input.elements[].element_input_urls
必填		array

多图主体的图片 URL 列表（需传入 2 至 4 张图片），或视频角色主体的视频 URL（仅需传入 1 个视频）。图片和视频不能混合传入。支持 HTTP、HTTPS 和 OSS 协议的地址。

minItems: 1

maxItems: 4

input.elements[].element_input_audio_urls
可选		array

主体音频素材的 URL 列表（可选配置）。支持 HTTP、HTTPS 和 OSS 协议的地址。

默认：[]

请求示例
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-omni/transformation",
  "callBackUrl": "https://example.com/input.png",
  "input": {
    "prompt": "Transform the input video into a cinematic night scene while preserving the character movements from the original video.",
    "video_urls": [
      "https://example.com/input.png"
    ],
    "resolution": "720p",
    "aspect_ratio": "auto",
    "audio": false
  }
}'
返回值与错误

HTTP 200

请求成功

参数类型说明与限制
code
可选		integer

Status code of the request. The HTTP status is 200 even when the request fails, so always check this field: 200 means success; any other value means the request failed and msg describes the reason. Common values: 401 invalid or missing API key; 402 insufficient credits; 429 rate limit exceeded; 422 or 500 the request could not be processed (read msg and check your parameters before retrying).

可选值：200, 401, 402, 404, 422, 429, 433, 455, 500, 501, 505

msg
可选		string

Response message, error description upon failure

data
必填		object
data.taskId
必填		string

The task ID can be used with the "Get Task Details" endpoint to query the task status.

任务状态与回调

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

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

文件、日志与计费

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

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