Vidu Q4 Preview 视频生成 | ToAPIs Documentation

POST

/v1/videos/generations

国内用户请注意： 中国大陆用户请使用 https://toapis.cn 作为接口地址（Base URL）。文档示例中的 https://toapis.com 请替换为 https://toapis.cn。

异步任务接口，提交后返回任务 ID
支持模型：viduq4-preview
两种生成模式：
- 首帧图生视频：单张图片作为首帧
- 参考生视频：多张参考图，可附加参考音频

请传入公网可访问的图片和音频 URL。不要在 image_urls、reference_images 或 sounds 中直接传 base64 数据；本地文件请先使用上传图片接口获取 URL。

认证

Authorizationstring请求头必填

所有接口均需要使用 Bearer Token 认证。

Authorization: Bearer YOUR_API_KEY

请求参数

modelstring请求体必填

模型名称，固定为 viduq4-preview。

promptstring请求体必填

视频提示词，描述主体、动作、场景、镜头和风格。

image_urlsstring[]请求体

图片 URL 数组。生成模式由 video_generation_mode 和图片数量决定：

首帧模式（默认）：在 image_urls 中传入恰好 1 张图片 URL，图片作为首帧。
参考模式：将 video_generation_mode 设为 reference_images_to_video，在 image_urls（或 reference_images）中传入参考图。

示例：["https://example.com/first-frame.jpg"]

video_generation_modestring请求体

生成模式选择器。

可选值：

reference_images_to_video - 多参考图生成，image_urls 中的多张图片按参考图处理

省略时为首帧图生视频。传入多张图片、reference_images 或 sounds 的请求会自动路由到参考生视频。

durationinteger请求体默认值: 5

视频时长（秒），3 到 16。

resolutionstring请求体默认值: 720p

视频分辨率。

可选值：

540p
720p
1080p
2K
4K

aspect_ratiostring请求体

视频宽高比，用于参考模式。

可选值：16:9、9:16、4:3、3:4、1:1

audioboolean请求体默认值: true

是否为视频生成音频。

watermarkboolean请求体默认值: false

是否在生成的视频上添加水印。

seedinteger请求体

随机种子，相同参数下可获得更可复现的结果。

metadataobject请求体

扩展参数，用于传递上游 API 支持但未暴露为顶层字段的参数。

展开 metadata 字段

is_recboolean请求体

是否自动扩写优化提示词。省略时上游默认为 true。

soundsstring[]请求体

参考音频 URL 数组（仅参考生视频模式），最多 3 个音频文件。

示例：["https://example.com/voice.mp3"]

wm_positioninteger请求体

水印位置，1 到 4。当 watermark 为 true 时生效。

wm_urlstring请求体

自定义水印图片 URL。当 watermark 为 true 时生效。

meta_datastring请求体

自定义元数据标识，JSON 格式字符串，原样透传到结果中。

callback_urlstring请求体

ToAPIs 任务最终 Webhook。需先配置 Token URL 和签名密钥，详见任务 Webhooks。

模式选择

模式	触发方式	图片输入	音频输入
首帧图生视频	`image_urls` 传 1 张图（默认）	恰好 1 张	仅 `audio` 开关
参考生视频	`video_generation_mode: "reference_images_to_video"`，或多图 / `reference_images` / `sounds`	最多 15 张参考图	最多 3 条 `sounds` + `audio` 开关

计费维度

Vidu Q4 Preview 按生成视频秒数计费，按分辨率分档定价：

540p / 720p / 1080p / 2K / 4K - 分辨率越高单价越高

响应

idstring

任务 ID，用于查询任务状态。

objectstring

对象类型，通常为 generation.task。

modelstring

请求使用的模型。

statusstring

任务状态：queued、in_progress、completed 或 failed。

created_atinteger

任务创建时间戳。

示例

首帧图生视频

{
  "model": "viduq4-preview",
  "prompt": "图片中的人物缓缓转身微笑，电影质感打光",
  "image_urls": ["https://example.com/portrait.jpg"],
  "duration": 5,
  "resolution": "1080p",
  "audio": true
}

参考生视频

{
  "model": "viduq4-preview",
  "prompt": "保持参考图中的人物一致，夜晚霓虹城市街道上行走",
  "video_generation_mode": "reference_images_to_video",
  "image_urls": [
    "https://example.com/character-front.jpg",
    "https://example.com/character-side.jpg"
  ],
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "3:4",
  "audio": true
}

带参考音频的参考生视频

{
  "model": "viduq4-preview",
  "prompt": "人物说出台词，口型与声音同步",
  "video_generation_mode": "reference_images_to_video",
  "image_urls": ["https://example.com/character.jpg"],
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "metadata": {
    "sounds": ["https://example.com/voice.mp3"]
  }
}

提示词扩写与水印

{
  "model": "viduq4-preview",
  "prompt": "一只猫在夕阳下的沙滩上行走",
  "image_urls": ["https://example.com/cat.jpg"],
  "duration": 8,
  "resolution": "2K",
  "watermark": true,
  "metadata": {
    "is_rec": true
  }
}

视频生成为异步任务。使用获取视频任务状态接口查询进度和结果。

请求示例

curl --request POST \
  --url https://toapis.com/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "viduq4-preview",
    "prompt": "图片中的人物缓缓转身微笑，电影质感打光",
    "image_urls": ["https://example.com/portrait.jpg"],
    "duration": 5,
    "resolution": "1080p",
    "audio": true
  }'

import requests

response = requests.post(
    "https://toapis.com/v1/videos/generations",
    headers={
        "Authorization": "Bearer <token>",
        "Content-Type": "application/json",
    },
    json={
        "model": "viduq4-preview",
        "prompt": "图片中的人物缓缓转身微笑，电影质感打光",
        "image_urls": ["https://example.com/portrait.jpg"],
        "duration": 5,
        "resolution": "1080p",
        "audio": True,
    },
)

print(response.json())

const response = await fetch("https://toapis.com/v1/videos/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "viduq4-preview",
    prompt: "图片中的人物缓缓转身微笑，电影质感打光",
    image_urls: ["https://example.com/portrait.jpg"],
    duration: 5,
    resolution: "1080p",
    audio: true
  })
});

console.log(await response.json());