API protocol
MiniMax-H3 / Context-IR: parameters, scenarios and API guide
Preview guide
Paste into an AI assistant to help with integration. Documentation and examples only; no real credentials.
Direct answerNative generation uses POST /v2/video_generation and content, not top-level prompt. Poll GET /v2/query/video_generation/{task_id}.
Updated · Reviewed
Purpose and workflows
H3 generates videos; Context-IR asynchronously improves prompts and returns text. Regeneration requires an eligible H3 source and is not generic transcoding.
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.
Models and endpoints
MiniMax-H3, MiniMax-H3-Context-IR
POST /v2/video_generation · POST /v2/h3_context_ir · POST /v2/video_regeneration
Reference media formats
| Media | Fields | Encoding and transport | Preparation and limits |
|---|---|---|---|
| Images / frames | content[].image_url.url + role | Site examples use HTTP(S) image URLs; raw Base64/data URIs are not claimed as supported without verification. | Prefer PNG/JPEG. role is first_frame, last_frame or reference_image; frame and reference modes are exclusive. |
| Reference / edit video | content[].video_url.url + role=reference_video | Use HTTP(S) video URLs. Accepting a non-empty string is not proof of Base64 support. | Prefer MP4 (H.264). Context-IR returns an enhanced prompt, not a finished video. |
| Reference audio | content[].audio_url.url + role=reference_audio | Use HTTP(S) audio URLs, not a Kling voice_id. Base64 and direct local upload are unverified. | Prefer WAV/MP3. Upload local media to a reachable URL first; follow family-specific counts and combination rules. |
Parameters and combinations
- Native generation uses POST /v2/video_generation and content, not top-level prompt. Poll GET /v2/query/video_generation/{task_id}.
- Context-IR uses POST /v2/h3_context_ir with wire model MiniMax-H3. Only model/content/duration/ratio/callback_url are allowed, not resolution, task_type or watermark.
- Context-IR duration is 4–15 whole seconds and text-only input requires ratio. Read task.content.prompt on success.
- Regenerate with POST /v2/video_regeneration and explicit resolution=2K. Choose source_task_id or one base_video. source_task_id must be an accessible site ID.
- Successful video results use task.content.url; Context-IR uses task.content.prompt. Do not require a video URL for both.
- Official media also supports mm_file:// references and image/video/audio data URIs. No MiniMax file-upload mapping is published here; do not reuse another account’s mm_file ID or another family’s asset:// ID. Prefer the media formats verified in this guide.
| Field | Type | Use and constraints |
|---|---|---|
Authorization | header string | Required: Bearer <site API key>, with Content-Type: application/json. |
model | string | Use MiniMax-H3 for generation, Context-IR and regeneration. MiniMax-H3-Context-IR is a site catalog/billing name; use /v2/h3_context_ir for that operation. |
content | object[] | Required for generation and Context-IR, with one non-empty text item. Frames and references are mutually exclusive. |
content[].type | string | text/image_url/video_url/audio_url; media-based regeneration uses video_url with role=base_video. |
content[].text | string | Required for text items. Text constraints differ by operation; enhanced text is not a video URL. Official generation/Context-IR limit: 7000 characters per item; regeneration: 40000, using the final prompt that generated the source. |
content[].role | string | Images: first_frame/last_frame/reference_image; video: reference_video; audio: reference_audio. Use base_video only under regeneration rules. |
content[].image_url.url | string | Image URL; JPG/JPEG/PNG/WEBP/HEIC/HEIF, ≤30 MB, 256–5760px, ratio 0.4–2.5. At most one first/last frame each or nine references. |
content[].video_url.url | string | Reference MP4/MOV, ≤50 MB each; ≤3 clips of 2–15s, total ≤15s. Regeneration sources follow separate endpoint limits. |
content[].audio_url.url | string | Reference WAV/MP3, ≤15 MB each; ≤3 clips of 2–15s, total ≤15s. |
duration | integer | Generation/Context-IR: 4–15s; officially required, site compatibility defaults to 5. Regeneration does not specify an independent target duration. |
resolution | string | Ordinary H3 officially requires 768P/2K; site compatibility default 768P. Rejected for Context-IR; regeneration requires 2K. Do not reuse Highspeed/Lite/Max enums. |
ratio | string | 16:9/9:16/1:1/4:3/3:4/21:9/adaptive. Text requires a concrete ratio (site default 16:9); references default adaptive, frames follow the image. Omit for regeneration. |
callback_url | string | Optional. Official provider sends a challenge requiring an unchanged response within 3s, then status updates. Keep site polling. |
source_task_id | string | Regeneration only, exclusive with base_video mode. Use an accessible successful site task ID; source requires provider eligibility/whitelisting and the official seven-day query window. |
aigc_watermark | boolean | Official regeneration option, default false. Site ordinary generation may forward it, but the current official creation table omits it. Rejected for Context-IR. |
use_context_ir | boolean | Site H3 compatibility extension, absent from the current official creation table; not promised across routes. Do not use for the Context-IR operation itself. |
extra.prompt_expansion_mode | string | Currently official MiniMax-H3-Max only, default balanced; not applicable to MiniMax-H3 here and not exposed by this site request. |
response_format | string | Ordinary H3 generation accepts task (default)/flat for the upstream response shape. Both task-ID shapes are handled; site task IDs and unified polling responses remain in use. Rejected for Context-IR and regeneration. |
Scenarios and code examples
H3 native text to video
Applies to: 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 first-frame animation
Applies to: 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));
Enhance a prompt
Applies to: 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));
Regenerate a completed task
Applies to: MiniMax-H3
POST /v2/video_regeneration
Requires an eligible completed H3 source plus access and pricing for this operation.
{
"model": "MiniMax-H3",
"source_task_id": "task_REPLACE_WITH_ELIGIBLE_VIDEO",
"resolution": "2K",
"aigc_watermark": false
}
Task results and downloads
Do not apply the unified video response shape to native endpoints. When GET /v2/query/video_generation/{task_id} returns task.status=succeeded, read task.content.url for video or task.content.prompt for Context-IR. Use the enhanced prompt as text content in a new generation request. Poll queued/running; inspect task.error on failed, and stop on unknown status. Keep task IDs and use a polling deadline without resubmitting creation. Regeneration needs an eligible H3 video, not a Context-IR text task.
Complete unified video Python / JavaScript polling and download examples
Troubleshooting
| Symptom | Check |
|---|---|
| Image validation / URI error | Ensure a video or task ID was not placed in an image field; check the URL returns media |
| Unsupported content type / field | Check the exact family and content/contents/input schema; voice_id cannot be an audio URL |
| 400 conflicting fields | Check prompt/input, frames/references, and seconds/response_format exclusivity |
| HTTP success but task failed | Retain the site task ID, time, model, domain and redacted request; submission 200 is not output success |
| 404 or inaccessible task | Check domain, key access and task type; do not use IDs from another site or the official API |
| Local file cannot be fetched | Use a supported upload flow or a reachable HTTPS media URL |
Sources and scope
Use cases
- Choose video models and media formats
- Diagnose request and task failures
API protocols
/v2/video_generation/v2/h3_context_ir/v2/video_regeneration
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
- H3 generation Official
- H3 Context-IR Official
- H3 regeneration Official
兔子API