MiniMax H3 Max API: Official Platform or fal?

There are now two practical ways to call a MiniMax H3 Max API: MiniMax's unified Video Generation V2 API and fal's family of H3 Max endpoints. They reach the same model family, but they are not drop-in replacements. MiniMax puts text, first/last frames, and image, video, or audio references into one content array. fal separates text-to-video, image-to-video, reference-to-video, and specialist edits into different routes.

Use the official MiniMax API when you want one contract for the core H3 Max generation modes. Use fal when its queue client, webhooks, split endpoints, or a specialist route documented on fal fits the rest of your stack. Choose the interface before you build your request validator; translating field names at the last minute is where the expensive mistakes begin.

AI Live Generator is a browser product, not an API-key service or an API proxy. Its regular text and image jobs use H3 Max Turbo, while its photo-led reference mode uses a separate H3 Max reference endpoint. The generator does not expose MiniMax or fal credentials, source-video uploads, or reference-audio inputs. This guide is for developers building their own server-side integration.

The two API surfaces in one table

Do not select a provider from a single price card. Compare the exact operation. A five-second text generation, a five-second output using a reference video, and a five-second Recast edit can have different input rules and bills even when every page says “H3 Max.”

A minimal official MiniMax H3 Max request

The official Create Video Generation Task documentation uses the following endpoint:

POST https://api.minimax.io/v2/video_generation

Every request needs a server-side Bearer key, model: "MiniMax-H3-Max", and at least one non-empty text item. Here is a first-frame request plan. The sample prompt is illustrative; it is not a claimed generation result.

curl --request POST \
  --url https://api.minimax.io/v2/video_generation \
  --header "Authorization: Bearer $MINIMAX_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "MiniMax-H3-Max",
    "content": [
      {
        "type": "text",
        "text": "A ceramic fox pauses beside a rain-dark window. Slow push-in, warm room tone, quiet rain outside. Keep the fox proportions and glaze pattern consistent."
      },
      {
        "type": "image_url",
        "image_url": { "url": "https://cdn.example.com/fox-first-frame.png" },
        "role": "first_frame"
      }
    ],
    "resolution": "768P",
    "duration": 5,
    "ratio": "adaptive"
  }'

For image-to-video, the input image determines the aspect ratio. The API treats ratio as adaptive even if another valid ratio is supplied, so the example says that plainly instead of pretending the field can reshape the first frame.

The create response contains a task_id, not the finished MP4. Store that ID against your own authenticated job before returning anything to the browser. Then query it:

curl --request GET \
  --url "https://api.minimax.io/v2/query/video_generation/TASK_ID" \
  --header "Authorization: Bearer $MINIMAX_API_KEY"

The query endpoint returns the task status and, after success, the output URL in task.content.url. It only queries tasks from the last seven days. MiniMax also accepts a callback_url: its server first sends a challenge, which your endpoint must return unchanged within three seconds, then posts task-status changes after verification. Copy completed media and the final usage fields into storage and records you control; neither a callback nor a seven-day task lookup is a durable user library.

Keep the API key on the server. A client bundle, public environment variable, mobile app, or HTML form is not a secret store. The browser should call your authenticated route, and that route should own authorization, validation, quota reservation, provider submission, and result settlement.

Map the content roles before writing application code

MiniMax's V2 API makes the generation mode a consequence of the content items. That is convenient only if your application rejects illegal combinations early.

Frame conditioning and reference conditioning are mutually exclusive. If a request includes reference_image, reference_video, or reference_audio, it cannot also include first_frame or last_frame. Make that a form-level rule instead of waiting for a paid job to fail.

The current H3 Max limits are specific enough to encode:

• output resolution is 480P or 768P; H3 Max does not support 2K;
• output duration is an integer from 5 through 15 seconds; four seconds is not accepted;
• the total request body is at most 64 MB, and public URLs are the practical choice for larger media;
• reference images are limited to nine;
• reference videos are limited to three, each 2–15 seconds, with no more than 15 seconds combined;
• reference audio files are limited to three, each 2–15 seconds, with no more than 15 seconds combined.

The complete image, codec, frame-rate, dimension, and file-size limits live in the current API schema. Mirror them in server validation, but keep them configurable: a hard-coded validator becomes misinformation when an upstream contract changes.

For first-and-last-frame work, the creative problem is different from reference generation. The two frames define the ends of one motion path. Read the H3 Max first and last frame guide before turning the feature into two generic upload boxes. For a new shot guided by an existing clip or audio, use reference roles and treat their order as part of the prompt plan.

