Vidu Q3 视频生成 | ToAPIs Documentation

POST

/v1/videos/generations

国内用户请注意： 中国大陆用户请使用 https://toapis.cn 作为接口地址（Base URL）。文档示例中的 https://toapis.com 请替换为 https://toapis.cn。

异步任务接口，提交后返回任务 ID
支持模型：viduq3-pro、viduq3-turbo、viduq3
viduq3-pro：高质量模型，支持音视频同步和分镜视频生成
viduq3-turbo：快速模型，支持智能场景切换，生成速度最快，性价比最高
viduq3：多机位一致性最优，支持智能镜头切换和多参考图生成

请传入公网可访问的图片 URL。不要在 image_urls 中直接传 base64 图片数据；本地图片请先使用上传图片接口获取 URL。

认证

Authorizationstring请求头必填

所有接口均需要使用 Bearer Token 认证。

Authorization: Bearer YOUR_API_KEY

请求参数

modelstring请求体必填

Vidu Q3 模型名称。

可选值：

viduq3-pro - 高质量模型，支持音视频同步和分镜视频生成
viduq3-turbo - 快速模型，支持智能场景切换，生成速度最快
viduq3 - 多机位一致性最优，适用于多参考图/Subjects 生成

promptstring请求体必填

视频提示词，最大 5000 字符。

描述主体、动作、场景、镜头和风格。使用 subjects 时可通过 @name 引用主体。

示例："一只猫咪在弹钢琴，镜头缓缓推近，电影质感"

durationinteger请求体默认值: 5

视频时长，单位秒。

viduq3-pro / viduq3-turbo：1 到 16
viduq3：3 到 16

resolutionstring请求体默认值: 720p

视频分辨率。

可选值：

540p
720p
1080p

aspect_ratiostring请求体

视频宽高比。

常用值：16:9、9:16、1:1

Q3 系列模型支持任意宽高比。传入 image_urls 时，宽高比通常由参考图片决定。

image_urlsstring[]请求体

参考图片 URL 数组。

viduq3-pro / viduq3-turbo
- 不传：文生视频
- 传 1 张：图生视频，图片作为首帧
- 传 2 张：首尾帧，第一张为首帧，第二张为尾帧
viduq3
- 必填，最多 7 张参考图片

示例：["https://example.com/reference.jpg"]

audioboolean请求体

是否启用音视频输出。

所有 Q3 模型默认 true

设为 true 时，系统根据提示词生成语音和背景音效。

seedinteger请求体

随机种子，用于在相同参数下复现相近结果。

metadataobject请求体

扩展参数，用于传递官方 API 支持但未作为顶层字段暴露的参数。

显示 metadata 字段

subjectsarray请求体

主体列表（Subjects 模式，仅 viduq3 支持）。每个主体包含 name 和 images 字段。

最多 7 个主体
每个主体最多 3 张图片
使用时在 prompt 中通过 @name 引用主体

示例：

[
  {"name": "cat", "images": ["https://example.com/cat.jpg"]},
  {"name": "dog", "images": ["https://example.com/dog.jpg"]}
]

auto_subjectsboolean请求体

是否启用智能实体库能力，默认 false。

voice_idstring请求体

语音 ID，用于指定视频中的语音角色。系统会自动推荐合适的语音。

audio_typestring请求体

音频类型，audio 为 true 时有效。

可选值：

all - 音效+人声（默认）
speech_only - 仅人声
sound-effect_only - 仅音效

off_peakboolean请求体

闲时模式，默认 false。

true：闲时生成，消耗更少积分
闲时任务将在 48 小时内生成，未完成自动取消并退还积分
Q3 模型在 audio=true 时支持闲时任务

payloadstring请求体

透传参数，不做处理仅传递数据，最大 1048576 字符。

callback_urlstring请求体

ToAPIs 最终任务 Webhook。需先配置 Token URL 和签名密钥；详见任务 Webhook。

模型选择

模型	适用场景	图片输入	分辨率	时长
`viduq3-pro`	高质量文生/图生/首尾帧	可选，最多 2 张	`540p` / `720p` / `1080p`	1-16s
`viduq3-turbo`	快速文生/图生/首尾帧	可选，最多 2 张	`540p` / `720p` / `1080p`	1-16s
`viduq3`	多参考图/Subjects 生成	必填，最多 7 张	`540p` / `720p` / `1080p`	3-16s

计费区分

Vidu Q3 按模型、分辨率和生成类型计费：

viduq3-pro：高质量档，价格约为 turbo 的 2 倍
viduq3-turbo：快速档，性价比最高
viduq3：多参考图生成，按参考生成计费

响应

idstring

任务 ID，用于查询任务状态。

objectstring

对象类型，通常为 generation.task。

modelstring

本次请求使用的模型名称。

statusstring

任务状态：queued、in_progress、completed 或 failed。

created_atinteger

任务创建时间戳。

示例

文生视频

{
  "model": "viduq3-pro",
  "prompt": "一只猫咪在弹钢琴，镜头缓缓推近，电影质感",
  "duration": 8,
  "resolution": "1080p",
  "aspect_ratio": "16:9",
  "audio": true
}

图生视频

{
  "model": "viduq3-turbo",
  "prompt": "让图片中的人物缓缓转身并微笑",
  "image_urls": ["https://example.com/portrait.jpg"],
  "duration": 5,
  "resolution": "720p"
}

首尾帧

{
  "model": "viduq3-pro",
  "prompt": "人物从站立自然坐下，动作流畅",
  "image_urls": [
    "https://example.com/first-frame.jpg",
    "https://example.com/last-frame.jpg"
  ],
  "duration": 8,
  "resolution": "720p"
}

多参考图生成视频

{
  "model": "viduq3",
  "prompt": "保持参考图中的角色一致，在未来城市街道中行走",
  "image_urls": [
    "https://example.com/character-front.jpg",
    "https://example.com/character-side.jpg"
  ],
  "duration": 6,
  "resolution": "1080p"
}

Subjects 模式

{
  "model": "viduq3",
  "prompt": "@cat 和 @dog 在公园里奔跑，阳光明媚",
  "image_urls": ["https://example.com/park-bg.jpg"],
  "duration": 8,
  "resolution": "720p",
  "audio": true,
  "metadata": {
    "subjects": [
      {"name": "cat", "images": ["https://example.com/cat.jpg"]},
      {"name": "dog", "images": ["https://example.com/dog.jpg"]}
    ],
    "audio_type": "all"
  }
}

视频生成为异步任务。提交后使用获取视频任务状态查询进度和结果。

请求示例

curl --request POST \
  --url https://toapis.com/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "viduq3-pro",
    "prompt": "一只猫咪在弹钢琴，镜头缓缓推近，电影质感",
    "duration": 8,
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "audio": true
  }'

import requests

response = requests.post(
    "https://toapis.com/v1/videos/generations",
    headers={
        "Authorization": "Bearer <token>",
        "Content-Type": "application/json",
    },
    json={
        "model": "viduq3-pro",
        "prompt": "一只猫咪在弹钢琴，镜头缓缓推近，电影质感",
        "duration": 8,
        "resolution": "1080p",
        "aspect_ratio": "16:9",
        "audio": True,
    },
)

print(response.json())

const response = await fetch("https://toapis.com/v1/videos/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "viduq3-pro",
    prompt: "一只猫咪在弹钢琴，镜头缓缓推近，电影质感",
    duration: 8,
    resolution: "1080p",
    aspect_ratio: "16:9",
    audio: true
  })
});

console.log(await response.json());