> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pipellm.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 路由与协议

> 为每种请求格式选择正确的原生路由或 converter 路由

PipeLLM 对外提供两类公共路由：

* `https://api.pipellm.ai` 下的原生公共路由
* `/openai`、`/anthropic`、`/gemini` 下的 converter 路由

只有当你的请求体已经符合目标协议时，才应该使用原生路由。想保留现有 SDK
格式、去调用别的协议族模型时，应该使用 converter 路由。

## 路由矩阵

| 请求格式                           | 原生路由                                           | Converter 路由                                          | 说明                                                                       |
| ------------------------------ | ---------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------ |
| OpenAI Chat Completions        | `/v1/chat/completions`                         | `/openai/v1/chat/completions`                         | 原生路由用于 OpenAI 兼容平台；converter 路由用于用 OpenAI 格式调用 Anthropic 或 Gemini 模型。    |
| OpenAI Responses               | `/v1/responses`                                | 暂未提供                                                  | 目前只支持 OpenAI 兼容平台原生路由；如果今天要跨协议调用，请先改用 OpenAI Chat Completions converter。 |
| Anthropic Messages             | `/v1/messages`                                 | `/anthropic/v1/messages`                              | 原生路由用于 Anthropic 兼容平台；converter 路由用于用 Anthropic 格式调用 OpenAI 或 Gemini 模型。 |
| Gemini Generate Content        | `/v1beta/models/{model}:generateContent`       | `/gemini/v1beta/models/{model}:generateContent`       | 原生路由用于 Gemini 平台；converter 路由用于用 Gemini 格式调用 OpenAI 或 Anthropic 模型。      |
| Gemini Stream Generate Content | `/v1beta/models/{model}:streamGenerateContent` | `/gemini/v1beta/models/{model}:streamGenerateContent` | 与 `generateContent` 采用同样的路由规则。                                           |

## 协议校验规则

* `/v1/chat/completions` 和 `/v1/responses` 只接受 OpenAI 兼容请求体，并且只会
  路由到 OpenAI 兼容平台。
* `/v1/messages` 只接受 Anthropic Messages 请求体，并且只会路由到 Anthropic
  兼容平台。
* Gemini 原生端点只接受 Gemini 请求体，并且只会路由到 Gemini 平台。
* `/openai/...`、`/anthropic/...`、`/gemini/...` 这类 converter 前缀路由不会被
  原生路由的协议 guard 拦截。

## 常见调用方式

| 目标                         | 应该使用的路由                                                               |
| -------------------------- | --------------------------------------------------------------------- |
| 保留 OpenAI SDK，调用 Claude    | `https://api.pipellm.ai/openai/v1/chat/completions`                   |
| 保留 OpenAI SDK，调用 Gemini    | `https://api.pipellm.ai/openai/v1/chat/completions`                   |
| 保留 Anthropic SDK，调用 GPT    | `https://api.pipellm.ai/anthropic/v1/messages`                        |
| 保留 Anthropic SDK，调用 Gemini | `https://api.pipellm.ai/anthropic/v1/messages`                        |
| 保留 Gemini SDK，调用 GPT       | `https://api.pipellm.ai/gemini/v1beta/models/{model}:generateContent` |
| 保留 Gemini SDK，调用 Claude    | `https://api.pipellm.ai/gemini/v1beta/models/{model}:generateContent` |

## 错误返回格式

协议不匹配时，错误体统一为：

```json theme={null}
{
  "error": {
    "type": "invalid_request_error",
    "code": "400",
    "message": "..."
  }
}
```

错误信息会明确告诉开发者：

* 识别到的请求格式是什么
* 为什么当前原生路由不兼容
* 应该改走哪条 converter 路由或原生路由
* 下一步该看哪篇文档

## 相关文档

<Columns cols={3}>
  <Card title="API 参考总览" icon="book" href="/api-reference/introduction.zh">
    公共路由和端点总览
  </Card>

  <Card title="转换器总览" icon="shuffle" href="/converter/overview.zh">
    保留 SDK 格式，跨协议调用模型
  </Card>

  <Card title="OpenAI Responses" icon="sparkles" href="/api-reference/openai/responses.zh">
    PipeLLM 上的 `/v1/responses`
  </Card>
</Columns>