API Reference

MiniMax H3

MiniMax H3 is a video generation series covering text-to-video, image-to-video and multimodal reference-to-video from a single pair of model IDs. There is no capability suffix in the model code (unlike HappyHorse): the mode is inferred from the materials you attach — a bare prompt is text-to-video, frame_images is image-to-video, input_references is reference-to-video.

POST https://llm.siraya.ai/v1/videos/generations

GET https://llm.siraya.ai/v1/videos/{video_id}

Synchronous by default, asynchronous on request

By default the request waits for the render and returns the finished file. A minimax-h3 render can take minutes, so async: true is recommended: you get an id back immediately with status: "processing", then poll GET /v1/videos/{video_id} until status is completed or failed. The result URL only appears on the completed response. See Asynchronous generation.

Supported Models

Model ID	Description	Resolutions	`seconds`
`minimax-h3`	MiniMax H3	768P, 2K	4–15
`minimax-h3-max`	MiniMax H3 Max — faster generation	480P, 768P	5–15

Both models cover all three modes and share the same request shape; only the resolution tiers and duration range differ.

Capabilities

✅ supported · — not accepted.

Mode	How to select it	`aspect_ratio`	`frame_images`	`input_references`
Text-to-video	`prompt` only	Required	—	—
Image-to-video	`frame_images` (or a top-level `image_url`)	Derived from the image	✅ first and/or last frame	—
Reference-to-video	`input_references`	✅	—	✅ images, videos, audio

Frames and references do not mix

First/last-frame control and multimodal reference are mutually exclusive on MiniMax H3. Keep a request to one or the other.

Authorization string Required

Your API Key (e.g., Bearer <API_KEY>).

Body

All MiniMax H3 parameters are sent flat, at the top level of the request body.

model string Required

minimax-h3 or minimax-h3-max — see Supported Models.

prompt string Required

A text description of the video content.

seconds integer

Video length in seconds. minimax-h3: 4–15. minimax-h3-max: 5–15. A duration the model does not accept returns a 400 at submit that names the supported values. duration is not a supported field — use seconds.

resolution string

minimax-h3: 768P, 2K. minimax-h3-max: 480P, 768P. Send the uppercase form shown here — the finished video reports it back in lowercase (768p).

aspect_ratio string Text-to-video

One of 16:9, 9:16, 4:3, 1:1, 3:4, 21:9. Required for text-to-video — there is no default. On image-to-video it is derived from the input image.

size string

Pixel dimensions, e.g. 1280x720. A standard size is converted to resolution + aspect_ratio; if you send all three they must agree.

frame_images array

Image-to-video. First-frame and/or last-frame control — see frame_images.

image_url string

Shorthand for a single first frame (URL or base64 data URI). Prefer frame_images.

input_references array

Reference-to-video. Reference images, videos and audio for style and content guidance — see input_references. Cannot be combined with frame_images.

async boolean Default: false

When false, the request waits for generation to finish and returns the completed file. When true, it returns immediately with a video id you poll for status — recommended here. See Asynchronous generation.

Accepted but ignored

These fields are in the shared video schema for portability across models, but MiniMax H3 does not use them. They are accepted without error and have no effect.

Parameter	Why
`seed`	MiniMax has no seed concept — the same prompt is not reproducible
`negative_prompt`	Not supported by MiniMax
`generate_audio`	H3 output always carries audio; there is no toggle
`output_format`	Not supported by MiniMax

cURLPython

curl https://llm.siraya.ai/v1/videos/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_KEY>" \
  -d '{
    "model": "minimax-h3",
    "prompt": "A cat walking on a sunny street",
    "seconds": 4,
    "resolution": "768P",
    "aspect_ratio": "16:9",
    "async": true
  }'

import time
import requests

base = "https://llm.siraya.ai"
headers = {"Authorization": "Bearer <API_KEY>"}

r = requests.post(
    f"{base}/v1/videos/generations",
    headers=headers,
    json={
        "model": "minimax-h3",
        "prompt": "A cat walking on a sunny street",
        "seconds": 4,
        "resolution": "768P",
        "aspect_ratio": "16:9",
        "async": True,
    },
).json()

video_id = r["id"]
while True:
    r = requests.get(f"{base}/v1/videos/{video_id}", headers=headers).json()
    if r["status"] in ("completed", "failed"):
        break
    time.sleep(10)

print(r.get("output_url") or r["error"]["message"])

Example Response ("async": true)

