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

# 自带密钥（BYOK）

> 通过 ARouter 使用您自己的服务商 API 密钥。BYOK 使用您的凭证将请求直接路由到服务商 — 无 ARouter 的 token 成本加价。

<Note>
  BYOK 目前处于开发阶段。请联系 [support@arouter.ai](mailto:support@arouter.ai) 申请加入内测。
</Note>

自带密钥（BYOK）允许您在 ARouter 中注册您自己的服务商 API 密钥。当请求路由到您已注册密钥的服务商时，ARouter 会使用您的密钥而非其共享密钥池。

**优势：**

* **零加价** — 直接以服务商标价付费，无 token 成本加价
* **您自己的配额** — 请求占用您自己的服务商频率限制，而非 ARouter 的共享池
* **您自己的数据政策** — 您与服务商之间现有的协议和数据条款适用
* **统一网关** — 仍可在上层享受 ARouter 的路由、故障切换和可观测性

***

## BYOK 工作原理

```
您的请求 → ARouter 网关 → [路由选择] → 服务商 API（使用您的密钥）
```

1. 您在 ARouter 控制台中注册服务商 API 密钥
2. 当 ARouter 将请求路由到该服务商时，它会替换为您的密钥
3. 您的账户不收取 token 成本（仅收取 ARouter 服务费，如适用）
4. 响应中返回 `usage.is_byok: true`

***

## 注册密钥

在 [ARouter 控制台](https://arouter.ai/settings/byok) 中添加服务商密钥。

支持的服务商及其密钥格式：

| 服务商              | 密钥格式           | 控制台标签                |
| ---------------- | -------------- | -------------------- |
| OpenAI           | `sk-...`       | OpenAI API Key       |
| Anthropic        | `sk-ant-...`   | Anthropic API Key    |
| Google (Gemini)  | `AIza...`      | Google AI Studio Key |
| Azure OpenAI     | 端点 + 密钥        | Azure OpenAI         |
| AWS Bedrock      | 访问密钥 + 秘密 + 区域 | AWS Bedrock          |
| Google Vertex AI | 服务账户 JSON      | Google Vertex AI     |

***

## BYOK 与服务商排序结合

将 BYOK 与 `provider.order` 结合使用来控制何时使用您的密钥：

```json theme={null}
{
  "model": "openai/gpt-5.4",
  "messages": [{"role": "user", "content": "Hello"}],
  "provider": {
    "order": ["OpenAI"]
  }
}
```

当 `OpenAI` 在排序列表中且您已注册 OpenAI BYOK 密钥时，ARouter 会自动为该服务商使用您的密钥。

### 部分 BYOK

您可以为部分服务商注册密钥，同时对其他服务商使用 ARouter 的共享池：

```json theme={null}
{
  "model": "anthropic/claude-sonnet-4.6",
  "provider": {
    "order": ["Anthropic", "AWS Bedrock"]
  }
}
```

如果您有 Anthropic BYOK 密钥，将首先使用您的密钥尝试 Anthropic。如果您有 AWS Bedrock 密钥，接下来尝试它。否则 ARouter 回退到其共享池。

***

## Azure OpenAI

注册您的 Azure OpenAI 端点和密钥：

```json theme={null}
{
  "provider_name": "Azure",
  "azure_endpoint": "https://your-resource.openai.azure.com",
  "azure_api_key": "your-azure-key",
  "azure_deployment": "gpt-5-4"
}
```

然后路由到它：

```json theme={null}
{
  "model": "openai/gpt-5.4",
  "provider": {
    "order": ["Azure"]
  }
}
```

***

## AWS Bedrock

两种认证选项：

**选项 1：Bedrock API 密钥（推荐）**

```json theme={null}
{
  "provider_name": "Bedrock",
  "aws_access_key_id": "AKIA...",
  "aws_secret_access_key": "your-secret",
  "aws_region": "us-east-1"
}
```

**选项 2：AWS 凭证**

```json theme={null}
{
  "provider_name": "Bedrock",
  "aws_credentials": {
    "access_key_id": "AKIA...",
    "secret_access_key": "...",
    "session_token": "...",
    "region": "us-east-1"
  }
}
```

***

## Google Vertex AI

```json theme={null}
{
  "provider_name": "VertexAI",
  "vertex_service_account": {
    "type": "service_account",
    "project_id": "your-project",
    "private_key_id": "...",
    "private_key": "-----BEGIN RSA PRIVATE KEY-----\n...",
    "client_email": "your-sa@your-project.iam.gserviceaccount.com"
  }
}
```

***

## 识别 BYOK 请求

当使用了您的密钥时，响应的 `usage` 对象中包含 `is_byok: true`：

```json theme={null}
{
  "usage": {
    "prompt_tokens": 120,
    "completion_tokens": 45,
    "total_tokens": 165,
    "cost": 0.00,
    "is_byok": true
  }
}
```

当 `is_byok: true` 时，`usage.cost` 反映您的直接服务商成本（非 ARouter 加价）。

***

## 密钥优先级与回退

| 场景                                  | 行为                                           |
| ----------------------------------- | -------------------------------------------- |
| 已为服务商注册 BYOK 密钥                     | 使用您的密钥                                       |
| BYOK 密钥已注册但服务商不可用                   | 回退到 ARouter 共享池（除非 `allow_fallbacks: false`） |
| 该服务商无 BYOK 密钥                       | 使用 ARouter 共享池                               |
| `allow_fallbacks: false` 且无 BYOK 密钥 | 请求失败，返回 404                                  |

***

## 调试 BYOK 问题

在控制台的活动页面中查看每个请求使用了哪个密钥。常见错误：

| 错误                 | 原因          | 修复方法                   |
| ------------------ | ----------- | ---------------------- |
| `401 Unauthorized` | 服务商密钥无效或已过期 | 在控制台设置中轮换密钥            |
| `403 Forbidden`    | 密钥缺少所需权限    | 检查服务商 IAM 设置           |
| `quota_exceeded`   | 您的服务商配额已用尽  | 升级服务商套餐或移除 BYOK 以使用共享池 |