> ## 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 以使用共享池 |