Vidu 系列
- 参考图生视频为主，参考图最多 7 张
- 首帧生视频可选，提示词可省略由模型按首帧补全
- Q4 预览版支持最高 4K 与参考音频
认证
All endpoints authenticate with a Bearer token.
Get an API key: open the console and create one.
Add it to the request header:
Authorization: Bearer YOUR_OAIRoute_KEY请求参数
提交成功只返回任务 ID，不含视频本身。拿成片用 task_id 轮询获取任务状态，成片地址在 result.videos[0].url，该地址约 24 小时后过期，请及时转存。
模型 ID，取值见下方模型列表。必须完全匹配，全小写。
画面描述。参考生视频必填；图生视频可省略，此时由模型根据首帧自行生成内容。
注意描述动作与镜头，外观与风格由参考图决定。
参考图或首帧，公网地址或 Base64 data URI。
图生视频传且只传 1 张；参考生视频 1 到 15 张。
带角色的图片数组，每项含 url 与 role。
role 取值 first_frame、reference_image（别名 reference）。last_frame 与其他值返回 400。
首帧图片，仅图生视频可用。不能与其他图片或音频混用。
参考音频，仅参考生视频可用。MP3，每段 3 到 12 秒，单段不超过 50MB，合计不超过 3 段。
单段参考音频，约束与 audio_urls 相同。
输出画幅，取值 16:9、9:16、4:3、3:4、1:1，默认 16:9。
仅参考生视频生效，图生视频会忽略。别名 size。
时长，单位秒，默认 5。
viduq3：3 到 16；viduq3-mix：1 到 16；viduq4-preview：3 到 16，不支持 1 到 2 秒。
输出分辨率，默认 720p。
viduq3：540p、720p、1080p；viduq3-mix：720p、1080p；viduq4-preview：540p 到 4K。
是否输出音轨，默认 true。开关不影响计费。
随机种子，省略或传 0 表示随机。
A successful submission returns only the task ID, not the video itself. Poll Get task status with the task_id; the video URL is at result.videos[0].url, expires after about 24 hours, so copy it promptly.
The model ID; see the model list below. Must match exactly, all lowercase.
The scene description. Required for reference to video; optional for image to video, where the model generates content from the first frame on its own.
Describe the action and camera work; appearance and style come from the reference images.
Reference images or the first frame, as public URLs or Base64 data URIs.
For image to video, pass exactly 1; for reference to video, 1 to 15.
An array of images with roles, each with url and role.
role is first_frame or reference_image (alias reference). last_frame and any other value return a 400.
The first-frame image; usable only for image to video. Can't be mixed with other images or audio.
Reference audio, usable only for reference to video. MP3, 3 to 12 seconds per clip, up to 50MB per clip, at most 3 clips.
A single reference audio clip; same constraints as audio_urls.
Output framing: 16:9, 9:16, 4:3, 3:4, or 1:1; default 16:9.
Takes effect only for reference to video; image to video ignores it. Alias: size.
Duration in seconds, default 5.
viduq3: 3 to 16; viduq3-mix: 1 to 16; viduq4-preview: 3 to 16, with 1 to 2 seconds unsupported.
Output resolution, default 720p.
viduq3: 540p, 720p, 1080p; viduq3-mix: 720p, 1080p; viduq4-preview: 540p through 4K.
Whether to output an audio track; defaults to true. The switch doesn't affect billing.
Random seed; omitted or 0 means random.
模式判定
只有一张首帧图，或只有一张 role 为 first_frame 的图，走图生视频。
只有一张不带角色也没有参考音频的图，同样按图生视频处理。
图片里出现 reference_image 角色，或者 2 到 15 张图且没有显式首帧，走参考生视频。
参考音频加 1 到 15 张图、没有显式首帧，也走参考生视频。
显式首帧与其他图片、参考角色或音频混用，提交阶段返回 400，不创建任务也不扣费。
Exactly one first-frame image, or one image with role set to first_frame, means image to video.
A single image with no role and no reference audio is likewise treated as image to video.
A reference_image role, or 2 to 15 images without an explicit first frame, means reference to video.
Reference audio plus 1 to 15 images with no explicit first frame also means reference to video.
Mixing an explicit first frame with other images, reference roles, or audio returns a 400 at submission, creating no task and charging nothing.
支持的模型列表
| 模型 ID | 定位 |
|---|---|
viduq4-preview | 预览版旗舰，最高 4K，支持参考音频，必须显式传 model |
viduq3-mix | 画质最高，支持 1 秒短片，最高 1080p |
viduq3 | 日常首选，镜头切换更聪明，支持 540p 到 1080p |
viduq3-pro | v3 的专业版，适合首尾帧与短片段 |
| Model ID | Positioning |
|---|---|
viduq4-preview | Preview flagship, up to 4K, supports reference audio; model must be passed explicitly |
viduq3-mix | Highest quality, supports 1-second clips, up to 1080p |
viduq3 | The everyday pick; smarter shot transitions, supports 540p through 1080p |
viduq3-pro | The pro v3 variant, suited to first-and-last frames and short clips |
使用限制
- 参考图合计 1 到 15 张，单张不超过 50MB，最短边至少 128 像素，宽高比 1:4 到 4:1
- Base64 时整个请求体不超过 20MB，大图建议用公网地址
viduq3-mix不接受 540pviduq4-preview不接受 1 到 2 秒- 成片链接 24 小时后过期
- Reference images total 1 to 15, at most 50MB each, shortest side at least 128 pixels, aspect ratio 1:4 to 4:1
- With Base64 the whole request body must stay under 20MB; use public URLs for large images
viduq3-mixdoesn't accept 540pviduq4-previewdoesn't accept 1 to 2 seconds- Finished video links expire after 24 hours
响应
提交成功返回统一的受理结构：
{
"code": 200,
"data": [
{
"status": "submitted",
"task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
}
]
}状态码，200 表示任务已受理。
本次提交的任务列表，逐项提交时按顺序排列。
受理状态，提交成功时为 submitted。
任务 ID，用它轮询结果。
A successful submission returns the standard accepted structure:
{
"code": 200,
"data": [
{
"status": "submitted",
"task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
}
]
}The status code; 200 means the task was accepted.
The list of tasks submitted this time, in order when submitting item by item.
The acceptance status; submitted on success.
The task ID; use it to poll for the result.
错误
| HTTP | type | 说明 |
|---|---|---|
| 400 | invalid_request_error | 请求参数无效，或参数组合冲突 |
| 401 | authentication_error | 身份验证失败，需检查 API Key |
| 402 | payment_required | 账户余额不足，需先充值 |
| 429 | rate_limit_error | 调用频率过高，稍后重试 |
参数错误在提交阶段同步返回，不创建任务、不扣费。
| HTTP | type | Notes |
|---|---|---|
| 400 | invalid_request_error | Invalid parameters, or a conflicting combination |
| 401 | authentication_error | Authentication failed; check the API key |
| 402 | payment_required | Insufficient account balance; top up first |
| 429 | rate_limit_error | Too many calls; retry later |
Parameter errors are returned synchronously at submission, creating no task and charging nothing.
For more status codes and retry guidance see Error codes and rate limits; for troubleshooting steps on common errors see the FAQ.
查询任务
GET /v1/tasks/{task_id} 返回任务进度与结果，status 为 completed 时成片地址在 result.videos[0].url，元素带 expires_at 过期时间戳。
建议每 5 到 10 秒轮询一次，客户端总超时设为 10 到 15 分钟。status 取值 pending、processing、completed、failed、cancelled，以状态判定完成，不要依赖 progress。
失败任务自动退回费用，error.message 给出原因。
GET /v1/tasks/{task_id} returns task progress and results; once status is completed, the video URL is at result.videos[0].url, with an expires_at timestamp on the element.
Poll every 5 to 10 seconds, with a 10 to 15 minute client timeout. status is one of pending, processing, completed, failed, cancelled; judge completion by status, not by progress.
Failed tasks are refunded automatically, with the reason in error.message.