MiniMax H3 API Guide: Text-to-Video and Reference Inputs

MiniMax H3 requests are easy to misconfigure when a client treats every model variant as interchangeable. The selected model ID affects duration and resolution validation, while the media mode determines which image, video, and audio fields can be sent together.

This guide describes the request contract represented in the ToAPIs frontend as of October 22, 2026. It is an integration guide, not a report of upstream performance or current account pricing. Confirm that your account has access to the requested model before sending production jobs.

Quick start

The generation endpoint used by the ToAPIs API examples is POST /v1/videos/generations. Authenticate with a ToAPIs API key and provide a prompt, an enabled model ID, duration, and ratio. For example:

curl -X POST "https://api.toapis.com/v1/videos/generations" \
  -H "Authorization: Bearer $TOAPIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-h3",
    "prompt": "A slow cinematic pan across a quiet coastal town at sunrise",
    "duration": 5,
    "ratio": "16:9"
  }'

Treat the response as an asynchronous task submission. Read the task identifier returned by your account's API response and use the documented task-status endpoint to poll it. Do not assume a fixed response envelope unless it is specified in the API reference for your account.

import os
import time
import requests

BASE_URL = "https://api.toapis.com/v1"
API_KEY = os.environ["TOAPIS_API_KEY"]
headers = {"Authorization": f"Bearer {API_KEY}"}

response = requests.post(
    f"{BASE_URL}/videos/generations",
    headers=headers,
    json={
        "model": "minimax-h3",
        "prompt": "A slow cinematic pan across a quiet coastal town at sunrise",
        "duration": 5,
        "ratio": "16:9",
    },
    timeout=30,
)
response.raise_for_status()
submission = response.json()
print("Submission response:", submission)

The example deliberately prints the response instead of assuming where a task ID or video URL appears. Match the parsing and polling code to the response schema documented for your account. This avoids silently treating a changed envelope as a successful task.

Choose the exact model ID

The frontend recognizes minimax-h3 and minimax-h3-global as base-family IDs, plus model IDs containing minimax-h3-max. For example, the Turbo model ID used in the product is minimax-h3-max-turbo. Use the canonical model identifier shown in the available model catalog; avoid inventing aliases or shortening the ID.

The frontend currently applies these capability boundaries:

These are frontend validation constraints, not a guarantee that every account or upstream route has the same availability. In particular, the extra 1080P option is attached only to the exact canonical minimax-h3-max ID in the current client. Do not infer that Turbo, a -global alias, or every H3 model supports 1080P.

Pick one media mode

The H3 form supports two mutually exclusive workflows:

1. Frame mode: provide at most one first_frame_image and at most one last_frame_image. The client selects an adaptive ratio when frame inputs are present.
2. Reference mode: provide reference images, videos, and/or audio without first- or last-frame inputs. The client uses the selected ratio for these references.

Example first-frame request:

{
  "model": "minimax-h3",
  "prompt": "The subject turns toward the camera as the camera gently moves forward",
  "duration": 5,
  "ratio": "16:9",
  "first_frame_image": ["https://example.com/starting-frame.jpg"]
}

Example reference-media request:

{
  "model": "minimax-h3",
  "prompt": "Use the supplied references to guide the scene and motion",
  "duration": 5,
  "ratio": "16:9",
  "media_mode": "reference",
  "reference_images": ["https://example.com/character-reference.jpg"],
  "reference_videos": ["https://example.com/motion-reference.mp4"]
}

The precise value format for uploaded media depends on the gateway's media-upload flow. These examples show the request fields, not a claim that arbitrary public URLs are accepted by every route. Use URLs or uploaded asset identifiers returned by the documented upload flow.

The frontend enforces these reference limits:

• Up to 9 reference images.
• Up to 3 reference videos.
• Up to 3 reference audio items.
• No more than 12 reference assets in total.
• Each reference video must be 2–15 seconds, with no more than 15 seconds total across the submitted references.
• Audio references require at least one visual reference.
• Turbo requests cannot include reference media.

Respect these constraints before submitting. A request that crosses input modes, exceeds a count, or omits required visual context is rejected locally by the frontend rather than sent as a valid H3 generation request.

Prompt and generation options

The prompt is required and limited to 7,000 Unicode characters by the current frontend. Write the scene, subject, movement, and visual intent in plain language. Treat bracketed camera tags or other special syntax as ordinary prompt text unless the upstream model documentation explicitly defines them. The available evidence in the frontend contract does not establish that strings such as [Pan Left] are native H3 commands.

The request builder passes supported optional controls such as prompt_optimizer, watermark, and seed according to the selected model route. Do not assume that optional fields are accepted identically by every upstream channel. If you expose them in your own UI, validate them against the model-specific catalog and remove stale fields when users switch model variants.

For aspect ratio, the frontend accepts adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, and 9:16. Frame inputs force adaptive. For text-to-video, an adaptive selection is normalized to 16:9; reference mode retains the requested supported ratio.

Build prompts that are testable

Prompt writing is not an API parameter, but it affects how useful a technical integration is to the person using it. Ask users to describe one scene and one primary action before adding camera direction, lighting, or style. A compact prompt might specify the subject, action, setting, and camera behavior in that order. Keep those pieces stable during a model comparison; otherwise, a changed prompt can explain a changed output.

Do not promise that a particular phrase guarantees a camera move, identity match, frame rate, or visual style. The frontend contract validates the prompt as text and applies a character limit. It does not define a standard command grammar for camera tags. If your application offers preset prompt controls, label them as prompt helpers rather than guaranteed model controls unless the upstream documentation confirms the behavior.

