Vidu MoE API 指南：专家混合视频模型

如果要用一句话总结： Vidu MoE 是一个面向短视频的 API，适合需要 1–16 秒片段、最高 1080p、24 fps、异步交付，以及在一次请求中可选音频的团队。

如果你在判断它是否适合生产，简短的答案是：当你能处理异步任务、为重试预留预算，并为每个阶段选择正确的模型档位时，它最有效。 我会用 viduq3-turbo 做预览，用 viduq3-pro 做最终输出。大多数任务在 720p 下约 60–120 秒、1080p 下约 90–180 秒完成，高峰等待时间可达约 4 分钟。

下面是最关键的内容：

• 输入模式： 文生视频、单图动画、Grok Imagine Video 替代方案、双帧首尾视频，以及多图参考输入
• 片段上限： 1 到 16 秒
• 输出： 最高 1080p，24 fps
• 音频： 可在同一次请求中开启
• 图像参考： 在更广的模型功能集中最多 7 张图像
• 主要 API 规则： 如果你发送图像 URL，不要发送 aspect_ratio
• 交付： 异步，带 task_id、轮询或回调
• 定价示例： Pro 约为 5 秒 $0.60 和 12 秒 $1.44
• 预算现实： 每条通过的片段需规划 2–3 次尝试

有几个细节很突出。该 API 使用一个简单的 JSON 请求，包含 model、prompt 和可选的媒体输入。模型选择很直接：turbo 用于更低成本的测试，pro 用于更高端的渲染。Seed 控制有助于你在重试间让输出保持大致相似的方向，尽管不是逐一精确匹配。

如果我为一个产品团队评估它，我会聚焦三个问题：

1. 我的应用能否干净地处理异步处理？
2. 我需要纯提示词生成、图像主导的控制，还是首/尾帧控制？
3. 算上重试后我的预算是否仍然成立，而不仅是首次成本？

快速对比

所以在你读完整份指南之前，要点很简单：当你想要多种输入模式、内置音频，并通过在 turbo 和 pro 之间切换来控制成本时，Vidu MoE 很适合基于 API 的短视频生成。 其余的就归结为请求设置、状态处理，以及挑选与你工作流匹配的输入方式。

Vidu MoE API 概览与核心能力

在 API 层面，Vidu MoE 映射到一小组模型名称、工作流和输出字段。

Vidu MoE 在 API 中以 viduq3-mix 出现，即均衡的 Q3 模型。viduq3-turbo 偏向速度，而 viduq3-pro 偏向更多细节。

专家混合（Mixture-of-Experts）在视频生成中意味着什么

专家混合把生成过程的不同部分分派给专门的组件。在实践中，这有助于运动、场景构图和遵循提示词。

Q3 系列也支持智能场景切换和智能镜头切换 ^[2][4]。这在多镜头序列中最重要，那里如果模型丢失了对场景的把握，连续性会很快崩塌。

支持的工作流：文生视频、图生视频和参考引导生成

从这里开始，主要差别取决于你发送的输入类型。

viduq3-mix 支持四种工作流：

• 文生视频，仅从提示词
• 图生视频，从一张起始图
• 参考生视频，从 1 到 7 张图像，用于外观和风格一致性
• 首尾生视频，从定义过渡的两帧

提示词最多支持 5,000 字符 ^[3][4]。viduq3-mix 不支持 Subjects 实体库。

输入与输出一览

每个任务返回一个 task_id 和 state，最终的 video_url 在处理完成后可用。

Q3 视频以 24 fps 运行，支持 1 到 16 秒的时长（与 Sora 2 能力相当），并提供 540p、720p 或 1080p 输出 ^[2]。图像输入每个文件限制为 50 MB ^[4][1]。

这些工作流选项决定了你接下来发送的负载，下一节会把它拆解为认证和请求格式。

认证、请求结构与 APIMart 设置

要生成 Vidu MoE 视频，你需要发送一个经过认证的 JSON 请求。请求体取决于输入模式：纯文本、单图或多图。

获取 API 凭证并设置请求头

从 APIMart API Key Management 页面生成你的 API 密钥 ^[6]。把它保存为 APIMART_API_KEY，然后在运行时用 Python 的 os.environ.get("APIMART_API_KEY") 或 Node.js 的 process.env.APIMART_API_KEY 加载。

