> ## 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 Image-to-Video

> Submit a first-frame image video generation task using `POST /vidu/ent/v2/img2video`.

# Vidu Image-to-Video

Vidu official image-to-video interface, submitted as `application/json`.

* The route entry is `POST /vidu/ent/v2/img2video`.
* Currently submitted as `application/json`.
* Supports first-frame image video generation.
* After successful submission, the task `task_id` and `status` are returned, and you can poll the result later with [Query Task](./query).

## Supported Models

* `viduq3-pro`: Efficiently generates high-quality audio and video content, making videos more vivid, realistic, and three-dimensional
* `viduq2-pro` / `viduq2-turbo`: New models with good results and rich details
* `viduq2-pro-fast`: Lowest price, fast generation speed
* `viduq1` / `viduq1-classic`: Clear visuals, stable camera movement
* `vidu2.0`: Fast generation speed

## Method and Path

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

## Request Example

<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>

## Response Example

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

## Authentication

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

## Body

<ParamField body="model" type="string" required>
  Model name. Supports `viduq3-pro`, `viduq2-pro`, `viduq2-turbo`, `viduq2-pro-fast`, `viduq1`, `viduq1-classic`, and `vidu2.0`.
</ParamField>

<ParamField body="images" type="array" required>
  First-frame image. Only 1 image is supported. Supports image Base64 encoding or image URL. Image formats: png, jpeg, jpg, webp. The image ratio must be less than 1:4 or 4:1, and the image size must not exceed 50 MB.
</ParamField>

<ParamField body="prompt" type="string">
  Text prompt. The text description for video generation. If you use the `is_rec` recommended prompt parameter, the model will ignore the prompt entered in this parameter.
</ParamField>

<ParamField body="audio" type="boolean">
  Audio and video direct output. `true`: output a video with dialogue and background sound; `false`: output a silent video.
</ParamField>

<ParamField body="voice_id" type="string">
  Voice ID. Used to determine the voice timbre in the video. If empty, the system will automatically recommend one. Note: does not take effect for q3 models.
</ParamField>

<ParamField body="is_rec" type="boolean">
  Whether to use recommended prompts. `true`: the system automatically recommends prompts (number of recommended prompts = 1); `false`: generate video based on the input prompt.
</ParamField>

<ParamField body="bgm" type="boolean">
  Background music. `true`: the system will automatically select suitable music from the preset BGM library and add it; `false`: do not add BGM.
</ParamField>

<ParamField body="duration" type="integer">
  Video duration (seconds). `viduq2` series: default 5 seconds, optional 1-10 seconds.
</ParamField>

<ParamField body="seed" type="integer">
  Random seed. If not provided or set to 0, a random number is used. If manually set, the specified seed is used.
</ParamField>

<ParamField body="resolution" type="string">
  Resolution. The default value depends on the model and video duration. `viduq2` (1-10 seconds): default 720p, optional 540p, 720p, 1080p.
</ParamField>

<ParamField body="off_peak" type="boolean">
  Off-peak mode. `true`: generate video during off-peak hours; `false`: generate video immediately.
</ParamField>

<ParamField body="watermark" type="boolean">
  Whether to add a watermark. `true`: add watermark; `false`: do not add watermark.
</ParamField>

<ParamField body="wm_position" type="integer">
  Watermark position. `1`: top-left; `2`: top-right; `3`: bottom-right; `4`: bottom-left.
</ParamField>

<ParamField body="wm_url" type="string">
  Watermark image URL. If not provided, the default watermark "Content generated by AI" is used.
</ParamField>

<ParamField body="payload" type="string">
  Pass-through parameter. No processing is performed; data is only transmitted.
</ParamField>

<ParamField body="meta_data" type="string">
  Metadata identifier. A JSON-formatted string, pass-through field.
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  Task ID, used to query the task status.
</ResponseField>

<ResponseField name="status" type="string">
  Task status. Possible values: `processing` (in progress), `failed` (failed), `completed` (completed).
</ResponseField>

<ResponseField name="created_at" type="integer">
  Creation timestamp (Unix timestamp).
</ResponseField>

## Related APIs

* [Vidu Overview](./overview)
* [Text-to-Video](./text2video)
* [Start-End Frame to Video](./start-end2video)
* [Reference-to-Video](./reference2video)
* [Query Task](./query)