> ## 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 Video Generation

> Use `POST /v1/videos` to call the Vidu model and submit asynchronous video tasks.

# Vidu Video Generation

The Vidu channel uses `POST /v1/videos` to submit tasks, submitted as `multipart/form-data`.

* The route entry is `POST /v1/videos`.
* Currently submitted as `multipart/form-data`.
* Supports text-to-video and image-to-video.
* Upload a single reference image file through the `images` field.
* After a successful submission, the task `id` and `status` are returned. Poll the result later with [Task Status Query](./vidu-query).

## Supported Models

* `viduq3-pro`: Efficiently generates high-quality audio and video content, making videos more vivid, more lifelike, and more three-dimensional
* `viduq2-pro`: New model, good results, rich details
* `viduq2-turbo`: New model, good results, fast generation

## Method and Path

```http theme={null}
POST /v1/videos
```

## Request Example

<CodeGroup>
  ```bash theme={null}
  curl -X POST https://octopusx.ai/v1/videos \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -F "model=viduq3-pro" \
    -F "prompt=A cat chasing butterflies on the grass" \
    -F "aspect_ratio=16:9" \
    -F "duration=5"
  ```

  ```python theme={null}
  import requests

  resp = requests.post(
      "https://octopusx.ai/v1/videos",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
      data={
          "model": "viduq3-pro",
          "prompt": "A cat chasing butterflies on the grass",
          "aspect_ratio": "16:9",
          "duration": 5,
      },
      timeout=60,
  )
  print(resp.json())
  ```
</CodeGroup>

### Image-to-Video Example

<CodeGroup>
  ```bash theme={null}
  # Request example with a reference image
  curl -X POST https://octopusx.ai/v1/videos \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -F "model=viduq3-pro" \
    -F "prompt=Have the person walk forward and smile" \
    -F "aspect_ratio=9:16" \
    -F "duration=5" \
    -F "images=@/path/to/image.png"
  ```

  ```python theme={null}
  # Request example with a reference image
  import requests

  with open("image.png", "rb") as f:
      resp = requests.post(
          "https://octopusx.ai/v1/videos",
          headers={"Authorization": "Bearer YOUR_API_KEY"},
          data={
              "model": "viduq3-pro",
              "prompt": "Have the person walk forward and smile",
              "aspect_ratio": "9:16",
              "duration": 5,
          },
          files={"images": f},
          timeout=60,
      )
      print(resp.json())
  ```
</CodeGroup>

## Response Example

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "video_123",
    "object": "video",
    "model": "viduq3-pro",
    "status": "queued",
    "progress": 0,
    "created_at": 1712697600,
    "size": "1024x1808",
    "seconds": "5",
    "quality": "standard"
  }
  ```
</ResponseExample>

## Authentication

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

## Body

<ParamField body="model" type="string" required>
  Model name. Supported values: `viduq3-pro`, `viduq2-pro`, `viduq2-turbo`.
</ParamField>

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

<ParamField body="images" type="file">
  Reference image. Upload a single image file for image-to-video scenarios. Supports passing an image Base64 encoding or an image URL (ensure it is accessible). Only 1 image is supported. Supported image formats: png, jpeg, jpg, webp. The image aspect ratio must be less than 1:4 or greater than 4:1, and the image size must not exceed 50 MB.
</ParamField>

<ParamField body="aspect_ratio" type="string">
  Aspect ratio. Optional values include `16:9` (default), `9:16`, `3:4`, `4:3`, `1:1`. Note: `3:4` and `4:3` are only supported by q2 and q3 models.
</ParamField>

<ParamField body="audio" type="boolean">
  Whether to use the audio-video direct output capability. `false`: no direct audio-video output, produces a silent video; `true`: direct audio-video output is required, producing a video with dialogue and background sound.
</ParamField>

<ParamField body="voice_id" type="string">
  Voice ID, not effective for q3 models. Used to determine the voice timbre in the video; when empty, the system will automatically recommend one.
</ParamField>

<ParamField body="is_rec" type="boolean">
  Whether to use recommended prompts. `true`: the system automatically recommends prompts and uses the prompt content to generate the video, recommended prompt count = 1; `false`: generate the video based on the input prompt.
</ParamField>

<ParamField body="bgm" type="boolean">
  Whether to add background music to the generated video. `true`: the system will automatically select suitable music from the preset BGM library and add it; `false`: no BGM is added.
</ParamField>

<ParamField body="duration" type="integer">
  Video duration (seconds). The default for the viduq2 series is 5; optional: 1-10.
</ParamField>

<ParamField body="seed" type="integer">
  Random seed. When not passed by default or passed as 0, a random number will be used instead. If set manually, the configured seed will be used.
</ParamField>

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

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

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

<ParamField body="watermark" type="boolean">
  Whether to add a watermark. `true`: add watermark; `false`: no 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 content, here it is an image URL. If not passed, the default watermark is used: content generated by AI.
</ParamField>

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

## Response

<ResponseField name="id" type="string">
  Task ID.
</ResponseField>

<ResponseField name="object" type="string">
  Fixed as `video`.
</ResponseField>

<ResponseField name="model" type="string">
  Model name.
</ResponseField>

<ResponseField name="status" type="string">
  Task status. Optional values include `queued` (in queue), `processing` (processing), `completed` (completed), `failed` (failed), `cancelled` (cancelled).
</ResponseField>

<ResponseField name="progress" type="integer">
  Progress percentage (0-100).
</ResponseField>

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

<ResponseField name="size" type="string">
  Video size, for example `1024x1808`.
</ResponseField>

<ResponseField name="seconds" type="string">
  Video duration (seconds).
</ResponseField>

<ResponseField name="quality" type="string">
  Video quality, for example `standard`.
</ResponseField>

## Related Endpoints

* [Vidu Video Overview](./overview)
* [Task Status Query](./vidu-query)