fal H3 Max API Guide: Preview and Director Integration

Which fal H3 Max API should you use?

Use the endpoint that matches the actual product behavior:

minimax/h3-max/text-to-video for a finished clip from text.
minimax/h3-max/image-to-video for a finished clip from an image.
minimax/h3-max/director for a continuous WebRTC stream that accepts new prompt versions while it runs.

Do not build a chain of finite clips and call it Director. The transport, billing, failure modes, and user experience are different.

Recommended browser architecture

Keep FAL_KEY on the server. The browser should connect through a narrowly scoped server proxy that allows only minimax/h3-max/director, verifies the signed-in user, checks a short-lived paid-session ticket, and rejects all other fal targets.

browser -> POST /api/live/session -> reserve credits + signed ticket
browser -> /api/fal/proxy         -> authenticated negotiation only
browser <-> fal WebRTC            -> continuous video/audio + control data

The proxy must not become a general-purpose relay for arbitrary fal endpoints. Rate-limit session creation and bind the ticket to the user and generation task.

Control messages and state

The public Director AsyncAPI contract defines the control channel. A practical client should:

send configure once with protocol_version, prompt, prompt_version, aspect_ratio, resolution, and memory;
increment prompt_version for every subsequent prompt message;
treat prompt_pending, prompt_applied, and prompt_rejected as provider truth rather than inventing progress timers;
handle chunk, deadline_missed, stream_exhausted, and error events;
send stop and close media tracks when the paid session ends.

Billing and refund boundary

Reserve credits atomically before creating a session. If the negotiation fails before fal accepts the session, restore the reservation. Once the provider session begins, the 60-second minimum has effectively been incurred, so a client disconnect should not automatically refund the full amount.

On September 4, 2026, fal listed a launch price of $0.02 per video second for two weeks and a standard price of $0.08 per second. Verify the current rate on the official H3 Max Director page.

A working product layer

AIR Live wraps this infrastructure in a visible director queue, 60-second countdown, voice-to-direction pipeline, and separate low-cost Preview mode. Open the director to see the intended product contract.

Building around the fal H3 Max API

Choose the fal H3 Max API contract first

The fal H3 Max API has finite generation and realtime contracts. Decide which fal H3 Max API behavior you need before choosing a player: a completed file can be replayed independently, while Director delivers an active media stream and accepts later scene directions.

A fal H3 Max API integration is not complete at the request function. The fal H3 Max API also needs a product boundary: authenticated access, a visible credit requirement, an understandable failure state and a result the customer can find after generation finishes.

Keep fal H3 Max API credentials server-side

Never ship the long-lived fal H3 Max API key in browser code. The client should reach the fal H3 Max API through an authenticated server boundary. That server checks the user and allowed action before making provider requests, rather than treating possession of a page URL as authorization.

Protect the fal H3 Max API proxy as carefully as the initial creation route. Hiding a fal H3 Max API button is not access control. Requests must still be checked when a user sends them directly, when a session expires, or when a second tab has an outdated view of the balance.

Handle queued fal H3 Max API clips

For a finite clip, follow the fal H3 Max API queue response and retain its request identity. Poll the returned status until completion or failure. The fal H3 Max API result then supplies a video URL; the browser should show an actual playable result rather than a new log entry alone.

Save enough fal H3 Max API metadata to find the same completed request again. Upload or download retries are not reasons to generate another clip. Keep failures distinct: a provider rejection, a timeout and a storage outage should not all look like successful video creation.

Use the fal H3 Max API realtime client for Director

Director uses the fal H3 Max API realtime connection instead of a normal queued clip request. Configure its initial scene, then send increasing prompt versions. The fal H3 Max API media stays on the active WebRTC connection while later instructions change what will be generated next.

Do not drop fal H3 Max API directions spoken during startup. Queue them within that attempt, send them after readiness, and discard them if the user cancels. Opening another session for those sentences would change both the experience and the provider-spending boundary.

Speech sits above the fal H3 Max API

The fal H3 Max API receives scene directions here, not raw microphone audio. Browser recognition captures words and Evolink cleans finalized text before the fal H3 Max API handoff. An optional Gemini Live connection is a separate speech transport, not a requirement of the video endpoint.

Validate speech-derived fal H3 Max API instructions like typed ones. Preserve useful captured text if cleanup fails, and invalidate pending callbacks when listening stops. Otherwise an old transcript could start or alter a session after the user believes that interaction has ended.

Record fal H3 Max API output explicitly

A fal H3 Max API video stream does not automatically become an account-owned file. Record the received tracks, finalize the container, and upload the result. Keep fal H3 Max API generation separate from storage retries so interrupted uploads do not trigger another paid model request.

The fal H3 Max API workflow should finish with playback and download. Check container type, actual audio tracks and account ownership, not only the existence of a URL. A filename ending in MP4 is not evidence that the contents are an MP4 video.

Test the fal H3 Max API without mixing claims

Separate fal H3 Max API transport tests from funded model tests. A local WebRTC peer can verify recording, but it cannot prove fal H3 Max API scene quality. Likewise, mocked balances can test an interface gate without proving the database accounting behavior behind that gate.

For a real fal H3 Max API smoke test, use one clear scene and a small number of changes. Keep the output and provider request identifiers. That gives you something to compare with the bill and avoids spending repeatedly just to rediscover a client-side problem.

Recheck the fal H3 Max API before release

Check current fal H3 Max API model names, supported settings and runtime limits before release. Promotions are dated, and a fal H3 Max API session minimum can matter more than the advertised per-second number. Budget from the billing unit your actual endpoint uses.

A working fal H3 Max API integration still needs a reachable domain and configured customer checkout before public paid use. Treat deployment, payment readiness and generation readiness as separate checks. Do not make a disabled provider appear available by returning a sample video as a successful response.