minimax/h3-max/director

The client provides a convenient way to interact with the model API.

Keep FAL_KEY on your server and expose an authenticated proxy route to your browser. For a Next.js App Router application, create app/api/fal/proxy/route.ts:

Set FAL_KEY in the server environment, and protect this route with your application's authentication before deploying it.

This deployment publishes a WMA WebRTC contract. The example uses fal.realtime.open; its media handlers, capture constraints, and control message are generated from the linked AsyncAPI document.

Session flow#

Configure once, wait for the model to acknowledge setup, then update the running session. The transport being live does not mean the model is configured.

1. Configure the session#

Send configure once with /prompt_version set to 1. These field paths are JSON Pointers into message payloads. Use the setup message reference below for all configuration fields.

{
  "prompt_version": 1,
  "resolution": "768p",
  "aspect_ratio": "16:9",
  "type": "configure",
  "prompt": "A continuous original live-action American sitcom produced in 1994, following the same ensemble of adult roommates, coworkers, neighbors, and rivals. Preserve appearances, apartment and workplace layouts, relationships, jobs, secrets, running jokes, and unresolved storylines. Advance through dialogue, entrances, misunderstandings, escalating attempts to hide mistakes, reversals, and warm character payoffs. Avoid references to existing sitcoms or actors.",
  "protocol_version": 1,
  "memory": 3
}

2. Wait for acknowledgement#

Wait for configured whose /prompt_version matches the version you sent in setup. Only that acknowledgement enables text updates. Pending, applied, or rejected input events do not confirm session readiness.

3. Update the running session#

Send prompt with your text at /prompt. Start from {"type":"prompt"}, add the text and the next /prompt_version, and validate the complete payload against the message schema. The first update uses 2; increase by 1 for each subsequent submission.

{
  "type": "prompt",
  "prompt": "They follow a narrow path down to the harbor.",
  "prompt_version": 2
}

This action sends only the template, text, and version fields. Other options in the raw message schema are outside this text-update flow. If you use them too, coordinate the same session-wide version sequence.

Track each update#

Match the version in each event to the submission it describes, including the initial setup input. Several updates can have different outcomes while the session stays ready.

• Pending (prompt_pending): The model is preparing this input. Match the submitted version at /prompt_version.
• Applied (prompt_applied): Accepted for generation. The result may not be generating or visible yet. Match the submitted version at /prompt_version.
• Rejected (prompt_rejected): This input was not accepted. An earlier applied input can remain active. Match the submitted version at /prompt_version.

You can send another update while preparation is pending. Newer updates can replace older pending preparation, and the older input may never receive a final event. A missing acknowledgement means the outcome is unknown; it does not prove rejection.

Handle errors#

For error, read the code at /code and the explanation at /error. Match input failures using /prompt_version.

• Session failure: Ends this session attempt, even without a matching version. Codes: configuration_timeout, initialization_timeout, invalid_initial_image, invalid_initial_audio, invalid_initial_script, invalid_input, balance_unavailable, content_policy, generation_timeout, generation_failed.
• Input failure: Fails only the submission with a known matching version. An absent or unknown version is diagnostic. Codes: stale_prompt_version.
• Diagnostic: Provides information without declaring the session or a submission failed. Codes: invalid_message, not_configured, immutable_settings.

Treat unknown codes as diagnostics. An input failure without a known matching submission is also diagnostic; do not guess which input failed.

End or reconnect#

stream_exhausted ends this session attempt. A closed or failed connection also ends the attempt. Later messages must not reopen it. A session failure does not need to emit a separate end event.

Do not automatically replay setup or updates. Start a new sequence at 1 for a new session. Gaps are allowed; never reuse a version after uncertain delivery, and keep versions within the message schema and JavaScript's safe integer range.