MiniMax H3 Max

Endpoint

POST https://api.roasos.com/v1/video/h3-max

Send your API key as a bearer token. The key needs the scope api:write. Every paid request also needs an Idempotency-Key header.

The envelope fields quote_only, quote_id, webhook_url and wait_timeout_seconds behave the same on each model endpoint. Refer to Jobs and Quotes and credits.

Good at

The model follows the prompt closely. Name the subject, the action and the camera move plainly, and it renders them. A single take can run 15 seconds.

Every output has a generated soundtrack. To use your own voiceover or music, send audio_url on text-to-video or image-to-video. The audio replaces the generated sound. It is trimmed to the clip, or padded with silence when it is shorter.

The reference lane takes up to 9 images, 3 video clips and 3 audio clips, and 12 files at most. Send references, video_urls and audio_urls. Add product_id to attach the product's kit shots, and avatar_id to attach a saved person. Each reference clip must be 2 to 15 seconds long, and the clips of one kind must total 15 seconds or less. The prompt names the media by type and position: Image 1, Video 1, Audio 1. The platform names the product and avatar shots for you at the end of the prompt.

Text-to-video takes six aspect ratios (21:9 to 9:16). The reference lane also takes auto (adaptive framing). Image-to-video takes its framing from the first frame, and end_image_url pins the last frame. A seed makes a result repeatable.

Pricing

The unit is one clip. Pricing key: h3-max.

The credits come from the roasOS pricing table. No other field changes the price. To get the exact price of your request, send it with quote_only: true first.

Modes

• text-to-video
• image-to-video
• reference-to-video

roasOS selects the mode from the media fields of your request. You do not send a mode.

Provider endpoints: minimax/h3-max/image-to-video · minimax/h3-max/reference-to-video · minimax/h3-max/text-to-video.

Request fields

The schema is strict. A field that is not in this table gets 400 unsupported_option. The field names are the roasOS role names. One role has one name in every family.

Media

This endpoint accepts these media roles:

• avatar_id — identity; the saved character reference sheet, with a derived portrait only where the model requires a single face or source frame
• product_id — product; resolves to the product image list
• references — style and appearance references
• image_url — first frame (or the single source image)
• end_image_url — last frame
• scene_id — first frame — a scene this workspace owns
• video_urls — reference videos
• audio_urls — reference or driving audio
• audio_url — the driving audio track

Every other role is refused: elements, product_images, reference_images, scene_image, video_url, voice_id. A refused role gets 400 unsupported_option.

Prompt

Limit 10,000 characters. The provider expands the prompt lightly before generation ("balanced" mode, pinned).

• Name the subject, one action and one camera move. The model adds the atmosphere.
• For a 10-15 second take, describe the action as one continuous progression.
• In image-to-video, describe the motion, not the scene. The first frame owns the scene.
• On the reference lane, say what each input controls: "the product in Image 1", "the motion of Video 1".
• Direct the sound (room tone, music mood, a spoken line in quotes), or the model makes its own.
• End with "No on-screen text, no captions, no subtitles." Add text in post-production.

Not exposed

These catalog entries describe omitted inputs, pinned values and source constraints. They do not imply that the provider accepts every listed field.

• prompt_expansion_mode — pinned to pinned to "balanced"; "disabled" and "quality" are not served.
• enable_safety_checker — pinned to provider default (on); never sent.
• sync_mode — not accepted by this public endpoint.
• negative_prompt — not accepted by this public endpoint.
• generate_audio — pinned to every output carries a generated soundtrack; there is no on/off field.
• cfg_scale — not accepted by this public endpoint.
• shot_type — not accepted by this public endpoint.
• multi_prompt — not accepted by this public endpoint.

Result

The result kind is video. Always present: url.

{
  "data": {
    "id": "gen_…",
    "kind": "video",
    "model": "h3-max",
    "status": "completed",
    "result": {
      "url": "https://cdn.roasos.com/workspaces/ws_01/result"
    }
  }
}

The files are immutable objects on https://cdn.roasos.com. A result URL is a valid media input for your next request.

Example

The three steps are always the same: quote, run, poll.

# 1. Quote. Nothing is spent.
curl -X POST https://api.roasos.com/v1/video/h3-max \
  -H "Authorization: Bearer roasos_sk_live_..." \
  -H "Idempotency-Key: 0f1c9e2a-h3-max-0001" \
  -H "Content-Type: application/json" \
  -d '{"quote_only":true,"prompt":"A woman holds the bottle at eye level in a bright kitchen, morning light, static camera."}'
# 200 { "data": { "kind": "quote", "quote_id": "q_7Hk...", "credits": 5, "expires_at": "...",
#        "confirmation": { "model": "h3-max", "example": "5s_768p" } } }

# 2. Run. Same body, same Idempotency-Key, quote_id in place of quote_only.
curl -X POST https://api.roasos.com/v1/video/h3-max \
  -H "Authorization: Bearer roasos_sk_live_..." \
  -H "Idempotency-Key: 0f1c9e2a-h3-max-0001" \
  -H "Content-Type: application/json" \
  -d '{"quote_id":"q_7Hk...","prompt":"A woman holds the bottle at eye level in a bright kitchen, morning light, static camera."}'
# 201 { "data": { "id": "gen_...", "status": "queued", "credits_reserved": 5 } }

# 3. Poll, then read the result.
curl https://api.roasos.com/v1/jobs/gen_.../status -H "Authorization: Bearer roasos_sk_live_..."
curl https://api.roasos.com/v1/jobs/gen_.../result -H "Authorization: Bearer roasos_sk_live_..."

The deprecated path

POST /v1/generations still reaches this model for one minor version. It is deprecated. This is how it maps:

POST /v1/video/h3-max with prompt, and image_url or scene_id (image-to-video), end_image_url, references, product_id, avatar_id, video_urls, audio_urls, audio_url, duration_seconds (5-15), aspect_ratio, resolution (480p|768p|1080p) and seed.

See also

• llms.txt for this model — the same facts as one plain-text file for an agent.
• GET https://api.roasos.com/v1/catalog/h3-max — the machine-readable form: enums, defaults, limits and prices. Refer to the API reference.
• Jobs — how to poll a job and read its result.
• Provider endpoints: minimax/h3-max/image-to-video · minimax/h3-max/reference-to-video · minimax/h3-max/text-to-video.