ToAPIsToAPIs
Vidu Q3

Vidu Q3 動画生成

Generate videos with Vidu Q3 models, including text-to-video, image-to-video, first-last frame, reference-to-video and subjects generation

POST
/v1/videos/generations

中国本土のユーザー向け: 中国本土のユーザーは https://toapis.cn を API エンドポイント(Base URL)としてご利用ください。本ドキュメント内の例では https://toapis.com を https://toapis.cn に置き換えてください。

  • Async task API, returns a task ID after submission
  • Supported models: viduq3-pro, viduq3-turbo, viduq3
  • viduq3-pro: High quality model, supports audio-video sync and storyboard generation
  • viduq3-turbo: Fast model, intelligent scene switching, fastest generation, best cost-effectiveness
  • viduq3: Best multi-camera consistency, intelligent camera switching, multi-reference generation

Use publicly accessible image URLs. Do not pass base64 image data in image_urls; upload local images with the Upload 画像API first.

Authorization

Authorizationstringヘッダー必須

All endpoints require Bearer Token authentication.

Authorization: Bearer YOUR_API_KEY

リクエストパラメータ

modelstringボディ必須

Vidu Q3 model name.

Options:

  • viduq3-pro - high quality, supports audio-video sync and storyboard generation
  • viduq3-turbo - fastest generation, intelligent scene switching
  • viduq3 - best multi-camera consistency, for multi-reference/subjects generation
promptstringボディ必須

Text prompt, maximum 5000 characters.

Describes subject, action, scene, camera movement, and style. When using subjects, reference them via @name in the prompt.

Example: "A cat playing piano, camera slowly zooms in, cinematic quality"

durationintegerボディデフォルト: 5

Video duration in seconds.

  • viduq3-pro / viduq3-turbo: 1 to 16
  • viduq3: 3 to 16
resolutionstringボディデフォルト: 720p

Video resolution.

Options:

  • 540p
  • 720p
  • 1080p
aspect_ratiostringボディ

Video aspect ratio.

Common values: 16:9, 9:16, 1:1

Q3 models support any aspect ratio. When image_urls is provided, the output ratio is usually determined by the reference image.

image_urlsstring[]ボディ

Reference image URL array.

  • viduq3-pro / viduq3-turbo
    • Omitted: text-to-video
    • 1 image: image-to-video, image as first frame
    • 2 images: first-last frame
  • viduq3
    • 必須, up to 7 reference images

Example: ["https://example.com/reference.jpg"]

audiobooleanボディ

Whether to enable audio-video output.

  • All Q3 models default to true

When true, the system generates speech and sound effects based on the prompt.

seedintegerボディ

Random seed for more reproducible results with the same parameters.

metadataobjectボディ

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

Show metadata fields
subjectsarrayボディ

Subject list (Subjects mode, viduq3 only). Each subject contains name and images fields.

  • Up to 7 subjects
  • Up to 3 images per subject
  • Reference subjects via @name in the prompt

Example:

[
  {"name": "cat", "images": ["https://example.com/cat.jpg"]},
  {"name": "dog", "images": ["https://example.com/dog.jpg"]}
]
auto_subjectsbooleanボディ

Whether to use intelligent entity library, defaults to false.

voice_idstringボディ

Voice ID for specifying the voice character in the video.

audio_typestringボディ

Audio type, effective when audio is true.

Options:

  • all - sound effects + speech (default)
  • speech_only - speech only
  • sound-effect_only - sound effects only
off_peakbooleanボディ

Off-peak mode, defaults to false.

  • true: off-peak generation, consumes fewer credits
  • Off-peak tasks will be generated within 48 hours; incomplete tasks are auto-cancelled with credits refunded
  • Q3 models support off-peak when audio=true
payloadstringボディ

Transparent passthrough parameter, max 1048576 characters.

callback_urlstringボディ

ToAPIs 最終 Task Webhook。Token URL と secret を設定してください。Webhook。

モデル Selection

モデルUse CaseImage InputResolutionDuration
viduq3-proHigh quality text/image/first-last frame任意, up to 2 images540p / 720p / 1080p1-16s
viduq3-turboFast text/image/first-last frame任意, up to 2 images540p / 720p / 1080p1-16s
viduq3Multi-reference/Subjects generation必須, up to 7 images540p / 720p / 1080p3-16s

Billing Dimensions

Vidu Q3 is billed by model, resolution, and generation type:

  • viduq3-pro: high quality tier, approximately 2x the price of turbo
  • viduq3-turbo: fast tier, best cost-effectiveness
  • viduq3: multi-reference generation, billed at reference generation rate

レスポンス

idstring

Task ID for querying task status.

objectstring

Object type, usually generation.task.

modelstring

モデル used for the request.

statusstring

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

created_atinteger

Task creation timestamp.

Examples

Text-to-Video

{
  "model": "viduq3-pro",
  "prompt": "A cat playing piano, camera slowly zooms in, cinematic quality",
  "duration": 8,
  "resolution": "1080p",
  "aspect_ratio": "16:9",
  "audio": true
}

Image-to-Video

{
  "model": "viduq3-turbo",
  "prompt": "The person in the image slowly turns and smiles",
  "image_urls": ["https://example.com/portrait.jpg"],
  "duration": 5,
  "resolution": "720p"
}

First-Last Frame

{
  "model": "viduq3-pro",
  "prompt": "The person naturally sits down from standing, smooth motion",
  "image_urls": [
    "https://example.com/first-frame.jpg",
    "https://example.com/last-frame.jpg"
  ],
  "duration": 8,
  "resolution": "720p"
}

Multi-Reference Image Video

{
  "model": "viduq3",
  "prompt": "Keep the character consistent from the reference images, walking through a futuristic city street",
  "image_urls": [
    "https://example.com/character-front.jpg",
    "https://example.com/character-side.jpg"
  ],
  "duration": 6,
  "resolution": "1080p"
}

Subjects Mode

{
  "model": "viduq3",
  "prompt": "@cat and @dog are running in the park, sunny day",
  "image_urls": ["https://example.com/park-bg.jpg"],
  "duration": 8,
  "resolution": "720p",
  "audio": true,
  "metadata": {
    "subjects": [
      {"name": "cat", "images": ["https://example.com/cat.jpg"]},
      {"name": "dog", "images": ["https://example.com/dog.jpg"]}
    ],
    "audio_type": "all"
  }
}

Video generation is asynchronous. Use the Get Video Task ステータス 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": "viduq3-pro",
    "prompt": "A cat playing piano, camera slowly zooms in, cinematic quality",
    "duration": 8,
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "audio": true
  }'
import requests

response = requests.post(
    "https://toapis.com/v1/videos/generations",
    headers={
        "Authorization": "Bearer <token>",
        "Content-Type": "application/json",
    },
    json={
        "model": "viduq3-pro",
        "prompt": "A cat playing piano, camera slowly zooms in, cinematic quality",
        "duration": 8,
        "resolution": "1080p",
        "aspect_ratio": "16:9",
        "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: "viduq3-pro",
    prompt: "A cat playing piano, camera slowly zooms in, cinematic quality",
    duration: 8,
    resolution: "1080p",
    aspect_ratio: "16:9",
    audio: true
  })
});

console.log(await response.json());