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

# Vidu Q4 Preview Video Generation

> Generate videos with the Vidu Q4 Preview model, including image-to-video and multi-reference-to-video with reference audio

<Note>
  **Note for users in mainland China:** Please use `https://toapis.cn` as the API endpoint (Base URL). Replace `https://toapis.com` with `https://toapis.cn` in the examples in this document.
</Note>

* Async task API, returns a task ID after submission
* Supported model: `viduq4-preview`
* Two generation modes:
  * **First-frame image-to-video**: one image as the first frame
  * **Reference-to-video**: multiple reference images, optional reference audio

<Warning>
  Use publicly accessible image and audio URLs. Do not pass base64 data in `image_urls`, `reference_images`, or `sounds`; upload local files with the [Upload Image API](../../uploads/images) first.
</Warning>

## Authorization

<ParamField header="Authorization" type="string" required>
  All endpoints require Bearer Token authentication.

  ```
  Authorization: Bearer YOUR_API_KEY
  ```
</ParamField>

## Request Parameters

<ParamField body="model" type="string" required>
  Model name, fixed to `viduq4-preview`.
</ParamField>

<ParamField body="prompt" type="string" required>
  Text prompt describing subject, motion, scene, camera movement, and style.
</ParamField>

<ParamField body="image_urls" type="string[]">
  Image URL array. The mode is determined by `video_generation_mode` and image count:

  * **First-frame mode** (default): pass exactly 1 image URL in `image_urls`. The image is used as the first frame.
  * **Reference mode**: set `video_generation_mode` to `reference_images_to_video` and pass the reference images in `image_urls` (or `reference_images`).

  Example: `["https://example.com/first-frame.jpg"]`
</ParamField>

<ParamField body="video_generation_mode" type="string">
  Generation mode selector.

  Options:

  * `reference_images_to_video` - multi-reference generation; multiple `image_urls` are treated as reference images

  Omit for first-frame image-to-video. Requests with multiple images, `reference_images`, or `sounds` are automatically routed to reference-to-video.
</ParamField>

<ParamField body="duration" type="integer" default="5">
  Video duration in seconds, `3` to `16`.
</ParamField>

<ParamField body="resolution" type="string" default="720p">
  Video resolution.

  Options:

  * `540p`
  * `720p`
  * `1080p`
  * `2K`
  * `4K`
</ParamField>

<ParamField body="aspect_ratio" type="string">
  Video aspect ratio, used in reference mode.

  Options: `16:9`, `9:16`, `4:3`, `3:4`, `1:1`
</ParamField>

<ParamField body="audio" type="boolean" default="true">
  Whether to generate audio for the video.
</ParamField>

<ParamField body="watermark" type="boolean" default="false">
  Whether to add a watermark to the generated video.
</ParamField>

<ParamField body="seed" type="integer">
  Random seed for more reproducible results with the same parameters.
</ParamField>

<ParamField body="metadata" type="object">
  Extended parameters for fields supported by the upstream API but not exposed as top-level fields.

  <Expandable title="Show metadata fields">
    <ParamField body="is_rec" type="boolean">
      Whether to expand and enhance the prompt automatically. Upstream default is `true` when omitted.
    </ParamField>

    <ParamField body="sounds" type="string[]">
      Reference audio URL array (reference-to-video mode only). Up to 3 audio files.

      Example: `["https://example.com/voice.mp3"]`
    </ParamField>

    <ParamField body="wm_position" type="integer">
      Watermark position, `1` to `4`. Effective when `watermark` is `true`.
    </ParamField>

    <ParamField body="wm_url" type="string">
      Custom watermark image URL. Effective when `watermark` is `true`.
    </ParamField>

    <ParamField body="meta_data" type="string">
      Custom metadata identifier, JSON format string passed through to the result.
    </ParamField>

    <ParamField body="callback_url" type="string">
      ToAPIs final Task Webhook. Configure the Token URL and signing secret first; see [Task Webhooks](/docs/en/api-reference/webhooks/task-webhooks).
    </ParamField>
  </Expandable>
