Kling Video

Kling Video 使用异步视频任务接口。客户端先创建任务，再通过查询接口轮询状态和结果。

接口地址

统一视频接口

能力	方法	路径
创建视频任务	POST	/v1/video/generations
查询视频任务	GET	/v1/video/generations/{task_id}

Kling 兼容接口

能力	方法	路径
文生视频	POST	/kling/v1/videos/text2video
图生视频	POST	/kling/v1/videos/image2video
查询文生视频	GET	/kling/v1/videos/text2video/{task_id}
查询图生视频	GET	/kling/v1/videos/image2video/{task_id}

请求需要携带 API Key：

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

支持模型

模型
kling-v3

实际可用模型以账号权限为准。

统一接口请求参数

参数	类型	必填	说明
model	string	是	Kling 模型名称
prompt	string	是	视频生成描述
image	string	否	首帧图片 URL；传入后按图生视频处理
mode	string	否	生成模式，例如 std、pro；默认 std
duration	number	否	视频时长，单位秒；默认 5
size	string	否	尺寸，用于转换画幅，例如 1920x1080、1080x1920、1024x1024
metadata	object	否	Kling 扩展参数

metadata 字段

metadata 会透传为 Kling 请求体字段，常用字段如下：

字段	类型	说明
negative_prompt	string	负向提示词
aspect_ratio	string	画幅，例如 16:9、9:16、1:1
image_tail	string	尾帧图片 URL
cfg_scale	number	提示词相关性
camera_control	object	镜头控制
static_mask	string	静态遮罩
dynamic_masks	object[]	动态遮罩
callback_url	string	回调地址
external_task_id	string	客户端自定义任务 ID

文生视频

curl -X POST https://cubicspaces.cloud/v1/video/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "kling-v3",
    "prompt": "A cinematic shot of a futuristic cubic city at sunrise, slow camera movement, realistic lighting",
    "mode": "std",
    "duration": 5,
    "size": "1920x1080",
    "metadata": {
      "aspect_ratio": "16:9",
      "negative_prompt": "blur, distortion, low quality"
    }
  }'

图生视频

curl -X POST https://cubicspaces.cloud/v1/video/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "kling-v3",
    "prompt": "Animate the product from the first frame with a slow clockwise rotation, keep the product shape stable",
    "image": "https://example.com/first-frame.png",
    "mode": "std",
    "duration": 5,
    "metadata": {
      "aspect_ratio": "16:9",
      "negative_prompt": "deformation, flicker"
    }
  }'

首尾帧视频

curl -X POST https://cubicspaces.cloud/v1/video/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "kling-v3",
    "prompt": "Create a smooth transition from the first frame to the last frame",
    "image": "https://example.com/first-frame.png",
    "duration": 5,
    "metadata": {
      "image_tail": "https://example.com/last-frame.png",
      "aspect_ratio": "16:9"
    }
  }'

镜头控制示例

{
  "model": "kling-v3",
  "prompt": "A slow push-in shot toward the product on a clean studio table",
  "image": "https://example.com/product.png",
  "duration": 5,
  "metadata": {
    "aspect_ratio": "16:9",
    "camera_control": {
      "type": "simple",
      "config": {
        "zoom": 1.2,
        "horizontal": 0,
        "vertical": 0
      }
    }
  }
}

Kling 兼容接口示例

如果你希望使用接近 Kling 官方格式的路径，可以调用兼容接口。

文生视频

curl -X POST https://cubicspaces.cloud/kling/v1/videos/text2video \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model_name": "kling-v3",
    "prompt": "A cinematic aerial shot of a futuristic cubic city",
    "mode": "std",
    "duration": 5,
    "aspect_ratio": "16:9",
    "negative_prompt": "blur, distortion"
  }'

图生视频

curl -X POST https://cubicspaces.cloud/kling/v1/videos/image2video \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model_name": "kling-v3",
    "prompt": "Animate the subject naturally while preserving the first-frame composition",
    "image": "https://example.com/first-frame.png",
    "mode": "std",
    "duration": 5,
    "aspect_ratio": "16:9"
  }'

创建任务返回

统一接口创建成功后返回视频任务对象：

{
  "id": "video_xxx",
  "task_id": "video_xxx",
  "object": "video",
  "model": "kling-v3",
  "status": "queued",
  "progress": 0,
  "created_at": 1770000000
}

id 和 task_id 都可用于后续查询。

查询任务

curl https://cubicspaces.cloud/v1/video/generations/video_xxx \
  -H "Authorization: Bearer YOUR_API_KEY"

查询返回

{
  "id": "video_xxx",
  "task_id": "video_xxx",
  "object": "video",
  "model": "kling-v3",
  "status": "completed",
  "progress": 100,
  "seconds": "5",
  "created_at": 1770000000,
  "completed_at": 1770000120,
  "metadata": {
    "url": "https://example.com/output.mp4"
  }
}

状态值

status	说明
queued	已排队
in_progress	生成中
completed	已完成
failed	失败

完成后从 metadata.url 读取视频地址。