Vidu Q3 系列
viduq3、viduq3-mix、viduq3-pro、viduq3-turbo：多参考图/文生/图生/首尾帧视频，1–16 秒、540p–1080p，异步，用 GET /v1/tasks/{task_id} 查询
POST/v1/videos/generations
GET/v1/tasks/{task_id}
Vidu Q3 系列包含 4 个子型号，图生视频输入的必填性与用法因型号而异。提交、轮询、任务对象与错误见接口说明。
| 项 | 值 |
|---|---|
| 模型 | viduq3、viduq3-mix、viduq3-pro、viduq3-turbo，差异见下表 |
| 模式 | 异步（提交 → 轮询 GET /v1/tasks/{task_id}） |
| 计费 | 按实际生成秒数 × 分辨率档位，见计费 |
| 媒体保留 | video_url 最长保留至任务完成后 72 小时 |
四个型号的能力对比：
| 模型 | 定位 | 时长 | 分辨率 | image_urls | 默认值 |
|---|---|---|---|---|---|
viduq3 | 多参考图、标准档 | 3-16 秒 | 540p、720p、1080p | 必填，1-7 张 | 5 秒、720p |
viduq3-mix | 多参考图、高画质 | 1-16 秒 | 720p、1080p（不支持 540p） | 必填，1-7 张 | 5 秒、720p |
viduq3-pro | 文生/图生/首尾帧，质量档 | 1-16 秒 | 540p、720p、1080p | 可选 | 5 秒、720p |
viduq3-turbo | 文生/图生/首尾帧，速度档 | 1-16 秒 | 540p、720p、1080p | 可选 | 5 秒、720p |
快速开始
curl https://api.vibelab.me/v1/videos/generations \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "viduq3-turbo",
"prompt": "无人机航拍山谷云海，镜头缓慢上升",
"resolution": "540p",
"duration": 5
}'响应示例（HTTP 202）：
{
"task_id": "vt_019c8d85-75fd-7a31-b33f-8cf90e83a62b",
"model": "viduq3-turbo",
"status": "pending",
"created_at": 1772942400,
"duration": 5,
"resolution": "540p"
}用 task_id 调用 GET /v1/tasks/{task_id} 查询，见响应。
模式选择
viduq3 与 viduq3-mix 必须传 image_urls（缺失 → 400 invalid_request_error），1-7 张图片按多参考图方式融合生成，不区分首尾帧。
viduq3-pro 与 viduq3-turbo 的 image_urls 可选，按图片数量路由：
| 图片数量 | 行为 |
|---|---|
| 0 | 文生视频 |
| 1 | 图生视频（首帧） |
| 2 | 首尾帧生成 |
请求参数
| 参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
model | string | 是 | - | viduq3、viduq3-mix、viduq3-pro 或 viduq3-turbo |
prompt | string | 是 | - | 视频内容描述 |
resolution | string | 否 | 720p | 范围见上表 |
duration | integer | 否 | 5 | 范围见上表 |
image_urls | string[] | 视模型 | - | viduq3/viduq3-mix 必填；viduq3-pro/viduq3-turbo 可选 |
audio | boolean | 否 | false | 是否生成人声/音效 |
callback_url | string | 否 | - | 任务到达终态后的 HTTPS 回调地址 |
请求示例
viduq3 多参考图（必须提供 image_urls）：
{
"model": "viduq3",
"prompt": "两个参考主体在同一场景中互动",
"image_urls": ["https://example.com/ref-1.jpg", "https://example.com/ref-2.jpg"],
"resolution": "720p",
"duration": 4
}viduq3-pro 首尾帧：
{
"model": "viduq3-pro",
"prompt": "镜头从清晨缓慢过渡到日落",
"image_urls": ["https://example.com/first.png", "https://example.com/last.png"],
"resolution": "1080p",
"duration": 5
}响应
用 GET /v1/tasks/{task_id} 查询，状态依次为 pending → running → succeeded / failed（终态）。
| 字段 | 类型 | 说明 |
|---|---|---|
status | string | pending、running、succeeded、failed |
video_url | string | 视频下载地址，仅 succeeded 返回，尽快转存 |
expires_at | integer | video_url 失效时间，Unix 秒 |
credits_charged | number | 本次实际扣费（积分） |
error | object | 仅 failed 返回：{"code": "timeout" | "upstream_error", "message": "..."} |
完整任务对象字段与示例见接口说明。
计费
按实际生成时长（秒）× 分辨率档位计费。提交时先按请求参数预扣，任务结束后按实际结果结算，多退少补。
| 分辨率 | viduq3-turbo | viduq3 | viduq3-mix | viduq3-pro |
|---|---|---|---|---|
540p | 约 0.384 积分/秒 | 约 0.48 积分/秒 | 不支持 | 约 0.672 积分/秒 |
720p（默认） | 约 0.576 积分/秒 | 约 0.96 积分/秒 | 约 1.2 积分/秒 | 约 1.44 积分/秒 |
1080p | 约 0.672 积分/秒 | 约 1.2 积分/秒 | 约 1.44 积分/秒 | 约 1.536 积分/秒 |
精确价格与实时变动以定价页为准。
错误
通用错误见接口说明。本模型提交时的参数校验返回 400 invalid_request_error：
message | 处理 |
|---|---|
image_urls is required for this model | viduq3、viduq3-mix 必须传非空 image_urls |
resolution must be one of 540p/720p/1080p | viduq3、viduq3-pro、viduq3-turbo 分辨率取上述值 |
resolution must be one of 720p/1080p | viduq3-mix 不支持 540p |
duration must be between 3 and 16 | viduq3 时长传 3–16 |
duration must be between 1 and 16 | 其余三个型号时长传 1–16 |
注意事项
viduq3/viduq3-mix缺image_urls→ 返回400 invalid_request_error。viduq3-mix传540p→ 不支持，用720p或1080p。