API 协议

MiniMax-H3 / Context-IR:参数、场景与调用指南

预览指南

粘贴给 AI,帮助理解文档并完成接入。 仅包含文档与示例,不包含真实密钥。

预览指南

MiniMax-H3 / Context-IR:参数、场景与调用指南

直接答案原生生成用 POST /v2/video_generation、content 数组;不接受顶层 prompt。查询 GET /v2/query/video_generation/{task_id}。

更新 · 审核信息

模型定位与适用场景

H3 生成视频;Context-IR 是异步增强提示词任务,返回文本而不是视频。再生成用于符合条件的 H3 源视频,不是任意视频转码。

本指南核对本站请求契约,不代表所有场景均已完成收费出片验收。使用模型广场显示的精确模型、分组和有效端点;示例中的 example.com 素材与占位任务 ID 必须替换。先以最小请求确认可用,再逐项添加参考素材和高级参数。价格以模型广场及实际账单为准。

型号与入口

MiniMax-H3, MiniMax-H3-Context-IR

POST /v2/video_generation · POST /v2/h3_context_ir · POST /v2/video_regeneration

参考素材格式

素材字段传输格式文件准备与限制
图片 / 首尾帧content[].image_url.url + role本站示例使用 HTTP(S) 图片直链;未核实的裸 Base64/data URI 不作为可用承诺。推荐 PNG/JPEG。role 为 first_frame、last_frame 或 reference_image;首尾帧与多参考模式互斥。
参考 / 编辑视频content[].video_url.url + role=reference_video使用 HTTP(S) 视频直链;不把接收非空字符串当作 Base64 支持证明。推荐 MP4(H.264);Context-IR 只返回增强提示词,不直接返回成片。
参考音频content[].audio_url.url + role=reference_audio使用 HTTP(S) 音频直链;不是 Kling voice_id。Base64 与本地文件直传未验收。推荐 WAV/MP3;本地素材先上传到可读地址。具体数量和组合遵循此系列约束。

参数与组合限制

  • 原生生成用 POST /v2/video_generation、content 数组;不接受顶层 prompt。查询 GET /v2/query/video_generation/{task_id}。
  • Context-IR 用 POST /v2/h3_context_ir,wire model 为 MiniMax-H3;只允许 model/content/duration/ratio/callback_url,不能传 resolution、task_type 或 watermark。
  • Context-IR 的 duration 为 4–15 整数秒,纯文字必须显式 ratio;成功后读取 task.content.prompt。
  • 再生成用 POST /v2/video_regeneration,显式 resolution=2K,source_task_id 与一个 base_video 二选一。source_task_id 必须是本人可访问的本站任务 ID。
  • 视频生成成功结果为 task.content.url;Context-IR 成功结果为 task.content.prompt。两者不要共用强制读取视频 URL 的解析器。
  • 官方媒体还支持 mm_file:// 文件引用及图片/视频/音频 data URI。本站尚无已发布的 MiniMax 文件上传映射;不要把其他账号的 mm_file ID 或其他系列的 asset:// ID 直接放入。优先使用本文已核对的素材格式。
