Vidu Q4 Preview 参考生成视频

Vidu Q4 Preview 参考生成视频（vidu/q4-preview）是 Vidu 的下一代多模态视频生成模型，通过统一接口提供高一致性的多主体参考视频生成，以及灵活的首帧和首尾帧图生视频功能。在 reference 模式下，最多支持 15 张参考图片和 3 段参考音频（sounds）；在 image 模式下，支持 1–2 张帧图片。支持生成 4–16秒的视频，分辨率覆盖 540p 至 4K（540p、720p、1080p、2K、4K），并支持原生音频合成，可在主流宽高比（16:9、9:16、3:4、4:3、1:1）下实现电影级动态效果、精准的主体一致性以及音画同步叙事。

基础 URL

https://api.icreat.ai

身份验证

所有 API 请求均须使用 API 密钥进行身份验证。您可以从控制台获取 API 密钥。

export ICREAT_API_KEY="your-api-key-here"

HTTP 请求头

import os

API_KEY = os.environ.get("ICREAT_API_KEY")
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer " + API_KEY,
}

保护您的 API 密钥 切勿在客户端代码或公共代码仓库中暴露 API 密钥。请使用环境变量或后端代理。

代码示例

图片和视频生成采用两步异步流程：首先提交任务以获取 task_id，然后通过查询任务结果接口进行轮询。响应包含 status 和 result（处理中为 []；当状态为 SUCCEEDED 时，result 包含生成资源，并返回 costUSD 字段）。以下示例在两个步骤中使用相同的 task_id。

1. 提交任务

向提交接口发送生成请求，请求体采用顶层平铺的 JSON 对象。参考生成视频（mode: "reference"）与图生视频（mode: "image"）共用同一个接口 URL。

POST/v1/task/submit/vidu/q4-preview

curl --fail-with-body --connect-timeout 10 --max-time 60 \
  -X POST https://api.icreat.ai/v1/task/submit/vidu/q4-preview \
  -H "Authorization: Bearer ${ICREAT_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "reference",
    "images": [
      "https://example.com/ref-scene.jpg"
    ],
    "sounds": [
      "https://example.com/ref-voice.mp3"
    ],
    "prompt": "根据参考图片和参考音频生成一段 5 秒的短视频。",
    "duration": 5,
    "resolution": "720p",
    "aspectRatio": "16:9",
    "audio": true,
    "seed": 42
  }'

2. 查询任务结果（轮询）

使用提交任务时返回的 task_id 轮询任务进度，直到任务进入终止状态。响应包含 status 和 result：处理中，result 为 []；状态为 SUCCEEDED 时，result 包含生成资源，并返回 costUSD；FAILED 表示任务失败。

POST/v1/task/result

curl --fail-with-body --connect-timeout 10 --max-time 60 \
  -X POST "https://api.icreat.ai/v1/task/result" \
  -H "Authorization: Bearer ${ICREAT_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"task_id": "task-xxx"}'

输入结构

提交任务 — 输入

请求体必须是顶层平铺的 JSON 对象（不要将字段包裹在 input 或 parameters 中）。

共 10 个字段：必填 1 个，可选 9 个（当 mode 为 "reference" 时，prompt 也为必填项）。

imagesarray[string]必填

可公开访问的 HTTPS（或 HTTP）图片 URL 列表。

当 mode 为 reference 时：需要 1–15 张参考图片。
当 mode 为 image 时：需要 1–2 张图片（1 张用于首帧图生视频；2 张用于首尾帧过渡）。

modestring必填

生成模式（不区分大小写）。设置为 reference 表示参考生成视频；设置为 image 表示首帧或首尾帧图生视频。

imagereference

promptstring必填

描述待生成视频的文本提示词（最多 2000 个 Unicode 字符）。当 mode 为 reference 时，必填且不能为空；当 mode 为 image 时，可选。

soundsarray[string]

可公开访问的 HTTPS（或 HTTP）参考音频 URL 列表。默认为 []。仅在 mode 为 reference 时支持，最多 2 个音频文件。当 mode 为 image 时，传入非空数组将直接返回 HTTP 400 错误。

durationinteger必填

视频时长，单位为秒。

最小值：4；最大值：16。

默认值"5"

resolutionstring必填

输出视频的分辨率（不区分大小写）。

默认值"720p"

540p720p1080p2K4K

aspectRatiostring必填

输出视频的宽高比。仅在 mode 为 reference 时生效。当 mode 为 image 时，请勿传入此字段（在 image 模式下，宽高比将根据首帧自动确定）。

默认值"16:9"

16:99:163:44:31:1

audioboolean

是否生成音轨。设置为 false 可明确禁用音频输出（无论是否提供 sounds，此参数均作为布尔值独立生效）。

默认值"true"

isRecboolean

是否使用 AI 推荐的提示词扩写功能。仅在 mode 为 image 时可用；当 mode 为 reference 时，请勿传入此参数。

seedinteger

生成时使用的随机种子。省略时使用随机种子；指定整数可固定生成种子。

查询任务结果 — 输入

共 1 个字段：必填 1 个，可选 0 个。

task_idstring必填

提交接口返回的任务 ID。

输出结构

