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-IRH3 生成视频;Context-IR 是异步增强提示词任务,返回文本而不是视频。再生成用于符合条件的 H3 源视频,不是任意视频转码。
Veo用于镜头创作与图像引导视频。本站目录包含 veo2、veo3、veo3.1 及 fast/pro/frames 别名,不把这些别名自动等同于官方 API 模型 ID。
Sora适合从文字或图像构建短视频。本站 sora-2、sora-2-pro 与旧画幅/时长别名是不同目录项,不能据名称推断相同能力。
Runway目录含 runway-vip-video,但当前匿名目录没有可用端点定义。不能套用官方 Gen 系列请求或通用视频参数作为本站可执行示例。
ViduVidu 的已配置 Q3/Q4 型号各有独立参数与调用指南;本页仅保留其他尚未核实型号的接入核对项,不能据此推断支持状态。
即梦 / Jimeng即梦视频与即梦图片属于不同调用任务;当前公开目录未核实视频端点。不能将图片生成示例当作视频生成请求。
Vidu Q4 PreviewVidu Q4 Preview 支持图生视频、图片参考。以下覆盖官方创建参数、模式限制及本站字段映射;标注“未开放”的参数仅供了解官方能力,不加入本站可执行示例。
Vidu Q3 ProVidu Q3 Pro 支持文生视频、图生视频、首尾帧。以下覆盖官方创建参数、模式限制及本站字段映射;标注“未开放”的参数仅供了解官方能力,不加入本站可执行示例。
Vidu Q3 Pro FastVidu Q3 Pro Fast 支持图生视频、首尾帧。以下覆盖官方创建参数、模式限制及本站字段映射;标注“未开放”的参数仅供了解官方能力,不加入本站可执行示例。
Vidu Q3 TurboVidu Q3 Turbo 支持文生视频、图生视频、首尾帧、图片参考。以下覆盖官方创建参数、模式限制及本站字段映射;标注“未开放”的参数仅供了解官方能力,不加入本站可执行示例。
Vidu Q3Vidu Q3 支持图片参考。以下覆盖官方创建参数、模式限制及本站字段映射;标注“未开放”的参数仅供了解官方能力,不加入本站可执行示例。
Vidu Q3 MixVidu Q3 Mix 支持图片参考。以下覆盖官方创建参数、模式限制及本站字段映射;标注“未开放”的参数仅供了解官方能力,不加入本站可执行示例。
Vidu Q3 DramaVidu Q3 Drama 支持图片参考。以下覆盖官方创建参数、模式限制及本站字段映射;标注“未开放”的参数仅供了解官方能力,不加入本站可执行示例。
Vidu Q3 AdVidu 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。资料只描述已核对的请求合同;计费、权限和媒体审核以本站当次响应为准,不能把失败自动等同于不收费。

视频协议与 MiniMax 原生任务详解

模型场景支持边界

适用场景

  • 选择视频模型和素材协议
  • 排查参数与任务失败

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 互换吗?

不能假定兼容。核对精确型号、入口、大小写、媒体角色及互斥字段。编辑、草稿和音色都要求对应类型、本人可访问的成功任务;官方能力也不等于本站已验收。

官方来源

  1. Tuzi API reference 官方