每个请求都要带上这些请求头：

• Authorization: Bearer YOUR_API_KEY
• Content-Type: application/json

视频生成任务的最小请求负载

Vidu Q3（MoE）生成的标准 APIMart 端点是 https://api.apimart.ai/v1/videos/generations ^[6]。API 根据 image_urls 判断模式：

• 0 个 URL = 文生视频
• 1 个 URL = 图生视频
• 2 个 URL = 首尾帧

下面是核心字段及其使用时机 ^[6]：

这里有一个容易犯的错误：不要在带 image_urls 时发送 aspect_ratio。当你包含图像时，API 会从源图像中提取画面比例。如果你仍然发送 aspect_ratio，请求会返回 400 错误。

一旦负载设置好，你就可以提交任务并开始轮询结果。

示例 API 调用与响应模式

文生视频请求示例：

curl -X POST https://api.apimart.ai/v1/videos/generations \
  -H "Authorization: Bearer $APIMART_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "viduq3-turbo",
    "prompt": "A product shot of a glass perfume bottle on a marble surface, camera slowly zooms in, soft studio lighting",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "audio": false
  }'

成功提交会返回一个 task_id 和 submitted 状态 ^[6]：

{
  "code": 200,
  "data": [{
    "status": "submitted",
    "task_id": "task_xxxxxxxxxx"
  }]
}

该 API 异步运行。这意味着第一个响应只告诉你任务已被接受。使用 task_id 轮询 “Get Task Status” 端点。当任务完成时，响应会包含 MP4 链接，通常有效期为 7 天 ^[6]。

一个简单的轮询节奏就很好用：

• 前 5 分钟每 5 秒轮询一次
• 之后每分钟轮询一次
• 持续轮询，直到状态为 completed

到那时，下载并存储返回的视频链接。

接下来，调整时长、分辨率、画面比例和参考输入，以控制最终视频。对于需要不同电影风格的项目，你也可以对比 Kling V3 的能力来做高端视频生成。

生成工作流、参数与输出控制

端到端流程：提交、监控、获取并存储结果

提交任务后，最大的生产决策很简单：用回调还是轮询状态。多数情况下，callback_url 是生产环境的更优选择。轮询可行，但应当作为你的备用方案。使用回调时，API 会把最终状态发送到你的端点。如果投递失败，它最多重试三次 ^[3]。

任务随后会沿着一条固定的状态路径推进：created → queueing → processing → success 或 failed ^[3][4]。如果某个任务落到 failed，响应会包含一个错误码。记录该码并在工作流中处理它，这样你的团队就能更快地发现规律并修复问题。

当状态变为 success 时，立即下载输出并保存到持久存储。这一步很重要，因为 API 托管的 URL 可能会过期 ^[9]。

影响构图、运动、时长和一致性的关键参数

一旦任务开始运行，几个参数会决定结果的样子、它在多次运行间保持多稳，以及你花多少额度。

有一个参数从一开始就值得追踪：seed。如果你得到一个喜欢的运动模式，记下那个整数并保留它。然后，当你之后调整提示词时，可以复用相同的 seed 来保住相似的整体构图，而不必从头开始。

何时仅用提示词、用图像参考，或两者并用

这些输入模式让你在速度和控制之间权衡。挑选与你视觉方向锁定程度相匹配的那个。

• 仅提示词（文生视频）： 最适合在视觉素材定稿前的早期构思、风格测试和场景实验。使用 viduq3-turbo 在 540p 或 720p 下保持较低的迭代成本，或将其与 WAN 2.6 这类高一致性替代方案对比 ^[7]。
• 单图（图生视频）： 最适合当你想让某个具体物体动起来时，比如产品照片、角色插画或品牌视觉。这非常适合电商和营销工作。
• 双图（首尾帧）： 最适合当过渡需要落在一个设定结果上时，比如产品转到某个角度，或角色进入某个特定姿势 ^[5]。

如果手动提示给你的结果参差不齐，开启 is_rec: true。API 会从你的图像生成一个优化后的提示词，这能帮助图像-提示词对齐，但每个任务会增加 10 额度 ^[1]。

性能、定价与真实集成场景

如何评估延迟、可靠性和每条视频成本

