Kling 视频生成 API

本文介绍如何通过本服务调用 Kling 视频生成模型。客户端使用本服务签发的 API Token；示例中的 BASE_URL 和 API_TOKEN 请替换为实际值。

扩展参数统一放在 metadata 中，字段名使用 PascalCase，例如 Sound、ImageTail、CameraControl。不要在 metadata 中传 Model、Prompt、Image、Duration、Mode，这些字段由顶层参数生成。

接口一览

方法	路径	用途	响应风格
`POST`	`/v1/videos`	创建视频生成任务	OpenAI Video 对象
`GET`	`/v1/videos/{task_id}`	查询任务状态和结果	OpenAI Video 对象
`GET`	`/v1/videos/{task_id}/content`	下载生成的视频	视频二进制
`POST`	`/v1/video/generations`	创建视频生成任务	旧兼容格式
`GET`	`/v1/video/generations/{task_id}`	查询任务状态和结果	旧兼容格式
`POST`	`/v1/videos/generations`	创建视频生成任务	旧兼容格式

能力路由

本服务会根据图片输入自动选择文生视频或图生视频：

请求形态	能力	说明
不传 `image` / `images`	文生视频	只使用文字提示词生成视频
传入 `image`	图生视频	使用 `image` 作为首帧或参考图
传入 `images`	图生视频	仅使用第一张图片作为首帧或参考图；尾帧请用 `metadata.ImageTail`

支持模型

API 模型名	上游模型码	文生视频	图生视频
`kling-v1`	`v1.0`	支持	不建议使用
`kling-v1-5`	`v1.5`	支持	不建议使用
`kling-v1-6`	`v1.6`	支持	支持
`kling-v2-master`	`v2.0`	支持	支持
`kling-v2-1`	`v2.1`	不建议使用	支持
`kling-v2-1-master`	`v2.1m`	支持	不建议使用
`kling-v2-5-turbo`	`v2.5`	支持	支持
`kling-v2-6`	`v2.6`	支持	支持
`kling-v3`	`v3.0`	支持	支持

kling-v2-1 对应图生视频文档中的 v2.1；kling-v2-1-master 对应文生视频文档中的 v2.1m。新接入请按能力选择模型，不要在图生视频中混用 kling-v2-1-master。

鉴权

所有请求都使用 Bearer Token：

http

Authorization: Bearer sk-...
Content-Type: application/json

请求参数

顶层参数

参数名称	类型	必选	描述
`model`	string	是	要调用的 Kling 模型名称，必须使用“支持模型”表中的 API 模型名，例如 `kling-v2-6`、`kling-v3`。服务会把该名称转换为上游模型码。
`prompt`	string	是	视频内容描述。建议同时描述主体、动作、场景、镜头语言和风格，例如“雨夜街头，一名男子撑伞走过霓虹灯牌，镜头缓慢跟拍，电影感”。最长建议 2500 字符。
`image`	string	图生视频必选	单张首帧或参考图。支持公网 HTTP/HTTPS URL 或 Base64 图片。传入后请求按图生视频处理。图片建议不超过 10MB，分辨率不小于 300x300，宽高比在 1:2.5 到 2.5:1 之间，格式为 JPG、JPEG 或 PNG。
`images`	string[]	否	图片 URL/Base64 数组。当前 Kling 图生视频只使用第一张；如需尾帧，不要放第二张到 `images`，应使用 `metadata.ImageTail`。
`duration`	integer/string	否	视频秒数。省略默认 `5`。可用值见下方 `Duration` 参数。
`mode`	string	否	生成模式。省略默认 `std`。可用值见下方 `Mode` 参数。
`metadata`	object	否	扩展参数对象。只能放下方“metadata 参数”表中的字段，字段名使用 PascalCase。

metadata 参数

metadata 中不要包含 Model、Prompt、Image、Duration、Mode，这些字段会由顶层 model、prompt、image / images、duration、mode 生成。若重复传入，容易造成请求内容和计费模型不一致。

