API 协议
视频模型系列指南与完整调用示例
预览指南
粘贴给 AI,帮助理解文档并完成接入。 仅包含文档与示例,不包含真实密钥。
直接答案先按系列选择文本、帧或参考素材的请求格式,再保存本站任务 ID,查询成功终态并下载结果。Kling 音频先创建音色,MiniMax 原生任务使用独立查询结构。
更新 · 审核信息
先选系列,再选素材用途
本指南核对本站请求契约,不代表所有场景均已完成收费出片验收。使用模型广场显示的精确模型、分组和有效端点;示例中的 example.com 素材与占位任务 ID 必须替换。先以最小请求确认可用,再逐项添加参考素材和高级参数。价格以模型广场及实际账单为准。
| 系列 | 场景与边界 |
|---|---|
| Wan 3.0 | 适合产品展示、人物动作参考、图生视频、有声短片和资料转视频。按素材用途选择首尾帧或多模态参考模式。 |
| Kling 4.0 | 标准版支持从文本、帧图片、参考图或视频构建镜头;自定义音色先创建,再以 voice_id 引用。不要把 Flash 与标准版的素材协议混用。 |
| Seedance 2.0 / 2.5 | 适合文字生成、首尾帧、多素材创作与人物参考。2.5 另有草稿与草稿转正式视频流程;各版本不要只替换名称后复用全部高级参数。 |
| HappyHorse | 按 t2v、i2v、r2v 区分纯文字、单首帧和多参考图。1.1 的 r2v 是参考图片生视频,不等同于参考视频。 |
| Gemini Omni | 视频生成与多轮编辑系列。本站的图片参考、外部视频输入和已有任务编辑使用不同字段;协议可解析不代表该场景已通过出片验收。 |
| MiniMax-H3 / Context-IR | H3 生成视频;Context-IR 是异步增强提示词任务,返回文本而不是视频。再生成用于符合条件的 H3 源视频,不是任意视频转码。 |
| Veo | 用于镜头创作与图像引导视频。本站目录包含 veo2、veo3、veo3.1 及 fast/pro/frames 别名,不把这些别名自动等同于官方 API 模型 ID。 |
| Sora | 适合从文字或图像构建短视频。本站 sora-2、sora-2-pro 与旧画幅/时长别名是不同目录项,不能据名称推断相同能力。 |
| Runway | 目录含 runway-vip-video,但当前匿名目录没有可用端点定义。不能套用官方 Gen 系列请求或通用视频参数作为本站可执行示例。 |
| Vidu | Vidu 的已配置 Q3/Q4 型号各有独立参数与调用指南;本页仅保留其他尚未核实型号的接入核对项,不能据此推断支持状态。 |
| 即梦 / Jimeng | 即梦视频与即梦图片属于不同调用任务;当前公开目录未核实视频端点。不能将图片生成示例当作视频生成请求。 |
| Vidu Q4 Preview | Vidu Q4 Preview 支持图生视频、图片参考。以下覆盖官方创建参数、模式限制及本站字段映射;标注“未开放”的参数仅供了解官方能力,不加入本站可执行示例。 |
| Vidu Q3 Pro | Vidu Q3 Pro 支持文生视频、图生视频、首尾帧。以下覆盖官方创建参数、模式限制及本站字段映射;标注“未开放”的参数仅供了解官方能力,不加入本站可执行示例。 |
| Vidu Q3 Pro Fast | Vidu Q3 Pro Fast 支持图生视频、首尾帧。以下覆盖官方创建参数、模式限制及本站字段映射;标注“未开放”的参数仅供了解官方能力,不加入本站可执行示例。 |
| Vidu Q3 Turbo | Vidu Q3 Turbo 支持文生视频、图生视频、首尾帧、图片参考。以下覆盖官方创建参数、模式限制及本站字段映射;标注“未开放”的参数仅供了解官方能力,不加入本站可执行示例。 |
| Vidu Q3 | Vidu Q3 支持图片参考。以下覆盖官方创建参数、模式限制及本站字段映射;标注“未开放”的参数仅供了解官方能力,不加入本站可执行示例。 |
| Vidu Q3 Mix | Vidu Q3 Mix 支持图片参考。以下覆盖官方创建参数、模式限制及本站字段映射;标注“未开放”的参数仅供了解官方能力,不加入本站可执行示例。 |
| Vidu Q3 Drama | Vidu Q3 Drama 支持图片参考。以下覆盖官方创建参数、模式限制及本站字段映射;标注“未开放”的参数仅供了解官方能力,不加入本站可执行示例。 |
| Vidu Q3 Ad | Vidu Q3 Ad 支持图片参考。以下覆盖官方创建参数、模式限制及本站字段映射;标注“未开放”的参数仅供了解官方能力,不加入本站可执行示例。 |
URL、Base64 与本地文件不是同一种格式
原始 Base64 只有编码内容;data URI 在其前面增加 MIME 前缀,例如 data:image/png;base64,...。Gemini Omni 的视频用原始 Base64 data,不能传公网视频 URL 或 data:video/mp4;base64,...;其他系列是否接受 URL 或 data URI,逐项查看各系列“参考素材格式”表。Base64 会使体积增加约三分之一,不是压缩。只有明确支持 multipart 的接口才能直接上传本地文件;JSON 中写电脑路径不会上传文件。
媒体扩展名、MIME 和真实文件内容应一致。URL 必须直接返回媒体,不能是网盘预览页或需要 Cookie/额外请求头的页面;签名 URL 的有效期须覆盖任务处理。仅调用端能下载不代表生成服务可读。素材 ID、任务 ID 和音色 ID 各有对应字段,不能互换。
字段不是跨模型通用参数
Wan:prompt + reference_videos/reference_audio;Kling:contents + settings;Seedance:content + role;HappyHorse:prompt/image/images + parameters;Gemini Omni:prompt 或 input;MiniMax:原生 content。同为参考音频,Wan/Seedance 是媒体输入,Kling 必须先创建音色再传 voice_id。HappyHorse r2v 参考的是图片。
准备最小请求
在对应系列页复制一个无前置任务的 JSON 为 request.json,替换 model 和素材 URL。下面脚本仅用于 POST /v1/videos,不能直接用于 MiniMax /v2 或音色创建。先配置 TUZI_BASE_URL 为你实际调用的本站域名(不带 /v1),TUZI_API_KEY 为有权限的 API Key。保持 Key 在服务端环境变量中,不放入公开网页。
export TUZI_BASE_URL="https://api.tu-zi.com"
# Set TUZI_API_KEY securely in your environment.
python video.py
# Or: node video.mjs
提交、轮询与下载
保存提交返回的 id 或 task_id。统一视频查询使用 GET /v1/videos/{task_id},等待 queued / in_progress 到 completed 或 failed;完成后读取 video_url(部分响应同时在 metadata.url 提供)。本站相对路径需与调用域名拼接,/content 入口使用本站 Key;外部下载 URL 不携带本站 Key。结果可能过期,请及时下载。网络超时保留任务 ID 继续 GET,不自动重试创建 POST。
示例最多轮询 30 分钟,间隔从 2 秒增长到 10 秒,单次请求设超时。下载上限示例设为 256 MiB,先写 .part,再在完整成功后保存 output.mp4。达到截止时间不等于任务取消,保留 ID 可稍后继续查询。生成提交无自动重试。
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");
终态、费用与排错
最小请求受理后仍要确认 completed 和可下载结果。失败记录至少保留模型、请求域名、本站任务 ID、发生时间和脱敏错误;不要提交 API Key 或包含签名密钥的完整 URL。资料只描述已核对的请求合同;计费、权限和媒体审核以本站当次响应为准,不能把失败自动等同于不收费。
适用场景
- 选择视频模型和素材协议
- 排查参数与任务失败
API 协议
/v1/videos/v2/video_generation/v1/general/custom-voices/v1/general/advanced-custom-elements
常见问题
拿到 task_id 就代表生成成功吗?
不代表。保存本站任务 ID,查询到成功终态并确认结果可读取后才算完成;failed 要查看错误,不要自动重建任务。
本地图片、视频和 WAV 能直接填写路径吗?
不能。URL 字段需要服务可读取的媒体地址;localhost、电脑路径及需要浏览器登录的链接不可用。Kling 本地 PCM WAV 的 multipart 音色上传需本站先启用该接口(2026-11-15 两站实测均为 404);其他素材按该系列上传或素材流程处理。
能把不同模型的参数和任务 ID 互换吗?
不能假定兼容。核对精确型号、入口、大小写、媒体角色及互斥字段。编辑、草稿和音色都要求对应类型、本人可访问的成功任务;官方能力也不等于本站已验收。
兔子API