Cubicspaces API

简体中文

English

简体中文

English

Appearance

Vidu Video ​

Vidu Video 用于创建短视频生成任务。你可以使用文本提示词生成视频，也可以传入图片作为首帧、尾帧或参考图来控制主体与画面风格。

创建任务后，接口会立即返回任务 ID。客户端需要使用查询接口轮询任务状态；任务完成后，可从查询结果的 metadata.url 或内容接口获取视频。

接口地址 ​

能力方法路径
创建视频任务POST/v1/videos
查询视频任务GET/v1/videos/{task_id}
获取视频内容GET/v1/videos/{task_id}/content
统一创建视频任务POST/v1/video/generations
统一查询视频任务GET/v1/video/generations/{task_id}

/v1/videos 和 /v1/video/generations 使用同一套请求字段。推荐新接入优先使用 /v1/videos。

支持模型 ​

模型说明
viduq3-turbo速度优先，适合快速生成与迭代
viduq3画面一致性更强，适合多镜头视频
viduq3-mix画面质感与动态效果均衡
viduq2适合参考图生视频与主体一致性场景

实际可用模型以账号权限和平台开放范围为准。

支持模式 ​

模式推荐模型输入方式
文生视频viduq3-turbo、viduq3、viduq3-mixprompt
图生视频viduq3、viduq2image、images 或 input_reference
首尾帧视频viduq2images 中传 2 张图片
参考图视频viduq2images 中传多张参考图

请求参数 ​

http
POST /v1/videos
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
参数必填说明
model是Vidu 模型名称，例如 viduq3-turbo、viduq3、viduq3-mix、viduq2
prompt是视频生成提示词，描述主体、动作、场景、镜头语言和风格
duration否视频时长，单位秒；也可以使用字符串字段 seconds
seconds否视频时长字符串，例如 "5"；与 duration 二选一即可
size否输出规格。可传分辨率如 720p、1080p，也可传比例如 16:9、9:16、1:1
image否单张图片 URL，等价于只传一项 images
images否图片 URL 数组。1 张图通常作为图生视频输入；2 张图可作为首尾帧；多张图可作为参考图
input_reference否单个参考图片 URL，等价于单张图片输入
metadata否Vidu 扩展参数对象

常用 metadata 字段：

字段说明
resolution输出清晰度，例如 720p、1080p
aspect_ratio输出画面比例，例如 16:9、9:16、1:1
movement_amplitude运动幅度，可传 auto、small、medium、large
bgm是否自动添加背景音乐
audio是否生成带声音的视频；实际效果以所选模型支持为准
audio_type音频类型，例如 all、speech_only、sound_effect_only
payload自定义透传字符串，会在任务结果中原样返回

图片 URL 需要可被公网访问。常见图片格式包括 jpg、jpeg、png、webp。

调用示例 ​

文生视频 ​

bash
curl -X POST https://cubicspaces.cloud/v1/videos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "viduq3-turbo",
    "prompt": "A cinematic shot of a glass cube floating above a quiet lake at sunrise, soft reflections, slow camera push in",
    "duration": 5,
    "size": "16:9",
    "metadata": {
      "resolution": "720p",
      "movement_amplitude": "auto"
    }
  }'

图生视频 ​

bash
curl -X POST https://cubicspaces.cloud/v1/videos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "viduq3",
    "prompt": "Keep the product shape consistent. The camera slowly rotates around the product on a clean studio background.",
    "images": [
      "https://example.com/product.png"
    ],
    "duration": 5,
    "size": "1:1",
    "metadata": {
      "resolution": "720p",
      "movement_amplitude": "small"
    }
  }'

首尾帧视频 ​

传入两张图片时，系统会按首帧和尾帧理解输入，适合做过渡动画。

bash
curl -X POST https://cubicspaces.cloud/v1/videos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "viduq2",
    "prompt": "Create a smooth transition from image 1 to image 2, keep lighting natural and motion fluid.",
    "images": [
      "https://example.com/start.png",
      "https://example.com/end.png"
    ],
    "duration": 5,
    "size": "16:9"
  }'

参考图视频 ​

传入多张图片时，系统会把图片作为参考素材，适合需要保持主体一致的场景。

bash
curl -X POST https://cubicspaces.cloud/v1/videos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "viduq2",
    "prompt": "Use the subject from the reference images. The character walks through a bright modern gallery, keeping identity and outfit consistent.",
    "images": [
      "https://example.com/ref-1.png",
      "https://example.com/ref-2.png",
      "https://example.com/ref-3.png"
    ],
    "duration": 5,
    "size": "9:16",
    "metadata": {
      "resolution": "720p"
    }
  }'

返回和查询 ​

创建成功后会返回视频任务对象：

json
{
  "id": "task_xxx",
  "task_id": "task_xxx",
  "object": "video",
  "model": "viduq3-turbo",
  "status": "queued",
  "progress": 0,
  "created_at": 1770000000
}

请保存 id，后续用它查询任务状态和获取视频内容。

查询任务：

bash
curl https://cubicspaces.cloud/v1/videos/task_xxx \
  -H "Authorization: Bearer YOUR_API_KEY"

生成中通常返回：

json
{
  "id": "task_xxx",
  "object": "video",
  "model": "viduq3-turbo",
  "status": "in_progress",
  "progress": 30,
  "created_at": 1770000000
}

任务完成后通常返回：

json
{
  "id": "task_xxx",
  "object": "video",
  "model": "viduq3-turbo",
  "status": "completed",
  "progress": 100,
  "created_at": 1770000000,
  "completed_at": 1770000600,
  "metadata": {
    "url": "https://example.com/generated-video.mp4"
  }
}

任务失败时会返回 status: "failed"，失败原因在 error.message：

json
{
  "id": "task_xxx",
  "object": "video",
  "model": "viduq3-turbo",
  "status": "failed",
  "progress": 100,
  "created_at": 1770000000,
  "completed_at": 1770000030,
  "error": {
    "code": "task_failed",
    "message": "The video generation task failed."
  }
}

状态值 ​

状态说明
queued已提交，等待处理
in_progress生成中
completed已完成
failed生成失败，请查看 error.message

建议第一次查询从 1 到 5 分钟后开始；仍在生成中时，再按较短间隔继续轮询。

获取视频内容 ​

任务完成后，可以直接下载或播放内容接口：

bash
curl -L https://cubicspaces.cloud/v1/videos/task_xxx/content \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output vidu-result.mp4

如果任务尚未完成，内容接口会返回错误；请先通过查询接口确认 status 为 completed。

注意事项 ​

  • 提示词建议写清楚主体、动作、镜头、场景和风格，避免只写非常短的名词。
  • 图生视频、首尾帧和参考图输入需要使用公网可访问的图片 URL。
  • 不同模型支持的时长、比例、清晰度和音频能力可能不同；不确定时建议先使用 duration: 5、resolution: "720p" 测试。
  • 结果视频地址可能有有效期限制，生产环境建议在任务完成后及时下载或转存。

Copyright © 2026-present Cubicspaces