{
    "id": "video_xtkWIW63c58NJiM-IKU4kUK_U5gHtLUGOiIoFE3jAmFnb8f6nBvW...",
    "object": "video",
    "status": "processing",
    "seconds": 4,
    "resolution": "768p",
    "model": "minimax-h3",
    "usage": { "completion_tokens": 0, "total_tokens": 0 }
}

Poll GET /v1/videos/{video_id} with that id until status is completed — see Poll for status.

Media inputs

Anything beyond plain text goes in frame_images or input_references.

frame_images

First-frame and/or last-frame control for image-to-video:

Field	Type	Description
`image_url`	string	Public URL or a base64 data URI.
`frame_type`	string	`first_frame` or `last_frame`.

{
  "model": "minimax-h3",
  "prompt": "The camera slowly pushes in",
  "frame_images": [
    { "image_url": "https://your-domain.com/still.jpg", "frame_type": "first_frame" }
  ],
  "seconds": 4,
  "async": true
}

A bare top-level image_url is treated as a single first frame. aspect_ratio is derived from the frame you supply, so choose one already cropped to the ratio you want.

input_references

Reference images, videos and audio that guide style or content:

{
  "model": "minimax-h3",
  "prompt": "The character from the reference image dances to the music",
  "input_references": [
    { "type": "image", "url": "https://your-domain.com/style.png" },
    { "type": "video", "url": "https://your-domain.com/motion.mp4" },
    { "type": "audio", "url": "https://your-domain.com/voice.mp3" }
  ],
  "aspect_ratio": "16:9",
  "async": true
}

Field	Type	Description
`type`	string	`image`, `video` or `audio`.
`url`	string	Public URL, or a `data:` base64 URI.
`role`	string	Optional. Defaults to `reference_image` / `reference_video` / `reference_audio` to match `type`.

Per-type limits: up to 9 reference images, 3 reference videos (2–15 s each) and 3 audio files. File formats and size caps follow MiniMax's own rules — see the official video generation reference.

Poll for status

GET https://llm.siraya.ai/v1/videos/{video_id}

curl https://llm.siraya.ai/v1/videos/<video_id> \
  -H "Authorization: Bearer <API_KEY>"

Call the status endpoint with the returned id until status reads completed or failed.

{
    "id": "video_xtkWIW63c58NJiM-IKU4kUK_U5gHtLUGOiIoFE3jAmFnb8f6nBvW...",
    "object": "video",
    "status": "completed",
    "seconds": 4,
    "resolution": "768p",
    "ratio": "16:9",
    "model": "minimax-h3",
    "output_url": "https://.../output_aigc.mp4?Expires=...&Signature=...",
    "usage": { "completion_tokens": 130196, "total_tokens": 130196 },
    "vendor_data": {
        "created_at": 1791768091,
        "updated_at": 1791768196,
        "input_image_count": 0,
        "input_seconds": 0,
        "output_seconds": 4,
        "total_seconds": 4,
        "prompt_tokens": 0,
        "task_type": "generation"
    }
}

Response object

Field	Present	Meaning
`status`	always	`processing` · `completed` · `failed`
`seconds`	completed	Produced duration in seconds
`resolution`, `ratio`	completed	The produced resolution (lowercase, e.g. `768p`) and aspect ratio
`output_url`	completed	Signed and time-limited — download the file if you need to keep it
`usage`	always	`{ "completion_tokens": N, "total_tokens": N }` — zeros until the render completes
`error`	failed	`{ code, message }`
`vendor_data`	completed	MiniMax-reported extras: timings, `output_seconds`, `input_image_count`, …

Behavior worth knowing

aspect_ratio has no default on text-to-video. Omitting it returns a 400. Image-to-video derives it from the input image.

Audio is always generated. There is no generate_audio toggle — H3 output carries a soundtrack and the field is ignored if sent.

The result URL expires. output_url is a time-limited signed link. Download and re-host anything you need to keep.

callback_url is not forwarded. MiniMax's own callback parameter is not supported. Poll GET /v1/videos/{video_id}, or use the platform's own callbackUrl together with async: true as described in Callback.

Not supported: aigc_watermark and prompt_expansion_mode.

Errors

Status	Meaning
`400`	Invalid parameter — the message names the field and the supported values (e.g. a duration the model does not accept, or a missing `aspect_ratio` on text-to-video)
`401`	Invalid API key
`503`	Every upstream route is unavailable — retry later
`200` with `status: "failed"`	The request was valid but generation failed (content moderation, unusable input). `error.message` carries the reason

Official references

Value sets MiniMax owns and this platform passes through for validation:

What	Where
Full parameter reference (input rules, per-model resolution/duration)	video-generation-v2-create
Task status fields and usage semantics	video-generation-v2-query