Vidu API 指南：MoE 模型与 Q 系列接入

如果要用一句话总结：用 Vidu MoE 处理更难的提示词逻辑，用 Q3 Pro 出最终成片，用 Q3 Turbo 做低成本测试——全部通过一套 APIMart 配置。

下面是你可以立刻动手的简版：

• 我能通过 APIMart，用一个 API key 和一套主请求流程访问 Vidu MoE、Vidu Q3 Pro 和 Vidu Q3 Turbo。
• 核心端点是 POST https://api.apimart.ai/v1/videos/generations。
• 视频任务是 异步 的，所以我先拿到一个 task_id，然后轮询 GET /v1/tasks/{task_id} 或使用 callback_url。
• Vidu 支持：
  • 文本生视频
  • 图像生视频
  • 基于参考的视频
  • 首尾帧过渡
• Q3 模型增加了 内置音频，如对话、音效和音乐。
• 片段最长可达 16 秒，输出为 540p、720p 或 1080p。
• 文章中列出的 APIMart 定价：
  • Q3 Pro： 720p 下约 $0.12/秒
  • Q3 Turbo： 720p 下约 $0.048/秒
• 输出链接在 24 小时 后失效，所以成功后我应尽快下载文件。

快速对比

让我印象深刻的是切换有多简单：在大多数情况下，我只需更改 model 字段，其余设置保持不变。这让这篇文章不那么关乎搭建工作，而更关乎 为成本、等待时间和 输出质量 挑选合适的模型。

Vidu 模型解析：MoE vs. Q 系列

Vidu 的 MoE 模型：它是什么以及何时使用

MoE（专家混合，Mixture of Experts） 模型把生成任务的不同部分分派给专门负责运动、场景一致性和提示词控制的专家。它在多场景或更长的提示词中最为合理，此时一致性比纯粹的速度更重要。

不过有个问题。MoE 占用更多算力，且周转比 Q 系列更慢 ^[7]。对于简单提示词，它往往超出你的需求。

Vidu Q 系列与 Vidu Q3 Pro：面向生产的性能

如果说 MoE 是专家，那么 Q 系列就是为生产工作打造的选项。Vidu Q3 Pro 专为精修的电影级输出和分镜驱动的视频而设计 ^[7]。它支持 1080p 视频、最长 16 秒的片段，以及带同步对话和音效的音画生成 ^[1][2][4]。在 APIMart 上，Q3 Pro 起价 每秒 $0.12 ^[2][3]。

Vidu Q3 Turbo 更偏向速度和低成本，场景切换更快 ^[6][7]。在 APIMart 上，Q3 Turbo 起价 每秒 $0.048 ^[3]。

如何为你的工作流在 MoE 与 Q 系列之间选择

这个选择主要取决于提示词复杂度、周转时间和预算。如果你的工作流依赖严格的指令遵循和多场景逻辑，就选 MoE。如果你需要带音画同步的精修输出，Q3 Pro 更合适。或者，Kling V3 为电影级 AI 视频提供了另一个高保真选项。如果你的主要目标是快速迭代或更低的单片段成本，Q3 Turbo 是实用的选择。

下表把每个模型映射到它最擅长处理的工作类型。对于正在对比高端选项的人，Sora 2 提供了带同步音频的类似电影级能力。

接下来，看看如何选择模型、认证，并通过 APIMart 发送请求。

如何通过 APIMart 访问 Vidu

账户设置、认证与 API Key 处理

选好模型后，你可以用 一个 API key 通过 APIMart 发送任务。首先，创建一个 APIMart 账户，并从仪表盘的 API key 管理页面生成你的 key ^[2][3]。

每个请求都在 Authorization 请求头中带上一个 Bearer token：

Authorization: Bearer YOUR_API_KEY

在存储方面，把 key 保存在环境变量或密钥管理器中，如 AWS Secrets Manager 或 GCP Secret Manager。为开发、预发布和生产使用单独的 key 也有帮助。如果 key 泄露，立即轮换它。也按固定计划做同样的轮换。记录请求时，只保存 task_id——绝不保存 token 本身 ^[5]。

在 APIMart 中查找 Vidu 模型、定价和输入 schema

登录后，在发送任何内容前先查看目录。那里可以确认模型名称、支持的输入和当前定价。在 APIMart 的目录中，Vidu 模型列在 视频生成（Video Generation） 下。你也可以在同一类别中找到其他高性能模型，如 MiniMax-Hailuo-02。用那个页面来对比 MoE、Q3 Pro 和 Q3 Turbo 的输入 schema、分辨率和每秒成本 ^[2][3]。

需要关注的主要字段是：

• model
• prompt
• duration
• resolution
• aspect_ratio

对于文本生视频任务，使用 aspect_ratio。对于基于图像的任务，系统会改用源图像的比例 ^[2]。文本提示词限制为 2,000 个字符 ^[2][3]。

端点、请求结构与异步任务处理

选好模型后，提交生成请求，并用返回的 task_id 跟踪异步任务。向 https://api.apimart.ai/v1/videos/generations 发送一个 POST 请求，然后用 GET https://api.apimart.ai/v1/tasks/{task_id} 轮询任务状态 ^[2][5]。

任务会经历这些状态：

• submitted
• queueing
• processing
• success 或 failed

如果你想让 APIMart 在任务完成时通知你的应用，添加 callback_url 并通过 webhook 接收结果 ^[5]。任务一旦达到成功状态，立即下载文件。从这里开始，你可以把请求字段映射到文本生视频流程或基于参考的流程。

文本生视频与基于参考视频的分步集成

带模型选择的基础文本生视频流程

从目录中选好模型后，文本生视频流程相当简单。从服务端在 Authorization 请求头中以 Bearer {your_api_key} 的形式发送你的 API key。

