Skip to content
FilmOpen documentation

fal: technical notes

These notes gather what fal documents about its API, for anyone comparing platforms or building on FilmOpen. The steps for getting a key are on fal. Every page in Sources was read on 15 September 2026.

  • Console facts. What fal’s site showed on 15 September 2026, while an account was opened with Google, is marked (console).
  • “Not documented” means fal’s pages say nothing about it.

Account and money

Section titled “Account and money”
  • Sign-in: GitHub, Google, Microsoft or single sign-on, with no sign-up by e-mail address and password. Continuing accepts fal’s Terms of Service and Privacy Policy (sign-in page).
    • One account per way of signing in. Each way makes a separate account, except that Google and GitHub with the same e-mail address share one; single sign-on is always separate (accounts and identity). Whether a Microsoft sign-in joins them: not documented.
    • After sign-in fal opened its dashboard, which shows the balance as Credits (console).
    • The dashboard’s Getting started list: create an account, add a payment method (Set up billing), add credits, and generate a first image or video (console).
  • Two-factor sign-in, phone and identity checks: not documented. Signing in with Google asked for none (console).
  • Teams: a new user gets a personal account. A team has its own keys, apps and billing, and its members have roles (accounts and identity, teams).
  • Billing: prepaid credits, drawn down as they are used (pricing).
  • The terms on money (terms):
    • payment by card or ACH, in US dollars;
    • prices exclude taxes;
    • credits expire 365 days after purchase, and free or promotional credits after 90;
    • credits are non-refundable.
  • What is charged: outputs made successfully, and time in the queue is free (pricing). Errors on fal’s side (5xx) are never charged, cold starts are not charged, and a client error such as a 422 may be, when a runner had already spent GPU time on the request (FAQ).
  • Smallest purchase, fees, automatic top-up and spending limits: not documented.
  • Settings (console):
    • The Settings menu: Account, Notification Settings, Usage, Credits & Tiers, Billing, API Keys, Webhooks, Activity, Errors and Request History.
    • The settings pages’ side list adds Address, Concurrency Limits, Invoices, Log Drains, Log Privacy and Training History.
  • Concurrency (concurrency limits):
    • a new account runs 2 requests at a time;
    • the limit rises with the invoices paid over the last four weeks, to 40 without talking to sales;
    • requests over it wait in the queue, and fal may set limits of its own on busy models.

Keys

Section titled “Keys”
  • Where: Settings → API Keys (console), at fal.ai/dashboard/keys.
  • Creating one (console):
    • Add key opens New Key, which asks for a Scope and a Description.
    • fal describes the API scope as for running models and calling inference endpoints, unable to manage keys, billing, usage or compute, and recommends it for most uses.
    • The window then shows Your new key, with Copy Key, and suggests storing the key in the environment, such as GitHub Secrets or .env.local.
  • Scopes (authentication, Platform API authentication):
    • API reaches the models and most Platform APIs;
    • ADMIN adds managing apps, and the Platform APIs that need it.
  • Shown once: a key must be copied when it is created (authentication).
  • Format: a key made through the Platform API is key_id:key_secret (creating a key). For a key made on the keys page: not documented.
  • A team’s keys belong to the team; only its admins create or delete them (teams).
  • A key made at sign-up: none. A new account’s API Keys page lists no key, under the columns Description, Key, Created At, Tags and Scope (console).
  • Expiry: not documented.
  • Checking a key: GET https://api.fal.ai/v1/models/pricing?endpoint_id=… needs a key and returns prices (pricing API).

Calling the API

Section titled “Calling the API”
  • Header: Authorization: Key <key>; fal’s SDKs read FAL_KEY (authentication).
  • The queue (queue):
    • POST https://queue.fal.run/<model_id> returns a request_id, with URLs for its status and result;
    • the status is IN_QUEUE, IN_PROGRESS or COMPLETED;
    • PUT …/requests/<request_id>/cancel cancels a request;
    • fal itself retries server errors, timeouts and rate limits in the queue.
  • Webhooks: ?fal_webhook=<url>. Deliveries are retried for about an hour, and signed with ED25519 against keys fal publishes (webhooks).
  • Synchronous calls: https://fal.run/<model_id>, without the queue (synchronous).
  • Realtime: WebSocket endpoints for a few models (real-time).
  • Errors (request errors):
    • The error itself: a body with detail and error_type, the type also in the X-Fal-Error-Type header.
    • Common codes: timeouts are 504, a runner’s failures 502 or 503, and a client’s cancellation 499.
  • Idempotency keys: not documented.
  • SDKs: fal documents a Dart client, fal_client (Dart client, pub.dev).

