API protocol
Video model families and complete API examples
Preview guide
Paste into an AI assistant to help with integration. Documentation and examples only; no real credentials.
Direct answerChoose the family-specific text, frame or reference format, save the site task ID, poll to completion and download the result. Create a voice before using Kling audio; MiniMax native tasks have a separate query structure.
Updated · Reviewed
Choose a family and a media role
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.
| Family | Workflows and boundaries |
|---|---|
| Wan 3.0 | Use for product shots, motion references, image animation, sound and document-based videos. Choose frame control or multimodal references explicitly. |
| Kling 4.0 | The standard model composes shots from text, frame images and image/video references. Create a custom voice before referencing voice_id. Flash uses a different voice contract. |
| Seedance 2.0 / 2.5 | Use text, frames, multimodal references and character assets. Version 2.5 also has draft and draft-to-final workflows; advanced parameters are version-specific. |
| HappyHorse | t2v uses text, i2v a first frame and r2v reference images. Version 1.1 r2v does not mean video input. |
| Gemini Omni | Video generation and conversational editing use distinct image, video and continuation fields. Parsed input does not prove successful generation. |
| MiniMax-H3 / Context-IR | H3 generates videos; Context-IR asynchronously improves prompts and returns text. Regeneration requires an eligible H3 source and is not generic transcoding. |
| Veo | For shot creation and image-guided video. Site veo2/veo3/veo3.1 and fast/pro/frames names are catalog aliases, not automatically official API IDs. |
| Sora | For short text- or image-guided videos. Site sora-2, sora-2-pro and legacy size/duration aliases are distinct entries. |
| Runway | The catalog includes runway-vip-video without a callable endpoint definition in the current public listing. Official Gen requests or generic video fields cannot be assumed to work here. |
| Vidu | Configured Vidu Q3/Q4 models have individual parameter and request guides. This page retains checks for other unverified models and does not establish their availability. |
| 即梦 / Jimeng | Jimeng image and video tasks differ. A public video endpoint was not verified; image examples are not video requests. |
| Vidu Q4 Preview | Vidu Q4 Preview supports Image to video, 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. |
| Vidu Q3 Pro | Vidu Q3 Pro supports Text to video, 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. |
| Vidu Q3 Pro Fast | 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. |
| Vidu Q3 Turbo | Vidu Q3 Turbo supports Text to video, Image to video, First/last frames, 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. |
| Vidu Q3 | Vidu Q3 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. |
| Vidu Q3 Mix | Vidu Q3 Mix 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. |
| Vidu Q3 Drama | 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. |
| Vidu Q3 Ad | 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. |
URLs, Base64 and local files are different formats
Raw Base64 contains only encoded bytes; a data URI adds a MIME prefix such as data:image/png;base64,.... Gemini Omni video uses raw Base64 data, not a public video URL or a data:video/mp4;base64,... URI. Check each family’s reference-media table for URL and data-URI support. Base64 increases size by about one third; it is not compression. Local file upload requires an explicitly supported multipart endpoint; a disk path in JSON does not upload bytes.
File extension, MIME and actual content must agree. A URL must return media directly, not a preview page or a resource requiring cookies/extra headers; signed URLs must remain valid throughout processing. Client access does not prove generation-service access. Asset, task and voice IDs each have their own fields and are not interchangeable.
Fields are family-specific
Wan uses prompt + reference_videos/reference_audio; Kling contents + settings; Seedance content + role; HappyHorse prompt/image/images + parameters; Gemini Omni prompt or input; MiniMax native content. Audio references are media inputs for Wan/Seedance, while Kling requires voice creation and a voice_id. HappyHorse r2v means reference images.
Prepare a minimal request
Save a scenario JSON with no prerequisite task as request.json and replace model/media placeholders. These scripts are only for POST /v1/videos, not MiniMax /v2 or voice creation. Set TUZI_BASE_URL to your site API origin without /v1 and TUZI_API_KEY to an authorized key. Keep credentials in server-side environment variables, not public browser code.
export TUZI_BASE_URL="https://api.tu-zi.com"
# Set TUZI_API_KEY securely in your environment.
python video.py
# Or: node video.mjs
Submit, poll and download
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.
The examples poll for at most 30 minutes, backing off from 2 to 10 seconds with per-request timeouts. Downloads have a sample 256 MiB limit and use a .part file before saving output.mp4. The deadline does not cancel a task; keep its ID to resume polling. Creation is never automatically retried.
Python
# pip install requests
# Save a /v1/videos scenario body as request.json. Set TUZI_BASE_URL and TUZI_API_KEY.
import json
import os
import re
import time
from pathlib import Path
from urllib.parse import urljoin, urlsplit
import requests
base = os.environ["TUZI_BASE_URL"].rstrip("/")
headers = {"Authorization": "Bearer " + os.environ["TUZI_API_KEY"]}
body = json.loads(Path("request.json").read_text(encoding="utf-8"))
# Submit once. A timeout can mean the task was created; do not blindly retry POST.
r = requests.post(base + "/v1/videos", headers=headers, json=body, timeout=60)
r.raise_for_status()
created = r.json()
task_id = created.get("id") or created.get("task_id")
if not isinstance(task_id, str) or not re.fullmatch(r"[A-Za-z0-9_-]+", task_id):
raise RuntimeError("Missing or invalid task ID")
print("Save task ID:", task_id)
deadline, delay = time.monotonic() + 1800, 2
while time.monotonic() < deadline:
r = requests.get(base + "/v1/videos/" + task_id, headers=headers, timeout=30)
r.raise_for_status()
task = r.json()
status = task.get("status")
if status == "completed":
break
if status in ("failed", "cancelled", "expired"):
raise RuntimeError(task.get("error") or status)
if status not in ("queued", "in_progress"):
raise RuntimeError("Unexpected task status: " + str(status))
time.sleep(min(delay, max(0, deadline - time.monotonic())))
delay = min(10, delay * 1.5)
else:
raise TimeoutError("Polling deadline reached; resume GET with " + task_id)
result = task.get("video_url") or task.get("metadata", {}).get("url")
if not result:
raise RuntimeError("Completed task has no video URL")
url = urljoin(base + "/", result)
origin = urlsplit(base)
# Only the site's own content endpoint needs the site API key.
for _ in range(6):
target = urlsplit(url)
if target.scheme not in ("https", "http") or target.username or target.password:
raise RuntimeError("Invalid download URL")
same_origin = (target.scheme, target.netloc) == (origin.scheme, origin.netloc)
auth = headers if same_origin and target.path == "/v1/videos/" + task_id + "/content" else {}
with requests.get(url, headers=auth, timeout=60, stream=True, allow_redirects=False) as media:
if media.status_code in (301, 302, 303, 307, 308):
if not media.headers.get("Location"):
raise RuntimeError("Redirect without Location")
url = urljoin(url, media.headers["Location"])
continue
media.raise_for_status()
kind = media.headers.get("Content-Type", "").split(";")[0]
if not (kind.startswith("video/") or kind == "application/octet-stream"):
raise RuntimeError("Expected video, got " + kind)
part, size = Path("output.mp4.part"), 0
try:
with part.open("wb") as output:
for chunk in media.iter_content(65536):
size += len(chunk)
if size > 256 * 1024 * 1024:
raise RuntimeError("Download exceeds example's 256 MiB limit")
output.write(chunk)
if size == 0:
raise RuntimeError("Empty download")
part.replace("output.mp4")
finally:
part.unlink(missing_ok=True)
print("Saved output.mp4")
break
else:
raise RuntimeError("Too many download redirects")
JavaScript (Node.js)
// Node.js 20+. Save a /v1/videos scenario as request.json.
// Set TUZI_BASE_URL and TUZI_API_KEY before running this file.
import { readFile, open, rename, rm } from "node:fs/promises";
import { setTimeout as sleep } from "node:timers/promises";
const base = process.env.TUZI_BASE_URL.replace(/\/$/, "");
const headers = { Authorization: `Bearer ${process.env.TUZI_API_KEY}` };
const body = JSON.parse(await readFile("request.json", "utf8"));
async function api(path, init = {}) {
const response = await fetch(base + path, {
...init,
headers: { ...headers, ...init.headers },
signal: AbortSignal.timeout(60000),
redirect: "error",
});
if (!response.ok)
throw new Error(`HTTP ${response.status}: ${await response.text()}`);
return response.json();
}
// Submit once. A POST timeout is not proof that creation failed.
const created = await api("/v1/videos", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(body),
});
const id = created.id || created.task_id;
if (typeof id !== "string" || !/^[A-Za-z0-9_-]+$/.test(id))
throw new Error("Invalid task ID");
console.log("Save task ID:", id);
const deadline = Date.now() + 1800000;
let task,
delay = 2000;
while (Date.now() < deadline) {
task = await api(`/v1/videos/${id}`);
if (task.status === "completed") break;
if (["failed", "cancelled", "expired"].includes(task.status))
throw new Error(JSON.stringify(task.error || task.status));
if (!["queued", "in_progress"].includes(task.status))
throw new Error(`Unexpected status: ${task.status}`);
await sleep(Math.min(delay, Math.max(0, deadline - Date.now())));
delay = Math.min(10000, delay * 1.5);
}
if (task?.status !== "completed")
throw new Error(`Polling deadline; resume GET with ${id}`);
const result = task.video_url || task.metadata?.url;
if (!result) throw new Error("Completed task has no video URL");
let url = new URL(result, base + "/"),
saved = false;
for (let hop = 0; hop < 6; hop++) {
if (
!["https:", "http:"].includes(url.protocol) ||
url.username ||
url.password
)
throw new Error("Invalid download URL");
// Never send the site API key to an external media host, including redirects.
const auth =
url.origin === new URL(base).origin &&
url.pathname === `/v1/videos/${id}/content`
? headers
: {};
const response = await fetch(url, {
headers: auth,
redirect: "manual",
signal: AbortSignal.timeout(120000),
});
if ([301, 302, 303, 307, 308].includes(response.status)) {
await response.body?.cancel();
const location = response.headers.get("location");
if (!location) throw new Error("Redirect without Location");
url = new URL(location, url);
continue;
}
const kind = response.headers.get("content-type")?.split(";")[0] || "";
if (
!response.ok ||
!response.body ||
!(kind.startsWith("video/") || kind === "application/octet-stream")
) {
await response.body?.cancel();
throw new Error(`Download failed: HTTP ${response.status}, ${kind}`);
}
let size = 0;
const part = "output.mp4.part";
try {
const file = await open(part, "w");
try {
for await (const chunk of response.body) {
size += chunk.length;
if (size > 256 * 1024 * 1024)
throw new Error("Download exceeds 256 MiB");
await file.writeFile(chunk);
}
} finally {
await file.close();
}
if (!size) throw new Error("Empty download");
await rename(part, "output.mp4");
} finally {
await rm(part, { force: true });
}
saved = true;
console.log("Saved output.mp4");
break;
}
if (!saved) throw new Error("Too many download redirects");
Terminal states, charges and troubleshooting
Check completed and a downloadable result even after a minimal request is accepted. For diagnosis retain the model, site origin, site task ID, timestamp and redacted error, never keys or signed credentials. This guide describes reviewed request contracts; billing, access and asset review follow the actual site response. Do not automatically equate a failed task with no charge.
Use cases
- Choose video models and media formats
- Diagnose request and task failures
API protocols
/v1/videos/v2/video_generation/v1/general/custom-voices/v1/general/advanced-custom-elements
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
- Tuzi API reference Official
兔子API