Vidu 视频生成 API

本文介绍如何通过本服务调用 Vidu 视频模型。客户端使用本服务签发的 API Token；示例中的 BASE_URL 和 API_TOKEN 请替换为实际值。

高级参数通过 metadata 透传到上游，请使用 PascalCase 字段名，例如 Audio、AudioType、CallbackUrl、LogoAdd。

接口一览

推荐使用 OpenAI Video 兼容路径：

方法	路径	用途	响应风格
`POST`	`/v1/videos`	创建视频生成任务	OpenAI Video 对象
`GET`	`/v1/videos/{task_id}`	查询任务状态和结果	OpenAI Video 对象
`GET`	`/v1/videos/{task_id}/content`	下载生成的视频	视频二进制

同时兼容旧路径：

方法	路径	用途
`POST`	`/v1/video/generations`	创建视频生成任务
`GET`	`/v1/video/generations/{task_id}`	查询任务状态和结果
`POST`	`/v1/videos/generations`	创建视频生成任务

能力路由

本服务会根据输入自动选择上游 Action：

请求形态	提交 Action	查询 Action	能力
不传 `image` / `images` / `input_reference`	`SubmitTextToVideoViduJob`	`DescribeTextToVideoViduJob`	文生视频
传入 `image` 或 `images` 1 到 2 张	`SubmitImageToVideoViduJob`	`DescribeImageToVideoViduJob`	图生视频；2 张图按首尾帧处理
传入 `input_reference`、`images` 3 张及以上，或 `metadata.Action=referenceGenerate` / `metadata.action=referenceGenerate`	`SubmitReferenceToVideoViduJob`	`DescribeReferenceToVideoViduJob`	参考生视频

metadata.Action / metadata.action 只用于本服务选路，不会转发给上游。

支持模型

API 模型名	上游 `Model`	文生视频	图生视频	参考生视频	说明
`viduq3-pro`	`viduq3-pro`	支持	支持	不建议	文生和图生推荐模型
`viduq3-turbo`	`viduq3-turbo`	支持	支持	不建议	相比 `viduq3-pro` 生成速度更快
`viduq3-pro-fast`	`viduq3-pro-fast`	不建议	需上游支持	不建议	本服务可识别，需账号侧实际开放
`viduq2-pro`	`viduq2-pro`	不支持	支持	会按 `viduq2` 提交	图生模型；参考生视频时本服务会降为 `viduq2`
`viduq2-turbo`	`viduq2-turbo`	不支持	支持	会按 `viduq2` 提交	图生模型
`viduq2-pro-fast`	`viduq2-pro-fast`	不支持	需上游支持	会按 `viduq2` 提交	本服务可识别，需账号侧实际开放
`viduq2`	`viduq2`	支持	不支持	支持	文生和参考生视频模型

生产调用建议优先使用上表明确支持的模型名。fast 后缀模型只有在上游账号实际开放时才应使用。

鉴权

所有请求都使用 Bearer Token：

http

Authorization: Bearer sk-...
Content-Type: application/json

顶层请求字段

字段	类型	必填	默认值	说明
`model`	string	是	无	上表中的 API 模型名
`prompt`	string	文生和参考生视频必填；图生可选	无	视频描述词，上游限制不超过 2000 个字符
`image`	string	图生可用	无	单张输入图的简写；传入后按图生视频处理
`images`	string[]	图生或参考生视频可用	无	1 张图为首帧图生，2 张图为首尾帧，3 到 7 张图为参考生视频
`input_reference`	string	否	无	触发参考生视频；本服务会作为参考图输入
`duration`	integer/string	否	`5`	视频时长，单位秒；可用范围见下方模型矩阵
`metadata`	object	否	`{}`	扩展参数，字段使用 PascalCase

图片可传公网可访问的 URL。Vidu 图生和参考生视频 Action 只接受 URL 字符串；如果传 Base64，本服务会在配置 COS 时先转成临时 URL，否则上游可能返回图片地址错误。

模型参数矩阵

时长

能力	模型	`duration` 可用范围
文生视频	`viduq3-pro`、`viduq3-turbo`	`1` 到 `16` 的整数，默认 `5`
文生视频	`viduq2`	`1` 到 `10` 的整数，默认 `5`
首帧图生视频	`viduq3-pro`、`viduq3-turbo`	`1` 到 `16` 的整数，默认 `5`
首帧图生视频	`viduq2-pro`、`viduq2-turbo`	`1` 到 `10` 的整数，默认 `5`
首尾帧图生视频	`viduq3-pro`、`viduq3-turbo`	`1` 到 `16` 的整数，默认 `5`
首尾帧图生视频	`viduq2-pro`、`viduq2-turbo`	`1` 到 `8` 的整数，默认 `5`
参考生视频	`viduq2`	`1` 到 `10` 的整数，默认 `5`

