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

# 透传 API

> 通过 GoModel 使用提供商的原生 API，包括经由透传端点路由的 Anthropic SDK 请求。

## 概览

> [!WARNING]
>
> 透传 API 目前处于 Beta 阶段。当您需要提供商原生的 API 格式时使用它；如果您需要最稳定的
> GoModel 接口，请优先使用兼容 OpenAI 的 `/v1` 路由。

透传 API 通过 GoModel 代理提供商原生的请求，不会转换请求体或响应体。

当客户端库期望使用提供商的原生 API 而非兼容 OpenAI 的 API 时，请使用透传 API。例如，
Anthropic SDK 会将请求发送到 `/v1/messages`，因此您可以将其指向 GoModel 的 Anthropic
透传基础 URL：

```text theme={null}
http://localhost:8080/p/anthropic
```

SDK 发送：

```text theme={null}
POST /p/anthropic/v1/messages
```

GoModel 会规范化可选的 `v1` 路径段，并以 Anthropic 原生格式将请求转发到上游：

```text theme={null}
POST /messages
```

## 工作原理

透传路由采用以下格式：

```text theme={null}
/p/{provider}/{endpoint}
```

对于 Anthropic，当 `ALLOW_PASSTHROUGH_V1_ALIAS=true`（默认值）时，以下两个路径会映射到同一个上游端点：

```text theme={null}
/p/anthropic/messages
/p/anthropic/v1/messages
```

GoModel 首先处理网关认证。如果启用了 `GOMODEL_MASTER_KEY` 或托管认证密钥，客户端必须发送
GoModel Bearer Token：

```http theme={null}
Authorization: Bearer change-me
```

GoModel 在转发请求前会移除客户端的 `Authorization` 和 `X-Api-Key` 请求头，然后使用服务器上配置的
上游提供商凭据。对于 Anthropic，GoModel 使用其配置的 `ANTHROPIC_API_KEY`。

由于透传是提供商原生的，响应也是提供商原生的。对于 Anthropic messages，响应使用 Anthropic 的
消息结构，而不是 OpenAI Chat Completion 结构。

启用用量追踪时，成功的透传推理响应会被记录：流式响应的 Token 数从 SSE 用量事件中读取，
JSON 响应的 Token 数从 `usage` 成员中读取，因此成本和预算会像其他路由一样计入透传流量。

## 访问控制

透传会使用服务器的凭据直接访问提供商账户，包括网关无法按调用方划定作用域的路由，例如
`GET /files`。因此访问受到限制：

* **`GOMODEL_MASTER_KEY`**：始终拥有透传访问权限。
* **托管 API 密钥**：默认创建时*不*带透传访问权限。在引入透传访问权限之前就已存在的密钥会保留该权限。
  没有访问权限的密钥会收到 `403`，错误代码为 `passthrough_access_denied`。
* **模型允许列表**：指定了 `model` 的请求体会根据调用方的允许列表进行检查。未指定模型的请求作用于
  整个提供商，因此允许列表必须授予整个提供商（`anthropic/`）或全部内容（`/`）的权限。仅限于
  `anthropic/claude-sonnet-4-6` 的密钥可以为该模型调用 `POST /p/anthropic/v1/messages`，
  但不能调用 `GET /p/anthropic/v1/models`。

您可以在创建密钥时（在 `POST /admin/auth-keys` 中设置 `"passthrough_access": true`）、在控制台的
API Keys 页面上，或在之后授予透传访问权限。只有全局管理员凭据（主密钥或不带用户路径的控制台密钥）
才能授予该权限，因为透传密钥的访问范围超出了任何用户路径；限定于某个用户路径的管理员会收到
`403 admin_scope_denied`，但可以撤销该权限。

```bash theme={null}
curl -X PUT "http://localhost:8080/admin/auth-keys/${KEY_ID}/passthrough-access" \
  -H "Authorization: Bearer $GOMODEL_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"passthrough_access": true}'
```

## Anthropic SDK 示例

将 Anthropic SDK 的基础 URL 设置为 GoModel 的 Anthropic 透传路由，并将 GoModel Token 用作
Anthropic SDK 的 Bearer 认证。

```python Python theme={null}
import os
from anthropic import Anthropic

client = Anthropic(
    base_url="http://localhost:8080/p/anthropic",
    auth_token=os.environ["GOMODEL_MASTER_KEY"],
)

message = client.messages.create(
    model="claude-3-haiku-20240307",
    max_tokens=16,
    messages=[
        {
            "role": "user",
            "content": "Reply with exactly ok",
        }
    ],
)

print(message.content[0].text)
```

```javascript JavaScript theme={null}
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  baseURL: "http://localhost:8080/p/anthropic",
  authToken: process.env.GOMODEL_MASTER_KEY,
});

const message = await client.messages.create({
  model: "claude-3-haiku-20240307",
  max_tokens: 16,
  messages: [
    {
      role: "user",
      content: "Reply with exactly ok",
    },
  ],
});

console.log(message.content[0].text);
```

如果您的网关不要求认证，请使用一个虚拟的 SDK API 密钥（例如 `not-needed`），而不是
`auth_token` 或 `authToken`。GoModel 在将透传请求转发到上游之前会移除 `X-Api-Key`。

## 当前限制

在 API 处于 Beta 阶段期间，透传的范围被有意限制得较窄。

* `openai`、`anthropic`、`openrouter`、`kilo`、`zai`、`sglang`、`vllm`、`llamacpp`、`llmd`、`deepseek`、`edenai` 和 `jev`
  默认启用。
* Chutes 支持透传，但需要运维人员显式启用，因为透传可能会转发不标识模型的提供商原生路由。
  只有在您确实打算暴露该接口时，才将 `chutes` 添加到 `ENABLED_PASSTHROUGH_PROVIDERS`。
* GoModel 不会转换透传的请求体或响应体。
* JSON 透传请求体中指定的 `model` 会根据调用方的模型允许列表进行检查，与请求体大小无关，
  最大不超过配置的请求体上限；更大的请求体会以该上限自身的错误被拒绝。重复包含顶层 `model`
  字段的请求体会被拒绝，因为否则将由上游决定哪一个生效。未指定模型的请求需要提供商级别的授权
  （参见[访问控制](#访问控制)）。
* 上游账户是共享的。拥有透传访问权限的密钥可以访问该账户上由其他密钥创建的对象，例如文件或批处理任务。
  只应将 `passthrough_access` 授予您信任其访问整个提供商账户的密钥。
* 提供商原生的错误响应体和状态码会被直接代理，而不会转换为兼容 OpenAI 的响应。
* 依赖兼容 OpenAI 的请求或响应格式的功能，可能不会以与 `/v1` 流量相同的方式作用于透传流量。

## 相关环境变量

透传路由默认启用：

```env theme={null}
ENABLE_PASSTHROUGH_ROUTES=true
ALLOW_PASSTHROUGH_V1_ALIAS=true
ENABLED_PASSTHROUGH_PROVIDERS=openai,anthropic,openrouter,kilo,zai,sglang,vllm,llamacpp,llmd,deepseek,edenai,jev
```

将 `ENABLED_PASSTHROUGH_PROVIDERS` 设置为您希望暴露的提供商类型。


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