# API reference — endpoints, headers, errors | Inpherio

Source: https://inpherio.co.uk/api-reference

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.

[Quick-start guide](https://inpherio.co.uk/developers)[Model IDs](https://inpherio.co.uk/marketplace)

## Endpoints.

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](https://inpherio.co.uk/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

| 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. |
|---|---|

Response headers

| 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.

Errors

| 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](https://inpherio.co.uk/pricing).
- **Budgets:** per-key spend budgets and account-wide daily/monthly caps refuse requests with `429` once reached.
