# Providers The providers FX speaks: how each is declared and where its keys and endpoints come from (§1), the adapters FX ships for them (§2), the route table FX ships (§3), and the feature names FX renamed (§4). How an adapter talks to its provider, and how each answer becomes an attempt's outcome and its bill, is the adapter contract, [adapters.md](adapters.md). What a capability's request and answer hold is [capabilities.md](capabilities.md). ## 1. Keys and endpoints Every provider FX sends requests to is **declared**: its credential (the variable that holds its key, and the header the key is sent in), its base URL (its default, and the variable that may move it), and, for a project adapter's `fetch`, the hosts its results may be downloaded from. FX's own providers are the built-in declarations below; a project declares others in its `fx.yaml`. A declaration is configuration, as a base URL is: it is not part of a route's fingerprint, and a plan does not record it. Only its `family` or its `adapter` reaches a fingerprint, by naming the adapters whose identity completes a route's contract that leaves it out ([identity.md](identity.md) §7). | Provider | Key | Header | Base URL | Default base | Download hosts | |---|---|---|---|---|---| | `gg` | `GG_API_KEY` | `authorization: Bearer ` | `GG_BASE_URL` | `https://gateway.grida.ai/v1` | | | `openai` | `OPENAI_API_KEY` | `authorization: Bearer ` | `OPENAI_BASE_URL` | `https://api.openai.com/v1` | | | `openrouter` | `OPENROUTER_API_KEY` | `authorization: Bearer ` | `OPENROUTER_BASE_URL` | `https://openrouter.ai/api/v1` | | | `fal` | `FAL_KEY` | `authorization: Key ` | `FAL_BASE_URL` (the run host) | `https://fal.run`; queue `https://queue.fal.run` | | | `tripo` | `TRIPO_API_KEY` | `authorization: Bearer ` | none | `https://openapi.tripo3d.ai/v3` | | | `elevenlabs` | `ELEVENLABS_API_KEY` | `xi-api-key: ` | `ELEVENLABS_BASE_URL` | `https://api.elevenlabs.io/v1` | | - **Codex and Grok Build are runtimes, not declarations.** The `codex` and `grok` adapters work through a program the user installed, which brings its own sign-in and network (§2): FX reads no key or base URL for them. Their names and the six above are FX's providers. - **A project declares a provider** under `providers:` in the planning project's `fx.yaml` ([store.md](store.md)), by its name, the provider part of its routes (`@acme`): ```yaml providers: acme: credential: { variable: ACME_API_KEY, header: authorization, scheme: Bearer } base_url: { variable: ACME_BASE_URL, default: "https://api.acme.test/v1" } download_hosts: [cdn.acme.test, "*.acme.test"] family: openai-compatible acme-media: credential: { variable: ACME_MEDIA_KEY } base_url: { default: "https://media.acme.test/v2" } download_hosts: [files.acme.test] adapter: adapters/acme_media.py#acme_media ``` - The name is `[a-z0-9._-]+`, as in a route. - `credential` is optional: a provider declared without one is sent no key and needs none, such as a server on this machine. Its `variable` is required. `header` defaults to `authorization` and is lowercase; `scheme` defaults to `Bearer`, and `""` sends the key bare. The key travels as `
: `, or `
: ` with no scheme. - `base_url.default` is required. It is normalized as any base URL is (below) when the file is read, and so must be `https` unless it names a loopback host. `base_url.variable` is optional; when it is set, its value replaces the default, as a built-in's does. - `download_hosts` lists the hosts a project adapter's `fetch` may download a result from: a host, or `*.` and a domain for every host below that domain (not the domain itself). It is empty when left out; an empty list permits no download through `fetch`. - `family` is the wire the provider speaks: `openai-compatible`, the one family, the OpenAI Chat Completions API. Its adapters (§2) serve the provider's `structured.generate` and `agent.turn` routes, each the default of its capability on that provider. - `adapter` names the provider's own adapter, written in Python or TypeScript in the planning project ([adapters.md](adapters.md) §9): `#`, the module's path, POSIX and relative to the planning project's root, without `./` and without `..` segments, and the name the module declares it under. It serves every capability it declares on the provider, each the default of its capability there, and its name and version or source complete the contract of each of the provider's routes ([identity.md](identity.md) §7). A declaration names a `family` or an `adapter`, not both: `providers.: a provider has a family or an adapter, not both`. - A route of a capability neither serves, or on a provider declared with neither, has no adapter: it plans and prices, a live call on it is refused with `no_route` ([protocol.md](protocol.md) §6.1), as on any provider no adapter serves, and `grida-fx doctor` reports it as `no adapter`. - A declared provider bills dollars, to the account of its key. No declaration can claim a plan, as Codex and Grok Build do (§2), and no project adapter. A variable is `[A-Za-z_][A-Za-z0-9_]*`, the `.env` file's grammar. A declaration is refused when `fx.yaml` is read (exit 2), each refusal reading `fx.yaml: providers.…: `: - a name FX ships, the eight above: `providers.: is a provider FX ships`; - a variable that a built-in declaration, an earlier declaration or the same one already reads, compared in any letter case: `providers..credential.variable: is already read for ` (or `….base_url.variable`); - a variable FX or the programs it starts read for themselves: any `GRIDA_FX_` variable, the proxy variables `HTTPS_PROXY`, `HTTP_PROXY`, `ALL_PROXY` and `NO_PROXY`, the certificate variables `SSL_CERT_FILE` and `SSL_CERT_DIR` ([adapters.md](adapters.md) §2), `PATH` and `HOME`, each in any letter case: `… is reserved for FX and the programs it starts`; - a default base URL that does not normalize: `providers..base_url.default: base_url must …`, with the base-URL sentences below. The variables Codex and Grok Build are started without beside the declared ones (`CODEX_API_KEY`, `XAI_API_KEY`, …; [Codex](../crates/grida-fx-providers/src/codex/README.md), [Grok Build](../crates/grida-fx-providers/src/grok/README.md)) are not read by FX, so a declaration may read them. - **Credential source order.** FX resolves each provider's key independently. The first available value in this order wins. 1. A nonblank value from the process environment. 2. A nonblank value from the planning project's `.env` file, when enabled. 3. The matching entry in Grida's credential store, when enabled and eligible (below). For precedence, FX trims values from the environment and the parsed `.env` and skips blanks. Different providers in the same run may obtain keys from different sources. For example, `.env` can supply `FAL_KEY` while Grida supplies `GG_API_KEY`. Only absence advances the cascade. Authentication failures are reported against the chosen credential without trying a lower-priority key. - **File source controls.** Set `GRIDA_FX_DISABLE_DOTENV=1` in the process to skip the project's `.env`, or `GRIDA_FX_DISABLE_GRIDA_STORE=1` to skip the store. Set both to use only process environment keys. Each opt-out leaves the remaining sources in the same order. The same process settings apply through the CLI and SDKs. - **Only the declared variables are read:** the eleven of the built-in declarations, then each project declaration's key and base-URL variable. Base URLs use the process environment and `.env` in the same order. - **The `.env` file is optional**, and it is read for the declared names only. Lines that name other variables are skipped without reading their values. It is refused when it is a symlink or not a regular file (`.env must be a regular file`), cannot be read (`.env could not be read`), or is not UTF-8 (`.env must be valid UTF-8`). Blank lines and `#` comments are skipped. - An assignment is `[export] NAME = value`. A line that starts with a declared name and is not an assignment is refused: `.env contains malformed assignment for on line `. - A declared name may appear only once: `.env contains duplicate key: `. - A value may be unquoted (a trailing ` #` comment is removed, and a quote inside it is refused), `'single quoted'` (literal), or `"double quoted"` (a JSON string literal: `.env contains malformed quoted value for on line `). An empty value is refused: `.env contains an empty value for `. A control character in the decoded value is refused: `.env contains an unsafe value for `. - Every refusal names the variable and the line, never the value. - Whenever FX loads provider settings with `.env` enabled, it validates the file even if process values take precedence for all declared variables. - **Grida's provider credential store** is a fallback on macOS and Linux when neither the process environment nor the project's `.env` supplies the key. FX reads the [v1 file protocol](https://github.com/gridaco/grida/blob/273961f8f050e4c9fd3df8714f1fe409484d5b00/packages/grida-auth/PROVIDER-CREDENTIALS-V1.md) and uses original synthetic fixtures based on its [compatibility fixtures](https://github.com/gridaco/grida/tree/273961f8f050e4c9fd3df8714f1fe409484d5b00/packages/grida-auth/fixtures/providers-v1), both pinned to Grida commit `273961f8f050e4c9fd3df8714f1fe409484d5b00`. - The engine reads `/providers/credentials.toml`. The home is the process `GRIDA_HOME` or, if unset, `$HOME/.grida`. If both variables are unset, the store is absent. The home must be an absolute normalized path and pass the protocol's ownership, mode, alias and ACL checks. An invalid explicit home refuses the lookup. The process alone selects the home and whether this source is enabled. - The store IDs are `gg` for `GG_API_KEY`, `openrouter` for `OPENROUTER_API_KEY`, `fal` for `FAL_KEY`, `tripo` for `TRIPO_API_KEY`, and `elevenlabs` for `ELEVENLABS_API_KEY`. The `gg` entry is a standalone Gateway API key. Account sessions and invocation grants are separate. OpenAI and project providers use their existing key sources. - The effective base URL must equal the provider's normalized default in the table above. This also applies to fal jobs on its fixed queue host. A custom base URL uses an explicit key from the environment or `.env`. - An uncached live call looks up a missing key for its provider before it reserves budget or records a job submission. Cancellation while waiting for this lookup leaves no charge or uncertain submission. A resumed run uses the same rules for new calls and resolves the key before polling an existing submission. A found key is retained for that provider during the invocation. A missing entry or refused lookup can be checked again by later calls. Offline preparation and execution and stand-in calls skip the store. Online OpenRouter discovery may use its stored key for a valid, missing selected binding ([model-selection.md](model-selection.md) §3). - A missing home, store or entry supplies no key. Invalid, inaccessible, unsafe, unsupported-version, or migration-pending storage, or a lock that cannot be acquired, refuses the lookup with a reason that omits secret values and local paths. The reader uses the protocol's shared lock and orphan-file housekeeping. Grida owns credential records, permissions and migration state. Stored secrets stay in the engine and are never injected into child process environments or written to portable records. - **A base URL** is trimmed and loses a trailing `/`. It must be an `http(s)` URL with a host, no userinfo, no query, no fragment and a valid port, and `http` is allowed only for a loopback host. The refusals are ` base_url must be an HTTP(S) URL without credentials, query, or fragment`, `… must use a valid network port` and `… must use HTTPS unless it targets a loopback host`, `` being `Grida Gateway`, `OpenAI`, `OpenRouter`, `fal` or `ElevenLabs` for a built-in, and the name for a declared provider. FX checks each configured base URL against the invocation's explicit keys and saved keys it has resolved before using the URL. A match is refused as ` holds a credential`. A custom destination with an explicit key does not itself trigger a Grida store lookup. A base URL is configuration: it is not part of a route's fingerprint. - **A built-in adapter downloads a result at the URL its provider returned.** FX owns credential isolation, bounded downloads and output checks; the provider owns the choice of download host. FX's fal image and background-removal adapters and its Tripo adapters accept `https` URLs with a DNS hostname rather than an IP literal, no userinfo, no port but 443 and no fragment, without a provider-host catalog ([fal](../crates/grida-fx-providers/src/fal/README.md), [Tripo](../crates/grida-fx-providers/src/tripo/README.md)). Their empty `download_hosts` entries do not deny these built-in downloads. GG's adapters and fal's video adapter keep their existing acceptance of any `https` URL ([GG](../crates/grida-fx-providers/src/gg/README.md)). Every download is credential-free, refuses redirects and has its adapter's response cap ([adapters.md](adapters.md) §2, §7). - **A project adapter's `fetch` downloads only from its declaration's `download_hosts`.** The URL is `https`, its host a name (not an address) that matches an entry or lies below a `*.` entry's domain, compared in lower case without a trailing `.`, with no userinfo, no port but 443 and no fragment. An empty list denies every download through `fetch` ([adapters.md](adapters.md) §9). - **Codex, Grok Build, the background service and the browser opener never inherit a declared variable.** Codex and Grok Build (§2), the background service `grida-fx start --background` starts, and the program that opens a browser start without every declared variable of the project the command works in: the planning project, the project `start` serves, or for `inspect` the project of the directory FX runs in. `view --run` and `view --plan` read no project, so their browser opener takes the declarations of the project of the directory FX runs in, or the built-in ones alone when that `fx.yaml` cannot be read. A node host ([protocol.md](protocol.md) §1), and so every program user code starts, inherits FX's environment as before: a declared variable set there reaches it, and one read only from `.env` does not. An adapter host ([adapters.md](adapters.md) §9) starts without every declared variable but its own declaration's, which it gets as FX read them, from the environment or `.env`. - **Key values are never printed,** and every key's value, a declared provider's too, is redacted from the reasons an adapter gives ([adapters.md](adapters.md) §7). `grida-fx doctor` says which keys are present and where each came from: `present (environment)`, `present (.env)`, or `present (grida)`. It explicitly checks eligible missing keys in the store to diagnose live availability. For a missing eligible key it points to Grida's provider configuration. A refused store lookup is diagnosed without keys or local paths and makes doctor exit 1. Doctor prints a `key` line for each built-in declaration, and for each of the project's declarations `provider present (environment)` (or `present (.env)`, or `missing`), or `provider needs no key` for one declared without a credential, `` being its base URL's host, with its port when the URL names one, or its default's when its variable is refused. For each declaration with an `adapter`, doctor loads it as planning does ([adapters.md](adapters.md) §9) and prints `adapter # version : (request), (job)` (`unversioned:` for one without a version), or `adapter # cannot load: `, which makes it exit 1; the routes of a capability the adapter declares are then judged as served by it. ## 2. The built-in adapters FX registers the adapters below by capability, provider and contract `adapter` ([adapters.md](adapters.md) §1), a family's adapters for each provider the planning project declares with that family, and a project adapter for each provider it declares with one ([adapters.md](adapters.md) §9), which no table lists. The tables are normative. A route's contract names the adapter that serves it as `adapter`, and its behaviour as `adapter_behavior`, written in JSON exactly as here: the string `"1"` and the number `1` are different contracts, with different fingerprints ([identity.md](identity.md) §7). Each adapter's reference, beside its code, is normative for that adapter under the adapter contract: its wire, refusals, answers, checks, statuses, costs, labels and limits. A reference's status rows override [adapters.md](adapters.md) §3.3 only where they say so. | Provider | Capability | Contract `adapter` | `adapter_behavior` | Reference | |---|---|---|---|---| | `openai` | `image.generate` | `fx-openai-image-v1` | `"1"` | [OpenAI](../crates/grida-fx-providers/src/openai/README.md) | | `openai` | `image.edit` | `fx-openai-image-v1` | `"1"` | [OpenAI](../crates/grida-fx-providers/src/openai/README.md) | | `openrouter` | `image.generate` | `openrouter-image` | `"1"` | [OpenRouter](../crates/grida-fx-providers/src/openrouter/README.md) | | `openrouter` | `image.edit` | `openrouter-image` | `"1"` | [OpenRouter](../crates/grida-fx-providers/src/openrouter/README.md) | | `openrouter` | `structured.generate` | `openrouter-structured` | `1` | [OpenRouter](../crates/grida-fx-providers/src/openrouter/README.md) | | `openrouter` | `agent.turn` | `openrouter-tool-loop` | `1` | [OpenRouter](../crates/grida-fx-providers/src/openrouter/README.md) | | `openrouter` | `music.generate` | `openrouter-music` | `1` | [OpenRouter](../crates/grida-fx-providers/src/openrouter/README.md) | | `fal` | `image.generate` | `fal-image` | `"1"` | [fal](../crates/grida-fx-providers/src/fal/README.md) | | `fal` | `image.edit` | `fal-image` | `"1"` | [fal](../crates/grida-fx-providers/src/fal/README.md) | | `fal` | `video.generate` | `fal-queue` | `1` | [fal](../crates/grida-fx-providers/src/fal/README.md) | | `fal` | `background.remove` | `fal-run-birefnet` | `1` | [fal](../crates/grida-fx-providers/src/fal/README.md) | | `tripo` | `mesh.generate` | `tripo-multiview` | `1` | [Tripo](../crates/grida-fx-providers/src/tripo/README.md) | | `tripo` | `mesh.rig` | `tripo-rig` | `1` | [Tripo](../crates/grida-fx-providers/src/tripo/README.md) | | `elevenlabs` | `sound.generate` | `elevenlabs-sound-effect` | `1` | [ElevenLabs](../crates/grida-fx-providers/src/elevenlabs/README.md) | | `elevenlabs` | `speech.generate` | `elevenlabs-speech` | `1` | [ElevenLabs](../crates/grida-fx-providers/src/elevenlabs/README.md) | | `codex` | `image.generate` | `fx-codex-image-v1` | `"2"` | [Codex](../crates/grida-fx-providers/src/codex/README.md) | | `codex` | `image.edit` | `fx-codex-image-v1` | `"2"` | [Codex](../crates/grida-fx-providers/src/codex/README.md) | | `gg` | `image.generate` | `gg-image` | `"1"` | [Grida Gateway](../crates/grida-fx-providers/src/gg/README.md) | | `gg` | `image.edit` | `gg-image` | `"1"` | [Grida Gateway](../crates/grida-fx-providers/src/gg/README.md) | | `gg` | `structured.generate` | `gg-structured` | `1` | [Grida Gateway](../crates/grida-fx-providers/src/gg/README.md) | | `gg` | `agent.turn` | `gg-tool-loop` | `1` | [Grida Gateway](../crates/grida-fx-providers/src/gg/README.md) | | `gg` | `video.generate` | `gg-video` | `1` | [Grida Gateway](../crates/grida-fx-providers/src/gg/README.md) | | `gg` | `mesh.generate` | `gg-mesh` | `1` | [Grida Gateway](../crates/grida-fx-providers/src/gg/README.md) | | `gg` | `mesh.rig` | `gg-rig` | `1` | [Grida Gateway](../crates/grida-fx-providers/src/gg/README.md) | | `grok` | `image.generate` | `fx-grok-image-v1` | `"1"` | [Grok Build](../crates/grida-fx-providers/src/grok/README.md) | | `grok` | `image.edit` | `fx-grok-image-v1` | `"1"` | [Grok Build](../crates/grida-fx-providers/src/grok/README.md) | Each row above is its capability and provider's **default**: the adapter that serves a route whose contract names no `adapter`. FX also ships these adapters, which serve only a route whose contract names them: | Provider | Capability | Contract `adapter` | `adapter_behavior` | Reference | |---|---|---|---|---| | `openrouter` | `image.generate` | `fx-openrouter-image-v1` | `"3"` | [OpenRouter](../crates/grida-fx-providers/src/openrouter/README.md) | | `openrouter` | `image.edit` | `fx-openrouter-image-v1` | `"3"` | [OpenRouter](../crates/grida-fx-providers/src/openrouter/README.md) | | `openrouter` | `image.generate` | `openrouter-image-discovered-v1` | `"1"` | [OpenRouter](../crates/grida-fx-providers/src/openrouter/README.md) | | `openrouter` | `image.edit` | `openrouter-image-discovered-v1` | `"1"` | [OpenRouter](../crates/grida-fx-providers/src/openrouter/README.md) | | `fal` | `image.generate` | `fx-fal-image-v1` | `"1"` | [fal](../crates/grida-fx-providers/src/fal/README.md) | | `fal` | `image.edit` | `fx-fal-image-v1` | `"1"` | [fal](../crates/grida-fx-providers/src/fal/README.md) | A provider the planning project declares with a `family` (§1) is served by its family's adapters below, each the default of its capability on that provider: | Family | Capability | Contract `adapter` | `adapter_behavior` | Reference | |---|---|---|---|---| | `openai-compatible` | `structured.generate` | `openai-compatible-structured` | `1` | [OpenAI-compatible](../crates/grida-fx-providers/src/openai_compatible/README.md) | | `openai-compatible` | `agent.turn` | `openai-compatible-tool-loop` | `1` | [OpenAI-compatible](../crates/grida-fx-providers/src/openai_compatible/README.md) | - A route is served by the adapter of its capability and provider that its contract's `adapter` names, in any of these tables, and by the default when it names none ([adapters.md](adapters.md) §1). A contract that names an adapter no table lists for its capability and provider, or its provider's family, and that is not its provider's declared adapter, is served by none: a call on it that must be sent is refused with `no_route` ([protocol.md](protocol.md) §6.1), and `grida-fx doctor` reports the route as `no adapter`. - A route whose contract names its adapter with another `adapter_behavior` than its row's is refused before the adapter sees the call ([adapters.md](adapters.md) §4 step 1). `background.remove` on fal has no route (§3); its behaviour is the integer `1`, as for every route outside images. - A route table's contract on a capability and provider of a row is filled in before its fingerprint is taken ([identity.md](identity.md) §7): a left-out `adapter` gets the default's, and a left-out `adapter_behavior` the behaviour of the row, in either of the first two tables, whose adapter the contract names. So a project route declared without a contract names its default, as every built-in route names its adapter, and one whose contract names only `fx-openrouter-image-v1` gets `"3"`. A declared provider's routes are filled the same way from its family's rows, or from its declared adapter's name and behaviour, the declaration read from the planning project, never from the provider's name: a route on a provider the planning project declares with neither, or of a capability its family or adapter does not serve, keeps its contract. - **The OpenRouter and fal image defaults are generic.** They serve any image model of their provider with what its image models share: the prompt, the input pictures and the provider options, and nothing FX chose for one model; an answer that is not a PNG becomes one, the same pixels ([OpenRouter](../crates/grida-fx-providers/src/openrouter/README.md), [fal](../crates/grida-fx-providers/src/fal/README.md)). The GPT Image adapters of the second table send what FX chose for GPT Image (its quality, its sizes, and on OpenRouter its moderation and routing), and the built-in OpenRouter and fal image routes name them. Up to 0.6.1 those were the only adapters of these pairs, so a project route there that named no adapter got GPT Image's request; it now gets the generic one's, under another fingerprint ([identity.md](identity.md) §7). One on OpenRouter whose contract states `adapter_behavior: "3"` without an `adapter` now names the generic adapter with a behaviour it does not serve, and a call on it is refused when it is sent ([adapters.md](adapters.md) §4 step 1); naming `adapter: fx-openrouter-image-v1` keeps GPT Image's. - **Discovered OpenRouter images** name `openrouter-image-discovered-v1`, behavior `"1"`. This separate adapter honors the standard size and background fields admitted by the model's metadata and sends one image (`n: 1`). Existing generic and GPT Image routes keep their existing request behavior and fingerprints. - **The OpenAI-compatible family** serves any model of a provider that speaks the OpenAI Chat Completions API, with what FX's structured output and agent turns need of that API and nothing chosen for one provider ([OpenAI-compatible](../crates/grida-fx-providers/src/openai_compatible/README.md)). It sends the key as the declaration says, and none for a provider declared without a credential. Its route contract may select picture detail, original structured-context pictures and the token-limit field; reasoning parameters use `provider_options`. By default it reads no cost, so each call is booked at its whole hold or cap ([adapters.md](adapters.md) §5). Its contract may opt into a documented final USD `usage.cost` and specific unbilled refusal statuses; valid reported costs win, invalid costs remain unknown, and each policy enters the route fingerprint. Its statuses follow [adapters.md](adapters.md) §3.3, except that a 408 is a possibly billed timeout (`Failed { cost, retryable: true }`), and a 429 carrying a cost or an unknown cost under the opt-in policy is a possibly billed failure too: wire compatibility does not prove non-receipt, so these repeats need new reserved attempts. The reference defines the settings and their conservative defaults. - Each reference lists the members its adapter owns, which `provider_options` may not set, and where the others go ([adapters.md](adapters.md) §8). The `codex` and `grok` adapters take none. - The `codex` and `grok` adapters work through a runtime and bill the user's own plan ([adapters.md](adapters.md) §1, §5). Every other adapter bills dollars, to the account of its provider's key (§1), a family's adapters and a project's own included. ## 3. The built-in route table [Model selection](model-selection.md) specifies independent provider preferences, canonical model metadata and automatic discovery of a selected missing image binding on GG or OpenRouter. Discovery reads that provider's APIs before offline core planning; authored tables remain authoritative and explicit `--routes` disables discovery. Pricing remains the existing allowance contract: FX maintains shipped estimates, projects may provide route prices or caps, and discovery uses a published rate where FX understands it. No provider estimate endpoint is required. Other providers and capabilities retain the project-route path. FX ships a default route table, embedded in `grida-fx`. It is the first table of the catalog ([identity.md](identity.md) §7): a project's `route_tables` override its entries, and any `--routes` file leaves it out. - It holds 29 routes over 10 capabilities. Every route MUST be served by an adapter of §2, and every capability is defined in [capabilities.md](capabilities.md). - **Prices are planning allowances** in US dollars, not provider quotes. What a call costs is settled from what the provider reports, or else from the whole hold ([adapters.md](adapters.md) §5). The video routes are priced per second, in tiers by `resolution`. - **The Codex routes, `imagegen@codex` for `image.generate` and for `image.edit`, are free:** $0 to $0, untiered. They run on the user's own Codex plan, which FX neither sees nor bills ([Codex](../crates/grida-fx-providers/src/codex/README.md)). Their adapter bills the user's plan ([adapters.md](adapters.md) §5), so a live run whose calls are all on them needs no ceiling. They declare `image_input`, `flexible_size`, `alpha`, `auto_background`, `opaque_background` and `png_output`, and the `image.generate` route also `text_to_image`: the controls their adapter honours, so no exact size and no mask. Both take at most 5 input pictures. - **The Grok Build routes, `imagine@grok` for `image.generate` and for `image.edit`, are free:** $0 to $0, untiered. They run on the user's own Grok subscription, which FX neither sees nor bills ([Grok Build](../crates/grida-fx-providers/src/grok/README.md)). Their adapter bills the user's plan ([adapters.md](adapters.md) §5), so a live run whose calls are all on them, or on them and the Codex routes, needs no ceiling. They declare `image_input`, `flexible_size`, `auto_background`, `opaque_background` and `png_output` (Grok Build draws JPEG; the answer is the same pixels as a PNG), and the `image.generate` route also `text_to_image`: so no transparency, no exact size and no mask. Both take at most 3 input pictures. - **The Grida Gateway routes' (`@gg`) prices are FX-maintained planning allowances, independent of GG's tariffs.** Usage-unit rates (`fal_output_units`, `provider_credits`) do not themselves predict a request's quantity, and a published scenario example is not a general formula. FX uses maintained allowances as it does for other variable-cost providers: `openai/gpt-image-2.5-sunburst@gg` OpenAI's image tiers, `alibaba/wan-3.0@gg` $0.05 a second at `480p`, $0.10 to $0.20 at `720p` and $0.20 at `1080p`, up to 30 seconds, the 3D routes Tripo's prices for the same models, and the text routes OpenRouter's prices for the same models, whose token rates GG's published ones equal. These allowances need no future GG pricing API; a project may replace them with its own route price or cap. A GG call is booked at GG's charge once it settles, which GG reports for every call; one whose charge has not settled in time is booked at its whole hold, as any call without a reported cost is ([adapters.md](adapters.md) §5). - **The other image routes are priced per call, in tiers by `size`** ([identity.md](identity.md) §12). A tier is named by the exact size text, such as `1024x1024`. A request whose `size` no tier names (`auto`, none, or any other `x`) is priced at the route's whole range. The plan prices a step by its `size`, and each attempt's hold is the high price of the request's own tier ([protocol.md](protocol.md) §6.1 step 6). - A tier's low is the image output at quality max for that size, at $30 per million output tokens, rounded down to the cent. The output is measured or, where only a call's bill is known, derived from that bill less an estimate of its input. The estimate is the same for every such bill: the measured input of one comparable call, a prompt and one input picture ($0.006314). Each such bill is below every high of its tier. A tier's high adds an allowance for the input, rounded up to the cent: $0.07 for a generate's prompt, and $0.21 for an edit's 16 input pictures and long prompt. - The whole range contains every tier: $0.09 to $0.70 for a generate and to $0.85 for an edit, from $0.13 on OpenRouter. - **OpenAI's highs are what an OpenAI call is booked at.** OpenAI reports token usage but no cost ([OpenAI](../crates/grida-fx-providers/src/openai/README.md)), so every OpenAI image call is booked at its whole hold, and a high below what a call can cost would under-count it. Each OpenAI high leaves room for one image output at its size, measured or derived as above. The fal and GG routes serve the same model in the same envelope, and take the same prices. - **OpenRouter's highs cover twice the output.** OpenRouter reports its cost ([OpenRouter](../crates/grida-fx-providers/src/openrouter/README.md)), so its high is only the hold. It has billed a 1024x1024 generate $0.42164: twice the output the same size cost at OpenAI directly (2 × $0.21072 = $0.42144), plus its prompt. Its tiers name only the sizes it serves ([OpenRouter](../crates/grida-fx-providers/src/openrouter/README.md)). - **An open risk.** That one bill does not show whether OpenRouter counts the output twice or the model now draws twice as much. If the model does, an OpenAI call, and a fal call whose answer reports no cost, can cost one more output than its high, and is under-counted by up to that much: a 1024x1024 generate would cost about $0.42 and be booked at $0.29. So the OpenAI and fal highs are not known to be worst cases. OpenAI's usage report for a call made since that bill settles it: one output means the doubling is OpenRouter's; two mean these highs need the same room as OpenRouter's. - A project that knows its calls better restates a route in its own route table, with tighter prices: an entry that `extends` the built-in route states only its `price`, which replaces the base's whole, tiers included ([identity.md](identity.md) §7). - **Contracts are identity.** Each contract object enters its route fingerprint, and so every cache key the route serves. Changing a contract changes every key under it. - A contract's `adapter` is the name §2 gives the adapter that serves the route, and its `adapter_behavior` is the behaviour §2 names. Every built-in route states both, so filling in a contract ([identity.md](identity.md) §7) moves none of their fingerprints. The OpenRouter and fal image routes name the GPT Image adapters of §2's second table, not their pairs' generic defaults. - The image routes carry `adapter_behavior` as a string (`"1"`, `"3"`), and every other route carries it as the integer `1`. Each adapter serves its behaviour only as spelled here: the string and the number are different contracts, with different fingerprints. - The two `openai/gpt-6-astra@openrouter` routes carry the `request_policy` of [OpenRouter's structured and agent adapters](../crates/grida-fx-providers/src/openrouter/README.md), and the structured one also `pictures: unchanged`. The two `openai/gpt-6-astra@gg` routes carry the same choices in [GG's](../crates/grida-fx-providers/src/gg/README.md) members: `image_detail: high` and `reasoning_effort: high`, and the structured one also `pictures: unchanged`. - The GG image routes carry `quality: max`, which the [OpenAI adapter](../crates/grida-fx-providers/src/openai/README.md) always sends, the GG 3D routes the `endpoint` they submit to, and the GG rig route its `check_endpoint`. - **Features** are the names [capabilities.md](capabilities.md) lists for each capability, and a route declares only what its adapter honours. So the OpenRouter and GG image routes declare no `mask`, the GG video route `text_to_video` (GG serves Wan 3.0's text operation) but no `first_last_frame` (it takes no last frame), the fal video route no `text_to_video` (an image-to-video endpoint, so its adapter refuses a request without a first frame), the GG mesh route no `quad`, and no `image.generate` route but Codex's and Grok Build's declares `image_input`, since every other one refuses references (§2). - **Input-picture limits are declared.** A route that takes input pictures declares `max_input_pictures`, the most it takes in one call: 16 on the OpenAI, OpenRouter, fal and GG `image.edit` routes (GPT Image's limit), 5 on both Codex routes, and 3 on both Grok Build routes. The plan refuses a step that would send more ([capabilities.md](capabilities.md) §1). The OpenAI, GPT Image, Codex and Grok Build adapters refuse more than their own limit, which is their routes'; the GG image adapter and the generic image adapters refuse more than their route declares, and leave a route that declares none to the provider ([GG](../crates/grida-fx-providers/src/gg/README.md)). - **Pacing is not identity.** The engine applies a route's pacing per route id, so routes of one id for several capabilities share it. The OpenAI and OpenRouter image routes declare `requests_per_minute: 150`. The 3D routes and the video routes declare `concurrency: 1`, and so do the GG image routes: GG runs one GPT Image call per organization at a time until it settles, and answers a second with a 429 ([GG](../crates/grida-fx-providers/src/gg/README.md)). The Codex routes declare `concurrency: 3`, shared by their one id: one Codex runs several turns at once (five at once drew in about the time of one), and three keeps the user's plan from being spent faster than they would by hand; a project sets its own in `fx.yaml`. The Grok Build routes declare `concurrency: 3` likewise, on their one Grok Build. A call waiting for its slot is recorded as waiting ([store.md](store.md) §8). The structured routes declare `concurrency: 4`, and the `openai/gpt-6-astra` agent routes declare `concurrency: 1`. - **Checked against Grida Models.** [`crates/grida-fx-providers/routes/models.json`](../crates/grida-fx-providers/routes/models.json), beside the table's source `default.yaml`, is a projection of the release of [Grida Models](https://github.com/gridaco/models) that `tools/make_models.py` pins (its `RELEASE`, `v1.20261014.1`, which its `--check` holds this page to): the members of its schema that the routes use, written by the tool from the release, verified against the release's `SHA256SUMS` and validated against its schema. FX never reads it when it runs. The providers crate's tests hold every route to it: - its wire ids, and the endpoint ids it sends to: fal's `/text-to-image` and `/edit`, Tripo's paths, and the GG 3D routes' `endpoint` and `check_endpoint`; GG's image and video routes by the interface of their endpoints, since FX posts to GG's `images` and `videos` APIs, not to an endpoint id; - its features, both ways: a feature the provider documents and the route's adapter honours is declared, and a declared feature that a fact could show is documented. An unknown fact never enables a feature; - its limits within the provider's: input pictures, the exact-size envelope and priced sizes, prompt length, face limit and a structured route's default output tokens; - the text routes' prices as bounds over the published token rates, never as equal to them: a `structured.generate` route's high holds its default `max_tokens` (16 000) at the highest output rate, and of two models on one capability and provider, the one whose every rate is at least the other's is priced at least as high, low and high. A fact Grida Models does not record is an exception, with its reason, in one table; an exception the facts no longer need fails. - **Shipped without a route:** `background.remove` has an adapter on fal, but no route until fal's price for it is recorded, so a call on it is `no_route` until a project's table adds one. `vision.annotate`, `vision.review` and `structured.review` have no adapter FX ships: a call on one is `no_route` even on a route a project's table adds, unless that route's provider is declared with a project adapter that declares the capability ([adapters.md](adapters.md) §9). ## 4. Renamed features A feature has one name. These names are not features, and a step that requires one is refused while planning as no feature of its capability, naming FX's instead ([capabilities.md](capabilities.md) §1): `masked_edit` is `mask`, `transparent_background` is `alpha`, and `reference_images` and `data_url_reference_input` are `image_input`.