Skip to main content
POST
Vidu Q3 Video Generation
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 unified generation.task after submission
  • Available models: viduq3-pro-fast, viduq3-ad, viduq3-drama, viduq3-mix
viduq3-ad, viduq3-drama, and viduq3-mix are not pure text-to-video models. Do not pass only prompt; reference material is required. Otherwise the upstream typically returns InvalidParameter, e.g. Missing required field 'subjects' in request body.

Authentication

string
required
All endpoints require Bearer Token authentication.

Supported Models

Request Parameters

string
required
Only the following 4 public model names are supported:
  • viduq3-pro-fast
  • viduq3-ad
  • viduq3-drama
  • viduq3-mix
string
required
The prompt.Even for reference generation models, always provide prompt to describe shots, motion, pacing, and style.
string[]
List of reference image URLs.
  • viduq3-pro-fast: only the first image is used, as the first frame
  • viduq3-ad / viduq3-drama / viduq3-mix: pass one or more subject/style reference images
Compatible fields:
  • input_reference
  • reference_images
  • images
  • image
string
Reference video URL.Only recommended for viduq3-ad / viduq3-drama / viduq3-mix. Equivalent to passing one primary reference video.
array
List of reference videos.Only used by viduq3-ad / viduq3-drama / viduq3-mix. Each item supports:
  • video_url
  • refer_type (optional)
  • keep_original_sound (optional)
integer
default:5
Video duration in seconds. Default 5.
string
default:"720P"
Resolution, supports 720P and 1080P.Recommendations:
  • Prefer 1080P for viduq3-drama
boolean
Whether to generate audio.Current server-side defaults:
  • viduq3-pro-fast: default true
  • viduq3-ad: default true
  • viduq3-mix: default true
  • viduq3-drama: pass the value explicitly; do not rely on the default
boolean
default:false
Whether to add a watermark.
integer
Random seed.
object
Extended parameters, passed through following the upstream video request structure.Common usage:
  • metadata.input.first_frame_url
  • metadata.input.last_frame_url
  • metadata.input.audio_url
  • metadata.parameters.audio
  • metadata.parameters.watermark
viduq3-ad / viduq3-drama / viduq3-mix may require structured subject input on the upstream side (e.g. subjects). Requests with only a plain text prompt usually fail.

Input Rules

1. viduq3-pro-fast

  • First-frame image-to-video model
  • At least 1 image required
  • When multiple images are provided, only the first one is used
  • Best for “animate a still image” scenarios

2. viduq3-ad / viduq3-drama / viduq3-mix

  • Reference video generation models; plain-prompt calls are not recommended
  • Recommended minimum input:
    • 1 reference video: url or video_list
    • 1 reference image: image_urls or a compatible image field
  • If subjects/reference material is missing, the upstream may return:
    • InvalidParameter
    • Missing required field 'subjects' in request body

Request Examples

viduq3-pro-fast first-frame image-to-video

viduq3-ad reference video generation

viduq3-drama narrative reference generation

viduq3-mix mixed reference generation

Success Response

Query Task

GET /v1/videos/generations/{task_id} In progress:
Completed:
Failed:

Notes

  • After submission, ToAPIs polls the upstream task status and returns standard video task results.
  • viduq3-pro-fast is the most stable integration form today, suitable for first-frame image-to-video.
  • viduq3-ad, viduq3-drama, and viduq3-mix have stricter requirements on reference material. Prepare complete material per the examples above before integrating; do not pass only a prompt.