API 协议
MiniMax-H3 / Context-IR:参数、场景与调用指南
预览指南
粘贴给 AI,帮助理解文档并完成接入。 仅包含文档与示例,不包含真实密钥。
直接答案原生生成用 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 直接放入。优先使用本文已核对的素材格式。
| 字段 | 类型 | 用法与限制 |
|---|---|---|
Authorization | header string | 必填。Bearer <本站 API Key>;JSON 请求使用 Content-Type: application/json。 |
model | string | 原生生成、Context-IR、再生成请求均使用 MiniMax-H3;MiniMax-H3-Context-IR 是本站计费/目录名称,操作入口为 /v2/h3_context_ir。 |
content | object[] | 生成及 Context-IR 必填,必须含一个非空 text 项。首尾帧与参考素材不能混用。 |
content[].type | string | text/image_url/video_url/audio_url;再生成素材模式用 video_url+role=base_video。 |
content[].text | string | text 项必填。生成、Context-IR、再生成的文本约束不同,不把增强返回内容当成视频 URL。 官方生成及 Context-IR 每项 ≤7000 字符;再生成 ≤40000 字符且须用源视频生成时最终提示词。 |
content[].role | string | 图片:first_frame/last_frame/reference_image;视频 reference_video;音频 reference_audio。再生成 base_video 必须单独按再生成端点要求使用。 |
content[].image_url.url | string | 图片地址,支持的图片格式 JPG/JPEG/PNG/WEBP/HEIC/HEIF;≤30 MB,宽高 256–5760 px、比例 0.4–2.5。首尾帧各 ≤1,参考图 ≤9。 |
content[].video_url.url | string | 参考视频 MP4/MOV,单段 ≤50 MB;最多 3 段、单段 2–15 秒且总长 ≤15 秒;再生成源视频另受该端点限制。 |
content[].audio_url.url | string | 参考音频 WAV/MP3,单段 ≤15 MB;最多 3 段、单段 2–15 秒且合计 ≤15 秒。 |
duration | integer | 生成和 Context-IR:4–15 秒;官方必填,本站兼容路径省略时补 5。再生成不独立指定目标时长。 |
resolution | string | 普通 H3 官方必填 768P/2K;本站兼容默认 768P。Context-IR 不接受;再生成必填 2K。不要套用 Highspeed/Lite/Max 枚举。 |
ratio | string | 16:9/9:16/1:1/4:3/3:4/21:9/adaptive;文生必须具体比例,本站默认 16:9;参考默认 adaptive,图生跟随图片。再生成不传。 |
callback_url | string | 可选;官方先发送 challenge 验证,须 3 秒内原样响应;之后推送任务状态。保留本站查询流程。 |
source_task_id | string | 仅再生成;与 base_video 素材模式互斥。本站成功任务 ID,源需本人可访问、符合白名单且仍在官方 7 天查询有效期内。 |
aigc_watermark | boolean | 官方再生成可选,默认 false;本站普通生成兼容路径也可转发,但当前官方普通生成参数表未列该项。Context-IR 不接受。 |
use_context_ir | boolean | 本站 H3 兼容扩展;当前官方普通生成参数表未列出,不宣称所有渠道支持;不要用于 Context-IR 操作自身。 |
extra.prompt_expansion_mode | string | 当前官方仅 MiniMax-H3-Max 支持,默认 balanced;不适用于本页 MiniMax-H3,本站请求亦未开放。 |
response_format | string | 普通 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 |
资料与适用范围
适用场景
- 选择视频模型和素材协议
- 排查参数与任务失败
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 互换吗?
不能假定兼容。核对精确型号、入口、大小写、媒体角色及互斥字段。编辑、草稿和音色都要求对应类型、本人可访问的成功任务;官方能力也不等于本站已验收。
兔子API