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

* 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](https://docs.toapis.com/docs/en/api-reference/uploads/images.md) first.

## Authorization

**Authorization** `string` *required*

All endpoints require Bearer Token authentication.

```
Authorization: Bearer YOUR_API_KEY
```

## Request Parameters

**model** `string` *required*

Model name, fixed to `viduq4-preview`.

**prompt** `string` *required*

Text prompt describing subject, motion, scene, camera movement, and style.

**image\_urls** `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"]`

**video\_generation\_mode** `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.

**duration** `integer` (default: 5)

Video duration in seconds, `3` to `16`.

**resolution** `string` (default: 720p)

Video resolution.

Options:

* `540p`
* `720p`
* `1080p`
* `2K`
* `4K`

**aspect\_ratio** `string`

Video aspect ratio, used in reference mode.

Options: `16:9`, `9:16`, `4:3`, `3:4`, `1:1`

**audio** `boolean` (default: true)

Whether to generate audio for the video.

**watermark** `boolean` (default: false)

Whether to add a watermark to the generated video.

**seed** `integer`

Random seed for more reproducible results with the same parameters.

**metadata** `object`

Extended parameters for fields supported by the upstream API but not exposed as top-level fields.

**Show metadata fields**

**is\_rec** `boolean`

Whether to expand and enhance the prompt automatically. Upstream default is `true` when omitted.

**sounds** `string[]`

Reference audio URL array (reference-to-video mode only). Up to 3 audio files.

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

**wm\_position** `integer`

Watermark position, `1` to `4`. Effective when `watermark` is `true`.

**wm\_url** `string`

Custom watermark image URL. Effective when `watermark` is `true`.

**meta\_data** `string`

Custom metadata identifier, JSON format string passed through to the result.

**callback\_url** `string`

ToAPIs final Task Webhook. Configure the Token URL and signing secret first; see [Task Webhooks](https://docs.toapis.com/docs/en/api-reference/webhooks/task-webhooks.md).

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

**id** `string`

Task ID for querying task status.

**object** `string`

Object type, usually `generation.task`.

**model** `string`

Model used for the request.

**status** `string`

Task status: `queued`, `in_progress`, `completed`, or `failed`.

**created\_at** `integer`

Task creation timestamp.

## 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](https://docs.toapis.com/docs/en/api-reference/tasks/video-status.md) endpoint to query progress and results.

```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());
```


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