分辨率和比例

参数	可用值	本服务说明
`AspectRatio`	`16:9`、`9:16`、`4:3`、`3:4`、`1:1`；参考主体调用常用 `16:9`、`9:16`、`1:1`	通过 `metadata.AspectRatio` 透传
`Resolution`	`540p`、`720p`、`1080p`，默认通常为 `720p`	当前本服务会过滤 `metadata.Resolution` / `metadata.resolution`，暂不转发
`MovementAmplitude`	`auto`、`small`、`medium`、`large`	当前本服务会过滤该字段；且 q2/q3 系列不生效
`Style`	`general`、`anime`	q2/q3 系列不生效

metadata 参数

metadata 中不要传 Model、Prompt、Images、Duration。这些字段由顶层 model、prompt、image / images、duration 生成，重复传入容易造成请求内容和计费模型不一致。

字段	类型	适用能力	说明
`AspectRatio`	string	文生、参考生视频	输出比例，常用 `16:9`、`9:16`、`4:3`、`3:4`、`1:1`
`Bgm`	boolean	文生、图生、参考生视频	是否添加系统预设背景音乐。Q3 系列不生效；Q2 系列在 9 秒或 10 秒时不生效
`Audio`	boolean	文生、图生、参考生视频	是否使用音视频直出能力。文生仅 Q3 系列支持；参考生视频仅主体调用支持
`AudioType`	string	音视频直出	`Audio=true` 时可传，常用 `all`、`speech_only`、`sound_effect_only`
`VoiceId`	string	图生或参考主体	指定音色；为空时由系统推荐，暂不支持声音复刻
`IsRec`	boolean	图生视频	是否使用系统推荐提示词；启用后上游不使用顶层 `prompt`，且会额外消耗 Token
`Subjects`	array<object>	参考生视频	主体参考信息，见“参考主体”
`Videos`	string[]	参考生视频	视频参考，仅 `viduq2-pro` 支持；通过 `metadata.Videos` 透传
`MetaData`	string	全部能力	JSON 字符串形式的元数据标识；为空时使用 Vidu 默认元数据
`CallbackUrl`	string	全部能力	上游回调地址。回调不替代本服务任务查询
`Payload`	string	全部能力	透传参数，最多 1048576 个字符
`OffPeak`	boolean	全部能力	错峰模式。开启后消耗 Token 更低，但任务可能在 48 小时内完成，未完成会取消并退还 Token
`LogoAdd`	integer	全部能力	水印开关，`1` 添加，`0` 不添加，其他数值按 `1` 处理
`LogoParam`	object	全部能力	自定义水印；字段见下方“水印参数”

Vidu 使用 LogoAdd / LogoParam 控制显式水印，不使用 Watermark、WmPosition、WmUrl。

请求示例

文生视频

bash

curl -X POST "${BASE_URL}/v1/videos" \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "viduq3-turbo",
    "prompt": "圣诞老人与熊在湖边相拥，雪花缓慢飘落，镜头轻微推进，温暖电影光",
    "duration": 5,
    "metadata": {
      "AspectRatio": "16:9",
      "Audio": true
    }
  }'

首帧图生视频

bash

curl -X POST "${BASE_URL}/v1/videos" \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "viduq3-pro",
    "prompt": "人物自然抬头看向镜头，背景灯光轻微流动，保持面部清晰",
    "image": "https://cdn.example.com/first-frame.png",
    "duration": 5,
    "metadata": {
      "Audio": true,
      "AudioType": "all"
    }
  }'

首尾帧图生视频

传 2 张图时，第一张作为首帧，第二张作为尾帧。两张图片的分辨率应接近，首帧分辨率 / 尾帧分辨率建议保持在 0.8 到 1.25。

json

{
  "model": "viduq3-turbo",
  "prompt": "从首帧自然过渡到尾帧，动作连贯，镜头平滑移动",
  "images": [
    "https://cdn.example.com/start.png",
    "https://cdn.example.com/end.png"
  ],
  "duration": 5,
  "metadata": {
    "Audio": true
  }
}

参考生视频

传 3 到 7 张 images 会自动走 SubmitReferenceToVideoViduJob。也可以用 metadata.Action=referenceGenerate 强制走参考生视频。

bash

curl -X POST "${BASE_URL}/v1/videos" \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "viduq2",
    "prompt": "保持参考图中的人物外观一致，在未来城市街道中自然行走",
    "images": [
      "https://cdn.example.com/character-front.png",
      "https://cdn.example.com/character-side.png",
      "https://cdn.example.com/scene.png"
    ],
    "duration": 5,
    "metadata": {
      "AspectRatio": "16:9"
    }
  }'

