Vidu Q4 API

Preview 模型以 viduq4-preview 这个 id 开放。官方文档拆成图生视频和参考生视频两种任务。viduq4.app 不是官方 API 控制台，而是产品界面：通过授权通道提交同一模型，并扣除工作区积分。创作器在提交前显示积分数量；10 积分 = $1。每秒标价见价格。

如果只想出片，跳过 HTTP，直接在首页创作器跑任务。如果要接自己的后端，使用下面的官方平台路径，密钥放在服务器上。

模型名与上线时间

官方调用请使用模型名 viduq4-preview。Preview 于 2026 年 10 月 7 日网页与 API 同步上线。本站目前没有单独的“正式版” id。文档给这个 id 标注的能力包括：音画同步、可选原生声音、单段内自动镜头切换。字段列表以供应商页面为准——拿不准某个参数时，以那些页面为源头。

官方鉴权

官方调用使用：

Authorization: Token <你的密钥>

目标是 https://api.vidu.com。密钥在供应商平台申请，不要写在本站设置里。本站不会让你在创作器粘贴该密钥，而是用站点自己的供应商凭证，按积分扣费。

密钥放在服务器环境变量中。不要提交到 git。不要从公开前端发送。如果密钥进过客户端包或聊天记录，立刻轮换。

图生视频

官方创建路径：

POST https://api.vidu.com/ent/v2/img2video

请求体大致包含：

• model — viduq4-preview（必填）。
• images — 恰好一张起始画面。URL 或 Base64。png / jpeg / jpg / webp。图片 ≤ 50MB。HTTP body ≤ 20MB。Base64 必须带内容类型前缀，例如 data:image/png;base64,...。
• prompt — 运动与机位（官方字段列表里为可选；最大长度记录为 20,000 字符）。静帧是第一帧；提示词应写接下来发生什么。
• is_rec — 是否使用平台推荐提示词（true / false，官方默认 true）。如果你写了认真的提示词，设为 false，以免系统把它换掉。
• duration — 整数 3–16，默认 5。
• resolution — 540p / 720p / 1080p / 2K / 4K，默认 720p。
• audio — true 为原生声音（对白与效果），false 为静音底板。默认 true。
• seed — 整数。省略或 0 为随机；追某条成片时再固定。
• payload — 透传字符串（文档最大 1,048,576 字符）。会随任务回传，便于你挂上自己的任务 id。
• callback_url — 状态变化时平台 POST 的 HTTPS 地址。

创建接口返回 task_id 和 state（created，随后是 queueing / processing / success / failed）。第一次响应里没有 MP4。

最小形状（替换图片 URL 和密钥）：

POST https://api.vidu.com/ent/v2/img2video
Authorization: Token YOUR_KEY
Content-Type: application/json

{
  "model": "viduq4-preview",
  "images": ["https://example.com/start-frame.png"],
  "prompt": "宇航员挥了挥手，镜头向上移动。",
  "is_rec": false,
  "duration": 5,
  "resolution": "720p",
  "audio": true
}

本站对应创作器选项是 Vidu Q4。上传静帧、输入提示词、提交。没有 JSON。

参考生视频

官方创建路径：

POST https://api.vidu.com/ent/v2/reference2video

请求体大致包含：

• model — viduq4-preview。
• prompt — 这条路径上为必填。官方示例用 [@reference_image_1]（以此类推）绑定静帧，用 [reference_audio_1] 绑定音色。不超过 20,000 字符。
• images — 1–15 张静帧，格式和大小限制与图生相同。这就是一致性包：角色、产品、风格、场景。
• sounds — 可选，0–3 个 MP3，每段约 3–12 秒，每个 ≤ 50MB。用来稳住音色。不是配乐。
• audio — 是否生成原生声轨（默认 true）。
• duration — 3–16 秒（默认 5）。部分介绍页写 1–16；本站仍使用 3–16。
• aspect_ratio — 16:9 / 9:16 / 1:1 / 3:4 / 4:3（默认 16:9）。
• resolution — 与图生同一档。
• seed、payload、callback_url — 与图生相同。

官方说明：Preview 暂不支持旧的“主体调用”方式。把图像（和可选的声音）放在这次任务上。不要指望上一代产品里存过的角色 id 在这里还能用。

本站对应创作器选项是 Vidu Q4 Refs。在参考区放入 1–15 张静帧。首页界面目前不采集那三段音色；若需要音色参考，走官方路径，或等该控件上线。

查询成片（轮询）

官方查询路径：

GET https://api.vidu.com/ent/v2/tasks/{id}/creations

请求头：Authorization: Token <你的密钥>（部分文档页也写过 Bearer——以密钥签发时的方案为准）。

当 state 为 success 时，creations[] 包含：

• url — 成片
• cover_url — 封面
• watermarked_url — 带水印副本

官方文档写这些 URL 有效 24 小时。需要更久请拷到自己的存储。failed 时看 err_code。官方响应里的 credits 是供应商单位，不是本站工作区积分。

简单轮询：等 2–5 秒，GET 任务，在 success 或 failed 时停下，给等待设上限（按分钟，不要按小时）。4K 图生比 540p 更久；不要在 15 秒时就超时。

用回调代替轮询

创建时设置 callback_url。任务状态变化时，平台 POST 的结构与查询接口相同。文档中的回调状态包括：processing、success、failed。发送失败会少量重试。用供应商的签名文档校验回调——不要信任一个开放 URL 上的原始 POST。

有公开 HTTPS 端点、同时很多任务在飞时用回调。调试单条 curl 时用轮询。

真正会踩的限制

• 图生一张图；参考生 1–15 张。
• 图像格式：png、jpeg、jpg、webp。音色：mp3。
• 每张图或每段音色 50MB；HTTP body 20MB。Base64 会变大——大静帧优先用 HTTPS URL。
• 提示词长度：20,000 字符。那是上限，不是目标。短的运动指令比小说更有效。
• 官方查询结果里的成片 URL 24 小时过期。
• 该模型 id 没有文生视频。

创建调用返回 400 时，检查 body 大小、data URI 的 content-type，以及即使只有一张图，images 也必须是数组。

不用 JSON，改用本站

首页创作器负责上传静帧、组装任务、按供应商估价扣除工作区积分，并轮询直到 MP4 就绪。你不用粘贴供应商密钥，也不用自己架 callback_url。本站鉴权失败意味着“请登录”，不是“缺少 Token 头”。

站点侧流程一览：

1. 登录。
2. POST 创作器生成接口，带上模型、提示词、参考 URL、时长、分辨率、纵横比、音频。
3. 轮询任务接口，直到 success 或 failed。
4. 从界面给出的结果 URL 下载。

这条路径给产品使用，不是给第三方应用的公开 REST 合同。若你要上线自己的应用，请用自己的密钥调用 api.vidu.com，并用自己的存储。

积分、标价和促销窗口在价格说明，没有第二套公式。创作器提交前显示的数量，就是任务开始后会扣除的数量。

错误和重试

• created / queueing / processing — 等待。
• success — 在 24 小时 URL 窗口内拷走文件。
• failed — 不要在 4K 上盲目重试。检查静帧（脸的大小、格式），缩短提示词，降低时长，再在 720p 重试。
• 官方路径 401 / 403 — 密钥错误或缺失。
• 本站积分不足 — 创作器会说明；到 /pricing 买积分包或订阅。

幂等：官方 payload 用来回传你自己的 id。本站创作器每次提交都创建新任务。

官方字段列表

• 图生视频
• 参考生视频
• 产品概览：vidu.com/vidu-q4

Preview 能生成和不能生成什么，见 Preview 指南。不想自己做轮询时，到首页生成。