</ParamField>

## Mode Selection

| Mode | How to trigger | Image input | Audio input |
| - | - | - | - |
| First-frame image-to-video | 1 image in `image_urls` (default) | Exactly 1 image | `audio` flag only |
| Reference-to-video | `video_generation_mode: "reference_images_to_video"`, or multiple images / `reference_images` / `sounds` | Up to 15 reference images | Up to 3 `sounds` + `audio` flag |

## Billing Dimensions

Vidu Q4 Preview is billed per second of generated video, priced by resolution:

* `540p` / `720p` / `1080p` / `2K` / `4K` - higher resolutions cost more per second

## Response

<ResponseField name="id" type="string">
  Task ID for querying task status.
</ResponseField>

<ResponseField name="object" type="string">
  Object type, usually `generation.task`.
</ResponseField>

<ResponseField name="model" type="string">
  Model used for the request.
</ResponseField>

<ResponseField name="status" type="string">
  Task status: `queued`, `in_progress`, `completed`, or `failed`.
</ResponseField>

<ResponseField name="created_at" type="integer">
  Task creation timestamp.
</ResponseField>

## Examples

### First-Frame Image-to-Video

```json theme={null}
{
  "model": "viduq4-preview",
  "prompt": "The person in the image slowly turns and smiles, cinematic lighting",
  "image_urls": ["https://example.com/portrait.jpg"],
  "duration": 5,
  "resolution": "1080p",
  "audio": true
}
```

### Reference-to-Video

```json theme={null}
{
  "model": "viduq4-preview",
  "prompt": "Keep the character consistent from the reference images, walking through a neon city street at night",
  "video_generation_mode": "reference_images_to_video",
  "image_urls": [
    "https://example.com/character-front.jpg",
    "https://example.com/character-side.jpg"
  ],
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "3:4",
  "audio": true
}
```

### Reference-to-Video with Reference Audio

```json theme={null}
{
  "model": "viduq4-preview",
  "prompt": "The character speaks the lines with matching lip sync",
  "video_generation_mode": "reference_images_to_video",
  "image_urls": ["https://example.com/character.jpg"],
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "metadata": {
    "sounds": ["https://example.com/voice.mp3"]
  }
}
```

### With Prompt Expansion and Watermark

```json theme={null}
{
  "model": "viduq4-preview",
  "prompt": "A cat walking on a beach at sunset",
  "image_urls": ["https://example.com/cat.jpg"],
  "duration": 8,
  "resolution": "2K",
  "watermark": true,
  "metadata": {
    "is_rec": true
  }
}
```

<Note>
  Video generation is asynchronous. Use the [Get Video Task Status](../../tasks/video-status) endpoint to query progress and results.
</Note>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://toapis.com/v1/videos/generations \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "viduq4-preview",
      "prompt": "The person in the image slowly turns and smiles, cinematic lighting",
      "image_urls": ["https://example.com/portrait.jpg"],
      "duration": 5,
      "resolution": "1080p",
      "audio": true
    }'
  ```

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

  response = requests.post(
      "https://toapis.com/v1/videos/generations",
      headers={
          "Authorization": "Bearer <token>",
          "Content-Type": "application/json",
      },
      json={
          "model": "viduq4-preview",
          "prompt": "The person in the image slowly turns and smiles, cinematic lighting",
          "image_urls": ["https://example.com/portrait.jpg"],
          "duration": 5,
          "resolution": "1080p",
          "audio": True,
      },
  )

  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://toapis.com/v1/videos/generations", {
    method: "POST",
    headers: {
      Authorization: "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      model: "viduq4-preview",
      prompt: "The person in the image slowly turns and smiles, cinematic lighting",
      image_urls: ["https://example.com/portrait.jpg"],
      duration: 5,
      resolution: "1080p",
      audio: true
    })
  });

  console.log(await response.json());
  ```
</RequestExample>


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