API protocol
Vidu Q3 Ad: parameters, scenarios and API guide
Preview guide
Paste into an AI assistant to help with integration. Documentation and examples only; no real credentials.
Direct answerUse JSON POST /v1/videos with a site API key. Save id and poll GET /v1/videos/{id} until completed or failed. Do not mix provider task_id/state conventions or authentication into site requests.
Updated · Reviewed
Purpose and workflows
Vidu Q3 Ad supports Image references. This guide covers official creation parameters, mode limits and site field mappings. Parameters marked unavailable describe provider capabilities and are excluded from runnable site examples.
This guide checks the site request contract; it does not claim paid generation acceptance for every scenario. Use the exact model, group and available endpoint shown in the marketplace. Replace example.com media and placeholder task IDs. Confirm a minimal request before adding references and advanced parameters. Consult marketplace pricing and actual billing for charges.
Models and endpoints
viduq3-ad
POST /v1/videos
Reference media formats
| Media | Fields | Encoding and transport | Preparation and limits |
|---|---|---|---|
| Images | images | Public URLs or data:image/<actual-format>;base64,... in a JSON array, not disk paths. | PNG/JPEG/JPG/WebP. Keep the complete request below 20 MB, including Base64 expansion. Q3 reference images must be at least 128×128. See images for counts. Q3 aspect-bound wording is ambiguous; prefer inputs within 1:4–4:1. |
Parameters and combinations
- Use JSON POST /v1/videos with a site API key. Save id and poll GET /v1/videos/{id} until completed or failed. Do not mix provider task_id/state conventions or authentication into site requests.
- Official parameters reviewed by model and mode on 2026-11-17. Site examples include implemented fields; new controls still require live generation acceptance. Non-Mix site defaults are 5 seconds, 1080p, which differ from some provider defaults. metadata.duration/resolution override top-level controls; meta_data is a different provider field.
- Official creation returns task_id/state; queries include err_code, payload and creations[].id/url/cover_url/watermarked_url. Unified site queries primarily expose status, video_url and metadata.url, not every provider field. Official output URLs generally expire after 24 hours; download promptly without attaching your site key to external URLs.
- Some official types/defaults are contradictory; the relevant rows identify these discrepancies. Unavailable controls may be ignored or rejected and cannot be enabled by placing them inside metadata. This guide does not claim paid-generation acceptance for every scenario.
- The official creation table for this model has no audio toggle; audio=false does not promise silent output.
| Field | Type | Use and constraints |
|---|---|---|
Authorization | header string | Required. Use Bearer <site API key> and Content-Type: application/json on this service. Direct Vidu APIs use Token <Vidu key>; do not mix credentials or schemes. |
model | string | Required: viduq3-ad. |
metadata.action | string | Site mode selection: Image references=referenceGenerate. Set it explicitly. This is a site field; Vidu selects modes through distinct creation endpoints. |
prompt | string | Describe content, motion, camera and sound. Required by official text/reference modes, optional for image/frames; the site requires a nonempty prompt except image mode with explicit is_rec=true. Maximum 20000 characters. |
images | string[] | Required for image modes; send an array on this service: 1–7 reference images; public URLs or Base64 data URIs with a MIME prefix, PNG/JPEG/JPG/WebP. |
duration | integer | Official range 3–15 seconds, default 5. Use top-level duration; the site defaults to 5 seconds when omitted. metadata.duration overrides it. The seconds alias is also accepted; prefer duration. |
resolution | string | Official values 720p/1080p, default 720p. The site uses metadata.resolution > resolution > size precedence; omitted values default to 1080p. The creation API does not expose 540p for this model even if pricing lists it. |
seed | integer | Optional; omitted or zero requests randomness, a nonzero value selects a seed. Official docs do not specify numeric bounds. Send top-level seed or metadata.seed, with metadata taking precedence; explicit zero is preserved. A repeated seed does not guarantee identical output. |
payload | string | Optional opaque text, at most 1048576 characters, not an object. Send payload or metadata.payload (metadata takes precedence). Official task/callback responses may echo it; the unified site query does not guarantee all raw fields. |
callback_url | string | Optional notification URL; send callback_url or metadata.callback_url (metadata takes precedence). Vidu POSTs processing/success/failed updates; failed success/failure deliveries retry three times. The body follows the official task query schema; verify the official callback signature. The provider task ID is not the site id; poll GET /v1/videos/{id} on the site. |
aspect_ratio | string | Official reference aspect ratio; 1:1/16:9/9:16/3:4/4:3/auto (reference only). Default 16:9. Reference-mode auto follows the input. The site accepts top-level aspect_ratio or metadata.aspect_ratio for text/reference modes, default 16:9. |
watermark | boolean | Optional watermark toggle. Several official tables specify true while prose says disabled by default; the default is inconsistent. Vidu exposes watermarked_url, which the unified site query does not guarantee. |
wm_position | integer | Optional, default 3: 1 top-left, 2 top-right, 3 bottom-right, 4 bottom-left; relevant to watermark output. |
wm_url | string | Optional watermark image URL; when omitted, Vidu uses its built-in AI-generated label. Depends on watermark output. |
meta_data | string (JSON) | Optional JSON-encoded string for output provenance, not the site metadata object. Official example keys: Label, ContentProducer, ContentPropagator, ProduceID, PropagateID, ReservedCode1, ReservedCode2; custom formats are allowed. Omission uses Vidu-generated metadata. |
Scenarios and code examples
Image references: minimal request
Applies to: viduq3-ad
POST /v1/videos
{
"model": "viduq3-ad",
"prompt": "镜头缓慢推进,保持主体外观一致。",
"duration": 3,
"size": "720p",
"metadata": {
"action": "referenceGenerate"
},
"images": [
"https://example.com/frame-1.png"
]
}
curl
curl --fail-with-body --silent --show-error --connect-timeout 10 --max-time 120 --request POST 'https://api.tu-zi.com/v1/videos' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"model": "viduq3-ad",
"prompt": "镜头缓慢推进,保持主体外观一致。",
"duration": 3,
"size": "720p",
"metadata": {
"action": "referenceGenerate"
},
"images": [
"https://example.com/frame-1.png"
]
}'
python
import json
import os
import requests
url = "https://api.tu-zi.com/v1/videos"
headers = json.loads("{\"Authorization\":\"Bearer YOUR_API_KEY\",\"Content-Type\":\"application/json\"}")
for name in ["API_KEY"]:
if not os.environ.get(name, "").strip():
raise RuntimeError("Set environment variable: " + name)
headers["Authorization"] = "Bearer " + os.environ["API_KEY"]
payload = json.loads("{\"model\":\"viduq3-ad\",\"prompt\":\"镜头缓慢推进,保持主体外观一致。\",\"duration\":3,\"size\":\"720p\",\"metadata\":{\"action\":\"referenceGenerate\"},\"images\":[\"https://example.com/frame-1.png\"]}")
response = requests.request("POST", url, headers=headers, json=payload, timeout=120)
response.raise_for_status()
result = response.json()
if isinstance(result, dict) and (result.get("success") is False or result.get("code") is False or result.get("error")):
raise RuntimeError(json.dumps(result, ensure_ascii=False))
print(json.dumps(result, ensure_ascii=False, indent=2))
javascript
// Node.js 20+
const url = "https://api.tu-zi.com/v1/videos";
const headers = {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
};
for (const name of ["API_KEY"]) {
if (!process.env[name]?.trim()) throw new Error("Set environment variable: " + name);
}
headers.Authorization = 'Bearer ' + process.env.API_KEY;
const response = await fetch(url, { method: "POST", headers, body: JSON.stringify({
"model": "viduq3-ad",
"prompt": "镜头缓慢推进,保持主体外观一致。",
"duration": 3,
"size": "720p",
"metadata": {
"action": "referenceGenerate"
},
"images": [
"https://example.com/frame-1.png"
]
}), signal: AbortSignal.timeout(120000) });
if (!response.ok) throw new Error(await response.text());
const result = await response.json();
if (result?.success === false || result?.code === false || result?.error) throw new Error(JSON.stringify(result));
console.log(JSON.stringify(result, null, 2));
Task results and downloads
Save id or task_id from submission. Poll GET /v1/videos/{task_id}: queued / in_progress lead to completed or failed. Read video_url on completion (some responses also expose metadata.url). Resolve relative URLs against the API origin. The site /content endpoint uses your site key; external downloads must not receive that key. Download expiring results promptly. Resume GET after a timeout rather than automatically repeating POST.
Complete unified video Python / JavaScript polling and download examples
Troubleshooting
| Symptom | Check |
|---|---|
| Image validation / URI error | Ensure a video or task ID was not placed in an image field; check the URL returns media |
| Unsupported content type / field | Check the exact family and content/contents/input schema; voice_id cannot be an audio URL |
| 400 conflicting fields | Check prompt/input, frames/references, and seconds/response_format exclusivity |
| HTTP success but task failed | Retain the site task ID, time, model, domain and redacted request; submission 200 is not output success |
| 404 or inaccessible task | Check domain, key access and task type; do not use IDs from another site or the official API |
| Local file cannot be fetched | Use a supported upload flow or a reachable HTTPS media URL |
Sources and scope
Use cases
- Choose video models and media formats
- Diagnose request and task failures
API protocols
/v1/videos
FAQ
Does a task ID prove generation succeeded?
No. Save the site task ID, poll to a successful terminal state and verify the result. Inspect failures instead of automatically creating a new task.
Can I put a local image, video or WAV path in JSON?
No. URL fields require reachable media, not localhost, disk paths or browser-login links. Kling PCM WAV requires an enabled multipart voice endpoint (both sites returned 404 on 2026-11-15). Follow each family’s asset workflow for other media.
Can parameters and task IDs be reused across models?
Do not assume compatibility. Check the exact model, endpoint, casing, media role and exclusive fields. Editing, drafts and voices require accessible successful tasks of the correct kind. Official capabilities are not evidence of site acceptance.
Related guides
Official sources
- Vidu Image references Official
- Vidu callback signature Official
兔子API