# OpenAI 兼容 API

URL: https://docs.router.ezat.io/zh/openai/base-url

> 面向使用 OpenAI API 格式的工具和代码：base URL、认证、端点对应关系和 SDK 配置。

## 何时阅读本页

你的代码或工具只支持 OpenAI 的 API 格式（`openai` SDK、LangChain 的 OpenAI 客户端、可以填写 OpenAI base URL 的编辑器）。本页给出 base URL、可用的端点，以及如何把 SDK 指向它们。请求和响应的详细说明见 [Chat Completions](https://docs.router.ezat.io/zh/openai/chat-completions.md)。

## Base URL 与 key

| 设置 | 值 |
| --- | --- |
| Base URL | `https://api.router.ezat.io/openai/v1` |
| API key | 你的 EZAT key（`ezat_sk_…`），以 `Authorization: Bearer <key>` 发送 |
| 模型 | [模型](https://docs.router.ezat.io/zh/models.md)中的一个 id，例如 `anthropic/claude-sonnet-5-5` |

Base URL 已经以 `/v1` 结尾。客户端会在后面加上 `/chat/completions` 和 `/models`。`https://api.router.ezat.io/v1` 是 [Anthropic 格式的 API](https://docs.router.ezat.io/zh/anthropic/messages.md)，没有 `/chat/completions`。

OpenAI 兼容 API 与 Anthropic 格式的 API 使用相同的 key、模型、余额、限额和路由。同一段对话通过任一 API 调用，费用都相同，两者的请求会一起显示在控制台的「用量」页面上。

## 端点

| OpenAI 路径 | EZAT URL | 状态 |
| --- | --- | --- |
| `POST /v1/chat/completions` | `https://api.router.ezat.io/openai/v1/chat/completions` | 支持，流式和非流式均可 |
| `GET /v1/models` | `https://api.router.ezat.io/openai/v1/models` | 支持 |
| `GET /v1/models/{model}` | `https://api.router.ezat.io/openai/v1/models/{model}` | 支持。带斜杠的 id 可以直接使用，别名也会被解析。 |
| `POST /v1/responses`（Responses API） | | 不可用 |
| `POST /v1/embeddings` | | 不可用 |
| `/v1/images/…`（图片生成） | | 不可用 |
| `/v1/audio/…`（语音合成、语音转写） | | 不可用 |
| `/v1/files`、`/v1/batches` | | 不可用 |
| `POST /v1/completions`（旧版 completions） | | 不可用 |
| `POST /v1/moderations` | | 不可用 |

不可用的路径返回 `404` 和 `{"statusCode": 404, "message": "Cannot POST /openai/v1/responses"}`。这个响应体不是 OpenAI 的错误格式，所以 SDK 会把它显示为普通的 not found 错误。

只调用 Responses API 的工具（例如较新版本的 OpenAI Codex CLI）目前还无法使用。见 [OpenAI 格式的工具](https://docs.router.ezat.io/zh/tools/openai-tools.md)。

## 配置 SDK

```python tab="Python" test
import os

from openai import OpenAI

client = OpenAI(
    base_url="https://api.router.ezat.io/openai/v1",
    api_key=os.environ["EZAT_API_KEY"],
)

completion = client.chat.completions.create(
    model="anthropic/claude-sonnet-5-5",
    max_tokens=64,
    messages=[{"role": "user", "content": "Say hello in five words."}],
)
print(completion.choices[0].message.content)
```

```ts tab="Node.js" test
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.router.ezat.io/openai/v1",
  apiKey: process.env.EZAT_API_KEY,
});

const completion = await client.chat.completions.create({
  model: "anthropic/claude-sonnet-5-5",
  max_tokens: 64,
  messages: [{ role: "user", content: "Say hello in five words." }],
});
console.log(completion.choices[0].message.content);
```

```bash tab="curl" test
curl --fail-with-body https://api.router.ezat.io/openai/v1/chat/completions \
  -H "Authorization: Bearer $EZAT_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-5-5",
    "max_tokens": 64,
    "messages": [{"role": "user", "content": "Say hello in five words."}]
  }'
```

用 `pip install openai` 或 `npm install openai` 安装 SDK。

## 环境变量

如果你没有传入 `base_url` / `baseURL` 和 `api_key` / `apiKey`，Python 和 Node.js 的 `openai` SDK 会读取 `OPENAI_BASE_URL` 和 `OPENAI_API_KEY`。很多基于这些 SDK 构建的工具也读取这两个变量：

```bash
export OPENAI_BASE_URL="https://api.router.ezat.io/openai/v1"
export OPENAI_API_KEY="$EZAT_API_KEY"
```

这些变量也会影响该 shell 中所有使用它们的其他程序。如果你同时还在调用 OpenAI 本身，请按项目或按命令设置。

## 模型 id

使用与 Anthropic 格式 API 相同的 id：`author/model` 形式的规范 id，或它们的别名。[模型](https://docs.router.ezat.io/zh/models.md)页面列出了这些 id，API 也可以列出：

```bash tab="curl" test
curl --fail-with-body https://api.router.ezat.io/openai/v1/models \
  -H "Authorization: Bearer $EZAT_API_KEY"
```

```json
{
  "object": "list",
  "data": [
    { "id": "anthropic/claude-sonnet-5-5", "object": "model", "created": 1790812800, "owned_by": "anthropic" }
  ]
}
```

列表包含你的 key 可以使用的模型。响应中的 `model` 字段原样返回你发送的名称。未知模型返回 `404`，code 为 `model_not_found`。

## 错误

错误采用 OpenAI 的外层结构 `{"error": {"message", "type", "param", "code"}}`，所以 SDK 会抛出它们惯常的异常。HTTP 状态与 Anthropic 格式的 API 相同，只有一处例外：模型过载时是 `503`，而不是 `529`。type 和 code 使用 OpenAI 的取值，例如余额用完（`402`）时为 `insufficient_quota`，模型不存在（`404`）时为 `model_not_found`。完整的对应关系见 [Chat Completions](https://docs.router.ezat.io/zh/openai/chat-completions.md)。

## 给 AI agent 的说明

1. Base URL 必须是 `https://api.router.ezat.io/openai/v1`，一字不差。OpenAI 格式的客户端不要用 `https://api.router.ezat.io/v1`。
2. API key：来自 `EZAT_API_KEY` 的 EZAT key，以 `Authorization: Bearer` 发送。使用 SDK 时，把它作为 `api_key` / `apiKey` 传入，或设置 `OPENAI_API_KEY`。
3. 模型：`GET https://api.router.ezat.io/openai/v1/models` 返回的 id。
4. 只有 Chat Completions 和模型端点。不要配置需要 Responses API、embeddings、图片生成或音频的工具。