---
title: "API 概览"
description: "pirouter API 由一个域名 https://api.pirouter.ai 提供，支持 OpenAI、Anthropic、Gemini 三种协议。需要 key 的端点都接受同一把 key。"
canonical: "https://pirouter.ai/zh/docs/api"
last-updated: "2026-10-13"
lang: "zh"
source: "content/docs/zh/api/index.mdx"
---

# API 概览

pirouter API 由一个域名 https://api.pirouter.ai 提供，支持 OpenAI、Anthropic、Gemini 三种协议。需要 key 的端点都接受同一把 key。

## 服务器地址

所有端点都在同一个域名下：

`Base URL`:

```text
https://api.pirouter.ai
```

路径决定协议。一个模型只在它登记的协议上应答，网关不做协议之间的转换。哪个模型接受哪种协议，见[模型与协议](https://pirouter.ai/zh/docs/models.md)。

## 鉴权

用两种请求头之一传 key。两者传的是同一把 key，一个请求里两者都有时以 `Authorization` 为准。

`作为 bearer token`:

```http
Authorization: Bearer $PIROUTER_API_KEY
```

`或者用 X-Api-Key`:

```http
X-Api-Key: $PIROUTER_API_KEY
```

四个模型目录端点是公开的：不需要 key，传了也不会读取。

> **注意：** 不要把 key 放进浏览器代码或移动应用。请从你的服务端调用 pirouter，并把 key 存在环境变量里。

## 错误

错误体有两种结构，取决于端点属于哪一类。

推理端点（对话补全、Responses、Messages、两个 Gemini 端点和图像）不论是哪种协议，都按下面的结构返回。`message` 与 `type` 一定有；只要平台对这个请求做出了判定，`code` 就有，绝大多数情况都是如此：

```json
{
  "error": {
    "message": "No such model. Model names are vendor-qualified (vendor/model), so a name copied from a provider's own docs needs its vendor prefix added. Call GET /v1/models for the slugs this gateway serves.",
    "type": "not_found_error",
    "code": "model_not_found"
  }
}
```

四个模型目录端点返回的是错误码加说明，没有 `type`：

```json
{
  "error": {
    "code": "model_not_found",
    "message": "string"
  }
}
```

请按 `error.code` 分支，它是稳定的字符串；响应里没有 code 时退回看 `error.type`。不要匹配 `message` 的文字。每个端点页列出了该端点可能返回的错误码，并给出它的错误体。每个错误码的含义和哪些错误可以重试，见[错误码](https://pirouter.ai/zh/docs/errors.md)。

上游 provider 自己返回的错误会连同状态码与响应体原样透传，不会改写成上面的结构。

## 端点

| 协议        | 端点                                                                   | 方法     | 路径                                             |
| --------- | -------------------------------------------------------------------- | ------ | ---------------------------------------------- |
| OpenAI    | [创建对话补全](https://pirouter.ai/zh/docs/api/chat-completions.md)        | `POST` | `/v1/chat/completions`                         |
| OpenAI    | [创建 Response](https://pirouter.ai/zh/docs/api/responses.md)          | `POST` | `/v1/responses`                                |
| OpenAI    | [生成图像](https://pirouter.ai/zh/docs/api/images.md)                    | `POST` | `/v1/images/generations`                       |
| Anthropic | [创建 Message](https://pirouter.ai/zh/docs/api/messages.md)            | `POST` | `/v1/messages`                                 |
| Gemini    | [生成内容](https://pirouter.ai/zh/docs/api/generate-content.md)          | `POST` | `/v1beta/models/{model}:generateContent`       |
| Gemini    | [流式生成内容](https://pirouter.ai/zh/docs/api/stream-generate-content.md) | `POST` | `/v1beta/models/{model}:streamGenerateContent` |
| 模型目录      | [列出模型](https://pirouter.ai/zh/docs/api/list-models.md)               | `GET`  | `/v1/models`                                   |
| 模型目录      | [按厂商列出模型](https://pirouter.ai/zh/docs/api/list-models-by-vendor.md)  | `GET`  | `/v1/models/{vendor}`                          |
| 模型目录      | [获取模型](https://pirouter.ai/zh/docs/api/get-model.md)                 | `GET`  | `/v1/models/{vendor}/{model}`                  |
| 模型目录      | [列出模型的上游](https://pirouter.ai/zh/docs/api/list-model-endpoints.md)   | `GET`  | `/v1/models/{vendor}/{model}/endpoints`        |

## OpenAPI 规范

本分区的页面由 API 的 OpenAPI 3.1 规范生成。可以下载它来生成客户端，或导入你自己的工具：[openapi.json](https://pirouter.ai/docs/api/openapi.json)。

> **提示：** 第一次来？从[快速开始](https://pirouter.ai/zh/docs/quickstart.md)入手。