Skip to main content

MiniMax H3 Integration

MiniMax H3 provides native asynchronous APIs for H3/H3-Max video generation, H3 2K upgrades, and Context-IR prompt generation. Submit with a platform API key, save the returned task_id, and query the result.

Capabilities and model names​

CapabilityMethod and pathRequest modelResolution / durationRequired token model permission
H3 video generationPOST /v2/video_generationMiniMax-H3Required: 768P or 2K; 4–15 secondsMiniMax-H3
H3-Max video generationPOST /v2/video_generationMiniMax-H3-Max480P or 768P; defaults to 768P; 5–15 secondsMiniMax-H3-Max
H3 2K upgradePOST /v2/video_regenerationMiniMax-H3Required: 2KMiniMax-H3-Regeneration
Context-IR prompt generationPOST /v2/h3_context_irMiniMax-H3Omit resolution; 4–15 secondsMiniMax-H3-Context-IR
Query any task aboveGET /v2/query/video_generation/{task_id}No bodyTask status and resultAPI key belonging to the task owner

The permission model names for upgrades and Context-IR differ from the request model. Do not put MiniMax-H3-Regeneration or MiniMax-H3-Context-IR in the request body. Availability and pricing depend on the current console configuration, token group, and permissions.

Authentication and base URL​

  • Send Authorization: Bearer {apiKey} using a platform sk- model API key, rather than a management access token or an upstream MiniMax key.
  • {baseUrl} is the platform API root without a trailing / or /v1. The full URL is {baseUrl}/v2/....
  • Put JSON fields directly at the top level without a body wrapper. Use the /v2 paths and native fields documented here.

Minimal example​

curl -X POST "{baseUrl}/v2/video_generation" \
  -H "Authorization: Bearer {apiKey}" \
  -H "Content-Type: application/json" \
  -d '{"model":"MiniMax-H3","resolution":"768P","duration":4,"ratio":"16:9","content":[{"type":"text","text":"A kitten stretches in the sunshine as the camera slowly moves closer"}]}'
{"task_id":"task_platform_example"}

Save the actual platform task ID from the response. A suggested polling interval is 5–10 seconds:

curl "{baseUrl}/v2/query/video_generation/{task_id}" \
  -H "Authorization: Bearer {apiKey}"
Submit generation / regeneration / h3_context_ir
                       ↓
              Save platform task_id
                       ↓
             queued → running → terminal status
                                 ├─ succeeded: video → task.content.url
                                 │             IR → task.content.prompt
                                 └─ failed / cancelled: inspect task.error

HTTP 200 with a task_id means that a platform task exists. It does not guarantee upstream acceptance or successful generation. Use the output only after task.status=succeeded.

Media input rules​

TypeStructureroleLimits
Text{"type":"text","text":"Prompt"}Not neededContent-based input requires at least one non-empty text item
Imageimage_url: {"url":"https://..."}first_frame, last_frame, or reference_image; omitted role is treated as first frameAt most one first frame, one last frame, and 9 reference images
Videovideo_url: {"url":"https://..."}reference_video; upgrades also allow base_videoAt most 3 reference videos; upgrades require exactly one base_video
Audioaudio_url: {"url":"https://..."}reference_audioAt most 3
  • First/last frames cannot be mixed with any reference_* media.
  • Each text item allows up to 7,000 characters for generation/Context-IR and 40,000 for upgrades.
  • Text-only generation and Context-IR must specify a concrete ratio; it cannot be omitted or adaptive when there are no frame/reference inputs.
  • Allowed ratio values: 21:9, 16:9, 4:3, 1:1, 3:4, 9:16, and adaptive.
  • Use upstream-accessible HTTP(S) media URLs. asset:// is unsupported. Dimensions, codecs, duration, and actual model capabilities remain subject to upstream requirements.
  • Data URIs require platform Base64-to-OSS support and are uploaded before submission. Supported formats: JPEG/PNG/WebP/HEIC/HEIF images, MP4/MOV videos, and WAV/MP3 audio. Decoded per-file limits are 30 MiB for images, 50 MiB for videos, and 15 MiB for audio; total request body limit is 64 MiB. MIME, format, and file contents must match.

Ambiguous submissions and billing​

Creation does not provide a client idempotency key. If a request may have been sent but upstream acceptance is uncertain, the platform may still return a task_id. Save it and query instead of submitting again. If the client times out without an ID, check console task logs or contact support before retrying to avoid duplicate tasks and charges.

The platform precharges and settles using the pricing configuration frozen for the task and actual usage obtained through authenticated queries. Video billing can involve output duration, input video duration, and image count; Context-IR uses input/output tokens. Refer to the final settlement in the console. Once a task fails at the platform timeout and is fully refunded, a late upstream success does not revive or recharge it.

API pages​