For repeated generation workflows, store a prompt template version alongside the task record. This makes it possible to distinguish a model change from a prompt change when users report different outputs. Avoid embedding API keys, private identifiers, or personal data in prompts. Review prompt content against your product's content and privacy policies before allowing unattended batch submission.

Normalize ratio and resolution deliberately

Ratio and resolution answer different questions: ratio describes the shape of the output, while resolution selects an output size supported by the model route. An accepted ratio does not imply that every resolution can be paired with it. Keep both fields in the interface and validate them against the currently selected model.

If the user selects first-frame or first/last-frame mode, the frontend forces an adaptive ratio so the input frames guide the canvas shape. Do not display a contradictory custom ratio as if it will be honored. In text-to-video mode, adaptive resolves to the default 16:9 behavior in the current builder. If you make that normalization visible, show the actual submitted value in a review step so users understand what the gateway receives.

Resolution labels also differ in capitalization between variants (768p versus 768P). Normalize them only if the API contract for the selected model explicitly allows it. Avoid converting model values globally, because a value accepted by one route may be rejected by another.

Polling and errors

Video generation is asynchronous. After submission, persist the task identifier and poll the status endpoint documented for your API account. Use bounded exponential backoff with jitter rather than a tight loop, set an overall deadline, and treat terminal failure separately from a timeout while waiting. A timeout does not prove that the upstream task failed; check task status before retrying a billable generation.

At minimum, your client should:

• Call raise_for_status() or equivalent on HTTP responses.
• Parse the response according to the published API schema.
• Stop polling on a documented terminal success or failure state.
• Cap retry count and total elapsed time.
• Avoid submitting a duplicate generation merely because a client-side request timed out.
• Log a request or task identifier, but never log the API key or private media URLs.

The generic error categories below are diagnostic starting points, not a guarantee of exact ToAPIs error codes:

Pricing and service guarantees

Pricing, uptime, refund behavior, and service-level agreements can vary by model, route, and account. This guide intentionally does not quote a per-second price or claim an availability SLA. Check the current ToAPIs model catalog and account pricing before estimating project costs. Do not use a planning-draft price as a production quote.

A safer request-building workflow

Keep model selection and validation in one place in your application. When a user changes the model, rebuild the allowed options instead of carrying every field from the previous selection into the next request. This matters when switching from base H3 to Max or Turbo: a stale resolution, reference-media list, or duration value can be valid for one model and invalid for another.

A reliable client-side sequence looks like this:

1. Read the currently selected model ID from the model catalog.
2. Load that model's duration and resolution choices.
3. Ask the user to select either frame mode or reference mode.
4. Validate field counts and compatibility before uploading media.
5. Upload the selected media through the documented asset endpoint.
6. Build a fresh request object from the validated values.
7. Submit once, save the returned task identifier, and expose task state to the user.

Avoid mutating an old request object in place. A fresh object makes it less likely that a field like reference_videos leaks into a Turbo request after a model switch. The ToAPIs frontend contract also makes the mode explicit: media_mode may be frame or reference, and mixed inputs are rejected.

For a custom integration, mirror these checks before the network call:

def validate_h3_request(model, duration, resolution, frame_images, refs):
    is_max_family = "minimax-h3-max" in model
    is_turbo = "turbo" in model
    min_duration = 5 if is_max_family else 4

    if not isinstance(duration, int) or not min_duration <= duration <= 15:
        raise ValueError("Duration is outside this model's supported range")
    if len(frame_images) > 2:
        raise ValueError("Use at most one first frame and one last frame")
    if frame_images and refs:
        raise ValueError("Frame inputs and reference media are separate modes")
    if is_turbo and refs:
        raise ValueError("This Turbo route does not accept reference media")
    if len(refs.get("images", [])) > 9:
        raise ValueError("Too many reference images")
    if len(refs.get("videos", [])) > 3:
        raise ValueError("Too many reference videos")

This is an illustrative client-side guard, not a replacement for server validation. Production code should additionally validate each media type, calculate total reference count and video duration, enforce the model-specific resolution list, and use the actual identifiers returned by the upload flow.

Upload and privacy considerations

Treat reference media as user data. Upload only files the user is authorized to use, and make sure your retention and access rules cover source images, audio, and video. Do not put private source media in public URLs merely to simplify a demo. If the API returns a temporary asset URL, avoid writing it to analytics or long-lived logs.

Validate files before upload: reject unsupported extensions and MIME types, enforce the documented size and count limits, and provide a clear error before spending time on a generation request. Keep the upload identifier associated with the task record, but do not expose internal storage paths in a public page. If an upload fails, stop before creating a generation task rather than submitting an incomplete request.

For retries, distinguish idempotent reads from billable generation submissions. Retrying a GET status check is generally different from repeating a POST that may already have created a task. If the client loses the submission response, first use any request identifier or recovery mechanism documented for the account. If none exists, surface an uncertain state to the operator rather than silently creating a duplicate.

Deployment checklist

Before shipping an H3 integration, test at least one valid request per model ID enabled for your account. Add negative tests for a fractional duration, unsupported resolution, too many references, combined frame and reference inputs, and references on Turbo. Verify that the UI clears incompatible values after a model switch.

In staging, record the request fields after validation and compare them with the documented gateway schema. Do not capture API keys or private media data in logs. Confirm the polling URL, task states, and result field with a non-production fixture or an approved test account. This article does not call a live endpoint or validate remote service behavior.

Finally, check the user's account price and model catalog immediately before launch. Model availability and pricing are account-level information; copied values in an old article can become stale even if the request fields remain unchanged.

Related models and next steps

• Browse video models
• Open the Playground with MiniMax H3
• Open the Playground with MiniMax H3 Max Turbo

Before deploying, verify the exact model ID, current route availability, upload format, response schema, and account price in the API documentation available to you.