---
title: "Requests"
description: "Interfaces, headers, streaming and the error envelope for api.airuntime.dev."
---

> Documentation Index
> Fetch the complete documentation index at: https://help.airuntime.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Requests

Every call goes to `https://api.airuntime.dev` with a Workspace API key. The Pool you name decides
which interface can answer.

## Interfaces

| Capability | Interface |
| --- | --- |
| `text`, `structured` | `POST /v1/responses`, `POST /v1/chat/completions` |
| `embedding` | `POST /v1/embeddings` |
| `image-embedding` | `POST /v1/image/embeddings` |
| `transcription` | `POST /v1/audio/transcriptions` |
| `speech` | `POST /v1/audio/speech` |
| `image` | `POST /v1/images/generations` |
| `ocr` | `POST /v1/ocr` |
| `privacy-filter` | `POST /v1/privacy/filter` |
| `realtime-*` | `wss://api.airuntime.dev/v1/realtime?model=YOUR_POOL_SLUG` |
| discovery | `GET /v1/models` |

`/v1/responses` is the canonical text interface; `/v1/chat/completions` is the OpenAI-SDK-compatible
shape for existing clients.

## Headers

| Header | Required | Meaning |
| --- | --- | --- |
| `Authorization: Bearer <key>` | yes | The Workspace API key |
| `X-AIRuntime-Route: <pool slug>` | yes | The Pool that serves the call |
| `Idempotency-Key: <your key>` | recommended | Retrying with the same value replays the first result instead of double-spending |
| `Content-Type: application/json` | for JSON bodies | — |

The response carries `x-airuntime-request-id`. That value identifies the invocation in error bodies,
in the console, and in support threads.

## Streaming

OpenAI-compatible interfaces accept `stream: true` and the upstream event stream is passed through
as `text/event-stream`. Real-time audio uses the WebSocket interface with the `airuntime.voice.v1`
subprotocol: configure the session, wait for `session.ready`, append base64 PCM16 mono 24 kHz audio,
then close the session and wait for `session.closed`. Do not replay audio automatically on
reconnect.

## Errors

Failures use one envelope:

```json
{
  "error": {
"message": "The Runtime Route hard budget has insufficient remaining capacity.",
"type": "rate_limit_error",
"param": null,
"code": "quota_hard_budget_exceeded"
  }
}
```

- `type` is `invalid_request_error`, `rate_limit_error` or `server_error`.
- `401` responses also set `WWW-Authenticate: Bearer`.
- `429` covers both rate limiting (`quota_runtime_rate_limit_exceeded`) and a Pool whose remaining
  budget cannot cover the request (`quota_hard_budget_exceeded`).

Retry a `429` only after the limit resets or the budget changes. Retry a `5xx` with the same
`Idempotency-Key` so a replay cannot be billed twice.

Source: https://help.airuntime.dev/gateway/requests/index.mdx
