奇链 奇链
← 教程库
进阶 约 25 分钟 2026-09-24 09:33:28 · 2 阅读

Vidu API 接入实操：注册拿 Key、text2video 出第一条视频、轮询取结果全流程

想把 Vidu 的视频生成接进自己的产品或脚本，官方开放平台给了一条最短路径：注册拿 API Key、发一个 POST 请求、轮询任务拿视频地址——官方快速入门页的说法是「从注册到第一段生成视频，5 分钟即可完成」。这篇依据 Vidu 开放平台官方文档（快速入门、文生视频接口、查询生成物接口三页）整理，每一步给出可以直接复制的请求结构和官方示例，请求体参数表里容易踩的联动限制也一并摘出。站内 AI 视频教程总纲在此，Vidu 的产品页在此。

接口长什么样：两个端点跑完全程

Vidu 的任务制 API 只需要记两个地址：创建任务用 POST https://api.vidu.cn/ent/v2/text2video（文生视频；图生、参考生、首尾帧各有自己的路径），查询结果用 GET https://api.vidu.cn/ent/v2/tasks/{task_id}/creations。两个请求的鉴权方式相同：请求头带 Authorization: Token {你的APIKey} 和 Content-Type: application/json。生成不占你本地机器的算力，视频在 Vidu 服务器上渲染，完成后通过查询接口或回调拿地址。

模型一列四档，都在同一个接口里切换：viduq3-turbo（比 pro 生成更快）、viduq3-pro（效果更好，官方描述是「高效生成优质音视频内容」）、viduq2、viduq1（画面清晰、运镜稳定）。下面会讲到，时长、分辨率、画幅的可选值都和这四个模型名挂钩，填错组合会直接报错。

注册与 API Key：默认 Key 能直接用

访问 Vidu 开放平台国内站（platform.vidu.cn），点右上角「开始接入」完成注册。进入控制台后不用自己摸索创建入口——系统已经默认生成了一把 Default Api Key，直接拿来测试就能用。官方的建议是正式接入前另建一把 Key：测试 Key 和生产 Key 分开，泄露时只作废一把，排查问题时也能按 Key 区分流量来源。Key 在控制台的密钥管理里创建，创建后只在生成时展示一次，记得存好。

积分怎么来：资源包价格与两条限制

API 按积分计费，没有免费额度直接可用。官方给两条路：在线购买资源包，或填写客户信息表获取赠送积分（官方注明信息准确的话一般当天发放）。2026 年 9 月在售的资源包价格如下，来自官方定价页快照，随时可能调整，以官方页面为准：

  • Vidu S2 定向资源包：350 元（原价 500 元），16,000 积分，限购 1 次，仅限新用户体验新发布模型；
  • 入门体验包：500 元，16,000 积分，约可生成 400 条 5 秒视频；
  • 进阶创作包：1,000 元，32,000 积分，约 800 条 5 秒视频；
  • 创作团队包：折后 4,500 元，160,000 积分，约 4,000 条 5 秒视频；
  • 企业级内容包：折后 16,000 元，640,000 积分，约 16,000 条 5 秒视频。

所有自助资源包的可用并发数都是 5，有效期 12 个月，这两条是官方文档里白纸黑字的限制。更大的并发、模型微调、私有化要走商务定制通道，不在自助充值范围内。

发出第一个请求：一条可复制的 curl

下面这条 curl 来自官方文生视频接口文档，可以直接复制，把 Token 换成你的 Key：

curl -X POST -H "Authorization: Token 你的APIKey" -H "Content-Type: application/json" -d '
{
    "model": "viduq3-pro",
    "style": "general",
    "prompt": "In an ultra-realistic fashion photography style featuring light blue and pale amber tones, an astronaut in a spacesuit walks through the fog. The background consists of enchanting white and golden lights, creating a minimalist still life and an impressive panoramic scene.",
    "duration": 5,
    "seed": 0,
    "aspect_ratio": "4:3",
    "resolution": "540p",
    "movement_amplitude": "auto",
    "off_peak": false
}' https://api.vidu.cn/ent/v2/text2video

这条示例提示词值得看一眼写法：先定风格与色调（ultra-realistic fashion photography style, light blue and pale amber tones），再给主体与动作（astronaut walks through the fog），最后补环境光效（white and golden lights, panoramic scene）。改写成中文场景同样成立，接口对中文提示词没有限制，但这条英文原文是官方文档里的示范，照抄必能出片。

请求体参数表里，除了 model 和 prompt 必填，其余都有默认值。有几个参数之间的联动关系是官方文档反复强调的坑：

  • duration：viduq3-pro / viduq3-turbo 可选 1-16 秒，viduq2 可选 1-10 秒，viduq1 只有 5 秒；
  • resolution：q3、q2 系列可选 540p / 720p / 1080p（默认 720p），viduq1 只有 1080p；
  • aspect_ratio：默认 16:9，可选 9:16、3:4、4:3、1:1，其中 3:4 和 4:3 仅 q2、q3 系列支持；
  • style 的 anime 值、movement_amplitude 整个参数，在 q2、q3 系列上不生效；
  • bgm 参数在 q2 的 9/10 秒时长和 q3 全系上不生效；
  • audio（音画直出，默认 true）仅 q3 系列支持。

