Headers

Request headers

Levers you send. Each one narrows the pool; they combine. x-aile-lender and x-aile-exclude-lender still work as the old names of x-aile-sharer and x-aile-exclude-sharer.

Header	Value	Effect
`x-aile-capacity`	`local` \| `nodeless` \| `node`	Which kind of capacity may serve. Must agree with the model: `local` only with a `local/` model, `node`/`nodeless` never with one.
`x-aile-provider`	provider id, `local`, `any`, or a comma list	Names the provider for a bare model id. Alias-resolved (`cc` → `claude`). Unknown value → `400` naming `GET /v1/models`. The model is sent to it as written; a prefix naming the same provider is dropped (so `groq/compound` needs `groq/groq/compound`). `any`, or several ids comma-separated (up to 64), lets a bare id use each provider that lists it, cheapest first, never self-hosted, as `auto/<model>` does; a list also limits `auto/`, and one provider beside `auto/` is a `400`. It needs an API key, and on a key pinned to one provider it is a `400`. See Any provider.
`x-aile-exclude-provider`	provider ids, comma-separated	Never these providers, for this request (up to 50): `auto/` skips them, and a model naming one is a `400` before anything is held. Adds to a key's Never these providers; `local` is refused (that is the key's Allow self-hosted model).
`x-aile-account`	account id	Pin one linked account.
`x-aile-node`	node id	Pin one machine.
`x-aile-sharer`	sharer handle, or a comma list	Pin one seller; any of their machines. The handle on their marketplace card (`L` + 16 hex). Several handles (up to 50) allow only those sellers, cheapest first; on a key with Only these sharers the request may pick among them, never add one. When none of them is sharing the model, `503` with `refusedBy: "x-aile-sharer"`.
`x-aile-exclude-sharer`	sharer handles, comma-separated	Never served by these sellers, for this request (up to 50); the next sharer serves. Adds to a key's Never these sharers and never takes one off; works without a key too. A malformed handle (anything but `L` + 16 hex) is a `400`, and so are excluding every sharer `x-aile-sharer` asks for, and excluding the sharer the key is pinned to. When it rules out every sharer for the model, the answer is `503` with `refusedBy: "x-aile-exclude-lender"`: "every sharer online for `<model>` is blocked by x-aile-exclude-sharer".
`x-aile-verified`	`1` \| `true` \| `yes`	Attested subscriptions only.
`x-aile-max-price`	`8` or `80%`	Absolute $/Mtok (a sharer's input and output price must both be at or under it), or a share of the higher of the model's published input and output rates.
`x-aile-min-price`	`20%`	A price floor: a sharer whose input or output price is under that share of the model's list is skipped, here more than 80% off. Above 0 and at most 100%; anything else is a `400`. The higher of it and the key's Max discount binds. Checked again on the quote that bills; when it leaves nobody, `503` with `refusedBy: "x-aile-min-price"`. Token-priced endpoints only. See A price floor.
`x-aile-max-cost`	dollars: `0.50`, `$2`, `0.000250`	The most this one request may be charged: above 0, at most `10000`, at most 6 decimals; a leading `$` is allowed. Anything else is a `400`. The lowest of this header, the key's Max cost per request and a route target's own binds, so it can lower a key's cap and never raise it; it works without a key too. On chat a sharer quoting above it is passed over, the request is sent the output cap it is priced at, and the charge never exceeds it; when no sharer fits, a `402` (with no payment document) or, in a route, the next target. A chat request the output cap cannot bound (`n` other than 1, a runtime's own `n_predict`/`n_cmpl`, a provider that sends no output cap such as `codex`, a thinking budget on top of `max_tokens`) is a `400` naming the cap, or in a route the next target. On the non-chat endpoints a request whose hold is above it is a `402` before anything is held, and so is an agent tool call (`POST /mcp/call`, `use_agent_tool`) priced above it. The MCP model tools do not pass it on. See Capping the cost of a request.
`x-aile-auto-tier`	`light` \| `standard` \| `heavy`	Auto routes only: serve this request from that tier, whatever its shape. Any other value is a `400` on an auto route and ignored elsewhere, so one client config serves both. See Auto routes.
`x-aile-session`	your id	Account affinity for a conversation. The ids clients already send work too (`x-claude-code-session-id`, Codex's `session-id`, `x-session-affinity`, `x-session-id`, a body `session_id`); a body `prompt_cache_key` pins each conversation under it, not everything sharing it; a multi-turn conversation sending none is recognised by its opening.
`Idempotency-Key`	your id	Dedupe over the balance reservation. A replay is `409` and does not fail over.
`x-aile-image-store`	`url` \| `none`	Chat and `/v1/images/generations`, where the deployment hosts images: `url` returns generated images as links that expire instead of inline base64; `none` always keeps them inline. On `/v1/images/generations`, `url` with a stream or keyless x402 is a `400`.
`x-aile-image-watermark`	`on`	`/v1/images/generations` on ByteDance Ark (`byteplus`, `volcengine`, `doubao`): keeps Ark's visible "AI generated" mark, which is off by default. Ignored elsewhere.
`x-aile-data-collection`	`deny` \| `allow`	`deny` refuses any provider whose published data policy is not a sourced "does not train" (self-hosted capacity too), with a `400` before anything is held. `allow` lifts nothing a key setting denies. Any other value is a `400`.
`x-aile-redact`	`on` \| `off`	Chat endpoints. Secret redaction is on by default: private keys, API keys, `.env` values and recovery phrases in the prompt are replaced by placeholders before the request leaves Aile, and put back in the answer. `off` sends this request as written; `on` redacts it even on a key with Hide secrets unticked. Any other value is a `400`. See Privacy.
`x-aile-hidden-prompt`	`deny` \| `allow`	`deny` keeps the request off any sharer account whose upstream was measured adding a prompt of its own to every request. Accounts never measured are still used. When it rules out every sharer, `503` with `refusedBy: "x-aile-hidden-prompt"`. `allow` lifts nothing a key setting denies. Any other value is a `400`.
`X-Aile-Tag`	a short tag	Groups your spend on the usage tab and in `GET /keys/usage`: letters, digits and `. _ : / -`, up to 64 characters. Anything else is not stored.
`HTTP-Referer`	your app's URL	Only the hostname is kept, to group your spend by app. Spoofable and display only; a hostname many accounts send may be listed on /stats. `X-Title` is never stored.
`X-End-User`	your end user's id	On any keyed request: an opaque id (up to 128 printable ASCII characters) recorded on the usage row, to group your spend. On a key that is not a partner's, a value containing `@` is dropped. On a partner credit account a user the partner has blocked is refused `403`.

The provider, excluded-provider, sharer, excluded-sharer, node, verified, account and capacity levers, and x-aile-max-cost, apply on every /v1 endpoint; x-aile-max-price and x-aile-min-price only where the endpoint bills tokens. The non-chat endpoints take <provider>/<model> ids only, so there x-aile-provider must match the prefix and any does nothing. Each list header (x-aile-provider, x-aile-exclude-provider, x-aile-sharer, x-aile-exclude-sharer) longer than 4 KiB is a 400.

x-aile-max-price as a percentage requires a model in the body. A model with no published list price is refused with a 404 before the percentage is read. A malformed value is a 400, never a silently ignored header.

A header narrows a pinned key filter, never widens it

Provider, sharer, node, a price ceiling, a price floor and a cost cap can be pinned to a key for clients that cannot set headers. A header naming a different provider, sharer or node than the key's pin is refused; a looser price ceiling, a lower price floor or a higher x-aile-max-cost is held to the key's. A key's sharer lists and excluded providers have no header that lifts them: x-aile-exclude-sharer and x-aile-exclude-provider only add to them, and x-aile-sharer naming a sharer the key blocks, or one its allowed sharers leave out, is a 400. See Choosing a sharer.

Not consulted

x-aile-region is ignored. It was closed as a security hole: only the sharer's own server-derived country code routes egress, because a caller-supplied region is a request to be routed somewhere, not a fact about anything.

Operator only

x-aile-upstream, x-aile-upstream-port, x-aile-refresh-upstream and x-aile-refresh-upstream-port are gated behind an override permission and are not a public lever. x-aile-peer-ip is internal to the relay-to-node hop.

Response headers

What happened. These arrive with the response head (on a stream, before the first token).

Header	Value
`x-aile-sharer`	The serving sharer's internal id, also sent as `x-aile-lender`. Not their handle: it cannot be sent back as the request header.
`x-aile-node`	The serving machine. Omitted on a nodeless serve.
`x-aile-provider`	Provider that served.
`x-aile-account`	Account that served.
`x-aile-capacity`	`subscription` \| `nodeless` \| `nodeless-oauth` \| `local`.
`x-aile-blind`	`true` on a relayed subscription; `false` when Aile terminated TLS itself, or on self-hosted capacity, whose machine reads the prompt.
`x-aile-data-notice`	`trains-on-prompts`: the model's publisher trains on the prompts and completions sent to it (Meta's contributor tier). Absent otherwise.
`x-aile-model`	The model it was priced on: `<provider>/<model>` (a bare id routed by header or key pin included), or `local/<id>` for self-hosted.
`x-aile-price`	Quoted USD; a key's balance can be billed past it with no `max_tokens`, on a route that sends no cap (codex), when tools or thinking raise the cap sent upstream, or when the provider reports cache writes (billed at up to 2x input), or when a tool the provider runs on its own servers on a route that bills its reported usage is declared (`hosted_tools` on `/v1/models`, which also lists what each X post it fetches adds).
`x-aile-cost`	What this request was charged (`$0.0123`). Buffered `2xx` chat replies only; a JSON body's `usage.cost` carries the same figure in USD as a number. Live streams and the non-chat endpoints send neither, a `stream: true` reply Aile had to buffer (x402, or a provider that cannot stream) sends the header but no body figure, and a held reply only the body figure: look those up with `GET /v1/generation`. `$0.0` when a stake window covered it; absent when nothing was committed.
`x-aile-attempts`	How many sharers were dialled.
`x-aile-session-affinity`	`fresh`, or the pinned-session verdict. Can read `pinned` on a request that sends no session id, when the reasoning or tool call id it sends back from the previous answer names the account that produced it.
`x-aile-combo-entry`	Index into a named route's fallback chain.
`x-aile-auto-tier`	An auto route only: the tier chosen, `light`, `standard` or `heavy`, after the capability check; a higher tier that served is in `x-aile-auto-escalated`. Also sent on an `x-aile-edge-hold` reply. See Auto routes.
`x-aile-auto-reason`	Why that tier: `header`, `reasoning`, `long-prompt`, `small`, `default` or `pinned` (a conversation keeping its tier), plus `+window` or `+vision` when a model that could not take the prompt or the image moved it up. Also sent on an `x-aile-edge-hold` reply.
`x-aile-auto-escalated`	The tier that served, only when it is above `x-aile-auto-tier` because the lower one had no sharer or failed. Served replies only, never on an `x-aile-edge-hold` reply.
`x-aile-auto-effort`	The effort Aile wrote from the target that served. On `/v1/messages`, `none` and `minimal` are written as the Claude model's lowest level. Absent when the request set its own reasoning, the target has no `effort`, or on `/v1/messages` the Claude model takes none. Served replies only; on an `x-aile-edge-hold` reply only from a route's last entry.
`x-aile-verified-model`	The model the response claims, when confirmed.
`x-aile-verified`	`false`, and only on a confirmed served-model mismatch.
`x-aile-error`	Classification tag on a non-retryable error, e.g. `context_overflow`, or `edge_deadline` when a non-streaming request outlived the deployment's buffered deadline.
`x-aile-service-tier-normalized`	Set when the service tier was rewritten.
`x-aile-speed-normalized`	`fast-removed`: a chat request set `speed` (fast mode); it ran at standard speed.
`x-aile-fallbacks-normalized`	`removed`: a `/v1/messages` request set `fallbacks`; a refusal is returned, not retried on another model.
`x-aile-redacted`	How many distinct secrets were replaced by placeholders before the request left Aile (`2`). Absent when none were.
`x-aile-cache-ttl-normalized`	`1h-removed`: a 1-hour cache marker on a Claude model served through a reseller not known to report the 1-hour share was not honoured; at most the 5-minute default applied.
`x-aile-edge-hold`	e.g. `25000ms`: no answer existed after that long, so the response was committed to `200` and kept alive until it did. A later failure arrives in the body (an SSE error frame, or a JSON error body). Only headers that could no longer change are sent. On chat, from a plain request or a route's last entry, that is `x-aile-provider`, `x-aile-model`, `x-aile-data-notice` and the `-normalized` notices, not the sharer, price or attempts, which a later attempt could change; self-hosted chat, which never fails over, also keeps its sharer, node, capacity, blind, attempts and price. Image and music routes send `x-aile-capacity: nodeless` and `x-aile-blind: false`. The `x-aile-discount*` headers follow the same rule: on chat that is never `applied`, which a later attempt could still turn into a full-price serve, nor a verdict a later route entry could change. On image and music routes the verdict is sent, `applied` included, and stays on a reply that then fails (not charged).
`x-aile-stake`	`applied` \| `exhausted` \| `off` \| `size` \| `unavailable`. A stake key's requests where its window applies. See Rate limits.
`x-aile-stake-resets`	Epoch milliseconds when the stake window or pool refills. Only with `exhausted`, and only when there is a refill time.
`x-aile-stake-wall`	`window` \| `pool`: your own window or the shared pool refused it. On a refusal only, never a served reply. Only where the window applies, beside `x-aile-stake`.
`x-aile-stake-fallback-pin`	The fallback key's pin that ruled the sharer out, as on the key form: `provider` (Provider, Never these providers, or Allow self-hosted model unticked), `lender` (Sharer handle, Only these sharers or Never these sharers), `machine` (Machine node id), `price` (Discount, Max discount, or an older key's Max $/Mtok), `verified` (an older key's verified-only pin). Only where the window applies, beside `x-aile-stake`.
`x-aile-discount`	`applied` \| `exhausted` \| `pinned` \| `ineligible` \| `off`: whether a stake-funded discount paid part of this request. Absent when the deployment runs no discount, and on a request paid by x402 or MPP. See Rate limits.
`x-aile-discount-percent`	The discount, whole percent (`50`). Not sent with `off`.
`x-aile-discount-remaining`	Discount-covered usage left network-wide on this endpoint when the request was decided, USD (`12.00`): rounded up to whole dollars, to $10 while aile's budget (the pool's resale line or the payer's balance) is the limit, less this request's own claim when applied. Not sent with `off`, nor while fewer than three stakers fund this endpoint.
`x-aile-status`	The real status behind a `503` on the wire. A `502` or `504` is sent as `503` so the edge passes the error body through; the original code rides here.
`x-aile-units`	Non-chat per-unit endpoints: how many units the answer produced, which is what is billed. A stream omits it (the count is unknown at the start); a video create says `0` (billed when the render completes); image generations send `x-aile-images` instead.
`x-aile-unit`	The unit billed: `image`, `page`, `minute`, `second`, …
`x-aile-images`	Images billed, on the image endpoints.
`x-aile-ocr-page-cap`	`/v1/ocr`, a document sent without `pages`: how many pages it was read up to, and no further.
`x-aile-debit-id`	Partner credit accounts only: the charge's id, for `GET /partner/charges/:id`. A stream or video create sends it at the start, and the charge reads `final: false` until the request finishes. Never on an `x-aile-edge-hold` reply.
`x-aile-refused-by`	Which rate limit refused a `429` (or `malformed_key` on a `401`). See Rate limits.
`x-should-retry`	`false` on a non-chat endpoint when the sharer's provider answered `401`–`403` (its key, credit or permissions): nothing fails over, so the same request fails the same way. Absent when a `401` retired a dead key or the refusal took the sharer's account or model off sale (a spent balance), since a retry can then reach another sharer.
`x-request-id`	`req_` + 12 hex: this request's id, on every `/v1` reply, errors included. A `500` names the same id in its message; quote it when reporting a problem. It is also the id `GET /v1/generation?id=` looks up.
`server-timing`	`pre` (Aile's work before dialling), `slot` (waiting for a sharer's slot) and `ttfb` (the model's time to first byte), in ms. Only the figures known when the headers were sent.

x-aile-blind describes the node, not the relay

true means the sharer's machine could not read the request. It makes no claim about Aile, which terminates TLS with the provider on every subscription and nodeless path in order to meter the call. See What Aile can see.

x-aile-verified is silent when a mismatch cannot be determined. Absence does not prove a match.

Upstream headers cannot forge these

Provider response headers pass through an allowlist before Aile's own are applied, so a rogue upstream x-aile-* can never override a decision Aile made. The sharer's own rate-limit headers and OpenAI organisation id are dropped too: they describe the sharer's account, not yours.

Streaming headers

HTTPhttp

1content-type: text/event-stream
2cache-control: no-cache, no-transform
3x-accel-buffering: no

A self-hosted, edge-held or non-chat stream sends cache-control: no-cache alone.

x-accel-buffering: no tells intermediate proxies not to accumulate the body. Without it a correctly streaming response arrives in one block at the end.

Payment headers (x402 v2)

Header	Direction	Content
`PAYMENT-REQUIRED`	server → client	base64 JSON: what must be paid. Accompanies the `402`.
`PAYMENT-SIGNATURE`	client → server	base64 JSON: the authorised payment.
`PAYMENT-RESPONSE`	server → client	base64 JSON: what settlement did.

This is x402 v2. A v1 client's X-PAYMENT is accepted too and answered in v1's shape, and settlement is echoed as both PAYMENT-RESPONSE and X-PAYMENT-RESPONSE. Verification happens before the sharer's quota is spent; settlement after the provider answers.

A chat reply paid from a key's balance carries the same receipt: success: true when it is charged to the balance, or success: false with an errorReason such as upstream returned 400; not charged. A stream whose provider answered an error status says false too; a 200 stream that ends unbilled keeps the true it was sent with, since headers cannot change once sent.

Payment headers (MPP)

Where the deployment enables MPP, the same 402 can be paid with the Payment HTTP auth scheme instead. See Pay with a wallet.

Header	Direction	Content
`WWW-Authenticate: Payment`	server → client	On a priced `402`, beside `PAYMENT-REQUIRED`: one challenge per method that can pay (`evm`, `solana`, `tempo`), comma-separated on one line. Each expires after 120 seconds.
`Authorization: Payment`	client → server	The paid credential, on a request with no API key. Never read as a key.
`Payment-Authorization`	client → server	The same credential on a chat request made with an API key, which stays in `Authorization`.
`Payment-Receipt`	server → client	base64url JSON: `method`, `challengeId`, `reference` (the transaction), `status`, `timestamp`, `chainId`. Sent with `Cache-Control: private`, and only when the payment settled. An MPP payment gets this instead of `PAYMENT-RESPONSE`.

Authentication

Header	Used by
`Authorization: Bearer sk-aile-…`	OpenAI-shaped SDKs
`x-api-key: sk-aile-…`	The Anthropic SDK, which sends only this

Either reaches the same key. A bare Bearer with nothing after it is not accepted as a key, and Authorization: Payment … is an MPP payment, never a key.