字段类型用法与限制
Authorizationheader string必填。Bearer <本站 API Key>;JSON 请求使用 Content-Type: application/json。
modelstring原生生成、Context-IR、再生成请求均使用 MiniMax-H3;MiniMax-H3-Context-IR 是本站计费/目录名称,操作入口为 /v2/h3_context_ir。
contentobject[]生成及 Context-IR 必填,必须含一个非空 text 项。首尾帧与参考素材不能混用。
content[].typestringtext/image_url/video_url/audio_url;再生成素材模式用 video_url+role=base_video。
content[].textstringtext 项必填。生成、Context-IR、再生成的文本约束不同,不把增强返回内容当成视频 URL。 官方生成及 Context-IR 每项 ≤7000 字符;再生成 ≤40000 字符且须用源视频生成时最终提示词。
content[].rolestring图片:first_frame/last_frame/reference_image;视频 reference_video;音频 reference_audio。再生成 base_video 必须单独按再生成端点要求使用。
content[].image_url.urlstring图片地址,支持的图片格式 JPG/JPEG/PNG/WEBP/HEIC/HEIF;≤30 MB,宽高 256–5760 px、比例 0.4–2.5。首尾帧各 ≤1,参考图 ≤9。
content[].video_url.urlstring参考视频 MP4/MOV,单段 ≤50 MB;最多 3 段、单段 2–15 秒且总长 ≤15 秒;再生成源视频另受该端点限制。
content[].audio_url.urlstring参考音频 WAV/MP3,单段 ≤15 MB;最多 3 段、单段 2–15 秒且合计 ≤15 秒。
durationinteger生成和 Context-IR:4–15 秒;官方必填,本站兼容路径省略时补 5。再生成不独立指定目标时长。
resolutionstring普通 H3 官方必填 768P/2K;本站兼容默认 768P。Context-IR 不接受;再生成必填 2K。不要套用 Highspeed/Lite/Max 枚举。
ratiostring16:9/9:16/1:1/4:3/3:4/21:9/adaptive;文生必须具体比例,本站默认 16:9;参考默认 adaptive,图生跟随图片。再生成不传。
callback_urlstring可选;官方先发送 challenge 验证,须 3 秒内原样响应;之后推送任务状态。保留本站查询流程。
source_task_idstring仅再生成;与 base_video 素材模式互斥。本站成功任务 ID,源需本人可访问、符合白名单且仍在官方 7 天查询有效期内。
aigc_watermarkboolean官方再生成可选,默认 false;本站普通生成兼容路径也可转发,但当前官方普通生成参数表未列该项。Context-IR 不接受。
use_context_irboolean本站 H3 兼容扩展;当前官方普通生成参数表未列出,不宣称所有渠道支持;不要用于 Context-IR 操作自身。
extra.prompt_expansion_modestring当前官方仅 MiniMax-H3-Max 支持,默认 balanced;不适用于本页 MiniMax-H3,本站请求亦未开放。
response_formatstring普通 H3 生成支持 task(默认)/flat,指定上游响应结构;本站兼容两种任务 ID 返回格式,并继续使用本站任务 ID 和统一查询响应。Context-IR、再生成不接受此字段。

场景与代码示例

H3 原生文生视频

适用型号:MiniMax-H3

POST /v2/video_generation

{
  "model": "MiniMax-H3",
  "content": [
    {
      "type": "text",
      "text": "纸雕白兔穿过晨雾森林。"
    }
  ],
  "duration": 5,
  "resolution": "768P",
  "ratio": "16:9"
}

curl

curl --fail-with-body --silent --show-error --connect-timeout 10 --max-time 120 --request POST 'https://api.tu-zi.com/v2/video_generation' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "MiniMax-H3",
  "content": [
    {
      "type": "text",
      "text": "纸雕白兔穿过晨雾森林。"
    }
  ],
  "duration": 5,
  "resolution": "768P",
  "ratio": "16:9"
}'

python

import json
import os
import requests

url = "https://api.tu-zi.com/v2/video_generation"
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\":\"MiniMax-H3\",\"content\":[{\"type\":\"text\",\"text\":\"纸雕白兔穿过晨雾森林。\"}],\"duration\":5,\"resolution\":\"768P\",\"ratio\":\"16:9\"}")
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/v2/video_generation";
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": "MiniMax-H3",
  "content": [
    {
      "type": "text",
      "text": "纸雕白兔穿过晨雾森林。"
    }
  ],
  "duration": 5,
  "resolution": "768P",
  "ratio": "16:9"
}), 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));

H3 首帧动画

适用型号:MiniMax-H3

POST /v2/video_generation

{
  "model": "MiniMax-H3",
  "content": [
    {
      "type": "text",
      "text": "人物走过花园,镜头缓慢推进。"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/subject.png"
      },
      "role": "first_frame"
    }
  ],
  "duration": 5,
  "resolution": "768P"
}

curl

curl --fail-with-body --silent --show-error --connect-timeout 10 --max-time 120 --request POST 'https://api.tu-zi.com/v2/video_generation' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "MiniMax-H3",
  "content": [
    {
      "type": "text",
      "text": "人物走过花园,镜头缓慢推进。"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/subject.png"
      },
      "role": "first_frame"
    }
  ],
  "duration": 5,
  "resolution": "768P"
}'

python

import json
import os
import requests