在你锁定请求格式之后，接下来要看的是速度、价格和任务成功率。这是一个异步工作流，所以你的应用应当提交任务、存储 task_id，并随后通过轮询或回调取回最终的 MP4 ^[3][6]。

任务通常沿一条简单路径推进：排队、完成或失败。当任务失败时，额度往往会自动退还 ^[3][10]。这在生产中很重要，因为重试是流程的一部分，而非某种边缘情况。

在周转时间方面，720p 生成通常在 60–120 秒内完成。对于 1080p，预计更像 90–180 秒。非高峰时段排队时间常为 15–30 秒，而高峰 p95 延迟可拉长到约 4 分钟 ^[7]。所以，是的，它在生产中可以很好地工作——但前提是你的系统被构建得能干净地处理异步完成。

在定价上，Pro 费率使 5 秒片段为 $0.60，12 秒片段为 $1.44 ^[10]。在实践中，大多数团队应当为每个通过的资产规划 2–3 次尝试。这使一条可用片段的最终成本落在 $1.20–$4.32 区间，取决于时长 ^[10]。如果你处于测试模式，viduq3-turbo 约为 Pro 的一半价格，更适合快速迭代。Pro 最好留给最终渲染 ^[10]。

这些数字仅涵盖基础生成。它们不包括重试。如果你的团队预期多次生成——大多数团队都会——把总额乘以 2–3，得到一个更贴近日常生产的预算。

用例：营销视频、教育片段和电商产品画面

一旦成本和等待时间清楚了，下一步就是为你需要交付的资产挑选正确的输入模式。最佳选择主要取决于一件事：你已经掌握了多少视觉控制。

一个简单的思考方式：

• 如果品牌一致性重要，用参考生视频
• 如果源图像已经够好，用图生视频
• 如果你需要两个状态之间的运动，用首尾帧
• 如果你想要大量快速的广告变体，用文生视频，或考虑用 MiniMax Hailuo 2.3 获得高一致性的专业输出。

对于想削减剪辑时间的团队，原生音频对工作流的改变最大。原生音频省去了单独的音源采集和剪辑工作 ^[8]，对于想从单次生成就拿到成片的团队，这能去掉额外的后期步骤。这正是该模型最有用的地方：当目标是接近一个可交付资产，而无需让文件经过冗长的交接链时。

结论：如何判断 Vidu MoE 是否契合你的生产工作流

当你需要最长 12–16 秒的短片段、多种输入模式，以及异步 API 设置中的原生音频时，Vidu MoE 就很有意义。seed 参数可以帮助让重复任务保持大致相同的方向，但你不应期待相同的输入产出逐位匹配的输出 ^[6][10]。失败的任务也往往会触发自动额度退还 ^[3][10]。

这适合那些规模化制作短视频、能为结果等几分钟、并在预算中为重试留出空间的团队。如果这听起来像你的工作流，APIMart 给你一种干净的方式，通过一个 API 界面来运行营销创意、产品画面和讲解内容。

常见问题

我应该先用哪个 Vidu MoE 模型？

对大多数开发者来说，viduq3-turbo 是最佳的起点。它给你最快的生成速度、强劲的性价比，以及音画同步和智能场景切换等高级功能。

如果你想要最完整的功能集，选 viduq3-pro。它包含分镜生成和最高质量的音画对齐。两个模型都支持 1 到 16 秒的视频和最高 1080p 的分辨率。

我该如何处理失败或延迟的视频任务？

在你的异步工作流中使用 task ID。

对于耗时较长的任务，要么时不时轮询状态 API，要么设置一个回调 URL，以便任务进入终态时收到通知。

如果任务失败，检查回调或状态响应中的错误详情。

为了生产稳定性，轮询时使用指数退避，以免撞上速率限制。

运行超过 48 小时的非高峰任务会被自动取消，积分会退还。

哪种输入模式提供最多的控制？

**多帧生成（Multi-Frame Generation）**让你对视频如何从一个时刻过渡到下一个时刻拥有最多控制。你不必依赖单个提示词或双帧设置，而是可以规划出最多 9 个关键帧的序列。

那份额外的控制很重要。对于每次过渡，你都可以添加一张特定图像和一个自定义提示词，这样视觉故事就会逐帧沿着你想要的路径展开。

要使用它，把你的图像和提示词通过 image_settings 数组发送到 multiframe 端点。