API reference

Bearer token. Issue and rotate keys in the dashboard.

Declare the payload class. Set true when the request contains protected health information — the router then restricts to PHI-eligible, in-jurisdiction providers. Defaults to false.

Override the routing region to pin where the request is processed. Defaults to WORLD.

Model id, or auto to let the router pick the cheapest eligible model for your region and tier.

The conversation, as OpenAI-style { role, content } objects.

Sampling temperature. Passed through to the upstream model.

Maximum number of tokens to generate in the completion.

How hard a reasoning model should think. Translated into each upstream's own dialect (OpenAI reasoning_effort, Anthropic thinking.budget_tokens, Z.ai thinking.type); on a model with no such control it is a no-op — reasoning models still think by default. When the model returns a trace it comes back as choices[0].message.reasoning_content (or reasoning, whichever spelling the upstream used), never mixed into content. Streaming sends it as delta.reasoning_content chunks. The Anthropic { thinking: { type, budget_tokens } } form is accepted as an alias.

Body field (not a header) that biases auto routing toward a class of model — a soft preference the router honours when an eligible model in that tier exists, otherwise it falls back to the cheapest eligible model. Distinct from the descriptive quality_tier (low/medium/high) that /v1/models reports per model.

Parts of type text or image_url. A data URI must stay under 200 KB.

Embedding model id, or auto.

A single string or an array of strings to embed.

The code before the cursor.

The code after the cursor. Omit it and you get a plain completion rather than a fill-in-the-middle.

Cap on the suggestion length.

auto, or pin mercury-edit.

A single user message in the tagged next-edit format. It must contain <|current_file_content|>, <|code_to_edit|> with a <|cursor|> marker, <|edit_diff_history|> and <|recently_viewed_code_snippets|> (each with its closing tag). A request missing any of them is rejected with missing_next_edit_tags, listing exactly which.

Cap on the predicted edit length.

The audio file (multipart field file).

auto, or pin whisper.

json (default), text, srt, vtt, or verbose_json.

The text to synthesize (max 4096 characters).

Provider voice id. Omit for a region-appropriate default.

mp3 (default), wav, opus, aac, flac, pcm. pcm streams where the host can (24 kHz, 16-bit little-endian, mono; response header x-phi-stream: true) — first audio in roughly 150 ms instead of after the whole clip.

ISO language hint (fr, de-CH) — picks a native voice when voice is omitted. Also accepted as the X-Language header.

Filter across every provider. Matches a bare language or any locale under it — fr matches fr-CH and fr-FR. When set, each voice carries native: true|false and natives sort first: a multilingual voice whose own locale is de-DE can read French, but it will sound German.

inworld-realtime, or auto / flash (cheapest) / pro (fastest).

Same as the X-Region header (browsers cannot set headers on a WebSocket).

Authorization: Bearer phi_live_…, or — from a browser — the subprotocol openai-insecure-api-key.phi_live_… alongside realtime.

{ type: "document_url" | "image_url", url } — an https or data: URI.

Restrict OCR to specific page indices.

Request structured annotations (billed at the higher annotation rate).

A map of your own question id → { type, instructions, criteria? }. Up to 32 questions per decision. Every answer is keyed by the id you chose.

What the questions are about — free text, or any JSON value. Max 65,536 characters. Optional: a question can be answered about nothing.

auto (or omitted) resolves to the multilingual checkpoint. Pin laya, laya-multilingual, laya-english or laya-typed-decisions.

Batch form — an array of { state?, questions } objects, up to 64 per call and 512 questions across the whole request. Send either a single decision or a requests batch, never both.

Hints forwarded to the upstream’s own checkpoint router. The gateway always pins the resolved model, so these are pass-through niceties rather than routing controls.

criteria is a non-empty { label: description } object (or an array of labels), max 64 options. The answer carries choice (the winning label) and probabilities over all of them — e.g. {"type":"choice","instructions":"What does the customer want?","criteria":{"refund":"wants money back","exchange":"wants a different item"}}.

criteria is a non-empty array of level descriptions, index 0 first. The answer carries score (the probability-weighted level, so it is fractional), the legend you passed and the per-level probabilities — e.g. {"type":"score","instructions":"How urgent is this ticket?","criteria":["routine","reply today","escalate now"]}.

A yes/no question answered as a probability. criteria is optional — pass an object with true / false descriptions to steer it, or omit it. The answer carries noul, the probability that the statement holds (0–1) — e.g. {"type":"noul","instructions":"Is the customer angry?"}.

One entry per question id you sent, each carrying its type, the typed verdict (choice / score / noul), a confidence and, for choice and score, the full probabilities distribution.

Encoder input tokens — what the call is billed on. output_tokens is always 0: a decision model generates nothing.

routing names the checkpoint that answered; id echoes your x-request-id when you send one.

Batch only — one entry per requests element, in order, each the same { answers, usage, routing, id } body. An entry the upstream could not answer is { error: … } and carries no usage, so it is never billed.

The encoder input tokens the charge was computed from — the billing unit.

How many questions were actually answered (summed over a batch). Informational, not the billing unit — it is here because a batch’s answered count can’t be read off the body without walking every result.

Which backend answered. For a self-hosted Swiss row this is residency evidence: anything but the local backend would mean the request left the box.

The decision host had no capacity and shed the request — nothing was computed and nothing is billed. The response carries Retry-After; retry shortly. Distinct from 502 upstream_error, which means the call was attempted and failed.

Malformed questions are rejected here rather than upstream, naming the exact question id and field: invalid_question_type, invalid_instructions, invalid_criteria, too_many_questions, too_many_options, state_too_large, batch_too_large.

true = the model may carry PHI on a DPA/BAA-verified host in that region (health data is OK). false = general traffic only (standard DPA, no health data).

