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

# Vidu 图生视频

> 使用 `POST /vidu/ent/v2/img2video` 提交首帧图生成视频任务。

# Vidu 图生视频

Vidu 官方格式图生视频接口,以 `application/json` 提交。

* 路由入口是 `POST /vidu/ent/v2/img2video`。
* 当前使用 `application/json` 提交。
* 支持首帧图生成视频。
* 提交成功后返回任务 `task_id` 与 `status`,后续用 [查询任务](./query) 轮询结果。

## 支持模型

* `viduq3-pro`: 高效生成优质音视频内容,让视频内容更生动、更形象、更立体
* `viduq2-pro` / `viduq2-turbo`: 新模型,效果好,细节丰富
* `viduq2-pro-fast`: 价格触底,生成速度快
* `viduq1` / `viduq1-classic`: 画面清晰,运镜稳定
* `vidu2.0`: 生成速度快

## 方法与路径

```http theme={null}
POST /vidu/ent/v2/img2video
```

## 请求示例

<CodeGroup>
  ```bash theme={null}
  curl -X POST https://octopusx.ai/vidu/ent/v2/img2video \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "viduq3-pro",
      "images": ["https://example.com/first-frame.png"],
      "prompt": "让人物向前走并微笑",
      "audio": true,
      "is_rec": false,
      "bgm": false,
      "duration": 5,
      "seed": 0,
      "resolution": "720p",
      "off_peak": false,
      "watermark": false
    }'
  ```

  ```python theme={null}
  import requests

  resp = requests.post(
      "https://octopusx.ai/vidu/ent/v2/img2video",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      json={
          "model": "viduq3-pro",
          "images": ["https://example.com/first-frame.png"],
          "prompt": "让人物向前走并微笑",
          "audio": True,
          "is_rec": False,
          "bgm": False,
          "duration": 5,
          "seed": 0,
          "resolution": "720p",
          "off_peak": False,
          "watermark": False
      },
      timeout=60,
  )
  print(resp.json())
  ```
</CodeGroup>

## 响应示例

<ResponseExample>
  ```json 200 theme={null}
  {
    "task_id": "48038932-0ff5-4251-8b4b-7a76c09fd114",
    "status": "processing",
    "created_at": 1774494511
  }
  ```
</ResponseExample>

## 认证

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Body

<ParamField body="model" type="string" required>
  模型名称。支持 `viduq3-pro`、`viduq2-pro`、`viduq2-turbo`、`viduq2-pro-fast`、`viduq1`、`viduq1-classic`、`vidu2.0`。
</ParamField>

<ParamField body="images" type="array" required>
  首帧图像。只支持输入 1 张图,支持图片 Base64 编码或图片 URL。图片格式:png、jpeg、jpg、webp。图片比例需要小于 1:4 或 4:1,图片大小不超过 50 MB。
</ParamField>

<ParamField body="prompt" type="string">
  文本提示词。生成视频的文本描述。若使用 `is_rec` 推荐提示词参数,模型将不考虑此参数所输入的提示词。
</ParamField>

<ParamField body="audio" type="boolean">
  音视频直出。`true`:输出带台词以及背景音的视频;`false`:输出静音视频。
</ParamField>

<ParamField body="voice_id" type="string">
  音色 ID。用来决定视频中的声音音色,为空时系统会自动推荐。注:q3 模型不生效。
</ParamField>

<ParamField body="is_rec" type="boolean">
  是否使用推荐提示词。`true`:系统自动推荐提示词(推荐提示词数量=1);`false`:根据输入的 prompt 生成视频。
</ParamField>

<ParamField body="bgm" type="boolean">
  背景音乐。`true`:系统将从预设 BGM 库中自动挑选合适的音乐并添加;`false`:不添加 BGM。
</ParamField>

<ParamField body="duration" type="integer">
  视频时长(秒)。`viduq2` 系列:默认 5 秒,可选 1-10 秒。
</ParamField>

<ParamField body="seed" type="integer">
  随机种子。不传或传 0 时使用随机数,手动设置则使用指定种子。
</ParamField>

<ParamField body="resolution" type="string">
  分辨率。默认值依据模型和视频时长而定。`viduq2`(1-10 秒):默认 720p,可选 540p、720p、1080p。
</ParamField>

<ParamField body="off_peak" type="boolean">
  错峰模式。`true`:错峰生成视频;`false`:即时生成视频。
</ParamField>

<ParamField body="watermark" type="boolean">
  是否添加水印。`true`:添加水印;`false`:不添加水印。
</ParamField>

<ParamField body="wm_position" type="integer">
  水印位置。`1`:左上角;`2`:右上角;`3`:右下角;`4`:左下角。
</ParamField>

<ParamField body="wm_url" type="string">
  水印图片 URL。不传时使用默认水印:"内容由 AI 生成"。
</ParamField>

<ParamField body="payload" type="string">
  透传参数。不做任何处理,仅数据传输。
</ParamField>

<ParamField body="meta_data" type="string">
  元数据标识。JSON 格式字符串,透传字段。
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  任务 ID,用于查询任务状态。
</ResponseField>

<ResponseField name="status" type="string">
  任务状态。可选值:`processing`(处理中)、`failed`(失败)、`completed`(已完成)。
</ResponseField>

<ResponseField name="created_at" type="integer">
  创建时间戳(Unix 时间戳)。
</ResponseField>

## 相关接口

* [Vidu 视频概览](./overview)
* [文生视频](./text2video)
* [首尾帧生视频](./start-end2video)
* [参考生视频](./reference2video)
* [查询任务](./query)