url = "https://api.tu-zi.com/v2/video_generation"
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\":\"MiniMax-H3\",\"content\":[{\"type\":\"text\",\"text\":\"人物走过花园,镜头缓慢推进。\"},{\"type\":\"image_url\",\"image_url\":{\"url\":\"https://example.com/subject.png\"},\"role\":\"first_frame\"}],\"duration\":5,\"resolution\":\"768P\"}")
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/v2/video_generation";
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": "MiniMax-H3",
  "content": [
    {
      "type": "text",
      "text": "人物走过花园,镜头缓慢推进。"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/subject.png"
      },
      "role": "first_frame"
    }
  ],
  "duration": 5,
  "resolution": "768P"
}), 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));

增强提示词

适用型号:MiniMax-H3, MiniMax-H3-Context-IR

POST /v2/h3_context_ir

{
  "model": "MiniMax-H3",
  "content": [
    {
      "type": "text",
      "text": "将白兔在森林旅行的创意扩展为镜头描述。"
    }
  ],
  "duration": 5,
  "ratio": "16:9"
}

curl

curl --fail-with-body --silent --show-error --connect-timeout 10 --max-time 120 --request POST 'https://api.tu-zi.com/v2/h3_context_ir' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "MiniMax-H3",
  "content": [
    {
      "type": "text",
      "text": "将白兔在森林旅行的创意扩展为镜头描述。"
    }
  ],
  "duration": 5,
  "ratio": "16:9"
}'

python

import json
import os
import requests

url = "https://api.tu-zi.com/v2/h3_context_ir"
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\":\"MiniMax-H3\",\"content\":[{\"type\":\"text\",\"text\":\"将白兔在森林旅行的创意扩展为镜头描述。\"}],\"duration\":5,\"ratio\":\"16:9\"}")
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/v2/h3_context_ir";
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": "MiniMax-H3",
  "content": [
    {
      "type": "text",
      "text": "将白兔在森林旅行的创意扩展为镜头描述。"
    }
  ],
  "duration": 5,
  "ratio": "16:9"
}), 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));

成功任务再生成

适用型号:MiniMax-H3

POST /v2/video_regeneration

仅限符合 H3 源视频要求的成功任务;需要该操作已配置价格和访问权限。

{
  "model": "MiniMax-H3",
  "source_task_id": "task_REPLACE_WITH_ELIGIBLE_VIDEO",
  "resolution": "2K",
  "aigc_watermark": false
}

任务结果与下载

原生端点不要套用统一视频查询结构。GET /v2/query/video_generation/{task_id} 的 task.status=succeeded 后,生成任务读取 task.content.url;Context-IR 读取 task.content.prompt,并将其作为新的 content 文本创建视频。queued/running 继续轮询,failed 查看 task.error;未知状态停止并检查响应。保留任务 ID,设置轮询截止时间;超时不重发创建。再生成需要符合条件的 H3 源任务,不能拿 Context-IR 的文本任务来生成 2K。

统一视频完整 Python / JavaScript 轮询下载示例

常见问题定位

现象检查方式
Error validating image / 图片 URI 错误视频或任务 ID 是否误填到了图片字段;检查媒体 URL 是否返回真实素材
unsupported content type / 字段不支持检查系列、版本和 content/contents/input 的准确类型;不要把音频 URL 填入 voice_id
400 参数冲突检查 prompt 与 input、首尾帧与多参考、秒数与 response_format 的互斥项
HTTP 成功但任务 failed记录本站任务 ID、时间、模型、域名和已脱敏参数;按任务错误定位,不能依据提交 200 宣称成功
404 或不可访问任务确认域名、Key 权限、本站任务类型;不要使用其他站点或官方任务 ID
本地文件无法访问使用系列明确支持的上传方式,或提供可读取的 HTTPS 媒体 URL

资料与适用范围

H3 generation

H3 Context-IR

H3 regeneration

适用场景

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

API 协议

  • /v2/video_generation
  • /v2/h3_context_ir
  • /v2/video_regeneration

常见问题

拿到 task_id 就代表生成成功吗?

不代表。保存本站任务 ID,查询到成功终态并确认结果可读取后才算完成;failed 要查看错误,不要自动重建任务。

本地图片、视频和 WAV 能直接填写路径吗?

不能。URL 字段需要服务可读取的媒体地址;localhost、电脑路径及需要浏览器登录的链接不可用。Kling 本地 PCM WAV 的 multipart 音色上传需本站先启用该接口(2026-11-15 两站实测均为 404);其他素材按该系列上传或素材流程处理。

能把不同模型的参数和任务 ID 互换吗?

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

官方来源

  1. H3 generation 官方
  2. H3 Context-IR 官方
  3. H3 regeneration 官方