Vidu video generation

Submit an async video task with Vidu models.

POST /v1/videos

Available models

Model	Description
	Q3 flagship; direct audio/video output
	Q2 Pro
	Q2 turbo

Headers

Name	Type	Required	Description
	string	Yes	Request authentication. Use a Bearer Token, for example: .

Request body

Name	Type	Required	Description
	string	Yes	Model name. See Available models above.
	string	Yes	Text prompt. Text description of the video. Ignored when recommended prompts are used.
	file	No	Reference image. Upload a single image for image-to-video. Base64 or image URL (must be accessible). Only one image; formats png, jpeg, jpg, webp. Aspect ratio must be less extreme than 1:4 or 4:1; max size 50 MB.
	string	No	Aspect ratio. Options: (default), , , , . Note: and are only supported on q2 and q3 models.
	boolean	No	Whether to use direct audio/video output. : silent video; : video with dialogue and ambient audio.
	string	No	Voice ID; ignored for q3 models. Determines voice timbre; auto-recommended when empty.
	boolean	No	Whether to use recommended prompts. : system auto-recommends prompts and generates from them (count=1); : generate from the input prompt.
	boolean	No	Whether to add background music. : pick suitable music from the preset BGM library; : no BGM.
	integer	No	Video duration in seconds. viduq2 series default 5; options 1–10.
	integer	No	Random seed. Omit or pass 0 for a random seed; set manually to use a fixed seed.
	string	No	Resolution. Default depends on model and duration. 1–10s: default 720p; options 540p, 720p, 1080p. 1–10s: default 720p; options 540p, 720p, 1080p.
	string	No	Passthrough parameter. Not processed; transmitted as-is.
	boolean	No	Off-peak mode. : generate during off-peak hours; : generate immediately.
	boolean	No	Whether to add a watermark. : add watermark; : no watermark.
	integer	No	Watermark position. : top-left; : top-right; : bottom-right; : bottom-left.
	string	No	Watermark content as an image URL. Default watermark when omitted: AI-generated content.
	string	No	Metadata identifier; JSON string; passthrough field.

Request example

Text-to-video

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

Image-to-video

curl -X POST https://octopusx.ai/v1/videos \
  -H "Authorization: Bearer <token>" \
  -F "model=viduq3-pro" \
  -F "prompt=Make the person walk forward and smile" \
  -F "aspect_ratio=9:16" \
  -F "duration=5" \
  -F "images=@/path/to/image.png"

Response example

{
  "id": "video_123",
  "object": "video",
  "model": "viduq3-pro",
  "status": "queued",
  "progress": 0,
  "created_at": 1712697600,
  "size": "1024x1808",
  "seconds": "5",
  "quality": "standard"
}

Response fields

Name	Type	Description
	string	Task ID.
	string	Always .
	string	Model name.
	string	Task status. Options: (queued), (in progress), (completed), (failed), (cancelled).
	integer	Progress percentage (0–100).
	integer	Creation time (Unix timestamp).
	string	Video dimensions, for example .
	string	Video duration in seconds.
	string	Video quality, for example .

Related endpoints

• Vidu video overview
• Video APIs overview
• Error codes