Vidu 视频

Vidu Q3（viduq3-pro / viduq3-turbo）是生数科技 Vidu 系列最新一代视频生成模型，支持文生视频与图生视频（单图首帧），时长 1–16 秒可调，默认开启音画同出（台词与音效直出，不另计价）。调用走统一 POST /v1/videos 接口，返回 OpenAI Video 风格（id / status / metadata.url），与其它视频模型共享同一套任务轮询机制。

计费方式

Vidu Q3 按生成时长（秒）× 分辨率档单价计费，540P / 720P / 1080P 三档单价不同；音画同出不另收费。不传 size 时按 720P（默认档） 计费。具体单价与计费表达式以控制台「模型广场」对应模型卡片展示为准（文档不展示实时价格）。

端点

• 创建任务：POST $URL/v1/videos
• 查询任务：GET $URL/v1/videos/{task_id}

支持模型

模型名称	定位	支持分辨率	时长
viduq3-pro	效果优先，画质与一致性更佳	540P / 720P / 1080P	1–16 秒
viduq3-turbo	速度优先，生成更快、更省	540P / 720P / 1080P	1–16 秒

同一个模型名下通过请求参数 size 区分分辨率档位（见下方「主要参数」）。

主要参数

参数	类型	必填	说明
model	string	是	viduq3-pro / viduq3-turbo
prompt	string	是	视频内容描述，最长 5000 字符，建议包含主体、动作、场景、镜头
size	string	否	分辨率档位：540p / 720p / 1080p，默认 720P
duration	integer	否	输出视频时长（秒），范围 1–16，默认 5 秒
image	string	否	首帧图片 URL（单张，公网可访问，用于图生视频）
metadata.duration	number	否	高级覆盖：输出时长（秒），优先级高于顶层 duration
metadata.resolution	string	否	高级覆盖：直接指定分辨率档位
metadata.seed	integer	否	随机种子，用于复现

能力范围

Vidu Q3 当前支持文生视频与单图首帧的图生视频。首尾帧生成（2 张图）与多图参考生成暂未开放，请勿传入 2 张图片，否则任务会失败。

请求示例

文生视频

curl

# 1. 创建视频任务（720P，5 秒）
curl $URL/v1/videos \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "viduq3-pro",
    "prompt": "超写实时尚大片风格，一名宇航员在浓雾中穿行，镜头缓慢推进",
    "duration": 5,
    "size": "720p"
  }'

# 2. 查询任务状态（替换 {task_id} 为上一步返回的 id）
curl $URL/v1/videos/{task_id} \
  -H "Authorization: Bearer $YOUR_API_KEY"

Python

import time
import requests

url = "$URL/v1/videos"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}
payload = {
    "model": "viduq3-turbo",
    "prompt": "超写实时尚大片风格，一名宇航员在浓雾中穿行",
    "duration": 5,
    "size": "720p",
}

task = requests.post(url, json=payload, headers=headers).json()
task_id = task["id"]

while True:
    result = requests.get(f"{url}/{task_id}", headers=headers).json()
    if result["status"] in ("completed", "failed"):
        break
    time.sleep(8)

print(result)

图生视频（首帧）

curl $URL/v1/videos \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "viduq3-turbo",
    "prompt": "让画面中的宇航员转身面向镜头挥手",
    "image": "https://example.com/first_frame.png",
    "duration": 5,
    "size": "1080p"
  }'

首帧图片要求

支持 PNG / JPEG / WEBP 公网可访问 URL，图片大小不超过 50 MB，宽高比需在 1:4 ~ 4:1 之间。上游会自行拉取图片，内网或本地地址会失败。

响应字段

创建任务与查询任务返回同一结构（OpenAI Video 风格）：

字段	类型	说明
id	string	任务 ID
status	string	任务状态（见下方状态说明）
metadata.url	string	生成完成后的视频地址（仅 completed 时返回）
progress	integer	生成进度，0~100
completed_at	integer	完成时间戳（秒，仅 completed 时返回）
error.message	string	失败原因（仅 failed 时返回）

任务状态

状态	含义	处理建议
queued	排队中	继续轮询
in_progress	生成中	继续轮询
completed	生成成功	从 metadata.url 获取视频地址，请尽快下载保存
failed	生成失败	查看 error.message

建议轮询间隔 5~10 秒

任务完成后请尽快下载转存：视频地址有时效性，过期后无法再访问。

响应示例

{
  "id": "task_xxxxxxxx",
  "status": "in_progress",
  "progress": 30
}

完成后：

{
  "id": "task_xxxxxxxx",
  "status": "completed",
  "progress": 100,
  "metadata": {
    "url": "https://cdn.example.com/.../result.mp4"
  },
  "completed_at": 1788769182
}

常见问题

Q: 提示词怎么写效果更好？

建议包含四个要素：主体（谁/什么）、动作（在做什么）、场景（在哪里）、镜头（怎么拍，如推进/环绕/俯拍）。Vidu Q3 支持音画同出，可在提示词中描述期望的旁白、台词或音效。

Q: 生成的视频有声音吗？

有。Vidu Q3 默认开启音画同出（台词 + 音效直出），不另计费。

Q: 任务大概多久完成？

与时长和分辨率相关，720P 5 秒通常在 1–2 分钟内完成，1080P 长时长会更久。请通过轮询查询接口获取最终状态；任务超过 20 分钟未完成会自动置为失败。

Q: 生成的视频链接会过期吗？

会。视频地址有时效性，生成完成后请尽快下载转存到自己的存储。

Q: 为什么传 2 张图片会失败？

首尾帧生成暂未开放，请只传 1 张首帧图（image）使用图生视频，或不传图使用文生视频。