API protocol

Vidu Q3 Drama: parameters, scenarios and API guide

Preview guide

Paste into an AI assistant to help with integration. Documentation and examples only; no real credentials.

Preview guide

Vidu Q3 Drama: parameters, scenarios and API guide

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 Drama 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-drama

POST /v1/videos

Reference media formats

MediaFieldsEncoding and transportPreparation and limits
ImagesimagesPublic 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.
FieldTypeUse and constraints
Authorizationheader stringRequired. 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.
modelstringRequired: viduq3-drama.
metadata.actionstringSite mode selection: Image references=referenceGenerate. Set it explicitly. This is a site field; Vidu selects modes through distinct creation endpoints.
promptstringDescribe 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.
imagesstring[]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.
durationintegerOfficial range 2–16 seconds, default 8. Use top-level duration; the site defaults to 5 seconds when omitted. metadata.duration overrides it. The seconds alias is also accepted; prefer duration.
resolutionstringOfficial values 720p/1080p, default 1080p. 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.
seedintegerOptional; 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.
payloadstringOptional 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_urlstringOptional 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_ratiostringOfficial reference aspect ratio; 16:9/9:16/auto. Image-reference docs omit the default; subject docs specify 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.
audiobooleanOptional, default true; false requests silent video. Subject voice_id takes effect only with audio=true.
off_peakbooleanOfficial default false (immediate); true queues off-peak for up to 48 hours, with cancellation and automatic cancellation if unfinished. Drama lists it only for subject references, not image references. Use the applicable published tariff; off_peak is forwarded for supported models; discounts follow the configured site tariff and are not automatically enabled by this flag. Not exposed by this service; omit it from site requests.
soundsstring[]Official image references only: optionally 0–3 MP3 clips, each 3–12 seconds and at most 50 MB. Use public URLs or documented Base64 within the 20 MB request limit. Prefer MP3 URLs because the documented data:video/mp3 example has an ambiguous MIME type.
watermarkbooleanOptional 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_positionintegerOptional, default 3: 1 top-left, 2 top-right, 3 bottom-right, 4 bottom-left; relevant to watermark output.
wm_urlstringOptional watermark image URL; when omitted, Vidu uses its built-in AI-generated label. Depends on watermark output.
meta_datastring (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.
auto_subjectsbooleanOfficial subject references only, default false; true enables intelligent subject-library capabilities. Not exposed by this service; omit it from site requests.
subjectsobject[]Required for official subject-reference mode: up to seven image/text subjects. This is a distinct contract from a plain images array. Not exposed by this service; omit it from site requests.
subjects[].namestringRequired subject name; refer to it in prompt using [@name]. Not exposed by this service; omit it from site requests.
subjects[].imagesstring[]Temporary subject images, marked required by the official schema, at most three per subject: public URLs or MIME-prefixed Base64, PNG/JPEG/JPG/WebP, at least 128×128. Follow the subject API requirements when using server_id; do not assume images become optional. Not exposed by this service; omit it from site requests.
subjects[].voice_idstringOptional voice ID from the official voice list or voice cloning; omission selects automatically. Requires audio=true. Not exposed by this service; omit it from site requests.
subjects[].server_idstringOptional ID from official subject creation. Omission creates a temporary, unsaved subject from uploaded images. Not a site video task ID. Not exposed by this service; omit it from site requests.

Scenarios and code examples

Image references: minimal request

Applies to: viduq3-drama

POST /v1/videos

{
  "model": "viduq3-drama",
  "prompt": "镜头缓慢推进,保持主体外观一致。",
  "duration": 2,
  "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-drama",
  "prompt": "镜头缓慢推进,保持主体外观一致。",
  "duration": 2,
  "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-drama\",\"prompt\":\"镜头缓慢推进,保持主体外观一致。\",\"duration\":2,\"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-drama",
  "prompt": "镜头缓慢推进,保持主体外观一致。",
  "duration": 2,
  "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

SymptomCheck
Image validation / URI errorEnsure a video or task ID was not placed in an image field; check the URL returns media
Unsupported content type / fieldCheck the exact family and content/contents/input schema; voice_id cannot be an audio URL
400 conflicting fieldsCheck prompt/input, frames/references, and seconds/response_format exclusivity
HTTP success but task failedRetain the site task ID, time, model, domain and redacted request; submission 200 is not output success
404 or inaccessible taskCheck domain, key access and task type; do not use IDs from another site or the official API
Local file cannot be fetchedUse a supported upload flow or a reachable HTTPS media URL

Sources and scope

Vidu Image references

Vidu Subject references

Vidu callback signature

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.

Official sources

  1. Vidu Image references Official
  2. Vidu Subject references Official
  3. Vidu callback signature Official