MiniMax-H3 API Examples

MiniMax-H3 is MiniMax's native video generation model. It supports text-to-video, image-to-video (first/last frame), and reference-to-video (reference image/video/audio), with 768P and 2K output. This page covers the four native MiniMax endpoints proxied by Agentsflare: video generation, video regeneration, H3-Context-IR (prompt enhancement), and task query.

Basic Configuration

Before starting to use the API, please ensure you have obtained an API Key. If not, please refer to Create API Key.

Endpoints

Purpose	Method & Path
Create video generation task	`POST https://api.agentsflare.com/minimax/v2/video_generation`
Create H3-Context-IR task (prompt enhancement)	`POST https://api.agentsflare.com/minimax/v2/h3_context_ir`
Create video regeneration task (768P → 2K)	`POST https://api.agentsflare.com/minimax/v2/video_regeneration`
Query task status/result	`GET https://api.agentsflare.com/minimax/v2/query/video_generation/{task_id}`

Authentication: Authorization: Bearer <API_KEY>
Content-Type: application/json
All create endpoints are asynchronous: they return a task_id, which you then poll via the Query endpoint until status becomes succeeded / failed / cancelled.
Vendor reference: MiniMax Video Generation V2

Request Parameters (summary)

Parameter	Required	Description
`model`	Yes	Currently only `MiniMax-H3`
`content`	Yes	Array of multimodal input, each item has `type` (`text`/`image_url`/`video_url`/`audio_url`) and optional `role`. Every request must include exactly one non-empty `text` item
`resolution`	Conditional	`768P` or `2K`. Required for video generation; regeneration only supports `2K`
`duration`	Conditional	Video duration in seconds, `4`–`15`. Required for video generation and H3-Context-IR; not used for regeneration
`ratio`	Optional	Aspect ratio. `adaptive` (default), `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`. Required (non-`adaptive`) for pure text-to-video
`source_task_id`	Conditional	For regeneration by task ID: the `task_id` of an existing succeeded generation task
`callback_url`	Optional	Task status change callback URL

Content role values: first_frame, last_frame, reference_image, reference_video, reference_audio, base_video (regeneration only). Image-to-video (first_frame/last_frame) and reference-to-video (reference_*) are mutually exclusive.

Request Examples

1. Create Video Generation Task

cURL - Text-to-VideocURL - Image-to-VideoPythonNode.js

bash

curl -X POST "https://api.agentsflare.com/minimax/v2/video_generation" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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."
      }
    ],
    "resolution": "2K",
    "duration": 5,
    "ratio": "16:9"
  }'

bash

curl -X POST "https://api.agentsflare.com/minimax/v2/video_generation" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "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://example.com/first-frame.png" },
        "role": "first_frame"
      }
    ],
    "resolution": "2K",
    "duration": 5,
    "ratio": "adaptive"
  }'

python

import requests
import os

API_BASE = "https://api.agentsflare.com/minimax/v2/video_generation"
API_KEY = os.getenv("API_KEY")

payload = {
    "model": "MiniMax-H3",
    "content": [
        {"type": "text", "text": "A boy playing basketball by the sea"}
    ],
    "resolution": "2K",
    "duration": 5,
    "ratio": "16:9"
}

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

resp = requests.post(API_BASE, json=payload, headers=headers)
result = resp.json()
print("Task ID:", result.get("task_id"))

javascript

const API_BASE = 'https://api.agentsflare.com/minimax/v2/video_generation';
const API_KEY = process.env.API_KEY;

async function createVideo() {
  const payload = {
    model: 'MiniMax-H3',
    content: [
      { type: 'text', text: 'A boy playing basketball by the sea' }
    ],
    resolution: '2K',
    duration: 5,
    ratio: '16:9'
  };

  const res = await fetch(API_BASE, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(payload)
  });

  const data = await res.json();
  console.log('Task ID:', data.task_id);
}

createVideo().catch(console.error);

Response:

json

{ "task_id": "424010985738629" }

2. Create H3-Context-IR Task (Prompt Enhancement)

H3-Context-IR does not generate a video. It deeply interprets multimodal context and returns a structured, semantically enriched prompt (billed by tokens), which you can then feed into the video generation task.

cURLPython

bash

curl -X POST "https://api.agentsflare.com/minimax/v2/h3_context_ir" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "content": [
      { "type": "text", "text": "A boy playing basketball by the sea" }
    ],
    "duration": 5,
    "ratio": "16:9"
  }'

python

import requests
import os

API_BASE = "https://api.agentsflare.com/minimax/v2/h3_context_ir"
API_KEY = os.getenv("API_KEY")

payload = {
    "model": "MiniMax-H3",
    "content": [
        {"type": "text", "text": "A boy playing basketball by the sea"}
    ],
    "duration": 5,
    "ratio": "16:9"
}

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

resp = requests.post(API_BASE, json=payload, headers=headers)
print(resp.json())

3. Create Video Regeneration Task (768P → 2K)

