MiniMax H3 Context-IR: What It Returns and What It Costs

MiniMax H3 Context-IR is a hosted, asynchronous prompt compiler for MiniMax H3. It returns an expanded, structured prompt; it does not return a video. You send a short brief plus any images, video, or audio that will condition the shot, wait for the task to finish, then read the string in task.content.prompt.

That string is the useful artifact. It can give H3-Base a more explicit visual plan, soundscape, and music direction in a format the model expects. If all you need is a straightforward browser generation, Context-IR is infrastructure you can skip. If you are assembling the official local H3-Base and 2K regeneration workflow, losing its output means losing part of the generation manifest.

Context-IR sits before the video model

MiniMax describes the complete H3 system as three stages:

1. H3-Context-IR interprets the free-form brief and its media relationships.
2. H3-Base turns the resulting context into 768P video and audio.
3. H3-Regenerate-2K can run a second model pass using the 768P result and the original context.

Only H3-Base is included in the open-weight release. The official H3 model card says Context-IR depends on multiple hosted models and services, so its implementation is not part of those downloadable weights. The API gives local-pipeline builders access to the official preprocessing stage; it does not make that stage local or open source.

This is also different from the Balanced and Quality options in our H3 Max prompt-expansion guide. Those are settings on fal's hosted H3 Max Turbo generation route. The Context-IR endpoint belongs to MiniMax-H3, exposes its own async task, returns the prompt for inspection, and is billed separately by tokens.

One prompt needs two API stages, not one video

The create call is deliberately small. It returns a task ID:

curl --request POST \
  --url https://api.minimax.io/v2/h3_context_ir \
  --header "Authorization: Bearer $MINIMAX_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "MiniMax-H3",
    "content": [
      {
        "type": "text",
        "text": "A brass desk fan starts by itself in an empty repair shop. One slow push in. Its loose grille rattles twice; no dialogue or music."
      }
    ],
    "duration": 5,
    "ratio": "16:9"
  }'

The immediate response is shaped like this:

{ "task_id": "TASK_ID" }

Poll the ordinary H3 query endpoint with that ID, or receive status changes through a verified callback:

curl --request GET \
  --url https://api.minimax.io/v2/query/video_generation/TASK_ID \
  --header "Authorization: Bearer $MINIMAX_API_KEY"

A successful task is identified by task_type: "h3_context_ir"; the result you keep is task.content.prompt:

{
  "task": {
    "status": "succeeded",
    "task_type": "h3_context_ir",
    "content": {
      "prompt": "integrated_multimodal_description: ...\noverall_soundscape: ...\nnon_diegetic_music: N/A."
    },
    "usage": {
      "prompt_tokens": 5664,
      "completion_tokens": 3426,
      "total_tokens": 9090
    }
  }
}

The token counts above come from MiniMax's current documentation example, not from the fan prompt and not from a generation we ran. The H3 Regenerate 2K guide explains why the final post-Context-IR prompt matters again if you later regenerate from a saved base video.

The role labels decide which workflow you are asking for

Every request needs at least one non-empty text item. Media is optional, but its role is not decorative.

Do not combine a first or last frame with reference roles in the same request. They are different conditioning modes, and the API rejects the mixture. Decide whether an image defines the beginning or end of the shot, or merely supplies identity, style, or another reference.

The current Context-IR API contract also sets limits worth enforcing before submission:

• duration is an integer from 4 through 15 seconds;
• the complete request body is at most 64 MB;
• reference images are limited to nine;
• reference video is limited to three clips, each 2–15 seconds and no more than 15 seconds combined;
• reference audio is limited to three clips, each 2–15 seconds and no more than 15 seconds combined;
• public URLs are the practical choice for larger media instead of Base64 inside JSON.

Validate the media formats, dimensions, frame rate, and file sizes against the live schema too. Those details can change independently of your form, so keep provider validation errors visible in job logs rather than reducing every failure to “prompt rejected.”

The official example costs about 1.74 cents

MiniMax currently lists Context-IR at $0.90 per million input tokens and $3.60 per million output tokens. Applying those rates to the official response example gives:

input:  5,664 × $0.90 / 1,000,000 = $0.0050976
output: 3,426 × $3.60 / 1,000,000 = $0.0123336
total:                                  $0.0174312

That is the cost of one documented example, not a typical-price promise. A richer media request or longer structured response can consume a different number of tokens. Use the returned usage object for settlement and MiniMax's live pricing table for estimates.

The video is a separate bill. Context-IR's token charge does not include an H3-Base generation or a later 2K regeneration. Treat the stages as separate line items so a failed video request does not disappear inside a single guessed cost.

Keep the compiler output editable

Context-IR can turn a loose idea into three useful sections: integrated_multimodal_description, overall_soundscape, and non_diegetic_music. That structure makes omissions visible. A silent product shot should say that music is absent. A dialogue shot should make the speaker, wording, timing, and room sound legible before you spend the larger video-generation cost.

It can also add details where the brief is underspecified. Read the returned prompt before treating it as an approved production instruction. If the compiler invents a camera cut, wardrobe detail, melody, or sound event that conflicts with the job, revise the source brief or the final prompt according to your pipeline. “Preserves intent as much as possible” is not the same as “cannot introduce a creative choice.”

This is why the endpoint is more useful as an inspectable compiler than as a hidden checkbox. Save both the user's request and the compiled prompt. When a result misses the brief, you can tell whether the mismatch entered during context interpretation or video generation.

Four failures that deserve four different fixes

400: the content array has no real prompt

A media item cannot stand alone. Include a non-empty text item that says what the output should do and what each reference controls.

A frame request behaves like the wrong mode

Check every role. first_frame and last_frame cannot coexist with reference_image, reference_video, or reference_audio. For text-only jobs, choose one of the six concrete ratios instead of adaptive.

The callback never becomes active

MiniMax first sends a verification request containing challenge. Your endpoint must return that value unchanged within three seconds. A generic 200 OK body is not enough. Keep polling available until callback verification and delivery are observable.

429: the API says to retry later

Do not translate a rate limit into five simultaneous create calls. Back off with jitter and cap the retry schedule. Persist the task ID as soon as a create call succeeds. If a create response is lost or ambiguous, inspect recent tasks through MiniMax's List Tasks endpoint and reconcile their task type and creation time before submitting another billable task; the create documentation does not promise an idempotency key.

The same discipline applies to video jobs. The MiniMax H3 API comparison has a fuller queue lifecycle for reservations, callbacks, and provider IDs.

What to save after a successful task

Keep one manifest containing the original brief, ordered media URLs or immutable file IDs, every role, duration, ratio, Context-IR task ID, returned prompt, usage, and provider timestamp. If you run H3-Base locally, add the checkpoint identifier and unedited output file. If you regenerate to 2K, add that task and its final usage instead of overwriting the 768P record.

That record is not busywork. It is the difference between “we generated something last week” and a pipeline that can explain what the model received, reproduce an eligible second pass, and charge the right account when a browser closes halfway through the job.