Cubicspaces API

简体中文

English

简体中文

English

Appearance

Kling Video ​

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

推荐接入：统一视频接口

新接入优先使用 /v1/video/generations 创建任务，并通过 /v1/video/generations/{task_id} 查询结果。

接口地址 ​

统一视频接口 ​

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

请求需要携带 API Key：

http
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

支持模型 ​

模型
kling-v3
kling-v3-omni

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

支持模式 ​

模式推荐模型输入方式
文生视频kling-v3 / kling-v3-omniprompt
图生视频kling-v3 / kling-v3-omniimage
首尾帧视频kling-v3 / kling-v3-omniimage + metadata.image_tail
Omni 全能视频kling-v3-omnimetadata.image_list、video_list、element_list、multi_shot 等

统一接口请求参数 ​

参数类型必填说明
modelstring是Kling 模型名称
promptstring是视频生成描述
imagestring否首帧图片 URL；传入后按图生视频处理
modestring否清晰度/生成档位，例如 std、pro、4k；默认 std。实际可用档位以模型和账号权限为准
durationnumber否视频时长，单位秒；默认 5。kling-v3 / kling-v3-omni 通常支持 3 到 15 秒；多镜头场景下总时长不能超过 15 秒
sizestring否用于推断画幅比例，不作为输出分辨率直接透传；例如 1920x1080 => 16:9、1080x1920 => 9:16、1024x1024 => 1:1
metadataobject否Kling 扩展参数

清晰度请优先使用 mode 控制。size 只用于统一接口推断 aspect_ratio，不要把 size 当成指定 720P、1080P 或 4K 的参数。

metadata 字段 ​

metadata 中支持的字段会合并到发送给 Kling 的请求体。当前公开支持的字段如下；未列出的字段不保证转发。

字段类型说明
negative_promptstring负向提示词
aspect_ratiostring画幅，例如 16:9、9:16、1:1
image_tailstring尾帧图片 URL
cfg_scalenumber提示词相关性
camera_controlobject镜头控制
static_maskstring静态遮罩
dynamic_masksobject[]动态遮罩
callback_urlstring回调地址
external_task_idstring客户端自定义任务 ID
soundboolean/objectOmni 音频开关或音频配置
image_listobject[]Omni 图片输入列表，可用于首帧、尾帧或参考图
video_listobject[]Omni 视频输入列表
element_listobject[]Omni 角色、主体或素材输入列表
multi_shotboolean是否启用 Omni 多镜头
shot_typestringOmni 多镜头类型
multi_promptstring/object[]Omni 多镜头提示词
voice_listobject[]Omni 声音/对白输入列表
watermark_infoobject水印配置

调用示例 ​

文生视频 ​

bash
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"
    }
  }'

图生视频 ​

bash
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"
    }
  }'

首尾帧视频 ​

bash
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"
    }
  }'

Omni 全能视频 ​

kling-v3-omni 使用 Omni 全能视频能力，支持文生视频、首尾帧、参考图、参考视频、多镜头和声音相关输入。最简单的文生视频请求可以直接使用统一视频接口：

bash
curl -X POST https://cubicspaces.cloud/v1/video/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "kling-v3-omni",
    "prompt": "A cinematic shot of a futuristic city at sunset, smooth camera movement, high detail, realistic lighting",
    "mode": "std",
    "duration": 5,
    "size": "1920x1080",
    "metadata": {
      "aspect_ratio": "16:9"
    }
  }'

Omni 首尾帧也可以使用 image 和 metadata.image_tail：

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

如果需要更完整的 Omni 输入结构，可以在 metadata 中传入 image_list、video_list、element_list、multi_shot 等字段：

json
{
  "model": "kling-v3-omni",
  "prompt": "A product showcase with a close-up opening shot and a final wide studio shot",
  "duration": 10,
  "metadata": {
    "mode": "pro",
    "aspect_ratio": "16:9",
    "image_list": [
      {
        "image_url": "https://example.com/first-frame.png",
        "type": "first_frame"
      },
      {
        "image_url": "https://example.com/end-frame.png",
        "type": "end_frame"
      }
    ],
    "multi_shot": true,
    "multi_prompt": [
      "Close-up of the product with soft studio lighting",
      "Wide shot showing the product in a clean futuristic showroom"
    ]
  }
}

镜头控制示例 ​

json
{
  "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
      }
    }
  }
}

返回和查询 ​

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

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

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

查询任务：

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

查询返回：

json
{
  "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 读取视频地址。

Copyright © 2026-present Cubicspaces