What the MiniMax H3 Max API actually costs

MiniMax's current pricing table lists H3 Max output at $0.05 per second for 480P and $0.08 per second for 768P. The output arithmetic is direct:

5-second 768P text-to-video
5 × $0.08 = $0.40

Reference media can add an input charge. Audio is currently free. The first two input images are free, then additional images are $0.074 each. Reference-video input is billed by its own duration and the selected output resolution: $0.0553 per second for 480P or $0.143 per second for 768P.

A request using one five-second reference video to make a five-second 768P output therefore has a list-price calculation of:

reference video: 5 × $0.143 = $0.715
generated output: 5 × $0.08  = $0.400
total:                         $1.115

That is a formula, not a universal quote. Multiple inputs, retry behavior, taxes, plan terms, and future pricing can change the invoice. Save the provider's returned usage with each job and reconcile it against your reservation rather than trusting the estimate forever.

Checked October 22, 2026, fal's standard H3 Max text and image routes show a 35% discount through October 31, 2026, while reference and specialist routes have their own price blocks. Check the live schema for the exact route at submission time. A discount on text-to-video does not prove that Reference-to-Video, Recast, or Reframe costs the same.

Build the queue around uncertainty, not the happy path

Video generation is asynchronous. A reliable integration has two IDs: your immutable job ID and the provider task or request ID. The provider ID tells you where work is running; your ID decides which account, project, reservation, and source files own it.

Use this lifecycle:

1. Create a local job and calculate a server-side estimate from validated inputs.
2. Reserve entitlement or credits once, using an idempotency key tied to the user's action.
3. Submit the provider request and persist its ID before acknowledging success to the client.
4. Move the UI to a processing state; do not keep one browser request open for the render.
5. Poll with backoff, or use a verified MiniMax callback or fal webhook. Treat callbacks as untrusted and idempotent.
6. On success, verify the returned duration, resolution, and URL before settling the reservation.
7. On terminal failure, release the reservation exactly once. Do not automatically resubmit a billable job unless your policy and the provider response make that safe.
8. Reconcile stalled jobs in a background task rather than asking the user to click Generate again.

Rate limits deserve their own state. A 429 means “try this request later,” not “create three new tasks now.” Use exponential backoff with jitter for status checks and only retry creation when you can prove the first create call did not produce a task.

Also copy successful outputs to storage governed by your retention policy. A provider URL is a delivery mechanism; it is not your product's archive, access-control layer, or deletion policy.

When fal is the better H3 Max API

fal is the cleaner choice when your application already uses its queue client or when the required operation is documented as a specialist fal route rather than in MiniMax's core V2 generation contract. Its route split can be an advantage: each form can expose only the controls that one operation actually accepts.

For example, minimax/h3-max/text-to-video takes a prompt and text-route settings. Reference-to-Video has its own media fields and limits. Recast begins with a finished source video and replacement portraits; the H3 Recast API guide covers that contract. Reframe changes an existing video's canvas; the Reframe guide explains why that is not ordinary image-to-video.

The cost of this clarity is more adapters. Do not build one giant “H3 request” object and spray its fields across every endpoint. Give each route its own typed input, validator, cost function, and result normalizer. Share the queue infrastructure, not assumptions about the media schema.

Choose fal when:

• you need a specialist H3 Max route documented on fal;
• you want its queue SDK and webhook workflow;
• you already centralize providers behind fal and can monitor route-level schema changes;
• a live route's price and regional availability are better for your workload.

Choose MiniMax Open Platform when:

• you want the first-party unified content model for H3 Max generation;
• one request builder must support text, first/last frames, and reference media;
• the official input usage fields and first-party billing contract fit your accounting;
• you do not need a separate fal specialist transformation.

Neither provider choice rescues a weak product boundary. If users can upload audio in your UI, your backend must really send reference audio. If the UI promises 2K, H3 Max is the wrong model. If you sell a four-second H3 Max option, the official contract will reject it.

The shortest sound implementation plan

Start with one mode, one resolution, and one duration. Text-to-video at five seconds is easier to observe than a form that accepts nine images, three clips, three audio files, six ratios, and two providers on day one. Log the estimate, provider ID, returned usage, terminal status, and stored output location. Once that path settles correctly, add first-frame input. Add reference media only after your asset validation and cost reservation can explain the larger bill before submission.

At that point, your application knows which contract it is calling and can still account for the job when the browser closes, the status request gets a 429, or the final video costs more than a text-only estimate.