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.
| Method & path | What it does | Body |
|---|---|---|
GET /v1/models | Every model live on the grid right now (a key routed to one node lists only that node's models). | — |
POST /v1/chat/completions | Chat / text generation, OpenAI format. Streaming ("stream": true) or not. | OpenAI chat body: model, messages, optional stream, max_tokens, temperature, tools … |
POST /v1/messages | Anthropic Messages format — translated to and from the node. | Anthropic body: model, messages, max_tokens, optional system, stream |
POST /api/chat | Ollama native chat format (streams NDJSON by default, as Ollama does). | Ollama body: model, messages, optional stream, options |
POST /v1/embeddings | Vector embeddings. | model, input (string or list of strings) |
POST /v1/audio/speech | Text-to-speech; returns audio. | model, input, optional voice, response_format |
POST /v1/audio/transcriptions | Speech-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.
| Header | Effect |
|---|---|
Authorization: Bearer … | Required. Your API key. |
X-Inpherio-Budget-Per-1M-Tokens | Price ceiling for this request, in pence per 1M output tokens (decimals allowed). Nodes above it are skipped. |
X-Inpherio-Min-Reliability | Minimum health score (0–100) a node must have to serve this request. |
| Header | Meaning |
|---|---|
X-Inpherio-Model | The model that served the request. |
X-Inpherio-Node-Name | The name its operator gave the node that served you (also X-Inpherio-Node-Id). Operators never see who you are. |
X-Inpherio-Charged-GBP | What 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-Cents | The same charge in micro-pence (1p = 1,000,000) — the ledger's own unit. |
X-Inpherio-Billed-Tokens | Tokens counted for billing (input + output). |
X-Inpherio-Stream | Whether the response was streamed. |
X-Inpherio-Failover / -Failed-Nodes | Whether the request was re-routed after a node failed, and how many failed. Non-streamed responses only. |
X-Inpherio-Free-Tier | free when a free model served it at no charge, or paid; reason=… with the limit that applied. |
X-Inpherio-Audio-Seconds · -Billed-Seconds · -Audio-Measured | Speech: 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 · -Reset | Your 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.
| Status | Meaning |
|---|---|
400 | Malformed request — invalid JSON, a missing model, or a field of the wrong type (e.g. messages not a list, a negative max_tokens). |
401 | Missing or invalid API key. |
402 | Your 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. |
403 | A disabled account, or a key without the scope this request needs. |
404 | No node is serving that model right now, or the model ID is wrong — check /v1/models. |
429 | Rate limit, a daily/monthly spend cap, or the key's own budget. Retry-After says when to retry. |
502 / 503 | Every 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
429once reached.