A coarse quality / capability band derived from the model class — most meaningful for chat / LLM models — letting a caller pick a tier. Distinct from the routing tier body field on /v1/chat/completions.

Whether the model accepts OpenAI function calling.

kind is the primary task; tasks lists every one it serves (chat, code, vision, embed, tts, stt, speech_to_speech, ocr, image, video, …).

What the model accepts and returns: text, image, audio, video, embedding. ["text","image"] in = it can see images (send them as image_url parts). Measured live, not guessed.

Measured reasoning behaviour: thinks on every call, thinks when reasoning_effort asks, or never. Omitted when unmeasured.

Tokens the model can read, and the separate (usually much smaller) ceiling on one completion. Omitted when unknown, never guessed.

The provider-agnostic alias a row belongs to; for flash (cheapest) / pro (fastest) / think, today's model; allowed output sizes (image/video); older generation; announced shutdown date.

The resolved route: modelId/regionCode/dataClass — authoritative record of what served the request.

Whether the chosen route was PHI-eligible.

How many routes were tried before one succeeded (fail-over stays inside the PHI tier for PHI requests).

Metered cost of the request, in USD micro-units (1 = $0.000001). The API always reports cost in USD micro; your wallet balance is shown in prepaid credits (1 USD = 300 credits).

Whether the answering model returned a reasoning trace on this call (chat only; omitted on passthrough-streamed responses, where headers are sent before the first upstream byte). Lets you tell “this model doesn't emit one” from “something dropped it”.

Unique id for the request — quote it in support tickets.

The first host for auto chat: CH → Infomaniak, EU → Scaleway, US → Together AI (each resident in its region); the other named regions → Google (processed globally); WORLD → price order across global clouds.

Production embeddings run in CH (Infomaniak) and EU (Scaleway) — the same model, Qwen3-Embedding-8B (4096-d).US and other regions return no_route for embeddings until the staged Fireworks (US) / Azure / Bedrock (other regions) rows are enabled.

Served only by providers whose data-processing agreement is verified for the region: CH → Infomaniak + Azure, EU → Scaleway + Azure, US → Azure (OCR / TTS / STT only). A region or modality with no verified host returns 403.

Identical to /v1/chat/completions — same auth, shape and routing — with a math-oriented system prompt and a code-execution sandbox enabled by default (override with code_execution: false). The model can run Python, R, or SQL in a region-pinned, network-isolated sandbox to compute and verify; charts come back as inspectable SVG (fenced ```svg blocks, never raster) and diagrams as ```mermaid. The response carries x-phi-sandbox / x-phi-sandbox-figures. General traffic only.

Free setup diagnostic: validates your key, dry-runs routing, and reports billing_active (true once you have prepaid credits; 1 USD = 300 credits). No upstream call, no usage — exempt from the payment gate so you can verify a key before adding credits.

krea-2 (image), wan or seedance (video), or avatar (talking avatar). Generation routes to fal.ai (paid, general / non-PHI only). On video you can pin the model or just pass quality.

Video only — standard (default, Krea-Wan 14B, $0.04/sec) or premium (Seedance 2.0, up to 720p with native audio, $0.51/sec). The 202 response echoes price_micro_per_second so you know the rate before the job settles. Doesn’t apply to avatar mode.

The text prompt. For image-to-video or a talking avatar, also pass an image (and audio for the avatar).

Premium video only — clip length in seconds (4–15, default 5). Also accepts resolution (480p | 720p) and aspect_ratio. Billing is per generated second, settled on the first completed poll.

Ingest sources (url, urls, html or text): the upstream extracts, chunks, embeds and stores them. Pass an optional collection — it is namespaced to your account server-side, so it can never collide with another customer’s.

Semantic retrieval over your collection. query is required; returns the best-matching chunks with scores. Scoped to your namespace — a query can only reach your own content.

Live web search. query is required. depth: "deep" runs an asynchronous research pass and returns a customer-bound job token to poll at /v1/jobs/{token}; shallow search is synchronous.

python, r or sql (DuckDB).

The source to execute. Returns a structured SandboxRunResult: ok, stdout, stderr, resultText, error (and any captured SVG artifacts).

Optional data payload. Written to /workspace/input.json and, for Python, pre-bound as the variable phi_input. Read it in SQL with read_json_auto('/workspace/input.json').

Optional per-run timeout (capped at 120000). Requires X-Region to be CH, EU, UK or US — other regions return no_sandbox_region.

No Bearer token on the request.

The token is invalid or revoked.

The key has passed its expiry. Only the short-lived keys the dashboard chat and playground create expire; keys you create on the Keys page do not.

Out of credits. Top up your prepaid credit balance in the dashboard → Billing (or enable auto-recharge).

X-PHI: true but no PHI-verified route exists for the requested region and modality. This is correct behaviour — the gateway refuses to silently cross a border.

No route serves this task / region / data-class combination.

The model you sent is not a model id or canonical alias this gateway serves — usually a typo or a stale id. A pinned model is never quietly swapped for another one, so an unrecognised id is rejected rather than served by something else. Call GET /v1/models for the list.

The model exists, but does not serve this task in this X-Region. The error body lists the regions and tasks it does serve.

The request body was not valid JSON, or failed schema validation.

Every candidate route failed at the upstream provider. For a pinned model this means every host of that model failed — the gateway will not answer a pinned request with a different model. Send model: "auto" (or a canonical alias) if you want it to fail over across models.

Live region map and which providers are PHI-eligible where.

nFADP / GDPR posture, sub-processors, and the audit trail you ship by default.

Prepaid credits (1 USD = 300 credits; $10 / 3,000-credit minimum) and every model's per-token price.

Architecture, statelessness contract, and how routing decisions are made.