参考主体

Subjects 用于主体调用。支持 1 到 7 个主体，主体图片总数 1 到 7 张；每个主体的图片最多 3 张。提示词中可以通过 @主体id 引用主体。

json

{
  "model": "viduq2",
  "prompt": "@subject_1 和 @subject_2 在街边咖啡馆交谈，旁白音说今天的天气很好",
  "duration": 5,
  "metadata": {
    "Action": "referenceGenerate",
    "Subjects": [
      {
        "Id": "subject_1",
        "Name": "subject_1",
        "Images": [
          "https://cdn.example.com/person-a-front.png",
          "https://cdn.example.com/person-a-side.png"
        ],
        "VoiceId": "male-qn-qingse"
      },
      {
        "Id": "subject_2",
        "Name": "subject_2",
        "Images": [
          "https://cdn.example.com/person-b-front.png"
        ]
      }
    ],
    "Audio": true,
    "AudioType": "speech_only"
  }
}

参考主体字段：

字段	类型	必填	说明
`Id`	string	是	主体 ID，提示词中可用 `@Id` 引用
`Images`	string[]	是	主体图片 URL；每个主体最多 3 张
`Name`	string	否	主体名称，通常与 `Id` 保持一致
`Videos`	string[]	否	主体视频 URL；仅 `viduq2-pro` 支持
`VoiceId`	string	否	主体音色 ID

视频参考

视频参考通过 metadata.Videos 透传。该能力仅 viduq2-pro 支持，最多传 1 个 8 秒视频或 2 个 5 秒视频，格式支持 mp4、avi、mov，大小不超过 100M。

json

{
  "model": "viduq2",
  "prompt": "参考视频中的人物动作节奏，生成主体一致的视频",
  "duration": 5,
  "metadata": {
    "Action": "referenceGenerate",
    "Videos": [
      "https://cdn.example.com/reference-motion.mp4"
    ]
  }
}

回调、错峰、水印和业务透传

json

{
  "model": "viduq3-pro",
  "prompt": "产品宣传片镜头，主体缓慢旋转，背景光线柔和",
  "image": "https://cdn.example.com/product.png",
  "duration": 5,
  "metadata": {
    "Payload": "client-order-20260909-0001",
    "CallbackUrl": "https://example.com/callbacks/video",
    "OffPeak": true,
    "LogoAdd": 0
  }
}

上游回调不替代本服务任务查询；客户端仍应使用本服务返回的 task_id 轮询状态。

输入素材约束

素材	约束
图生图片	支持 URL 或 Base64；格式 `png`、`jpeg`、`jpg`、`webp`；大小不超过 50M；画面比例避免超过 `1:4` 或 `4:1`
首尾帧图片	传 2 张；第一张首帧、第二张尾帧；两张图分辨率需接近，首帧分辨率 / 尾帧分辨率在 `0.8` 到 `1.25`
参考图片	`images` 支持 1 到 7 张；格式 `png`、`jpeg`、`jpg`、`webp`；像素不小于 `128x128`；大小不超过 50M
参考主体图片	`Subjects` 支持 1 到 7 个主体，主体图片总数 1 到 7 张；每个主体最多 3 张图片
参考视频	支持 1 个 8 秒视频或 2 个 5 秒视频；格式 `mp4`、`avi`、`mov`；像素不小于 `128x128`；大小不超过 100M

水印参数

json

{
  "metadata": {
    "LogoAdd": 1,
    "LogoParam": {
      "LogoUrl": "https://cdn.example.com/logo.png",
      "LogoRect": {
        "X": -222,
        "Y": -54,
        "Width": 202,
        "Height": 34
      }
    }
  }
}

字段	类型	说明
`LogoUrl`	string	水印图片 URL
`LogoImage`	string	水印图片 Base64；和 `LogoUrl` 同时传时以 `LogoUrl` 为准
`LogoRect.X`	integer	水印框 X 坐标；正数从左向右，负数从右向左
`LogoRect.Y`	integer	水印框 Y 坐标；正数从上向下，负数从下向上
`LogoRect.Width`	integer	水印框宽度，单位 px
`LogoRect.Height`	integer	水印框高度，单位 px

提交响应

POST /v1/videos 提交成功后返回公开任务 ID。任务仍在异步执行，需要继续查询。

json

{
  "id": "task_7a31e02c4b",
  "task_id": "task_7a31e02c4b",
  "object": "video",
  "model": "viduq3-pro",
  "status": "queued",
  "progress": 0,
  "created_at": 1788912000
}

