MiniMax-H3 Video API

MiniMax-H3 generates videos asynchronously from text, images, videos, and audio. Submit a task first, then poll the query endpoint with the returned task_id until the task reaches a terminal state.

API Overview

Item	Value
Model	MiniMax-H3
Base URL	https://api.exchangetoken.ai
Create task	POST /v2/video_generation
Query task	GET /v2/query/video_generation/{task_id}
Authentication	Authorization: Bearer YOUR_API_KEY
Content type	application/json (documented default; send it explicitly)

Callback URLs are not supported

Do not send callback_url. Poll the Exchange Token query endpoint with the returned platform task_id instead.

Create a Video Generation Task

POST https://api.exchangetoken.ai/v2/video_generation

Request Fields

Field	Type	Required	Default	Description
model	string	Yes	None	Must be MiniMax-H3
content	object[]	Yes	None	Multimodal input array; every request must contain a non-empty text item
resolution	string	Yes	None	768P or 2K
duration	integer	Yes	None	Generated video duration, from 4 to 15 seconds
ratio	string	Conditional	adaptive when optional	adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, or 9:16; see the scenario-specific behavior below

callback_url from the upstream MiniMax API is not accepted by Exchange Token.

Content Items

Every item in content has a type. Media items contain a nested object with a url field.

type	Value field	Supported role	Default behavior	Description
text	text	—	None	Prompt, up to 7,000 characters; at least one non-empty text item is required
image_url	image_url.url	first_frame, last_frame, reference_image	With exactly one image and no role, the role defaults to first_frame	First/last frame or reference image
video_url	video_url.url	reference_video	None	Reference video
audio_url	audio_url.url	reference_audio	None	Reference audio

Media URLs can be public URLs or supported Base64 data URLs. Because the total JSON request body cannot exceed 64 MB and Base64 increases payload size, use public URLs for large media.

Supported Scenarios

Scenario	content combination	ratio rule
Text to video	One text item only	Required; cannot be adaptive
First-frame image to video	text + one image_url with first_frame (or no role)	Treated as adaptive
Last-frame image to video	text + one image_url with last_frame	Treated as adaptive
First- and last-frame video	text + first_frame + last_frame images	Treated as adaptive
Reference to video	text + any valid combination of reference image, video, and audio	Optional; defaults to adaptive

First/last-frame inputs cannot be mixed with reference_image, reference_video, or reference_audio inputs in the same request.

For clarity, ratio=adaptive is not a valid default for text-to-video: text-to-video requests must explicitly select a concrete ratio. In image-to-video, the input image determines the aspect ratio and the API treats ratio as adaptive, even if another valid value is supplied. In reference-to-video, omitting ratio uses adaptive.

Media Limits

Media	Limits
Image	JPG, JPEG, PNG, WEBP, HEIC, or HEIF; up to 30 MB each; width and height 256–5760 px; aspect ratio 0.4–2.5; up to one first frame, one last frame, or nine reference images
Video	MP4 or MOV; H.264/H.265 video; up to 50 MB each; 2–15 seconds each and 15 seconds total; up to 3 clips; 256–5760 px; aspect ratio 0.4–2.5; 23.976–60 FPS
Audio	WAV or MP3; up to 15 MB each; 2–15 seconds each and 15 seconds total; up to 3 clips

Text-to-Video Example

curl -sS -X POST "https://api.exchangetoken.ai/v2/video_generation" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "content": [
      {
        "type": "text",
        "text": "A cinematic tracking shot of an astronaut walking through a neon-lit rainstorm, reflections shimmering on the street."
      }
    ],
    "resolution": "2K",
    "duration": 5,
    "ratio": "16:9"
  }'

Image-to-Video Example

curl -sS -X POST "https://api.exchangetoken.ai/v2/video_generation" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "content": [
      {
        "type": "text",
        "text": "The camera slowly pushes in while steam rises from the cup."
      },
      {
        "type": "image_url",
        "image_url": {"url": "https://example.com/first-frame.png"},
        "role": "first_frame"
      }
    ],
    "resolution": "768P",
    "duration": 5,
    "ratio": "adaptive"
  }'

Reference-to-Video Example

curl -sS -X POST "https://api.exchangetoken.ai/v2/video_generation" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "content": [
      {
        "type": "text",
        "text": "Keep the subject appearance and follow the movement and voice from the references."
      },
      {
        "type": "video_url",
        "video_url": {"url": "https://example.com/reference.mp4"},
        "role": "reference_video"
      },
      {
        "type": "audio_url",
        "audio_url": {"url": "https://example.com/reference.mp3"},
        "role": "reference_audio"
      }
    ],
    "resolution": "2K",
    "duration": 5,
    "ratio": "adaptive"
  }'

Create Response

{
  "task_id": "sg_vid_xxxxxxxxxxxxxxxx"
}

Save this Exchange Token task ID. It is the only ID you need for subsequent queries.

Query a Task

Replace {task_id} with the value returned by the create endpoint.