参数名称	类型	必选	适用模型 / 能力	描述
`ImageTail`	object	否	`kling-v1-6`、`kling-v2-master`、`kling-v2-1`、`kling-v2-5-turbo`、`kling-v2-6`、`kling-v3`；仅图生	尾帧图。对象字段：`Url` string，公网图片地址；`Base64` string，图片 Base64。二选一。图片要求同 `image`。不要与 `CameraControl`、`StaticMask`、`DynamicMasks` 同时传。
`AspectRatio`	string	否	全部文生模型	输出画幅。可选 `16:9`、`9:16`、`1:1`，省略默认 `16:9`。图生视频由输入图决定画幅，不要传该字段。
`NegativePrompt`	string	否	全部模型；文生、图生	负向提示词，用于减少模糊、畸变、低清晰度等问题。最长建议 2500 字符。
`CfgScale`	number	否	`kling-v1`、`kling-v1-5`、`kling-v1-6`、`kling-v2-1`、`kling-v2-1-master`、`kling-v3`	提示词相关性强度，取值 `[0,1]`，省略默认 `0.5`。不要用于 `kling-v2-master`、`kling-v2-5-turbo`、`kling-v2-6`。
`Sound`	string	否	`kling-v2-6`、`kling-v3`；文生、图生	是否生成声音。可选 `on`、`off`。`kling-v2-6` 使用 `mode=std` 时只能无声；需要声音时用 `mode=pro` 或省略 `mode`。
`VoiceList`	array<object>	否	`kling-v2-6`；仅图生	指定音色列表，需要同时传 `Sound=on`。最多 2 个对象，每个对象包含 `VoiceId` string。`Prompt` 中需要引用对应音色 ID。不要与 `ElementList` 同时传；`kling-v3` 不支持指定音色。
`CameraControl`	object	否	`kling-v1-6`、`kling-v2-master`、`kling-v2-1`、`kling-v2-1-master`、`kling-v2-5-turbo`、`kling-v2-6`、`kling-v3`；文生、图生	运镜控制。对象字段：`Type` string，可选 `simple`、`down_back`、`forward_up`、`right_turn_forward`、`left_turn_forward`；`Config` object。`Type=simple` 时 `Config` 必填，且 `Horizontal`、`Vertical`、`Pan`、`Tilt`、`Roll`、`Zoom` 六选一，类型均为 number，取值 `[-10,10]`。图生时不要与 `ImageTail`、`StaticMask`、`DynamicMasks` 同时传。
`StaticMask`	string	否	`kling-v1-6`、`kling-v2-master`、`kling-v2-1`、`kling-v2-5-turbo`、`kling-v2-6`、`kling-v3`；仅图生	静态遮罩图片，传公网 URL 或 Base64。格式要求同 `image`，宽高比必须与 `image` 一致；如同时传 `DynamicMasks`，分辨率必须与 `DynamicMasks.Mask` 一致。不要与 `ImageTail`、`CameraControl` 同时传。
`DynamicMasks`	array<object>	否	`kling-v1-6`、`kling-v2-master`、`kling-v2-1`、`kling-v2-5-turbo`、`kling-v2-6`、`kling-v3`；仅图生	动态遮罩列表，最多 6 个对象。每个对象包含：`Mask` string，遮罩图 URL/Base64，格式要求同 `image`，宽高比必须与 `image` 一致；`Trajectories` array<object>，运动轨迹点。每个轨迹点包含 `X` integer、`Y` integer，5 秒视频轨迹点数量为 2 到 77 个，坐标原点为图片左下角。不要与 `ImageTail`、`CameraControl` 同时传。
`MultiShot`	boolean	否	`kling-v3`；文生、图生	是否开启多镜头。设为 `true` 时 `Prompt` 不生效，需要同时传 `ShotType`；图生场景不要同时传 `ImageTail`。
`ShotType`	string	否	`kling-v3`；文生、图生	分镜方式。可选 `customize`、`intelligence`。使用 `customize` 时必须传 `MultiPrompt`。
`MultiPrompt`	array<object>	否	`kling-v3`；文生、图生	自定义分镜提示词，1 到 6 个对象。每个对象包含 `Index` integer、`Prompt` string、`Duration` string；单个分镜文本最长 512 字符，分镜时长不小于 1 秒且不大于任务总时长，所有分镜 `Duration` 之和需要等于任务总时长。
`ElementList`	array<object>	否	`kling-v3`；仅图生	参考主体列表，最多 3 个对象。每个对象包含 `ElementId` string，表示主体库中的主体 ID。不要与 `VoiceList` 同时传。
`LogoAdd`	boolean/integer	否	全部模型；文生、图生	是否添加水印或 AI 标识。传 `false` 或 `0` 可关闭。
`LogoParam`	object	否	全部模型；文生、图生	水印参数对象。字段：`LogoUrl` string，水印图片 URL；`LogoImage` string，水印图片 Base64，和 `LogoUrl` 二选一且同时传时以 `LogoUrl` 为准；`LogoRect` object，包含 `X`、`Y`、`Width`、`Height` integer，单位 px。
`CallbackUrl`	string	否	全部模型；文生、图生	上游回调地址。上游回调不替代本服务任务查询。
`ExternalTaskId`	string	否	全部模型；文生、图生	外部任务 ID，用于业务幂等或追踪。

