MiniMax-H3 Create H3-Context-IR Task

Deeply understands multi-modal context and generates structured, semantically richer video prompts. This API only returns the enhanced video prompt and does not create a video generation task.

Endpoint

POST /minimax/v2/h3_context_ir

Request Headers

Parameter	Type	Required	Default	Description
Content-Type	string	Yes	application/json	Request body media type
Authorization	string	Yes	-	Authentication, format Bearer <API_KEY>

Request Body

Parameter	Type	Required	Description
model	string	Yes	Fixed value MiniMax/MiniMax-H3-Context-IR3
content	object[]	Yes	Multi-modal context input array
duration	integer	Yes	Target video duration (seconds), integers from 4 to 15
ratio	string	Conditionally required	Target video aspect ratio, same rules as create video generation task
callback_url	string	No	Callback URL for task status changes

content Element Details

Every request must include a non-empty text item (prompt is required); otherwise a parameter error is returned.

Supported Input Combinations

Scenario	Combination
Text-to-video	A single text element only
Image-to-video - first frame	text + 1 image_url (role=first_frame or unset)
Image-to-video - last frame	text + 1 image_url (role=last_frame)
Image-to-video - first & last frame	text + 2 image_url (roles first_frame and last_frame)
Multi-modal reference-to-video	text + reference images (role=reference_image) + reference videos (role=reference_video) + reference audio (role=reference_audio)

Mutual exclusion: Image-to-video and multi-modal reference-to-video are mutually exclusive. If content contains any of reference_image / reference_video / reference_audio, it cannot contain first_frame / last_frame (and vice versa).

Input Media Limits

Total request body size ≤ 64 MB; use public URLs for large files, do not use Base64.

Input material can also be uploaded via the File Upload API first, then referenced as mm_file://{file_id} in the url field.

Image (image_url)

Limit	Detail
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, multi-modal reference scenario only)

Limit	Detail
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-segment 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, multi-modal reference scenario only)

Limit	Detail
Format	WAV, MP3
Single file size	≤ 15 MB
Count	≤ 3
Per-segment duration	[2, 15] s; total ≤ 15 s

ratio Parameter Details

Scenario	ratio Behavior
Text-to-video (content contains only text)	ratio is required and cannot be adaptive
Image-to-video (contains first_frame / last_frame images)	Aspect ratio determined by input image, always adaptive; other values are ignored
Multi-modal reference-to-video	ratio optional, default adaptive; a specific ratio can be explicitly specified

callback_url Details

Once configured, the MiniMax server will:

1. First send a verification request containing a challenge field (return the challenge as-is within 3 seconds)
2. After verification, POST push notifications to this URL whenever the task status changes

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

Usage Flow

1. Create task: POST to /v2/h3_context_ir to get task_id
2. Query result: Use task_id to call the Query Task API
3. Get enhanced prompt: Extract from content.prompt after the task succeeds
4. (Optional) Integrate into the video generation workflow: Use the enhanced prompt for subsequent video generation

Request Examples

# Text-to-video (t2va)
curl --request POST \
  --url https://neolink.com/api/minimax/v2/h3_context_ir \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "MiniMax/MiniMax-H3-Context-IR",
    "content": [
      {
        "type": "text",
        "text": "史诗级太空歌剧院线预告：女舰长独自站在巨大观景窗前，最后一支舰队正在集结并跃迁离去，强光爆闪、舰桥震动，她被留在原地。"
      }
    ],
    "duration": 5,
    "ratio": "16:9"
  }'
# Image-to-video (i2va)
curl --request POST \
  --url https://neolink.com/api/minimax/v2/h3_context_ir \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "MiniMax/MiniMax-H3-Context-IR",
  "content": [
    {
      "type": "text",
      "text": "Pull focus to the people in the background and add more steam to the ramen bowl."
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://cdn.hailuoai.com/prod/hailuo_demo/testsets/H3_AA_I2VA/gallery/sr_v17_variants_seed42_43_20260724/inputs/4a3a90bf9100_KDmcbkhzYo5sjjxr9FqcVmWVnzb.png"
      },
      "role": "first_frame"
    }
  ],
  "duration": 5,
  "ratio": "adaptive"
}
'
# Multi-modal reference-to-video (r2va)
curl --request POST \
  --url https://neolink.com/api/minimax/v2/h3_context_ir \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "MiniMax/MiniMax-H3-Context-IR",
  "content": [
    {
      "type": "text",
      "text": "角色说话：Follow the wind, live free.Leave worries behind, enjoy the moment，音色参考音频1"
    },
    {
      "type": "video_url",
      "video_url": {
        "url": "https://cdn.hailuoai.com/prod/hailuo_demo/testsets/h3_promo_eval_ref2va/gallery/sr_v2p26_trio_seed42_20260724/inputs/297573323635_00_%E8%A7%86%E9%A2%911_YnyRbxEwio_video_20260525_163755_1927e9d3.mp4"
      },
      "role": "reference_video"
    },
    {
      "type": "audio_url",
      "audio_url": {
        "url": "https://cdn.hailuoai.com/prod/hailuo_demo/testsets/h3_promo_eval_ref2va/gallery/sr_v2p26_trio_seed42_20260724/inputs/f463d523c5ce_01_%E9%9F%B3%E9%A2%911_RSLcbpzJPo_6%E6%9C%885%E6%97%A5(1).mp3"
      },
      "role": "reference_audio"
    }
  ],
  "duration": 5,
  "ratio": "adaptive"
}
'

Success Response (HTTP 200)

{
  "task_id": "424010985738629"
}

Field	Type	Description
task_id	string	Task ID, used to query task status and results

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 ..."
    },
    "duration": 5,
    "usage": {
      "total_tokens": 9090,
      "prompt_tokens": 5664,
      "completion_tokens": 3426
    },
    "ratio": "16:9",
    "task_type": "h3_context_ir",
    "modality": "text"
  }
}

Field	Description
task.content.prompt	Enhanced video prompt (core output)
task.task_type	Fixed value h3_context_ir
task.modality	Fixed value text

Error Responses

HTTP Status	Error Type	Error Code	Description
400	bad_request_error	2013	Invalid params, content must include a non-empty text item
401	authorized_error	1004	Authentication failed
402	insufficient_balance_error	1008	Insufficient balance
422	unprocessable_entity_error	1026	Video description contains sensitive content
429	rate_limit_error	1002	Rate limit, please retry later
500	server_error	1000	Internal error