Create H3-Context-IR Task

curl --request POST \
  --url https://api.minimax.io/v2/h3_context_ir \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "model": "MiniMax-H3",
  "content": [
    {
      "type": "text",
      "text": "Epic space-opera theatrical teaser: a female captain stands alone before a massive observation window as the last fleet gathers and jumps away in a blinding flash, the bridge shaking, leaving her behind."
    }
  ],
  "duration": 5,
  "ratio": "16:9"
}
'

{
  "task_id": "424010985738629"
}

{
  "type": "error",
  "error": {
    "type": "bad_request_error",
    "message": "invalid params, content must include a non-empty text item (prompt is required) (2013)",
    "http_code": "400"
  },
  "request_id": "021785229015510a2c883cf675b9804d"
}

{
  "type": "error",
  "error": {
    "type": "authorized_error",
    "message": "login fail: Please carry the API secret key in the 'Authorization' field of the request header (1004)",
    "http_code": "401"
  },
  "request_id": "021785229015510a2c883cf675b9804d"
}

{
  "type": "error",
  "error": {
    "type": "insufficient_balance_error",
    "message": "insufficient balance (1008)",
    "http_code": "402"
  },
  "request_id": "021785229015510a2c883cf675b9804d"
}

{
  "type": "error",
  "error": {
    "type": "unprocessable_entity_error",
    "message": "video description contains sensitive content (1026)",
    "http_code": "422"
  },
  "request_id": "021785229015510a2c883cf675b9804d"
}

{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "message": "rate limit, please retry later (1002)",
    "http_code": "429"
  },
  "request_id": "021785229015510a2c883cf675b9804d"
}

{
  "type": "error",
  "error": {
    "type": "server_error",
    "message": "internal error (1000)",
    "http_code": "500"
  },
  "request_id": "021785229015510a2c883cf675b9804d"
}

POST

h3_context_ir

curl --request POST \
  --url https://api.minimax.io/v2/h3_context_ir \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "model": "MiniMax-H3",
  "content": [
    {
      "type": "text",
      "text": "Epic space-opera theatrical teaser: a female captain stands alone before a massive observation window as the last fleet gathers and jumps away in a blinding flash, the bridge shaking, leaving her behind."
    }
  ],
  "duration": 5,
  "ratio": "16:9"
}
'

{
  "task_id": "424010985738629"
}

{
  "type": "error",
  "error": {
    "type": "bad_request_error",
    "message": "invalid params, content must include a non-empty text item (prompt is required) (2013)",
    "http_code": "400"
  },
  "request_id": "021785229015510a2c883cf675b9804d"
}

{
  "type": "error",
  "error": {
    "type": "authorized_error",
    "message": "login fail: Please carry the API secret key in the 'Authorization' field of the request header (1004)",
    "http_code": "401"
  },
  "request_id": "021785229015510a2c883cf675b9804d"
}

{
  "type": "error",
  "error": {
    "type": "insufficient_balance_error",
    "message": "insufficient balance (1008)",
    "http_code": "402"
  },
  "request_id": "021785229015510a2c883cf675b9804d"
}

{
  "type": "error",
  "error": {
    "type": "unprocessable_entity_error",
    "message": "video description contains sensitive content (1026)",
    "http_code": "422"
  },
  "request_id": "021785229015510a2c883cf675b9804d"
}

{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "message": "rate limit, please retry later (1002)",
    "http_code": "429"
  },
  "request_id": "021785229015510a2c883cf675b9804d"
}

{
  "type": "error",
  "error": {
    "type": "server_error",
    "message": "internal error (1000)",
    "http_code": "500"
  },
  "request_id": "021785229015510a2c883cf675b9804d"
}

This endpoint only returns an enhanced video prompt. It does not create a video generation task.

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.

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.

After creating the task, use Query Task or List Tasks. H3-Context-IR tasks have task_type=h3_context_ir; when the task succeeds, retrieve the enhanced prompt from content.prompt.

Authorizations

Authorization

string

header

required

HTTP: Bearer Auth

Security Scheme Type: http
HTTP Authorization Scheme: Bearer API_key, used to verify account information, can be found in Account Management>API Keys.

Headers

Content-Type

enum<string>

default:application/json

required

Media type of the request body. Set it to application/json.

Available options:

application/json

Body

application/json

Request parameters for creating an H3-Context-IR task.

model

enum<string>

required

Model name. Currently available: MiniMax-H3.

Available options:

MiniMax-H3

content

object[]

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

Show child attributes

duration

enum<integer>

required

Target video duration in seconds. Required, integer. Available values: 4-15.

Available options:

4,

5,

6,

7,

8,

9,

10,

11,

12,

13,

14,

15

ratio

enum<string>

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.

Available options:

adaptive,

21:9,

16:9,

4:3,

1:1,

3:4,

9:16

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 endpoint.

Callback status values: queued, running, succeeded, failed, cancelled.

Response

The create endpoint returns a task_id. Use this task_id with the Query Task endpoint to retrieve the task status and result. When the task succeeds, retrieve the enhanced prompt from content.prompt.

Successful Query Task response example

{
  "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"
  }
}

task_id

string

ID of the task, used to query the task status and result later.

Using the API

Text

Video

Speech

Image

Music

File

Models

Authorizations

Headers

Body

Response