> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Vidu Q4 Preview 视频生成

> 支持单张首帧图生视频及最多 15 张参考图、3 段参考音频的参考生视频，3–16 秒，最高 4K，默认带音轨。

<Info>
  本模型支持图生视频和参考生视频，不支持无图文生视频或首尾帧。提交成功后从 `data[0].task_id` 获取任务 ID，通过 [任务查询](/cn/api-reference/tasks/status) 获取状态和结果。
</Info>

## 生成模式

同一个模型 `viduq4-preview` 根据图片、角色及参考音频自动选择模式，不需要额外的模式参数。

| 输入方式 | 模式 |
| - | - |
| 仅提供 `first_frame_image` 或一个 `role: "first_frame"` 图片 | 图生视频 |
| 仅 1 张无角色图片，未提供参考音频 | 图生视频 |
| 图片包含 `reference_image` 或 `reference` 角色，且没有显式首帧 | 参考生视频 |
| 合计 2–15 张图片，且没有显式首帧 | 参考生视频 |
| 提供参考音频，同时提供 1–15 张图片，且没有显式首帧 | 参考生视频 |

* **图生视频**：恰好 1 张首帧，提示词可选，不接受参考音频。
* **参考生视频**：1–15 张参考图，最多 3 段参考音频，**提示词必填**。没有参考音频且仅用 1 张图时，请显式设置 `role: "reference_image"`，否则按图生视频处理。
* 显式首帧（`first_frame_image` 或 `role: "first_frame"`）不能与其他图片、参考图角色或参考音频混用，否则返回 HTTP 400。

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.apimart.ai/v1/videos/generations \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "viduq4-preview",
      "prompt": "女孩回头微笑，长发被风吹起，镜头缓缓推近",
      "image_urls": ["https://example.com/first-frame.png"],
      "duration": 5,
      "resolution": "1080p"
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.apimart.ai/v1/videos/generations",
      headers={"Authorization": "Bearer <token>"},
      json={
          "model": "viduq4-preview",
          "prompt": "女孩回头微笑，长发被风吹起，镜头缓缓推近",
          "image_urls": ["https://example.com/first-frame.png"],
          "duration": 5,
          "resolution": "1080p"
      }
  )
  response.raise_for_status()
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.apimart.ai/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/first-frame.png"],
      duration: 5,
      resolution: "1080p"
    })
  });
  if (!response.ok) throw new Error(await response.text());
  console.log(await response.json());
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "code": 200,
    "data": [
      {
        "status": "submitted",
        "task_id": "task_01K..."
      }
    ]
  }
  ```
</ResponseExample>

## 请求头

<ParamField header="Authorization" type="string" required>
  Bearer 认证，格式为 `Bearer <token>`，其中 `<token>` 为你的 APIMart API Key。
</ParamField>

## 请求参数

<ParamField body="model" type="string" required>
  固定为 `viduq4-preview`，全小写，需精确匹配。
</ParamField>

<ParamField body="prompt" type="string">
  视频生成提示词，最多 20,000 个字符。

  * 图生视频：可选，不传时由模型根据首帧自行生成内容。
  * 参考生视频：必填，缺失时返回 HTTP 400。
</ParamField>

<ParamField body="image_urls" type="string[]">
  图片数组，支持公网可访问的图片 URL 或 Base64 Data URL，例如 `data:image/png;base64,...`。

  * 图生视频：仅 1 张，作为首帧。
  * 参考生视频：与 `image_with_roles` 合计 1–15 张。

  可与 `image_with_roles` 混用，张数合计计算；不要与 `first_frame_image` 或显式 `first_frame` 角色混用。单张无角色图片是否进入参考生模式，还取决于是否提供参考音频。
</ParamField>

<ParamField body="image_with_roles" type="object[]">
  带角色的图片数组。图生视频使用 1 个元素；参考生视频与 `image_urls` 合计 1–15 张。

  <Expandable title="显示图片字段">
    <ParamField body="url" type="string" required>
      图片的公网 URL 或 Base64 Data URL。
    </ParamField>

    <ParamField body="role" type="string">
      图片角色，大小写不敏感：

      * `first_frame`：图生视频首帧。
      * `reference_image`：参考生视频参考图，也接受 `reference`。
      * 不传或留空：无参考音频时按合计张数判断，1 张为图生视频，2 张及以上为参考生视频；有参考音频时进入参考生视频。

      其他值（如 `last_frame`）会同步返回 HTTP 400。
    </ParamField>
  </Expandable>

  可与 `image_urls` 合并提供参考图，但首帧角色不能与参考素材混用。
</ParamField>

<ParamField body="first_frame_image" type="string">
  仅用于图生视频，传入首帧图片的公网 URL 或 Base64 Data URL。

  使用此字段时不要再提供其他图片或参考音频。参考生视频请使用 `image_urls` 或 `image_with_roles`。
</ParamField>

<ParamField body="audio_urls" type="string[]">
  参考音频 URL 数组，仅用于参考生视频。与 `audio_url` 合计最多 3 段。

  要求 MP3 格式，每段 3–12 秒、单段不超过 50MB。提供参考音频时仍需至少 1 张图片，并且必须填写 `prompt`。

  音频格式或时长不符合要求时，会在任务执行阶段失败并全额退款，而不是提交时同步返回 HTTP 400。
</ParamField>

<ParamField body="audio_url" type="string">
  单段参考音频 URL，要求与 `audio_urls` 相同；两个字段合计最多 3 段。
</ParamField>

<ParamField body="aspect_ratio" type="string" default="16:9">
  仅用于参考生视频，支持 `1:1`、`9:16`、`16:9`、`3:4`、`4:3`，默认 `16:9`。

  图生视频的宽高比由首帧图片决定，此参数会被忽略。
</ParamField>

<ParamField body="size" type="string">
  宽高比的兼容字段，可替代 `aspect_ratio`，支持相同取值。建议只使用其中一个字段。图生视频中不生效。
</ParamField>

<ParamField body="duration" type="integer" default="5">
  视频时长，单位为秒。支持 3–16 秒，不支持 1–2 秒。
</ParamField>

<ParamField body="resolution" type="string" default="720p">
  视频分辨率，支持 `540p`、`720p`、`1080p`、`2K`、`4K`，大小写不敏感。
</ParamField>

<ParamField body="audio" type="boolean" default="true">
  是否输出带对白和音效的音视频。

  * `true`：输出带音轨的视频（默认）。
  * `false`：输出无声视频。

  有声和无声视频价格相同。
</ParamField>

<ParamField body="seed" type="integer">
  随机种子。不传或传 `0` 时随机生成。
</ParamField>

## 素材要求

* 图生视频：必须恰好提供 1 张首帧图，不接受参考音频。
* 参考生视频：必须提供 1–15 张参考图，可选最多 3 段参考音频。
* 支持 PNG、JPEG、JPG、WEBP，单张图片不超过 50MB。
* 使用 Base64 时，整个请求体必须小于 20MB，建议优先使用公网 URL。
* 图片 URL 必须能从公网访问。请将示例中的 URL 替换为实际可访问的图片地址。

<Warning>
  两种模式均不能省略图片，也不支持 `last_frame_image`。首帧与参考素材混用、图片或音频数量超限等参数错误会在提交时返回 HTTP 400，不创建任务、不扣费。参考音频的格式和时长不符则在执行阶段失败并退款。
</Warning>

## 请求示例

### 仅提供首帧，不传提示词

```json theme={null}
{
  "model": "viduq4-preview",
  "image_urls": ["https://example.com/first-frame.png"]
}
```

默认生成 5 秒、720p、带音轨的视频。

### 带角色的首帧与 4K 输出

```json theme={null}
{
  "model": "viduq4-preview",
  "prompt": "镜头缓缓推近，人物自然微笑",
  "image_with_roles": [
    {
      "url": "https://example.com/first-frame.png",
      "role": "first_frame"
    }
  ],
  "duration": 8,
  "resolution": "4K",
  "audio": true
}
```

### 使用首帧字段生成无声视频

```json theme={null}
{
  "model": "viduq4-preview",
  "first_frame_image": "https://example.com/first-frame.png",
  "duration": 5,
  "resolution": "1080p",
  "audio": false
}
```

### 多图与参考音频生成视频

```json theme={null}
{
  "model": "viduq4-preview",
  "prompt": "图1的男孩用参考音频的内容对图2的女孩说话，背景是图3的咖啡馆",
  "image_urls": [
    "https://example.com/boy.png",
    "https://example.com/girl.png",
    "https://example.com/cafe.png"
  ],
  "audio_urls": ["https://example.com/line.mp3"],
  "aspect_ratio": "16:9",
  "duration": 8,
  "resolution": "720p"
}
```

### 单张图片进入参考生模式

```json theme={null}
{
  "model": "viduq4-preview",
  "prompt": "参考图中的人物走进咖啡馆，与店员挥手打招呼",
  "image_with_roles": [
    {
      "url": "https://example.com/person.png",
      "role": "reference_image"
    }
  ],
  "aspect_ratio": "9:16",
  "duration": 5,
  "resolution": "1080p"
}
```

此示例未传参考音频，通过 `reference_image` 角色明确选择参考生模式。示例中的图片和音频 URL 均需替换为实际可访问的素材地址。

## 提交响应

<ResponseField name="code" type="integer">
  响应状态码，成功为 `200`。
</ResponseField>

<ResponseField name="data" type="array">
  任务提交结果。

  <Expandable title="显示任务字段">
    <ResponseField name="status" type="string">
      提交成功时为 `submitted`，不代表视频生成完成。
    </ResponseField>

    <ResponseField name="task_id" type="string">
      任务 ID，用于查询状态和结果。
    </ResponseField>
  </Expandable>
</ResponseField>

## 查询任务结果

建议每 5–10 秒轮询一次，状态为 `completed` 或 `failed` 时停止。使用统一查询接口：

```bash theme={null}
curl --request GET \
  --url https://api.apimart.ai/v1/tasks/task_01K... \
  --header 'Authorization: Bearer <token>'