Upgrades a source video that meets the MiniMax-H3 768P output specification to 2K. Supports two modes: by source_task_id (existing succeeded generation task, requires whitelist access) or by base_video (provide the original 768P video plus the exact original inputs).

cURL - By source_task_idcURL - By base_video

bash

curl -X POST "https://api.agentsflare.com/minimax/v2/video_regeneration" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "source_task_id": "424010985738629",
    "resolution": "2K"
  }'

bash

curl -X POST "https://api.agentsflare.com/minimax/v2/video_regeneration" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "content": [
      { "type": "text", "text": "A boy playing basketball by the sea" },
      {
        "type": "video_url",
        "video_url": { "url": "https://example.com/h3-768p-source.mp4" },
        "role": "base_video"
      }
    ],
    "resolution": "2K"
  }'

Note

This endpoint only upgrades videos that already meet the MiniMax-H3 768P output spec (24fps, width/height divisible by 32, area ≤ 768×1344, 107–362 frames). It does not process arbitrary videos.

4. Query Task

All three task types (generation, regeneration, h3_context_ir) share the same query endpoint. Task IDs are only queryable within a 7-day window.

cURLPython

bash

curl -X GET "https://api.agentsflare.com/minimax/v2/query/video_generation/424010985738629" \
  -H "Authorization: Bearer YOUR_API_KEY"

python

import requests
import os

task_id = "424010985738629"
API_BASE = f"https://api.agentsflare.com/minimax/v2/query/video_generation/{task_id}"
API_KEY = os.getenv("API_KEY")

resp = requests.get(API_BASE, headers={"Authorization": f"Bearer {API_KEY}"})
result = resp.json()

status = result["task"]["status"]
print("Status:", status)
if status == "succeeded":
    print("Result:", result["task"]["content"])

Response Examples

Video Generation — Succeeded

json

{
  "task": {
    "id": "424010985738629",
    "model": "MiniMax-H3",
    "status": "succeeded",
    "created_at": 1785125529,
    "updated_at": 1785125946,
    "content": {
      "url": "https://your-cdn.example.com/h3-generated-2k-output.mp4"
    },
    "resolution": "2K",
    "duration": 5,
    "usage": {
      "total_seconds": 5,
      "input_seconds": 0,
      "output_seconds": 5,
      "input_image_count": 0
    },
    "ratio": "16:9",
    "task_type": "generation",
    "modality": "video"
  }
}

H3-Context-IR — Succeeded

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

Failed

json

{
  "task": {
    "id": "424010985738630",
    "model": "MiniMax-H3",
    "status": "failed",
    "error": { "code": "1026", "message": "video description contains sensitive content" },
    "created_at": 1785125529,
    "updated_at": 1785125700,
    "resolution": "2K",
    "duration": 5,
    "usage": { "total_seconds": 0, "input_seconds": 0, "output_seconds": 0, "input_image_count": 0 },
    "ratio": "16:9",
    "task_type": "generation",
    "modality": "video"
  }
}

Response Fields

Field	Description
`status`	`queued` / `running` / `succeeded` / `failed` / `cancelled`
`task_type`	`generation` / `regeneration` / `h3_context_ir`
`modality`	`video` (generation/regeneration) or `text` (h3_context_ir)
`content.url`	Video download URL (time-limited, download promptly) — video tasks
`content.prompt`	Enhanced prompt text — H3-Context-IR tasks
`usage.total_seconds` / `input_image_count`	Billing usage for video tasks
`usage.total_tokens` / `prompt_tokens` / `completion_tokens`	Billing usage for H3-Context-IR tasks

Important Notes

API Key Security: Do not hardcode API Keys in your code, use environment variables
Async polling: Poll the Query endpoint (recommended interval 3–5s) instead of blocking on the create request
7-day query window: Task results are only queryable for 7 days; download video URLs promptly
Image-to-video vs reference-to-video: These input modes are mutually exclusive within a single request

Supported Models

MiniMax-H3

💡 Tip

The model field in the request example can be replaced with any model name above.

MiniMax-H3 API Examples ​

Basic Configuration ​

Endpoints ​

Request Parameters (summary) ​

Request Examples ​

1. Create Video Generation Task ​

2. Create H3-Context-IR Task (Prompt Enhancement) ​

3. Create Video Regeneration Task (768P → 2K) ​

4. Query Task ​

Response Examples ​

Video Generation — Succeeded ​

H3-Context-IR — Succeeded ​

Failed ​

Response Fields ​

Important Notes ​

Related Links ​

Supported Models ​

MiniMax-H3 API Examples

Basic Configuration

Endpoints

Request Parameters (summary)

Request Examples

1. Create Video Generation Task

2. Create H3-Context-IR Task (Prompt Enhancement)

3. Create Video Regeneration Task (768P → 2K)

4. Query Task

Response Examples

Video Generation — Succeeded

H3-Context-IR — Succeeded

Failed

Response Fields

Important Notes

Related Links

Supported Models