The query endpoint has no optional request fields or default values. The task_id path parameter and Authorization header are required.

GET https://api.exchangetoken.ai/v2/query/video_generation/{task_id}

curl -sS "https://api.exchangetoken.ai/v2/query/video_generation/sg_vid_xxxxxxxxxxxxxxxx" \
  -H "Authorization: Bearer YOUR_API_KEY"

Task Statuses

Status	Meaning
queued	Waiting to run
running	Generation is in progress
succeeded	Generation completed; read the video URL from task.content.url
failed	Generation failed; inspect task.error
cancelled	Task was cancelled

Query Response Fields

The HTTP response body contains a top-level task object.

Field	Type	Returned	Description
task	object	Always	Video generation task details

task object

Field	Type	Returned	Description
id	string	Always	Exchange Token platform task ID. This is the same ID used in the query path; the upstream task ID is not exposed
model	string	Always	Model used by the task; MiniMax-H3 for this endpoint
status	string	Always	Current task status: queued, running, succeeded, failed, or cancelled
error	object	On failure	Failure details. See the task.error table below
created_at	integer	Always	Task creation time as a Unix timestamp in seconds
updated_at	integer	Always	Last task update time as a Unix timestamp in seconds
content	object	On success	Generated output. See the task.content table below
resolution	string	Always	Requested/output resolution: 768P or 2K
duration	integer	Always	Requested/output duration in seconds
usage	object	Always	Metered usage. Basic counters are 0 before usage is available; see the task.usage table below
ratio	string	When available	Actual output aspect ratio. For adaptive generation, use this value to learn the selected ratio
task_type	string	Always	Fixed to generation on this Exchange Token endpoint
modality	string	Always	Fixed to video on this Exchange Token endpoint

task.content object

Field	Type	Returned	Description
url	string	When status=succeeded	Time-limited URL of the generated video; download or store it promptly

task.error object

Field	Type	Returned	Description
code	string	On an upstream-reported failure	MiniMax failure code. It may be absent for a platform-side failure
message	string	When status=failed	Human-readable failure reason

task.usage object

Field	Type	Returned	Description
total_seconds	integer	Always	Total metered video seconds: input_seconds + output_seconds; 0 while unavailable
input_seconds	integer	Always	Total input reference-video seconds; 0 when no reference video is used or while unavailable
output_seconds	integer	Always	Generated output video seconds; 0 while unavailable
input_image_count	integer	Always	Total input image count, including first frame, last frame, and reference images; 0 when none
input_audio_seconds	integer	When reference audio usage is returned	Sum of input reference-audio segment durations, rounded to seconds
total_tokens	integer	When returned by MiniMax	Total equivalent usage tokens: prompt_tokens + completion_tokens
prompt_tokens	integer	When returned by MiniMax	Equivalent input tokens derived from reference video, images, and reference audio; 0 when there is no multimodal input usage
completion_tokens	integer	When returned by MiniMax	Equivalent output tokens derived from the generated video

Fields marked “Always” refer to a successful HTTP query response, including tasks that are still queued/running or have failed. Optional usage fields may be omitted until MiniMax returns them.

Successful Query Response

{
  "task": {
    "id": "sg_vid_xxxxxxxxxxxxxxxx",
    "model": "MiniMax-H3",
    "status": "succeeded",
    "created_at": 1785125529,
    "updated_at": 1785125946,
    "content": {
      "url": "https://example.com/generated-video.mp4"
    },
    "resolution": "2K",
    "duration": 5,
    "usage": {
      "total_seconds": 5,
      "input_seconds": 0,
      "output_seconds": 5,
      "input_image_count": 1,
      "input_audio_seconds": 6,
      "total_tokens": 273890,
      "prompt_tokens": 13500,
      "completion_tokens": 260390
    },
    "ratio": "16:9",
    "task_type": "generation",
    "modality": "video"
  }
}

Generated video URLs are time-limited. Download or store the result promptly after the task succeeds.

Failed Query Response

{
  "task": {
    "id": "sg_vid_xxxxxxxxxxxxxxxx",
    "model": "MiniMax-H3",
    "status": "failed",
    "error": {
      "code": "1026",
      "message": "video description contains sensitive content"
    },
    "resolution": "2K",
    "duration": 5,
    "ratio": "16:9",
    "task_type": "generation",
    "modality": "video"
  }
}

Error Format

Gateway errors use the Exchange Token error envelope:

{
  "error": {
    "type": "invalid_request",
    "message": "content must include a non-empty text item"
  }
}

HTTP status	Typical meaning
400	Invalid JSON, unsupported callback_url, missing prompt, or invalid model/resolution/duration
401 / 403	Missing, invalid, disabled, or unauthorized API key
402	Insufficient quota
404	Task not found or not owned by the current API key
422	Input rejected by content safety checks
429	Rate limit exceeded
500	Internal error
502	Upstream request or response error
503	No available channel or asynchronous task service unavailable