提交任务 — 输出

共 1 个字段。

task_idstring

异步任务标识符。

查询任务结果 — 输出

字段总数：不固定。

statusstring

当前任务状态。任务成功前，result 通常为 []；当状态为 SUCCEEDED 时，result 包含生成资源，并返回 costUSD 字段。

SUBMITTEDIN_PROGRESSSUCCEEDEDFAILEDNOT_FOUND

resultarray[object]

生成的资源。处理中或失败时为空数组；成功时为对象数组。

costUSDnumber

任务费用，单位为美元。仅当 status 为 SUCCEEDED 时返回。

大语言模型提示词

以下 Markdown 是一份便于大语言模型理解的提示词，可粘贴到 AI 助手（如 Cursor、ChatGPT）中，帮助其理解此模型的 API、调用流程和关键参数。请使用复制供 AI 使用按钮，或复制下方代码块中的内容。

# vidu/q4-preview

> Vidu Q4 Preview 参考生成视频（`vidu/q4-preview`）是 Vidu 的下一代视频生成模型，通过统一接口支持多图/音频参考生成视频（`mode: "reference"`），以及首帧或首尾帧图生视频（`mode: "image"`）。

## 概述

使用 iCreat 的两步异步任务 API：先提交包含平铺 JSON 请求体的生成请求，再轮询任务结果查询接口；成功后从 `result` 中读取资源，响应中同时包含 `costUSD`。

## API 信息

- **基础 URL**：`https://api.icreat.ai`
- **提交接口（POST）**：`/v1/task/submit/vidu/q4-preview`
- **结果查询接口（POST）**：`/v1/task/result`
- **模型 ID**：`vidu/q4-preview`
- **身份验证**：`Authorization: Bearer ${ICREAT_API_KEY}`

## 调用流程

1. **提交**：按照输入说明，将平铺 JSON 请求体 POST 至提交接口；响应为 `{ "task_id": "..." }`。
2. **查询结果**：向 `/v1/task/result` 发送 POST 请求，请求体为 `{ "task_id": "..." }`；响应包含 `status` 和 `result`（处理中为 `[]`）。当状态为 `SUCCEEDED` 时，`result` 包含生成资源，并返回 `costUSD`；当 `type` 为 `Video` 时，读取 `url` 或 `download_url`。

### 输入示例（参考生成视频）

```json
{
  "mode": "reference",
  "images": [
    "https://example.com/ref-scene.jpg](https://example.com/ref-scene.jpg"
  ],
  "sounds": [
    "https://example.com/ref-voice.mp3](https://example.com/ref-voice.mp3"
  ],
  "prompt": "根据参考图片和参考音频生成一段 5 秒的短视频。",
  "duration": 5,
  "resolution": "720p",
  "aspectRatio": "16:9",
  "audio": true,
  "seed": 42
}
```

### 输入说明

* 顶层请求体：平铺 JSON 对象（不要包裹在 `input` 或 `parameters` 中）。
* `mode`（可选）：`"image"`（默认）或 `"reference"`，不区分大小写。
* `images`（必填）：图片 HTTP/HTTPS URL 数组。当 `mode="reference"` 时为 `1–15` 张；当 `mode="image"` 时为 `1–2` 张（1 张用于首帧，2 张用于首尾帧）。
* `prompt`（条件必填）：当 `mode="reference"` 时，必填且不能为空；当 `mode="image"` 时，可选。最多 2000 个 Unicode 字符。
* `sounds`（可选）：音频 HTTP/HTTPS URL 数组，最多 2 个。仅在 `mode="reference"` 时支持。在 `image` 模式下传入非空 `sounds` 会导致 400 错误。
* `duration`（可选）：整数，范围为 `4–16` 秒，默认为 `5`。
* `resolution`（可选）：`"540p"`、`"720p"`（默认）、`"1080p"`、`"2K"` 或 `"4K"`，不区分大小写。
* `aspectRatio`（可选）：`"16:9"`（默认）、`"9:16"`、`"3:4"`、`"4:3"` 或 `"1:1"`。仅在 `mode="reference"` 时生效；当 `mode="image"` 时，请勿传入。
* `audio`（可选）：布尔值，默认为 `true`。设置为 `false` 可关闭音频输出。
* `isRec`（可选）：布尔值，表示是否使用 AI 提示词推荐功能。仅在 `mode="image"` 时支持；当 `mode="reference"` 时，请勿传入。
* `seed`（可选）：整数种子，用于复现生成结果。

### 输出说明

* 轮询：读取 `status`；处理中（`SUBMITTED` 或 `IN_PROGRESS`），`result` 为 `[]`。
* 成功：`status` 为 `SUCCEEDED`，`result` 为 `[{ "type": "Video", "url": "...", "download_url": "..." }]`，同时返回 `costUSD`。

## 注意事项

* 两个步骤使用同一个 `task_id`；处理中，`result` 为 `[]`，请继续轮询。
* `FAILED` 和 `NOT_FOUND` 均为终止状态，请勿继续轮询；应检查请求参数或媒体 URL。
* 生成的媒体 URL 为临时地址；请及时下载并持久化保存视频，不要将临时 URL 硬编码到程序中。