Vidu API 五分钟上手：从创建 Key 到文生视频拿成片，四接口参数全拆解
把 AI 视频能力接进自己的产品，Vidu 开放平台给了一条五分钟的路：注册、创建 API Key、发请求、轮询拿结果。这篇教程依据 Vidu 官方平台文档（platform.vidu.cn）整理，覆盖三大模型系列的定位、文生视频接口的完整参数表、官方 curl 示例的逐行解读，以及错峰、水印、回调这些容易踩坑的可选项。
三大系列：先选对模型
平台的模型地图分三大系列，官方对它们的定位一句话能说清。
实时生成模型 S1：低延迟实时生成，边输入边出画，适合直播互动与实时相伴场景。官方宣传语是「视频，不再只是等待生成，而是开始回应世界」。这一系列的价值在交互——传统生成是提交后干等，S1 把等待变成了响应，弹幕互动、实时相伴这类产品形态才有得做。
官方平台对 S1 的介绍：实时交互，视频开始回应世界，适合直播互动场景
视频生成模型 Q：旗舰视频大模型，长时长、高一致、大动态，文生/图生/参考生全覆盖。Q3 系列的主打口号是「为剧而生、万物可参、声画同出」——参考素材保持主体一致，画面声音一次生成。
官方平台对 Q3「参考生」能力的示例画面：西部牛仔黄昏场景，主体一致性与声画同出
图像生成模型：文生图与参考生图，最高 4K 输出，支持多张参考图，主体一致性突出。
计费是统一积分制，标准需求自助充值；规模化与定制需求（高并发 SLA、私有化部署、专属 onboarding）走商务通道。API 与网页版功能同源。
三步跑通第一个任务
官方把上手路径压缩成三步：注册并创建 API Key（控制台一键生成密钥，完成鉴权配置）；发起第一个请求（复制示例代码，替换 Key 即可调用）；轮询任务结果（拿到生成视频地址，接入你的产品）。从注册到第一段视频，官方口径五分钟。
注册用手机号和短信验证码，也支持谷歌账号登录。企业协作场景另有子账号体系：主账号可以给成员分配独立登录身份、单独设置积分限额和并发上限，未设置独立额度的账号共享主账号余额。
文生视频：官方示例逐行拆
平台首页给的官方示例代码，是最短可用路径：
# 发起一次文生视频请求
curl -X POST \
-H "Authorization: Token {your_api_key}" \
-H "Content-Type: application/json" \
-d '{
"model": "viduq3-pro",
"style": "general",
"prompt": "...",
"duration": 5,
"seed": 0,
"aspect_ratio": "4:3",
"resolution": "540p",
"movement_amplitude": "auto",
"off_peak": false
}' \
https://api.vidu.cn/ent/v2/text2video
# 用 task_id 轮询获取生成结果
curl -X GET \
-H "Authorization: Token {your_api_key}" \
https://api.vidu.cn/ent/v2/tasks/{task_id}/creations
示例里的 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.（超写实时尚摄影风格，浅蓝与淡琥珀色调，一名宇航员穿着宇航服在雾中行走。背景是迷人的白色与金色光点，构成极简静物与壮观全景。）
逐行看关键参数。鉴权走 Authorization: Token {api_key} 请求头，Key 在控制台创建。端点是 POST https://api.vidu.cn/ent/v2/text2video，创建成功返回 task_id，然后拿它调 GET /ent/v2/tasks/{task_id}/creations 轮询，任务状态从 created（创建成功）、queueing（排队中）、processing（处理中）到 success（成功）或 failed（失败），成功后返回视频下载地址。
请求体里 model 是必填的模型名。文生视频接口的可选值及官方定位：
viduq3-pro：高效生成优质音视频内容，更生动形象立体，效果最好；viduq3-turbo：对比 pro 生成速度更快；viduq2：官方标注「最新模型」；viduq1：画面清晰，平滑转场，运镜稳定。
时长按模型分档：q3 系列默认 5 秒、可选 1–16 秒；q2 默认 5 秒、可选 1–10；q1 固定 5 秒。分辨率 q3/q2 默认 720p，可选 540p、720p、1080p；q1 默认 1080p 只有 1080p。画幅默认 16:9，可选 9:16、3:4、4:3、1:1——其中 3:4 和 4:3 仅 q2、q3 系列支持。提示词上限 5000 字符，seed 不传或传 0 用随机数，想复现同一构图就手动固定种子。
风格参数 style 默认 general，另有 anime 档——仅在动漫风格表现突出，可用不同动漫风格的提示词细分控制；注意 q2、q3 系列模型不生效这个参数。运动幅度 movement_amplitude 可选 auto、small、medium、large，同样在 q2、q3 系列上不生效——新系列模型把动态幅度交给了提示词控制。
还有一个实用的可选项 is_rec（推荐提示词）：传 true 时系统自动推荐提示词并直接按它生成，省去自己写的功夫；代价是每个任务多消耗 10 积分，且开启后你自己传的 prompt 会被忽略。赶时间出创意草稿可以用，正式产出还是自己写提示词更可控。
四个接口，四种玩法
除了文生视频，文档还列了另外三个常用视频接口，覆盖了从图动起来到多素材融合的场景。
图生视频（POST /ent/v2/img2video）：传一张首帧图，模型以它为起点生成视频。可选模型比文生多出 viduq3-pro-fast、viduq2-pro-fast、viduq2-turbo 等 fast 档——官方对 q2-pro-fast 的说明是「价格触底、效果稳定，生成速度较 viduq2-turbo 提高 2-3 倍」。图片支持 Base64 或 URL 传入，png/jpeg/jpg/webp 格式，最大 50MB，注意整个 POST body 不超过 20MB。
官方平台的参考合成示例：摩托车手与喷火龙两张素材图，合成出骑士迎战巨龙的连贯画面
参考生视频（POST /ent/v2/reference2video）：传 1–7 张参考图（viduq2-pro 传视频时上限 4 张），模型以图中的主体为参考生成主体一致的视频。这一档的模型选择最全，还包括 viduq3-mix（画面质感强，支持智能切镜与音画同出，均衡性最强）和 viduq2-pro（支持参考视频与视频编辑替换）。
首尾帧生视频（POST /ent/v2/start-end2video）：传两张图锁定起点和终点，中间的过渡由模型补全。两张图分辨率要相近——首帧分辨率除以尾帧分辨率须在 0.8–1.25 之间，差太远直接被拒。
所有接口的响应体结构一致：task_id、state、model、prompt、duration、resolution、credits（本次消耗积分）、created_at 等字段，接进产品后按统一结构解析。
容易踩坑的可选项
几个参数的官方注释里有明确的坑，值得单独拎出来。
错峰模式 off_peak：传 true 积分更便宜，但任务在 48 小时内生成，超时未完成的任务自动取消并返还积分。适合不赶时间的批量任务，赶交付就别开。viduq3-mix 不支持错峰。
水印 watermark：默认不加。开启后水印内容由 AI 生成（固定样式），可用 wm_url 传自定义水印图片 URL，wm_position 选四角位置（默认右下）。
音画直出 audio：q3 系列支持，true 时输出带台词和音效的有声视频，q3 系列默认开启；q2 及更早系列输出静音视频。配套的 audio_type 可拆分「音效+人声 / 仅人声 / 仅音效」（q2、q1、2.0 系列支持拆分），voice_id 指定音色（q3 不生效），还能用声音复刻 API 复刻任意音色。
回调 callback_url：创建任务时设置一个 POST 地址，任务状态变化时 Vidu 主动推送，结构与查询接口返回体一致，省掉轮询。发送失败重试三次，鉴权走回调签名算法。回调状态机很简单：processing → success 或 failed。
接入产品前的准备清单
把流程串起来，一个最小可用集成需要：控制台创建 API Key → 选模型（按需求定档：效果选 q3-pro、速度选 q3-turbo、低价选 q2-pro-fast）→ 发起任务拿 task_id → 轮询或回调等结果 → 从 creations 接口取视频 URL。批量生产场景再考虑错峰模式压成本、子账号体系分额度、商务通道要并发。
积分消耗在每个任务的响应里都有 credits 字段回传，接进产品后可以按任务记账。具体每个模型每秒的积分单价，官方放到了产品定价页，以那边实时数字为准。
来源与延伸
本文接口、参数与限制均整理自 Vidu 开放平台官方文档（platform.vidu.cn/docs），示例代码为官方首页原文，配图转存自官方平台，版权归原作者所有。