上游原始提交响应中的 JobId 会被本服务映射为内部任务的上游 ID，客户端只需要保存本服务返回的 task_id。

查询任务

bash

curl "${BASE_URL}/v1/videos/task_7a31e02c4b" \
  -H "Authorization: Bearer ${API_TOKEN}"

成功完成时的响应示例：

json

{
  "id": "task_7a31e02c4b",
  "object": "video",
  "model": "viduq3-pro",
  "status": "completed",
  "progress": 100,
  "created_at": 1788912000,
  "completed_at": 1788912060,
  "metadata": {
    "url": "https://example.com/generated-video.mp4"
  }
}

上游查询状态会映射为本服务任务状态：

上游 `Status`	含义	本服务状态
`WAIT`	等待中	`queued` / submitted
`RUN`	执行中	`in_progress`
`DONE`	任务成功	`completed`
`FAIL`	任务失败	`failed`

上游 ResultVideoUrl 的有效期为 24 小时。本服务如果配置了 COS 转存，会把上游临时链接转存为自有 COS 链接；未配置或转存失败时会返回上游原始临时链接。

轮询示例

bash

TASK_ID="task_7a31e02c4b"

while true; do
  BODY=$(curl -s "${BASE_URL}/v1/videos/${TASK_ID}" \
    -H "Authorization: Bearer ${API_TOKEN}")
  echo "${BODY}"

  STATUS=$(printf '%s' "${BODY}" | jq -r '.status')
  if [ "${STATUS}" = "completed" ] || [ "${STATUS}" = "failed" ]; then
    break
  fi

  sleep 5
done

建议 3 到 5 秒查询一次。不要为同一个业务请求重复创建多个视频任务。

下载视频

bash

curl -L "${BASE_URL}/v1/videos/task_7a31e02c4b/content" \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -o output.mp4

如果查询响应中的 metadata.url 或旧路径响应中的 result_url 是临时地址，可能会过期；长期保存请下载后转存到自己的对象存储。

常见错误

错误表现	可能原因	处理建议
`unsupported model`	模型名不在本服务模型列表，或管理员未开放该模型	检查 `model` 拼写和后台模型配置
文生请求被拒绝	使用了只支持图生的视频模型，如 `viduq2-pro`、`viduq2-turbo`	换用 `viduq2`、`viduq3-pro` 或 `viduq3-turbo`
图生请求被拒绝	使用了只支持文生的视频模型，或图片 URL / Base64 不合规	换用图生模型；确认图片格式、大小、比例和可访问性
Base64 图片失败	Vidu Action 需要 URL，本服务未配置 COS 转换，或 Base64 无法解析	直接传公网 HTTPS 图片，或让管理员配置 COS
参考生视频失败	使用了非 `viduq2` 模型、图片/主体/视频数量不合规，或素材格式不合规	优先用 `viduq2`；按素材约束减少输入数量或更换素材
`Resolution` 不生效	当前本服务会过滤 `metadata.Resolution` / `metadata.resolution`	先用默认分辨率；如需支持需调整适配器
`Watermark` 不生效	Vidu 使用 `LogoAdd` / `LogoParam`	改用 `metadata.LogoAdd=0` 或传 `LogoParam`
音频未生成	模型或能力不支持 `Audio`，或 `AudioType` / `VoiceId` 不匹配	文生优先用 Q3 系列；参考生视频只在主体调用时开启音频
查询一直未完成	上游任务仍在 `WAIT` / `RUN`，或开启 `OffPeak` 后进入低峰队列	继续轮询；错峰模式最长可能在 48 小时内完成
下载失败	上游 URL 过期或代理安全策略拦截	尽快下载；必要时让管理员检查 COS 转存和视频代理配置

Vidu 视频生成 API ​

接口一览 ​

能力路由 ​

支持模型 ​

鉴权 ​

顶层请求字段 ​

模型参数矩阵 ​

时长 ​

分辨率和比例 ​

metadata 参数 ​

请求示例 ​

文生视频 ​

首帧图生视频 ​

首尾帧图生视频 ​

参考生视频 ​

参考主体 ​

视频参考 ​

回调、错峰、水印和业务透传 ​

输入素材约束 ​

水印参数 ​

提交响应 ​

查询任务 ​

轮询示例 ​

下载视频 ​

常见错误 ​

Vidu 视频生成 API

接口一览

能力路由

支持模型

鉴权

顶层请求字段

模型参数矩阵

时长

分辨率和比例

metadata 参数

请求示例

文生视频

首帧图生视频

首尾帧图生视频

参考生视频

参考主体

视频参考

回调、错峰、水印和业务透传

输入素材约束

水印参数

提交响应

查询任务

轮询示例

下载视频

常见错误