> ## 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 路由

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

* `https://api.pipellm.ai` 下的原生公共路由
* `/openai`、`/responses`、`/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` | `/responses/v1/responses` | 原生路由用于 OpenAI 兼容平台；converter 路由用于用 Responses 格式调用 Anthropic 或 Gemini 模型，为无状态实现，[限制见文档](/zh/converter/responses-format#不支持的功能)。 |
| 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` | 原生流式输出可用；跨协议转换为 Gemini 流式输出尚未实现。 |
| Jev / System One | `/v1/systemone` | — | `jev-1.13.0` 的原生类型化判断接口，使用 `state` 和 `questions`；不支持聊天格式或流式输出。[接口说明](/zh/api-reference/systemone)。 |
| 视频 | `/v2/videos` | — | 异步视频任务。只有原生路由；创建、查询、取消共用同一任务信封。 |

## 协议校验规则

* `/v1/chat/completions` 和 `/v1/responses` 只接受 OpenAI 兼容请求体，并且只会
  路由到 OpenAI 兼容平台。
* `/v1/messages` 只接受 Anthropic Messages 请求体，并且只会路由到 Anthropic
  兼容平台。
* Gemini 原生端点只接受 Gemini 请求体，并且只会路由到 Gemini 平台。
* `/v2/videos` 只接受平台无关的视频任务请求体，并且只会路由到视频平台。
* `/openai/...`、`/responses/...`、`/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` |
| 保留 Responses 客户端（OpenAI SDK、Codex CLI），调用 Claude 或 Gemini | `https://api.pipellm.ai/responses/v1/responses` |
| 保留 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` |
| 生成视频 | `https://api.pipellm.ai/v2/videos` |

## 错误返回格式

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

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

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

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

## 相关文档

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

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

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.