Vidu Q3 Video Generation
curl --request POST \
--url https://toapis.com/v1/videos/generations \
--header 'Authorization: <authorization>' \
--header 'Content-Type: application/json' \
--data '
{
"model": "<string>",
"prompt": "<string>",
"image_urls": [
"<string>"
],
"url": "<string>",
"video_list": [
{}
],
"duration": 123,
"resolution": "<string>",
"audio": true,
"watermark": true,
"seed": 123,
"metadata": {}
}
'import requests
url = "https://toapis.com/v1/videos/generations"
payload = {
"model": "<string>",
"prompt": "<string>",
"image_urls": ["<string>"],
"url": "<string>",
"video_list": [{}],
"duration": 123,
"resolution": "<string>",
"audio": True,
"watermark": True,
"seed": 123,
"metadata": {}
}
headers = {
"Authorization": "<authorization>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: '<authorization>', 'Content-Type': 'application/json'},
body: JSON.stringify({
model: '<string>',
prompt: '<string>',
image_urls: ['<string>'],
url: '<string>',
video_list: [{}],
duration: 123,
resolution: '<string>',
audio: true,
watermark: true,
seed: 123,
metadata: {}
})
};
fetch('https://toapis.com/v1/videos/generations', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://toapis.com/v1/videos/generations",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'model' => '<string>',
'prompt' => '<string>',
'image_urls' => [
'<string>'
],
'url' => '<string>',
'video_list' => [
[
]
],
'duration' => 123,
'resolution' => '<string>',
'audio' => true,
'watermark' => true,
'seed' => 123,
'metadata' => [
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: <authorization>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://toapis.com/v1/videos/generations"
payload := strings.NewReader("{\n \"model\": \"<string>\",\n \"prompt\": \"<string>\",\n \"image_urls\": [\n \"<string>\"\n ],\n \"url\": \"<string>\",\n \"video_list\": [\n {}\n ],\n \"duration\": 123,\n \"resolution\": \"<string>\",\n \"audio\": true,\n \"watermark\": true,\n \"seed\": 123,\n \"metadata\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "<authorization>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://toapis.com/v1/videos/generations")
.header("Authorization", "<authorization>")
.header("Content-Type", "application/json")
.body("{\n \"model\": \"<string>\",\n \"prompt\": \"<string>\",\n \"image_urls\": [\n \"<string>\"\n ],\n \"url\": \"<string>\",\n \"video_list\": [\n {}\n ],\n \"duration\": 123,\n \"resolution\": \"<string>\",\n \"audio\": true,\n \"watermark\": true,\n \"seed\": 123,\n \"metadata\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://toapis.com/v1/videos/generations")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"model\": \"<string>\",\n \"prompt\": \"<string>\",\n \"image_urls\": [\n \"<string>\"\n ],\n \"url\": \"<string>\",\n \"video_list\": [\n {}\n ],\n \"duration\": 123,\n \"resolution\": \"<string>\",\n \"audio\": true,\n \"watermark\": true,\n \"seed\": 123,\n \"metadata\": {}\n}"
response = http.request(request)
puts response.read_bodyVidu Q3
Vidu Q3 Video Generation
Generate async video tasks with Vidu Q3 video models.
POST
/
v1
/
videos
/
generations
Vidu Q3 Video Generation
curl --request POST \
--url https://toapis.com/v1/videos/generations \
--header 'Authorization: <authorization>' \
--header 'Content-Type: application/json' \
--data '
{
"model": "<string>",
"prompt": "<string>",
"image_urls": [
"<string>"
],
"url": "<string>",
"video_list": [
{}
],
"duration": 123,
"resolution": "<string>",
"audio": true,
"watermark": true,
"seed": 123,
"metadata": {}
}
'import requests
url = "https://toapis.com/v1/videos/generations"
payload = {
"model": "<string>",
"prompt": "<string>",
"image_urls": ["<string>"],
"url": "<string>",
"video_list": [{}],
"duration": 123,
"resolution": "<string>",
"audio": True,
"watermark": True,
"seed": 123,
"metadata": {}
}
headers = {
"Authorization": "<authorization>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: '<authorization>', 'Content-Type': 'application/json'},
body: JSON.stringify({
model: '<string>',
prompt: '<string>',
image_urls: ['<string>'],
url: '<string>',
video_list: [{}],
duration: 123,
resolution: '<string>',
audio: true,
watermark: true,
seed: 123,
metadata: {}
})
};
fetch('https://toapis.com/v1/videos/generations', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://toapis.com/v1/videos/generations",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'model' => '<string>',
'prompt' => '<string>',
'image_urls' => [
'<string>'
],
'url' => '<string>',
'video_list' => [
[
]
],
'duration' => 123,
'resolution' => '<string>',
'audio' => true,
'watermark' => true,
'seed' => 123,
'metadata' => [
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: <authorization>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://toapis.com/v1/videos/generations"
payload := strings.NewReader("{\n \"model\": \"<string>\",\n \"prompt\": \"<string>\",\n \"image_urls\": [\n \"<string>\"\n ],\n \"url\": \"<string>\",\n \"video_list\": [\n {}\n ],\n \"duration\": 123,\n \"resolution\": \"<string>\",\n \"audio\": true,\n \"watermark\": true,\n \"seed\": 123,\n \"metadata\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "<authorization>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://toapis.com/v1/videos/generations")
.header("Authorization", "<authorization>")
.header("Content-Type", "application/json")
.body("{\n \"model\": \"<string>\",\n \"prompt\": \"<string>\",\n \"image_urls\": [\n \"<string>\"\n ],\n \"url\": \"<string>\",\n \"video_list\": [\n {}\n ],\n \"duration\": 123,\n \"resolution\": \"<string>\",\n \"audio\": true,\n \"watermark\": true,\n \"seed\": 123,\n \"metadata\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://toapis.com/v1/videos/generations")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"model\": \"<string>\",\n \"prompt\": \"<string>\",\n \"image_urls\": [\n \"<string>\"\n ],\n \"url\": \"<string>\",\n \"video_list\": [\n {}\n ],\n \"duration\": 123,\n \"resolution\": \"<string>\",\n \"audio\": true,\n \"watermark\": true,\n \"seed\": 123,\n \"metadata\": {}\n}"
response = http.request(request)
puts response.read_bodyNote 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.taskafter 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.
Authorization: Bearer YOUR_API_KEY
Supported Models
| Model | Generation type | Recommended input | Recommended resolution |
|---|---|---|---|
viduq3-pro-fast | First-frame image-to-video | 1 reference image | 720P / 1080P |
viduq3-ad | Reference video generation | Reference video + reference image | 720P / 1080P |
viduq3-drama | Narrative reference video generation | Reference video + reference image | 1080P |
viduq3-mix | Mixed reference generation | Reference video + reference image | 720P / 1080P |
Request Parameters
string
required
Only the following 4 public model names are supported:
viduq3-pro-fastviduq3-adviduq3-dramaviduq3-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 frameviduq3-ad/viduq3-drama/viduq3-mix: pass one or more subject/style reference images
input_referencereference_imagesimagesimage
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_urlrefer_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
1080Pforviduq3-drama
boolean
Whether to generate audio.Current server-side defaults:
viduq3-pro-fast: defaulttrueviduq3-ad: defaulttrueviduq3-mix: defaulttrueviduq3-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_urlmetadata.input.last_frame_urlmetadata.input.audio_urlmetadata.parameters.audiometadata.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:
urlorvideo_list - 1 reference image:
image_urlsor a compatible image field
- 1 reference video:
- If subjects/reference material is missing, the upstream may return:
InvalidParameterMissing required field 'subjects' in request body
Request Examples
viduq3-pro-fast first-frame image-to-video
curl --request POST \
--url 'https://toapis.com/v1/videos/generations' \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"model": "viduq3-pro-fast",
"prompt": "让角色自然抬头微笑,镜头轻微推进,保留原画风格。",
"image_urls": [
"https://example.com/first-frame.png"
],
"duration": 5,
"resolution": "720P",
"audio": true,
"watermark": false
}'
viduq3-ad reference video generation
curl --request POST \
--url 'https://toapis.com/v1/videos/generations' \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"model": "viduq3-ad",
"prompt": "延续参考视频中的节奏与镜头语言,让主角走入商场中庭并面向镜头挥手。",
"url": "https://example.com/reference-video.mp4",
"image_urls": [
"https://example.com/subject-reference.png"
],
"duration": 5,
"resolution": "1080P",
"audio": true
}'
viduq3-drama narrative reference generation
curl --request POST \
--url 'https://toapis.com/v1/videos/generations' \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"model": "viduq3-drama",
"prompt": "保持角色一致性,情绪逐步递进,镜头由中景切到近景。",
"video_list": [
{
"video_url": "https://example.com/reference-scene.mp4"
}
],
"image_urls": [
"https://example.com/character.png"
],
"duration": 5,
"resolution": "1080P",
"watermark": false
}'
viduq3-mix mixed reference generation
curl --request POST \
--url 'https://toapis.com/v1/videos/generations' \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"model": "viduq3-mix",
"prompt": "融合参考视频动作与参考图角色设定,生成一个更具广告感的过场镜头。",
"url": "https://example.com/reference-action.mp4",
"image_urls": [
"https://example.com/brand-character.png"
],
"duration": 5,
"resolution": "720P",
"audio": true
}'
Success Response
{
"id": "vid_01KABCDEF1234567890",
"object": "generation.task",
"model": "viduq3-pro-fast",
"status": "queued",
"progress": 0,
"created_at": 1784169600
}
Query Task
GET /v1/videos/generations/{task_id}
In progress:
{
"id": "vid_01KABCDEF1234567890",
"object": "generation.task",
"model": "viduq3-pro-fast",
"status": "in_progress",
"progress": 60,
"created_at": 1784169600
}
{
"id": "vid_01KABCDEF1234567890",
"object": "generation.task",
"model": "viduq3-pro-fast",
"status": "completed",
"progress": 100,
"created_at": 1784169600,
"completed_at": 1784169660,
"expires_at": 1784256060,
"result": {
"type": "video",
"data": [
{
"url": "https://files.toapis.com/videos/vid_01KABCDEF1234567890.mp4",
"format": "mp4"
}
]
}
}
{
"id": "vid_01KABCDEF1234567890",
"object": "generation.task",
"model": "viduq3-ad",
"status": "failed",
"progress": 100,
"created_at": 1784169600,
"completed_at": 1784169620,
"error": {
"code": "InvalidParameter",
"message": "Missing required field 'subjects' in request body"
}
}
Notes
- After submission, ToAPIs polls the upstream task status and returns standard video task results.
viduq3-pro-fastis the most stable integration form today, suitable for first-frame image-to-video.viduq3-ad,viduq3-drama, andviduq3-mixhave stricter requirements on reference material. Prepare complete material per the examples above before integrating; do not pass only a prompt.