Developers

API reference.

Base URL https://inpherio.co.uk. Authenticate every request with Authorization: Bearer <your API key>. Bodies are the standard OpenAI, Anthropic or Ollama shapes — anything the proxy doesn't use itself is passed to the engine untouched.

Endpoints.

Endpoints
Method & pathWhat it doesBody
GET /v1/modelsEvery model live on the grid right now (a key routed to one node lists only that node's models).—
POST /v1/chat/completionsChat / text generation, OpenAI format. Streaming ("stream": true) or not.OpenAI chat body: model, messages, optional stream, max_tokens, temperature, tools …
POST /v1/messagesAnthropic Messages format — translated to and from the node.Anthropic body: model, messages, max_tokens, optional system, stream
POST /api/chatOllama native chat format (streams NDJSON by default, as Ollama does).Ollama body: model, messages, optional stream, options
POST /v1/embeddingsVector embeddings.model, input (string or list of strings)
POST /v1/audio/speechText-to-speech; returns audio.model, input, optional voice, response_format
POST /v1/audio/transcriptionsSpeech-to-text; multipart upload.model, file

Model IDs are exactly as listed by /v1/models and on the marketplace.

Headers.

Routing preferences you set in the dashboard (price ceiling, minimum health, tier, warm-only, per-key policies) apply to every request automatically; these headers override them for one request.

Optional request headers
HeaderEffect
Authorization: Bearer …Required. Your API key.
X-Inpherio-Budget-Per-1M-TokensPrice ceiling for this request, in pence per 1M output tokens (decimals allowed). Nodes above it are skipped.
X-Inpherio-Min-ReliabilityMinimum health score (0–100) a node must have to serve this request.
Response headers
HeaderMeaning
X-Inpherio-ModelThe model that served the request.
X-Inpherio-Node-NameThe name its operator gave the node that served you (also X-Inpherio-Node-Id). Operators never see who you are.
X-Inpherio-Charged-GBPWhat the request cost, in pounds (8 decimal places). Non-streamed responses only — a stream settles when it ends; see your usage history.
X-Inpherio-Charged-CentsThe same charge in micro-pence (1p = 1,000,000) — the ledger's own unit.
X-Inpherio-Billed-TokensTokens counted for billing (input + output).
X-Inpherio-StreamWhether the response was streamed.
X-Inpherio-Failover / -Failed-NodesWhether the request was re-routed after a node failed, and how many failed. Non-streamed responses only.
X-Inpherio-Free-Tierfree when a free model served it at no charge, or paid; reason=… with the limit that applied.
X-Inpherio-Audio-Seconds · -Billed-Seconds · -Audio-MeasuredSpeech: the audio length, the seconds charged (rounded up, at least 1), and whether the length was read from the audio or estimated.
X-RateLimit-Limit · -Remaining · -ResetYour rate-limit window on this route.

Streaming.

With "stream": true, /v1/chat/completions returns server-sent events in the OpenAI chunk format, ending with data: [DONE]. While a slow model loads, the stream sends SSE comment lines (: keepalive) that every SSE client ignores. If something goes wrong mid-stream, a final event carries an error object with a message and type; a stream that ends in an error isn't charged.

A request can fail over to another node only before any of the reply has been sent. Once text has reached you, a node failure ends the stream with an error (code: node_failed_mid_stream) rather than replaying it.

Errors and limits.

Errors
StatusMeaning
400Malformed request — invalid JSON, a missing model, or a field of the wrong type (e.g. messages not a list, a negative max_tokens).
401Missing or invalid API key.
402Your balance can't cover the prompt, or a speech or embedding request in full — nothing ran (you're never put into debt). Or a free model past its limit with no credit; the message gives the price. A reply your balance only partly covers is not refused: it stops where your credit ends, with X-Inpherio-Stopped: balance.
403A disabled account, or a key without the scope this request needs.
404No node is serving that model right now, or the model ID is wrong — check /v1/models.
429Rate limit, a daily/monthly spend cap, or the key's own budget. Retry-After says when to retry.
502 / 503Every candidate node failed, or the model is at capacity. Safe to retry with backoff.
  • Rate limits: 60 requests a minute per API key on chat completions; 30 a minute per IP on /v1/models.
  • Billing: prepaid credit; per token for text and embeddings, per second of audio for speech; failed requests are never charged. Full rules on pricing.
  • Budgets: per-key spend budgets and account-wide daily/monthly caps refuse requests with 429 once reached.