Duration

API 模型名	文生视频可用值	图生视频可用值
`kling-v1`	`5`、`10`	不建议使用
`kling-v1-5`	建议省略，使用上游默认	不建议使用
`kling-v1-6`	`5`、`10`	`5`、`10`
`kling-v2-master`	`5`、`10`	`5`、`10`
`kling-v2-1`	不建议使用	`5`、`10`
`kling-v2-1-master`	`5`、`10`	不建议使用
`kling-v2-5-turbo`	`5`、`10`	`5`、`10`
`kling-v2-6`	`5`、`10`	`5`、`10`
`kling-v3`	`3` 到 `15` 的整数	`3` 到 `15` 的整数

Mode

API 模型名	文生视频可用值	图生视频可用值
`kling-v1`	`pro`	不建议使用
`kling-v1-5`	`pro`	不建议使用
`kling-v1-6`	`std`、`pro`	仅首帧或首尾帧建议使用 `pro`
`kling-v2-master`	建议省略	建议省略
`kling-v2-1`	不建议使用	首尾帧建议使用 `pro`
`kling-v2-1-master`	建议省略	不建议使用
`kling-v2-5-turbo`	首尾帧可用 `pro`；其他场景建议省略	首尾帧建议使用 `pro`
`kling-v2-6`	`pro` 或省略；需要声音时不要用 `std`	首尾帧建议使用 `pro`；需要声音时不要用 `std`
`kling-v3`	建议省略	建议省略

请求示例

文生视频

bash

curl -X POST "${BASE_URL}/v1/videos" \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v2-6",
    "prompt": "日出时分，一艘白色帆船缓慢穿过海湾，电影感镜头，柔和金色光线",
    "duration": 5,
    "mode": "pro"
  }'

图生视频

bash

curl -X POST "${BASE_URL}/v1/videos" \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v2-6",
    "prompt": "镜头缓慢向前推进，海面和云层自然流动，保持主体构图稳定",
    "image": "https://cdn.example.com/first-frame.png",
    "duration": 5,
    "mode": "pro"
  }'

音视频直出

json

{
  "model": "kling-v3",
  "prompt": "雨夜街头的电影感镜头，人物低声旁白，车辆灯光从背景掠过",
  "image": "https://cdn.example.com/start.png",
  "duration": 5,
  "metadata": {
    "Sound": "on"
  }
}

首尾帧

json

{
  "model": "kling-v2-6",
  "prompt": "从首帧自然过渡到尾帧，镜头平滑移动，人物动作连贯",
  "image": "https://cdn.example.com/start.png",
  "duration": 5,
  "mode": "pro",
  "metadata": {
    "ImageTail": {
      "Url": "https://cdn.example.com/end.png"
    }
  }
}

运镜

json

{
  "model": "kling-v2-6",
  "prompt": "镜头从远景缓慢推近到人物面部，电影感景深",
  "image": "https://cdn.example.com/portrait.png",
  "duration": 5,
  "mode": "pro",
  "metadata": {
    "NegativePrompt": "模糊，畸变，低清晰度，画面抖动",
    "CameraControl": {
      "Type": "simple",
      "Config": {
        "Zoom": 2.0,
        "Vertical": 0.2
      }
    }
  }
}

运动笔刷

json

{
  "model": "kling-v2-6",
  "prompt": "只让人物手臂轻微挥动，背景保持稳定",
  "image": "https://cdn.example.com/portrait.png",
  "duration": 5,
  "metadata": {
    "DynamicMasks": [
      {
        "Mask": "https://cdn.example.com/arm-mask.png",
        "Trajectories": [
          { "X": 410, "Y": 520 },
          { "X": 460, "Y": 500 }
        ]
      }
    ]
  }
}

