API protocol

Vidu Q3 Pro Fast: 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 Pro Fast: 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 Pro Fast supports Image to video, First/last frames. 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-pro-fast

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. Official limit: 50 MB per image. 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-pro-fast.
metadata.actionstringSite mode selection: Image to video=generate; First/last frames=firstTailGenerate. 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. Official image mode uses a recommended prompt when is_rec=true; the site supports this toggle in image mode.
imagesstring[]Required for image modes; send an array on this service: one first frame; two images ordered first, last; public URLs or Base64 data URIs with a MIME prefix, PNG/JPEG/JPG/WebP. First/last image resolution ratio: 0.8–1.25. The official string/one-image annotation conflicts with its two-frame description; the site sends a two-image array.
durationintegerOfficial range 1–16 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.
resolutionstringOfficial 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.
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.
audiobooleanOptional, default true; false requests silent video.
is_recbooleanOfficial image mode only: recommended/expanded prompts; Q3 defaults to false; true uses a recommended prompt instead of the supplied prompt. The site supports true/false and preserves explicit false; omission follows the provider default.
off_peakbooleanOfficial default false (immediate); true queues off-peak for up to 48 hours, with cancellation and automatic cancellation if unfinished. 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.
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.

Scenarios and code examples

Image to video: minimal request

Applies to: viduq3-pro-fast

POST /v1/videos

{
  "model": "viduq3-pro-fast",
  "prompt": "镜头缓慢推进,保持主体外观一致。",
  "duration": 1,
  "size": "720p",
  "metadata": {
    "action": "generate"
  },
  "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-pro-fast",
  "prompt": "镜头缓慢推进,保持主体外观一致。",
  "duration": 1,
  "size": "720p",
  "metadata": {
    "action": "generate"
  },
  "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-pro-fast\",\"prompt\":\"镜头缓慢推进,保持主体外观一致。\",\"duration\":1,\"size\":\"720p\",\"metadata\":{\"action\":\"generate\"},\"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-pro-fast",
  "prompt": "镜头缓慢推进,保持主体外观一致。",
  "duration": 1,
  "size": "720p",
  "metadata": {
    "action": "generate"
  },
  "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));

First/last frames: minimal request

Applies to: viduq3-pro-fast

POST /v1/videos

{
  "model": "viduq3-pro-fast",
  "prompt": "镜头缓慢推进,保持主体外观一致。",
  "duration": 1,
  "size": "720p",
  "metadata": {
    "action": "firstTailGenerate"
  },
  "images": [
    "https://example.com/frame-1.png",
    "https://example.com/frame-2.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-pro-fast",
  "prompt": "镜头缓慢推进,保持主体外观一致。",
  "duration": 1,
  "size": "720p",
  "metadata": {
    "action": "firstTailGenerate"
  },
  "images": [
    "https://example.com/frame-1.png",
    "https://example.com/frame-2.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-pro-fast\",\"prompt\":\"镜头缓慢推进,保持主体外观一致。\",\"duration\":1,\"size\":\"720p\",\"metadata\":{\"action\":\"firstTailGenerate\"},\"images\":[\"https://example.com/frame-1.png\",\"https://example.com/frame-2.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-pro-fast",
  "prompt": "镜头缓慢推进,保持主体外观一致。",
  "duration": 1,
  "size": "720p",
  "metadata": {
    "action": "firstTailGenerate"
  },
  "images": [
    "https://example.com/frame-1.png",
    "https://example.com/frame-2.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 to video

Vidu First/last frames

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 to video Official
  2. Vidu First/last frames Official
  3. Vidu callback signature Official