---
title: "请求"
description: "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.

# 请求

所有调用都发往 `https://api.airuntime.dev`，并带上一个 Workspace API Key。你指定的 Pool 决定哪个
接口可以回答。

## 接口

| 能力 | 接口 |
| --- | --- |
| `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` |
| 发现 | `GET /v1/models` |

`/v1/responses` 是文本的标准接口；`/v1/chat/completions` 是给现有 OpenAI SDK 客户端用的兼容形态。

## 请求头

| 请求头 | 是否必需 | 含义 |
| --- | --- | --- |
| `Authorization: Bearer <key>` | 必需 | Workspace API Key |
| `X-AIRuntime-Route: <pool slug>` | 必需 | 服务这次调用的 Pool |
| `Idempotency-Key: <your key>` | 建议 | 用同一个值重试会重放第一次结果，而不会重复计费 |
| `Content-Type: application/json` | JSON 请求体必需 | — |

响应头里有 `x-airuntime-request-id`。这个值同时出现在错误体、控制台和客服沟通里，用来定位同一次调用。

## 流式

OpenAI 兼容接口接受 `stream: true`，上游事件流会以 `text/event-stream` 透传。实时音频走 WebSocket
接口，子协议是 `airuntime.voice.v1`：先配置会话，等 `session.ready`，再追加 base64 PCM16、单声道
24 kHz 音频，最后关闭会话并等待 `session.closed`。重连时不要自动重放音频。

## 错误

失败统一使用一种格式：

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

- `type` 取 `invalid_request_error`、`rate_limit_error` 或 `server_error`。
- `401` 响应同时会带 `WWW-Authenticate: Bearer`。
- `429` 同时覆盖限流（`quota_runtime_rate_limit_exceeded`）和剩余预算不足以覆盖这次请求
  （`quota_hard_budget_exceeded`）。

`429` 要等限额重置或预算变化后再重试。`5xx` 重试时请用同一个 `Idempotency-Key`，这样重放不会被
计费两次。

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