还有一个省钱开关值得单独说：off_peak 错峰模式。设为 true 时积分消耗更低，代价是任务会在 48 小时内完成，超时未完成的自动取消并返还积分，也可以手动取消。内测赶工期别开，批量囤素材可以开。

任务创建成功后，响应体里最重要的是这两个字段：

{
  "task_id": "your_task_id_here",
  "state": "created",
  "model": "viduq3-pro",
  ...
  "credits": credits_number,
  "created_at": "2025-01-01T15:41:31.968916Z"
}

把 task_id 记下来，这是下一步查询的唯一凭据。credits 字段告诉你这次任务扣了多少积分，方便对账。

查询任务：五种状态与 24 小时时效

用 task_id 调查询接口：GET https://api.vidu.cn/ent/v2/tasks/{task_id}/creations，同样带 Token 头。任务的 state 有五个值：created（创建成功）、queueing（排队中）、processing（处理中）、success（成功）、failed（失败）。官方文档特别提醒：state 一旦进入 processing 就无法取消，轮询脚本里看到 processing 只能继续等。

成功后的响应体长这样（官方示例原文）：

{
  "id": "your_task_id",
  "state": "success",
  "err_code": "",
  "credits": 4,
  "payload": "",
  "creations": [
    {
      "id": "your_creations_id",
      "url": "your_generated_results_url",
      "cover_url": "your_generated_results_cover_url",
      "watermarked_url": "your_generated_results_watermarked_url"
    }
  ]
}

视频地址在 creations[0].url，封面在 cover_url。注意官方文档标注的硬限制：生成物 URL 有效期 24 小时，过期即失效。所以拿到地址后第一时间下载转存到自己的存储，别把 Vidu 的临时 URL 直接写进数据库当永久链接用。

不想轮询的话，创建任务时传 callback_url，任务状态变化时 Vidu 会 POST 回调你的地址，内容结构与查询接口的返回体一致；success 和 failed 的回调在发送失败时会重试三次。回调的合法性验证走 Vidu 的回调签名算法，官方文档有单独一页讲密钥和验签实现。

Vidu 官方文档示例：宇航员图生视频示例帧

官方文档图生视频接口的示例输入帧：宇航员立于星云前——快速入门里的示例任务即以这张图为输入，配提示词 The astronaut waved and the camera moved up

Vidu 首尾帧生视频官方示例帧

官方文档首尾帧生视频接口的示例帧：车内视角望向窗外火鸟飞过雪山湖泊，同一套任务制 API，换接口路径即可调用

官方 FAQ 里的实战答案

快速入门页末尾的 FAQ 是官方踩坑记录的直接来源，几条对新手最要紧：

云服务器上创建任务后拿不到响应体。官方明确：系统目前仅支持 TLSv1.2 和 TLSv1.3，不支持 sslv3。本地能通、上云不通，先查服务器的 TLS 协议配置。

图片 URL 传了但任务失败。官方要求图片地址务必可访问，URL 里带中文必须 encode。用国内对象存储的链接尤其注意签名参数和中文文件名。

Windows CMD 里 curl 总提示被拒绝。官方建议改用 APIfox 或 Postman 调试，文档专门为 CMD 用户写了替代示例。

频繁返回 TaskPromptPolicyViolation。所有生成内容都要过审核，涉黄、涉政、暴力内容无法通过，这不是接口故障，改提示词才有用。

查询积分。控制台的「使用明细」页面，或积分查询接口——注意 Key 不能跨账号查积分，只能查自己账号的。开票流程官方也给了完整链路：控制台 → 充值明细 → 去开票 → 填邮箱收链接 → 填开票信息。

模型矩阵比四个名字更宽：实时数字人 Vidu S2、图像生成、声音复刻、文生音频、语音合成各有独立接口，还有一键广告成片、AI-MV、解说漫等解决方案级 API，全部走同一套任务制模式——学会文生视频这一条，其余接口照着文档换路径就行。

Vidu S2 实时交互与实时编辑能力官方宣传图

官方首页的 Vidu S2 能力图：同一张原图实时换风格、换背景、换服装、换主体、换道具，S2 系列接口适用于实时音视频交互任务

本文步骤、参数表与代码示例依据 Vidu 开放平台官方文档（快速入门 / 文生视频 / 查询生成物接口 / 产品定价）整理，版权归原作者所有。积分价格与模型参数以官方页面实时为准。

本篇用到的工具

Vidu
Vidu
Vidu是生数科技发布的AI视频生成工具，支持文本生成16秒1080P高清视频，帮助用户快速创建高质量视频内容，适用于短视频、广告、教育等场景。

评论 (0)