```

成功响应示例（视频 URL 为占位示例）：

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01K...",
    "status": "completed",
    "progress": 100,
    "result": {
      "videos": [
        {
          "url": ["https://example.com/generated-video.mp4"]
        }
      ]
    }
  }
}
```

| 状态 | 处理方式 |
| - | - |
| `pending` | 排队中，继续轮询 |
| `processing` | 生成中，继续轮询 |
| `completed` | 成功，从 `data.result.videos[0].url` 数组读取视频链接 |
| `failed` | 失败，从 `data.error.message` 获取原因；停止轮询，费用全额退回 |

视频链接有效期为 24 小时，请及时下载转存。不要依赖固定进度节点判断任务完成，以 `status` 为准。

## 计费说明

按视频时长与分辨率计费：费用 = 时长（秒）× 对应分辨率每秒单价。

具体价格以[模型定价](https://apimart.ai/pricing)为准。图生与参考生同价，开启或关闭音轨同价，参考图片与参考音频不额外收费；任务失败时自动全额退款。

## 常见参数错误

以下情况同步返回 HTTP 400，不创建任务、不扣费：

| 情况 | 处理方式 |
| - | - |
| 未提供图片 | 图生提供 1 张首帧，参考生提供 1–15 张参考图 |
| 显式首帧与其他图片、参考角色或参考音频混用 | 图生只保留 1 张首帧；参考生移除显式首帧字段或角色 |
| `role` 为 `last_frame` 等不支持的值 | 使用 `first_frame`、`reference_image`、`reference`，或留空 |
| 参考生超过 15 张图片 | 减少图片数量，`image_urls` 与 `image_with_roles` 合计不超过 15 张 |
| 参考音频超过 3 段 | `audio_urls` 与 `audio_url` 合计不超过 3 段 |
| 参考生缺少 `prompt` | 补充提示词，最多 20,000 个字符 |
| 参考生宽高比不支持，例如 `21:9` | 使用 `1:1`、`9:16`、`16:9`、`3:4` 或 `4:3` |
| 提供 `last_frame_image` | 删除该字段，本模型不支持首尾帧 |
| `duration` 小于 3 或大于 16 | 使用 3–16 秒的整数 |
| 分辨率为 `480p`、`8K` 等不支持的值 | 使用 `540p`、`720p`、`1080p`、`2K` 或 `4K` |

## 其他 Vidu 模型

需要文生视频或首尾帧时，使用 [Vidu Q3 Pro / Turbo](/cn/api-reference/videos/vidu-q3-pro/generation)。本模型已支持多图参考，也可查看 [Vidu Q3 Mix / Standard](/cn/api-reference/videos/vidu-q3/generation) 的参考生能力。需要 1–2 秒短片时可选择 `viduq3-pro`，本模型最短为 3 秒。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.