多镜头和主体参考

json

{
  "model": "kling-v3",
  "prompt": "角色从室外走进咖啡店，保持角色一致",
  "duration": 10,
  "metadata": {
    "MultiShot": true,
    "ShotType": "customize",
    "MultiPrompt": [
      { "Prompt": "远景，角色走过街角" },
      { "Prompt": "中景，角色推门进入咖啡店" }
    ],
    "ElementList": [
      {
        "Name": "main_character",
        "Image": {
          "Url": "https://cdn.example.com/character.png"
        }
      }
    ]
  }
}

提交响应

POST /v1/videos 提交成功后返回公开任务 ID。任务仍在异步执行，需继续查询。

json

{
  "id": "task_2c8f7b3e9a",
  "task_id": "task_2c8f7b3e9a",
  "object": "video",
  "model": "kling-v2-6",
  "status": "queued",
  "progress": 0,
  "created_at": 1788912000
}

查询任务

bash

curl "${BASE_URL}/v1/videos/task_2c8f7b3e9a" \
  -H "Authorization: Bearer ${API_TOKEN}"

成功完成时的响应示例：

json

{
  "id": "task_2c8f7b3e9a",
  "object": "video",
  "model": "kling-v2-6",
  "status": "completed",
  "progress": 100,
  "created_at": 1788912000,
  "completed_at": 1788912042,
  "metadata": {
    "url": "https://example.com/generated-video.mp4"
  }
}

旧路径响应中的 result_url 与 OpenAI Video 响应中的 metadata.url 指向同一类结果视频。

轮询示例

bash

TASK_ID="task_2c8f7b3e9a"

while true; do
  BODY=$(curl -s "${BASE_URL}/v1/videos/${TASK_ID}" \
    -H "Authorization: Bearer ${API_TOKEN}")
  echo "${BODY}"

  STATUS=$(printf '%s' "${BODY}" | jq -r '.status')
  if [ "${STATUS}" = "completed" ] || [ "${STATUS}" = "failed" ]; then
    break
  fi

  sleep 5
done

建议 3 到 5 秒查询一次。不要为同一个业务请求重复创建多个视频任务。

下载视频

bash

curl -L "${BASE_URL}/v1/videos/task_2c8f7b3e9a/content" \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -o output.mp4

如果查询响应中的 metadata.url 或 result_url 是临时地址，可能会过期；长期保存请下载后转存到自己的对象存储。

常见错误

错误表现	可能原因	处理建议
`unsupported model`	模型名不在支持列表，或渠道未开放该模型	检查 `model` 拼写和后台模型配置
图片地址被拒绝	图片不可公网访问、格式/尺寸不符合要求	使用公网 HTTPS 图片，并检查图片大小、格式和宽高比
参数被上游拒绝	字段与“metadata 参数”表不匹配，或互斥字段同时传入	按表移除不支持字段；尾帧、运镜、静态遮罩、动态遮罩只保留一种
音频未生成	非 `kling-v2-6` / `kling-v3`，或 `kling-v2-6` 使用了 `mode=std`	换 `kling-v2-6` / `kling-v3`，并使用 `mode=pro` 或省略模式
查询一直未完成	上游队列拥塞或模型生成耗时较长	继续轮询同一个任务 ID，避免重复提交
下载失败	结果 URL 过期或代理安全策略拦截	尽快下载；必要时让管理员检查视频代理和 SSRF 配置

Kling 视频生成 API ​

接口一览 ​

能力路由 ​

支持模型 ​

鉴权 ​

请求参数 ​

顶层参数 ​

metadata 参数 ​

Duration ​

Mode ​

请求示例 ​

文生视频 ​

图生视频 ​

音视频直出 ​

首尾帧 ​

运镜 ​

运动笔刷 ​

多镜头和主体参考 ​

提交响应 ​

查询任务 ​

轮询示例 ​

下载视频 ​

常见错误 ​

Kling 视频生成 API

接口一览

能力路由

支持模型

鉴权

请求参数

顶层参数

metadata 参数

Duration

Mode

请求示例

文生视频

图生视频

音视频直出

首尾帧

运镜

运动笔刷

多镜头和主体参考

提交响应

查询任务

轮询示例

下载视频

常见错误