The models FilmOpen uses

Section titled “The models FilmOpen uses”

Prices from each model’s page:

Model Endpoint Price
Nano Banana Pro fal-ai/nano-banana-pro, and /edit $0.15 an image at 1K or 2K, $0.30 at 4K
Nano Banana 2 fal-ai/nano-banana-2, and /edit $0.08 an image at 1K; 0.75 times at 0.5K, 1.5 times at 2K, twice at 4K; $0.002 more with high thinking
GPT Image 2.5 openai/gpt-image-2.5/sunburst/… and /flare/… Per million tokens: text $5 in, $1.25 cached, $10 out; image $8 in, $2 cached, $30 out
HiDream-O1-Image fal-ai/hidream-o1-image $0.01 a megapixel
Z-Image-Turbo fal-ai/z-image/turbo $0.005 a megapixel
Qwen-Image-Edit-2511 fal-ai/qwen-image-edit-2511 $0.03 a megapixel
FLUX.2 [klein] 4B fal-ai/flux-2/klein/4b/edit $0.01 a megapixel
Veo 3.1 fal-ai/veo3.1/lite/… $0.05 a second at 720p with sound, $0.03 without
Kling 3.0 fal-ai/kling-video/v3/standard/… $0.084 a second without sound, $0.126 with
Seedance 2.5 bytedance/seedance-2.5/… About $0.22 a second at 480p, fal’s estimate
MiniMax H3 minimax/h3-max/…, minimax/h3-max-turbo/… $0.05 a second at 480p; Turbo $0.025
LTX-2.5 lightricks/ltx-2.5/…/fast $0.09 a second at 720p
Kling Avatar 2.0 fal-ai/kling-video/ai-avatar/v2/standard $0.0562 a second
Eleven v3 fal-ai/elevenlabs/tts/eleven-v3, …/text-to-dialogue/eleven-v3 $0.10 per 1,000 characters
  • Web search adds $0.015 to a Nano Banana request.
  • Voice design: fal-ai/elevenlabs/text-to-voice/design/eleven-v3 makes a voice from a description, at $0.10 per 1,000 characters the voice performs (voice design), and returns previews and the saved voice’s voice_id (its API).
    • Using the voice. The dialogue endpoint takes a voice’s name or id; the speech endpoint’s voice mentions no id.
    • Not documented: where fal keeps a saved voice, and for how long.

Media in

Section titled “Media in”
  • Input files (fal CDN):
    • public URLs that serve the file directly;
    • links presigned on S3, Google Cloud Storage or R2;
    • base64 data URIs, which fal advises against beyond a few kilobytes.
  • Uploads go through fal’s SDKs to its storage and need the key; large files go up in 10 MB chunks (fal CDN).
  • Not documented: a REST upload endpoint, size limits, and whether an input URL may redirect.

Media out

Section titled “Media out”
  • Results are kept on fal’s CDN, under fal.media, and are public by default, so downloading one needs no key (fal CDN, file access controls).
  • For how long: at least 7 days by default (FAQ).
    • For one request: its X-Fal-Object-Lifecycle-Preference header sets its own expiry (media expiration).
    • For the account: its storage settings set a default (storage).
  • Private results: a request can make its files private, which are then read with a token or a signed link (file access controls).
  • Request payloads are kept 30 days by default; X-Fal-Store-IO: 0 keeps none (media expiration).
  • Writing results straight to your own storage: not documented.

Usage and cost

Section titled “Usage and cost”
  • A finished request reports its inference time; no cost field is documented (queue).
  • The usage API: GET https://api.fal.ai/v1/models/usage needs an ADMIN key, and gives quantities, unit prices and costs by endpoint, key and time (usage API). How late it reports: not documented.
  • Charged or not: errors on fal’s side are never charged, and a 422 may be when a runner had already spent GPU time (FAQ); time in the queue is free (pricing). Cancelled requests: not documented.

Open questions

Section titled “Open questions”
  • What is the smallest purchase, and does fal offer automatic top-up or a spending limit?
  • Does the pricing read that checks a key cost anything?
  • Whose usage does a realtime token book to?
  • Does fal train on customers’ inputs and outputs? Its data processing addendum was not read.
  • Where is a designed voice kept, and does the speech endpoint take its id?

Sources

Section titled “Sources”

Read on 15 September 2026: