Repository navigation
Fal Native
Everything on this page needs the FAL_NATIVE_ENABLED feature flag, which is off by default.
Turn it on under Dashboard → Settings → Feature Flags or set FAL_NATIVE_ENABLED=true. With
the flag off, /v1/fal/* and /api/providers/{id}/fal answer 404, the provider page has no
native panel, and Fal requests on the image, video and music routes keep their established
request shape, endpoint mapping and response format.
Add a Fal.ai API-key connection under Dashboard → Providers → Fal.ai. The provider page contains a native model panel with catalog search, category filtering, pagination, schema loading, typed controls, ordered reference uploads, JSON input, job retrieval, cancellation, and artifact downloads. Select the connection before loading its schema.
OmniRoute's provider ID is fal-ai. The native endpoint_id is a separate value such as
openai/gpt-image-2.5/sunburst/edit. Qualified publisher IDs are preserved. Historical
short IDs have explicit mappings in open-sse/config/falEndpoint.ts.
Seedream, Dreamina and Recraft historical selections map explicitly to their fal-ai/
endpoints. Native google/..., xai/... and openai/... publishers remain unchanged.
On the image, video and music routes, a selection whose first segment is not a known publisher
is a first-party app and gets the fal-ai/ owner, so fal-ai/aura-flow reaches
fal-ai/aura-flow. Use POST /v1/fal/run for a publisher outside that list; it takes the
endpoint_id unchanged.
The retained Bria 3.2 alias keeps its historical destination; both its old and prefixed
OpenAPI URLs returned 404 on 2026-11-03. This is upstream availability evidence, not a
reason to remove the registry entry or route it to a different publisher.
GET /v1/fal/models accepts q, category, cursor, limit, and status. Pass the returned
next_cursor with the same filters to retrieve another page. Discovery does not prove that
an account can run a paid model. Missing metadata does not prevent native execution.
GET /v1/fal/models?endpoint_id=... lazily loads the endpoint's OpenAPI schema and returns its
inputs, required fields, documented reasoning controls, category, kind, and transports.
Schemas are cached for one hour per provider connection. refresh=true reloads an automatic
cache entry. connection_id selects a connection within the caller's permitted scope.
Schema errors stop execution; they do not become permissive input validation.
The authenticated management API at /api/providers/{id}/fal supports:
-
GET: catalog search or schema loading for that connection. -
PUT: register{ "endpoint_id": "owner/app", "openapi": { ... }, "metadata": { ... } }. Registration compiles and validates the supplied OpenAPI input schema before storing it. Use this for private endpoints or incomplete discovery. It does not perform paid inference. -
DELETE ?endpoint_id=...: remove an override/cache entry so the next schema read uses upstream discovery again. Manual overrides otherwise remain pinned during refresh.
These management operations require the existing management authorization policy. All execution URLs are pinned to Fal hosts; neither a registered endpoint nor a job can act as an arbitrary URL proxy. External schema references are rejected without fetching them.
The examples use the same JSON envelopes exercised by tests/unit/fal-native-routes.test.ts.
They require a real Fal connection and may incur upstream charges when executed.
curl "$OMNIROUTE_URL/v1/fal/run" \
-H "Authorization: Bearer $OMNIROUTE_API_KEY" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: my-3d-request-1' \
-d '{
"endpoint_id": "fal-ai/hunyuan3d-v21",
"transport": "queue",
"input": {"input_image_url": "https://example.com/source.png"}
}'The request accepts an optional connection_id. input contains exactly the model's
documented fields. Values are validated without coercion, default insertion, clamping,
or removal. Explicit false, 0, nullable values, arrays, and nested objects are retained.
Unsupported controls produce a validation error. Model-native limits come from its schema.
When an upstream dependency is expressed only in prose, upstream remains authoritative;
an operator can encode the dependency in a schema override.
Use multipart form data for uploads: endpoint_id, transport, and input (a JSON string)
are envelope fields. File field names are native input names. A name ending in [] creates
an ordered array, including when only one file is uploaded. Files become data URIs and
are then checked against the endpoint schema. Existing public URLs, data URIs, and native
Base64 strings can be supplied in JSON when the endpoint accepts them. OmniRoute does not
fetch client-supplied URLs while preparing native requests.
The existing image generation/edit routes retain compatibility envelopes. New qualified
image endpoints use their schemas; size maps to documented image_size, n to
num_images, and mask to mask_url. Use fal_input for complex native fields. Image edits
preserve additional JSON and multipart options instead of rebuilding a prompt-only body.
Known historical FLUX and video/music routes retain their existing defaults. Other native
music models do not receive ACE-Step's tags request shape. Use /v1/fal/run for TTS,
transcription, audio transformations, 3D, analysis, workflow/training jobs, and capabilities
that do not fit an existing compatibility response.
Queue submission returns HTTP 202 with a local id, upstream request_id, job kind, and
gateway status/result/cancellation URLs. Job ownership and the selected provider connection
are persisted in SQLite's existing key_value table; no migration is needed.
curl "$OMNIROUTE_URL/v1/fal/jobs/$JOB_ID?result=true" \
-H "Authorization: Bearer $OMNIROUTE_API_KEY"
curl -X DELETE "$OMNIROUTE_URL/v1/fal/jobs/$JOB_ID" \
-H "Authorization: Bearer $OMNIROUTE_API_KEY"GET only polls/retrieves the original job. It never submits a generation or records another dispatch. DELETE uses the upstream cancellation URL when provided. An in-progress "CANCELLATION_REQUESTED" response does not claim that generation has stopped. Retrieval and cancellation continue after a key's spend allowance is exhausted, while key status, model, endpoint, and connection authorization still apply.
Use a stable Idempotency-Key for queue requests. OmniRoute reserves its receipt before
dispatch. Repeating the same key and input returns the receipt; changing the input is an
error. Transport failures retain "SUBMISSION_UNKNOWN" rather than retrying an uncertain
submission. Retry with the same key to recover the local ID after a disconnect. If Fal did
not return an upstream request ID, the gateway cannot determine whether the job ran; inspect
the Fal account's request history before issuing a new idempotency key. Cancellation is
unavailable when upstream did not provide a cancellation URL.
The dashboard reserves an immutable submission snapshot before dispatch and reads
X-Request-ID on every response status before parsing its body. Recover original
submission reuses the original queue input and key, including after an error or abort.
New generation explicitly allocates another key and can incur another charge. Editing
the draft never changes the retained recovery snapshot. A synchronous lock prevents
concurrent clicks from creating separate submissions.
This tab keeps up to 20 recovery receipts in session storage: endpoint, connection, transport, key, local job ID, status and a SHA-256 input fingerprint. Credentials and input payloads are not persisted. After reload, restore the exact draft before recovery; reordered object keys are equivalent, while array order, null, false and zero remain significant. Switch back to the original connection to recover its receipt. "SUBMISSION_UNKNOWN" stays visibly uncertain. A receipt without an upstream ID cannot recover a missing upstream result.
Only GET requests retry on 429/503, at most twice. Retry-After delays up to five seconds are honored; longer delays are returned to the client instead of retrying early. Inference POSTs and WebSocket messages are not retried. Client abort/deadline signals stop HTTP waits and close realtime sockets. A queue timeout/disconnect does not mean upstream work was cancelled.
transport: "stream" forwards actual Fal SSE output in order. It requires a documented
/stream schema path or catalog metadata.stream_url; a management override can supply
that metadata when catalog discovery omits it. Streaming preserves native partial/final
and separate reasoning fields. Queue logs/status are never presented as generated tokens.
transport: "realtime" opens a server-side WebSocket and returns native results as SSE.
The built-in fast-LCM contract uses the official /realtime OpenAPI components, with the
optional string/URI image_url from Fal's official realtime guide. That guide and the
published components differ: the latter omit image_url. The two sources, retrieval date,
required prompt and published field limits are recorded in realtimeSchema.json; the
unmodified upstream document is a test fixture. HTTP validation remains separate and strict.
Fast-turbo currently has no discoverable usable schema (404 on 2026-11-03), so it is not
advertised solely because the guide mentions its transport.
For another verified realtime endpoint, register an OpenAPI override containing
"x-fal-realtime": {"path": "/realtime", "input_schema": {"type":"object", ...}}.
The same transport-specific compiled validator checks the initial and every later message.
Cached HTTP definitions do not supply realtime validators. Overrides remain scoped to their
connection and pinned during refresh. Existing path-only overrides remain stored, but do
not advertise realtime; upgrade them with a valid input_schema. Registration rejects an
invalid upgrade. Ordinary direct/queue/HTTP-WebSocket inputs continue using the HTTP schema.
The response's X-Request-ID is the realtime job ID. Send additional inputs with
POST /v1/fal/jobs/{id} and { "input": { ... } }. Each message passes the gateway's
authorization, quota, budget, and schema checks before it is sent on the existing socket.
DELETE or disconnect closes the socket. API keys never leave the server. Native MessagePack
output is decoded; native binary values remain available as binary_base64, and binary
image content additionally gets an authenticated download. No completion semantics are
invented for a persistent connection.
Realtime sockets are process-local and expire at the configured upstream request deadline. Repeated messages must reach the same worker; a restart or another worker returns 410 instead of silently opening a new billable session. HTTP(S) CONNECT proxies are supported; edge relays and other proxy transports explicitly reject realtime. The dashboard can start and stop a realtime stream; repeated-message clients use the native POST API.
transport: "http-websocket" implements Fal's separate JSON/HTTP wire protocol at
wss://ws.fal.run/{endpoint_id}. It works with the ordinary HTTP input schema. The server
sends the input object directly, receives start with request ID/status/headers, then raw
body chunks and end with matching request ID/status/timing. MessagePack is not involved.
The gateway emits http-start and native SSE events where applicable. SSE response completion
emits http-end with HTTP metadata, without replacing the model's final snapshot; failed HTTP
responses emit error. JSON/text and binary responses emit final or error with the output
and HTTP metadata. Cumulative model output replaces the previous snapshot. Non-JSON error
text and upstream status/content type remain available.
Binary responses are delivered through authenticated
GET /v1/fal/jobs/{id}?artifact={file_id} downloads with their content type and filename;
the event contains an artifact URL. This avoids converting binary HTTP response bodies into
text. Files expire after 10 minutes, reside on the same worker, have a 32 MiB response limit
and a shared 128 MiB cache limit (oldest files may be evicted sooner). Fetch promptly.
Registered exact operation IDs such as fal-ai/any-llm/stream retain their own HTTP input
schema and path; the gateway never appends a second /stream. Register the operation's
schema when discovery exposes only the parent app. Final snapshots preserve explicit
null, false, zero and empty text; these values do not mean that completion is missing.
After end, clients can submit another invocation with POST /v1/fal/jobs/{id}. Every
invocation repeats authorization, quota, budget and schema checks and records one attributed
dispatch. A pending invocation returns 409 rather than accepting a duplicate. Each invocation
has a deadline; the socket also has the request lifetime limit. Disconnects never reconnect
or replay input. Cancellation, worker affinity and proxy limitations match realtime.
The dashboard incrementally decodes UTF-8/SSE across chunk boundaries, preserves native event names, extracts and deduplicates downloads, and retains the latest 40 native events. Partial, final and reasoning values remain separate. Truncated frames or upstream errors remain visible without deleting files already received. Stopping the reader releases it and closes a socket; it does not claim that a queued generation was cancelled. The JSON editor accepts only a non-null object; invalid text remains editable and blocks execution.
Native JSON responses contain output (the original structured result) and artifacts
(all discovered media/file URLs with their original metadata and location in the result).
Meshes, textures, previews, filenames, MIME types, formats, dimensions, and durations remain
available without format conversion. The dashboard links every artifact for download;
interactive 3D rendering is not required. Fal media expiration still applies.
Sunburst's quality=max does not add an undocumented thinking flag. Wan's enable_thinking
and any-LLM's reasoning boolean retain their separate meanings. Reasoning controls appear
only when present in the schema. Reasoning output remains inside native output, separate
from the final answer where Fal provides separate fields.
Native dispatches use existing credential selection, connection scopes, account proxies, key rate/quota/budget checks, sanitized errors, and attributed call logs. A schema/catalog entry is not pricing evidence. Native calls with unknown prices invoke OmniRoute's existing unpriced-usage policy; a limited key fails closed for subsequent inference until its allowance is reset or pricing/policy is configured. This also covers uncertain, potentially billable submissions. Unlimited keys remain usable. Retrieval does not charge the same job again. This implementation does not report invented dollar costs for catalog-only models.
| Capability | Execution / delivery | Verification |
|---|---|---|
| Four GPT Image 2.5 Sunburst/Flare generation/edit endpoints | Compatibility images and native inputs; ordered references, masks, dimensions, quality=max
|
Official schemas; mocked adapter regressions |
| Wan 3.0 reference-to-video | Native queue/direct; image/video/audio references and thinking booleans | Official schema; mocked validation |
| Music / TTS / transcription / audio transformation | Separate native schemas; ACE-Step, Kokoro, Whisper, Demucs and isolation fixtures | Official schemas; mocked validation |
| 3D and multiple assets | Native queue/direct; mesh, textures and preview downloads | Hunyuan3D schema; mocked route/result lifecycle |
| Text / vision / mixed analysis | Schema-driven native input and unmodified structured output | Any-LLM reasoning fixture; other discovered schemas validated on demand |
| Workflows / training / future categories | Native schema-driven model APIs, preserving catalog kind | Adapter path available; account-specific endpoints not live-tested |
| Direct execution | One Fal HTTP POST | Mock-tested |
| Queue submit / status / result / cancel | Persisted receipt; trusted upstream tracking URLs; no regeneration on GET | Mock-tested, including scope, cancellation and budget recovery |
| Generation/token SSE | Native SSE; explicit schema/metadata transport declaration | Mock-tested framing and ordering; no paid live test |
| Realtime WebSocket | Validated MessagePack inputs; native SSE output; per-message gateway checks | Official transport guide; mocked socket protocol and abort cleanup |
| HTTP over WebSockets | Ordinary HTTP schema; start/body/end; native text/SSE and authenticated binary downloads | Official wire documentation; mock peer and real-route authorization/accounting tests |
| Other/undocumented transports | Explicitly unavailable until supported schema/transport information exists | Unsupported, not inferred from category names |
Fixtures in tests/fixtures/fal/ were fetched from Fal's official model API on 2026-11-03.
They are discovery/schema evidence. All inference tests use mocked upstream responses;
no paid upstream inference or live transport validation was performed. Account access,
upstream behavior, prose-only constraints, and client rendering support remain separate
from schema validation and mocked protocol coverage.
Sources: model search and OpenAPI, queue, streaming, realtime, HTTP over WebSockets.
OmniRoute · Website · npm · Docker Hub
- Setup Guide
- User Guide
- Features
- Quick Start (Docker)
- Electron Desktop App
- Termux (Android)
- PWA Guide
- MCP Server
- A2A Server
- Agent Protocols
- OpenCode Plugin
- Webhooks
- Cloud Agents
- Skills
- Memory
- Evals
- Gamification
- Guardrails
- Compliance
- Error Sanitization
- Public Credentials
- Route Guard Tiers
- Stealth Guide
- CLI Token Auth