Vidu Q4 Preview Video Generation

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

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

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

{
  "id": "<string>",
  "object": "<string>",
  "model": "<string>",
  "status": "<string>",
  "created_at": 123
}

POST

videos

generations

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

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

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

{
  "id": "<string>",
  "object": "<string>",
  "model": "<string>",
  "status": "<string>",
  "created_at": 123
}

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

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

Authorization

string

required

All endpoints require Bearer Token authentication.

Authorization: Bearer YOUR_API_KEY

Request Parameters

string

required

Model name, fixed to viduq4-preview.

string

required

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

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

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.

integer

default:"5"

Video duration in seconds, 3 to 16.

string

default:"720p"

Video resolution.Options:

540p
720p
1080p
2K
4K

string

Video aspect ratio, used in reference mode.Options: 16:9, 9:16, 4:3, 3:4, 1:1

boolean

default:"true"

Whether to generate audio for the video.

boolean

default:"false"

Whether to add a watermark to the generated video.

integer

Random seed for more reproducible results with the same parameters.

object

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

Show Show metadata fields

boolean

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

string[]

Reference audio URL array (reference-to-video mode only). Up to 3 audio files.Example: ["https://example.com/voice.mp3"]

integer

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

string

Custom watermark image URL. Effective when watermark is true.

string

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

string

ToAPIs final Task Webhook. Configure the Token URL and signing secret first; see Task Webhooks.

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

string

Task ID for querying task status.

string

Object type, usually generation.task.

string

Model used for the request.

string

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

integer

Task creation timestamp.

Examples

First-Frame Image-to-Video

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

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

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

{
  "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
  }
}

Video generation is asynchronous. Use the Get Video Task Status endpoint to query progress and results.

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

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

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

Overview

Quick Start

Model Catalog

Chat API

Image API

Video API

Music API

Task Management

File Uploads

Account

FAQs

Authorization

Request Parameters

Mode Selection

Billing Dimensions

Response

Examples

First-Frame Image-to-Video

Reference-to-Video

Reference-to-Video with Reference Audio

With Prompt Expansion and Watermark

​Authorization

​Request Parameters

​Mode Selection

​Billing Dimensions

​Response

​Examples

​First-Frame Image-to-Video

​Reference-to-Video

​Reference-to-Video with Reference Audio

​With Prompt Expansion and Watermark

Authorization

Request Parameters

Mode Selection

Billing Dimensions

Response

Examples

First-Frame Image-to-Video

Reference-to-Video

Reference-to-Video with Reference Audio

With Prompt Expansion and Watermark