---
title: "Create H3-Context-IR Task"
method: POST
path: "/v2/h3_context_ir"
tags: ["Video V2"]
---

# Create H3-Context-IR Task

`POST /v2/h3_context_ir`

## Request

- Base URL: `https://api.minimax.io`
- URL: `https://api.minimax.io/v2/h3_context_ir`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/minimax/apis/minimax-api/docs/v2/h3_context_ir/post.ts> (a function with typed inputs; its response is checked against the schema)

H3-Context-IR deeply interprets multimodal context across text, images, audio, and video. It analyzes relationships among the inputs and between those inputs and the intended output, performs complex reasoning, and converts that understanding into a structured representation with richer semantic detail while preserving the user's original intent as much as possible. This endpoint only returns an enhanced prompt; it does not create a video generation task.

H3-Context-IR is a complex system and its implementation is not open sourced. This API can be used both to validate the official Full 2K-Workflow results and in production workflows.

## Headers

- `Content-Type` 'application/json', required

## Request body

- H3ContextIRReq: Request parameters for creating an H3-Context-IR task.
  - `model` 'MiniMax-H3', required: Model name. Currently available: `MiniMax-H3`.
  - `content` ContentItem[], required: Array of multimodal context describing the intended video and the relationships among the inputs. Each element is distinguished by `type` (`text` / `image_url` / `video_url` / `audio_url`) and can be labeled with a `role`. **Every request must include one non-empty `text` item (the prompt is required)**; otherwise a parameter error is returned. Supported input combinations (corresponding to different generation scenarios): - **Text-to-video**: a single `text` element only. - **Image-to-video, first frame**: `text` + 1 `image_url` (`role=first_frame`, or omitted). - **Image-to-video, last frame**: `text` + 1 `image_url` (`role=last_frame`). - **Image-to-video, first & last frame**: `text` + 2 `image_url` items with `role` set to `first_frame` and `last_frame` respectively. - **Reference-to-video**: `text` + any combination of reference images (`role=reference_image`), reference videos (`role=reference_video`), and reference audio (`role=reference_audio`). > **Image-to-video and reference-to-video are mutually exclusive**: if any `reference_image` / `reference_video` / `reference_audio` role appears in content, then `first_frame` / `last_frame` must not appear (and vice versa); the two cannot be mixed. --- **Input media limits** (total request body ≤ 64 MB; use public URLs for large files, avoid Base64) Image `image_url`: | Item | Limit | | :--- | :--- | | Format | JPG, JPEG, PNG, WEBP, HEIC, HEIF | | Single file size | ≤ 30 MB | | Width/height range | [256, 5760] px | | Aspect ratio (w/h) | [0.4, 2.5] | | Count | first frame ≤ 1, last frame ≤ 1, reference images ≤ 9 | Video `video_url` (reference scenario only): | Item | Limit | | :--- | :--- | | Container / format | MP4 (`.mp4`), MOV (`.mov`) | | Codec | Video H.264/AVC, H.265/HEVC; audio AAC, MP3 | | Single file size | ≤ 50 MB | | Count | ≤ 3 | | Per-clip duration | [2, 15] s; total ≤ 15 s | | Width/height range | [256, 5760] px | | Aspect ratio (w/h) | [0.4, 2.5] | | Frame rate | [23.976, 60] | Audio `audio_url` (reference scenario only): | Item | Limit | | :--- | :--- | | Format | WAV, MP3 | | Single file size | ≤ 15 MB | | Count | ≤ 3 | | Per-clip duration | [2, 15] s; total ≤ 15 s |
    - `type` 'text' | 'image_url' | 'video_url' | 'audio_url', required: Type of the input content.
    - `text` string: Text prompt, **required**: every scenario must include one non-empty `text` describing the desired video. Length is counted by characters, with a maximum of 7000 characters per `text`.
    - `image_url` object: Image object when `type=image_url` (see the content description above for format / size / dimension / count limits).
      - `url` string, required: Image location. Supported: a public URL; `mm_file://{file_id}` (reference an existing platform file, e.g. an uploaded file or a previous output's file_id); a `data:image/<format>;base64,<Base64>` data URI (`<format>` lowercase).
    - `video_url` object: Video object when `type=video_url` (reference video, reference scenario only; see the content description above for format / size / duration limits).
      - `url` string, required: Video location. Supported: a public URL; `mm_file://{file_id}` (reference an existing platform file's file_id); a `data:video/mp4;base64,<Base64>` data URI. Note the total request body must be ≤ 64 MB and Base64 inflates size by about 33%, so use a public URL or mm_file:// for large videos.
    - `audio_url` object: Audio object when `type=audio_url` (reference audio, reference scenario only; see the content description above for format / size / duration limits).
      - `url` string, required: Audio location. Supported: a public URL; `mm_file://{file_id}` (reference an existing platform file's file_id); a `data:audio/<format>;base64,<Base64>` data URI (`<format>` lowercase).
    - `role` 'first_frame' | 'last_frame' | 'reference_image' | 'reference_video' | 'reference_audio': Position or purpose of the content, conditionally required: - `first_frame`: first-frame image (image-to-video; when there is a single image and no role is set, it defaults to first_frame). - `last_frame`: last-frame image (image-to-video first & last frame, must be paired with first_frame). - `reference_image`: reference image (reference-to-video). - `reference_video`: reference video (reference-to-video). - `reference_audio`: reference audio (reference-to-video).
  - `duration` 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15, required: Target video duration in seconds. Required, integer. Available values: `4`-`15`.
  - `ratio` 'adaptive' | '21:9' | '16:9' | '4:3' | '1:1' | '3:4' | '9:16': Aspect ratio of the target video. Defaults to `adaptive`. Available values: `adaptive`, `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`. **Text-to-video (t2va, content contains only `text`)**: `ratio` is required and cannot be `adaptive`; available values `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`. **Image-to-video (i2va, content contains a `first_frame` / `last_frame` image)**: the aspect ratio is determined by the input image and `ratio` is always `adaptive`; passing another valid value does not error but is ignored and treated as `adaptive`. **Reference-to-video (r2va, content contains `reference_image` / `reference_video` / `reference_audio`)**: `ratio` is optional and defaults to `adaptive`; you may also explicitly specify any of the concrete ratios above.
  - `callback_url` string: Callback URL for task status changes. Once configured, the MiniMax server first sends a verification request containing a `challenge` field (you must return the `challenge` unchanged within 3 seconds to complete verification); after verification succeeds, it POSTs an update to this URL whenever the task status changes. The push body has the same structure as the response of the [Query Task](/api-reference/video-generation-v2-query) endpoint. Callback `status` values: `queued`, `running`, `succeeded`, `failed`, `cancelled`.

## Response `200`

The create endpoint returns a `task_id`. Use this `task_id` with the [Query Task](/api-reference/video-generation-v2-query) endpoint to retrieve the task status and result. When the task succeeds, retrieve the enhanced prompt from `content.prompt`.

**Successful Query Task response example**

```json
{
  "task": {
    "id": "426586401755526",
    "model": "MiniMax-H3",
    "status": "succeeded",
    "created_at": 1785702855,
    "updated_at": 1785702884,
    "content": {
      "prompt": "integrated_multimodal_description: [Shot 1] Cinematic, wide shot with a slow push in on a female captain standing center frame with her back to the camera. She has a slender build and short, swept-back silver hair, wearing a crisp, dark navy-blue futuristic military uniform adorned with rigid silver epaulets. Before her stretches a colossal, curved glass observation window dominating the dimly lit starship bridge. The interior features sleek metallic consoles on the left and right emitting soft cyan light. Outside the window, a massive fleet of dark-grey, heavily armored dreadnoughts and cruisers is assembling against a backdrop of a swirling deep-purple and magenta nebula. The rear thrusters of the distant ships glow intensely with fiery orange light. [Shot 2] At 00:02.800, the camera cuts to a medium close-up of the captain from Shot 1 in profile facing right, while the camera shakes strongly. Her facial features are now visible, revealing a woman in her late forties with sharp cheekbones and a stoic expression. A sudden, blinding flash of brilliant cyan and white light bursts through the window as the fleet outside simultaneously jumps into warp, casting harsh, overexposed illumination across her face. The bridge vibrates violently, causing her shoulders to tense and her uniform collar to tremble. The intense light instantly fades into deep shadow, leaving her completely alone against the newly emptied, pitch-black void of space.\noverall_soundscape: Deep, resonant low-frequency thrumming of ship engines, overlaid with rhythmic, high-pitched electronic beeps from the consoles, followed by a sudden, deafening sub-bass boom and a loud, sizzling crackle as the warp drives engage. The immense acoustic impact causes a heavy, metallic clattering of the bridge panels, which instantly drops off into a stark, quiet mechanical hum.\nnon_diegetic_music: Symphonic orchestral score, beginning with a slow, rising brass and string crescendo that abruptly cuts off, instantly transitioning into a single, sustained, low-register solo cello note with no dynamic swell."
    },
    "duration": 5,
    "usage": {
      "total_tokens": 9090,
      "prompt_tokens": 5664,
      "completion_tokens": 3426
    },
    "ratio": "16:9",
    "task_type": "h3_context_ir",
    "modality": "text"
  }
}
```

- VideoGenerationV2Resp
  - `task_id` string: ID of the task, used to query the task status and result later.

## Other responses

- `400`: Invalid parameters
- `401`: Authentication failed
- `402`: Insufficient balance/quota
- `422`: Input contains sensitive content
- `429`: Rate limit triggered
- `500`: Server error

---

[API](https://skmtc.dev/minimax/apis/minimax-api.md) - [All operations](https://skmtc.dev/minimax/apis/minimax-api/llms.txt) - [OpenAPI document](https://skmtc.dev/minimax/apis/minimax-api/revisions/81353c47e0e6?raw)