下面是一个使用 viduq3-pro 的文本生视频任务的最小负载：

{
  "model": "viduq3-pro",
  "prompt": "A red fox running through a snowy forest at dusk, cinematic slow motion",
  "duration": 8,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "audio": true
}

响应中包含一个 task_id 和一个状态，如 submitted、queueing 或 processing。之后，你可以用返回的 task_id 轮询 GET /v1/tasks/{task_id}，或在请求中传入 callback_url，让平台在任务达到 success 或 failed 时通知你的应用 ^[1][7][10]。如果你想切换到 viduq3-turbo，基本上只需更改 model 字段。

异步模式在各模式间保持不变。变化的是输入字段。

添加图像或参考输入及高级控制

对于图像生视频，在 image_urls 数组中传入一个图像 URL。文本生视频用 0 张图像，图像生视频用 1 张，首尾帧模式用 2 张 ^[2]。在基于图像的模式中，输出宽高比来自源图像，所以你可以省略 aspect_ratio ^[2]。如果你直接上传文件而不使用 URL，每张图像保持 PNG、JPEG 或 WebP 格式，小于 50 MB，并保持 HTTP 总体积小于 20 MB ^[9][8]。

对于基于参考的生成，使用 /reference2video 端点配合一个 subjects 数组。用 name 和它的 images 定义每个主体，然后在提示词中用 @subjectname 调用它。Q3 模型在 subjects 功能中允许最多 7 张参考图或文本描述 ^[6]。如果你使用首尾帧模式，让两张图像在宽高比上接近，最好在 0.8 到 1.25 的比例范围内，以减少失败 ^[8]。当涉及面孔或手部时，让运动提示词保持微妙，以减少畸变伪影 ^[5]。

下表展示了两种流程中的主要参数：

测试时如果你想在多次运行间得到相同的视觉结果，就设置一个固定的 seed ^[2][9]。对于不急的批量任务，把 off_peak 设为 true。这些任务通常在 48 小时内完成，并使用更少的 credit ^[1][6]。

追踪用量、成本与生产可靠性

请求跑通后，下一个任务是在生产中把成本和可靠性控制好。

为每个请求记录 task_id 和时间戳。这给了你一种安全的调试方式，而无需存储敏感凭证 ^[5]。分别追踪排队时间和生成时间也有帮助，这样你就能区分平台延迟和模型延迟。

在成本估算方面，Vidu Q3 Pro 在 720p 下约为 APIMart 上的 每秒 $0.12，Q3 Turbo 约为 每秒 $0.048 ^[3]。在你月度预算上限的 50%、80% 和 100% 处设置自动告警，这样开销就不会失控 ^[5]。

重试同样重要。在 5xx 错误上，使用指数退避：在向用户显示错误前，先在 2 秒、然后 5 秒、再 15 秒时重试 ^[5]。Vidu Q3 系列模型为生产工作负载提供 99.9% SLA ^[3]，但短暂的失败仍会发生，所以重试应是任何上线版本的一部分。

模型选择清单与关键要点

面向开发者、创作者和产品团队的使用场景清单

根据三点来挑选：提示词复杂度、速度和输出质量。下表把模型对比转化为一个实用的上线选择。

选定一行之后，从集成部分沿用相同的请求 schema。说白了：在 Q3 Turbo 中开始构思，然后把最终的 1080p 渲染交给 Q3 Pro。这是个简单的工作流，它能帮你快速推进而不必花超出所需的钱。

对于运动保真度最重要的片段，把目标定在 5–10 秒，而不是硬撑到 16 秒上限。更短的片段往往能给你更紧凑的运动和更少的麻烦。

上线前要记住的要点

MoE 是复杂、多场景逻辑的首选。Q3 Pro 给你高保真、电影级的 1080p 输出 ^[3]。Q3 Turbo 是更低成本的选项，720p 下 $0.048/秒 ^[3]。

在 APIMart 上，在这些模型之间切换只需更改单个 model 参数。请求中其余部分保持不变 ^[3]。这意味着你可以测试一个模型、切换到另一个，同时保持集成工作稳定。

每次都使用相同的异步流程：

• 提交请求
• 捕获 task_id
• 轮询状态或使用 callback_url

另外，生成的视频就绪后尽快下载。输出链接在 24 小时 后失效 ^[3][11]。

常见问题

我应该从哪个 Vidu 模型开始？

从符合你对速度、音频和视觉控制需求的模型开始。

• viduq3-pro：最适合音画同步和镜头分段
• viduq3-turbo：生成比 pro 版本更快
• viduq1 或 viduq2：稳定视频制作和可靠镜头运动的可靠选择

提交后我如何追踪一个视频任务？

你可以用两种方式追踪你的视频生成任务。

对于生产用途，最佳选择是在初始请求中包含一个 callback_url。这样做之后，Vidu API 会把任务更新和结果元数据自动发送到你的 URL。这意味着你无需自己反复检查任务状态。

另一种选择是用提交后拿到的 task_id 轮询状态查询 API。一旦任务状态变为 success，响应中会包含视频下载 URL 和其他相关元数据。

集成前我应该了解哪些输入和限制？

在集成 Vidu API 之前，确保你的输入保持在以下限制内：

• 图像：仅限 PNG、JPEG、JPG 或 WebP；每个文件必须小于 50 MB，且至少 128×128 像素
• HTTP 请求总体积：最大 20 MB
• 文本提示词：最多 5,000 个字符
• 负载透传数据：最多 1,048,576 个字符

时长限制取决于你使用的模型。Q3 支持 1–16 秒，Q2 支持 1–10 秒，Q1 支持 5 秒。

另外，保管好你的 API key。不要在客户端代码中暴露它们。改为通过 服务端中间层 发送请求。