BYOK（Bring Your Own Keys）允许你在 OpenRouter 上使用自己的 provider API Key，直接控制速率限制和成本。配置后的密钥会被加密存储，所有路由到该 provider 的请求优先使用你的 Key。费用为同等调用正常价格的 5%（每月前 100 万次 BYOK 请求免收此费用）。BYOK Key 始终优先于路由顺序，即使在 order 数组中排在后面。支持 Azure（JSON 数组）、AWS Bedrock（Bedrock API Key 字符串或 AWS Credentials JSON）、Google Vertex（服务账号 JSON）三类 provider。

OpenRouter 支持使用自己的 provider API Key（BYOK），让你直接控制速率限制和成本。

基本说明

• 密钥加密存储，用于所有路由到该 provider 的请求
• 费用：正常价格的 5%，每月前 100 万次 BYOK 请求免费
• 在 账户设置 > Integrations 中管理

Key 优先级与 Fallback

OpenRouter 始终优先使用你的 provider Key。默认情况下，如果 Key 遇到速率限制或失败，会自动 fallback 到 OpenRouter 的共享 credits。

配置"Always use this key"可防止任何 fallback——只用你的 Key，Key 耗尽时直接报错，确保所有请求走你的账户。

BYOK 与 Provider 路由顺序

BYOK Key 始终优先于路由顺序中的位置，无论 order 数组怎么排列。所有 BYOK endpoints 耗尽后，再按指定顺序 fallback 到共享容量。

示例：有 Bedrock、Vertex、Anthropic 三个 BYOK Key，order 为 ["amazon-bedrock", "google-vertex", "anthropic"]，实际路由顺序：

1. Amazon Bedrock（你的 BYOK Key）
2. Google Vertex AI（你的 BYOK Key）
3. Anthropic（你的 BYOK Key）
4. Amazon Bedrock（共享容量）
5. Google Vertex AI（共享容量）
6. Anthropic（共享容量）

部分 BYOK

只有 Google Vertex BYOK，order 为 ["amazon-bedrock", "google-vertex"]：

1. Google Vertex AI（BYOK，虽然排第二但优先）
2. Amazon Bedrock（共享容量）
3. Google Vertex AI（共享容量）

同一 Provider 多个 Key

所有 Key 都参与路由，但多个 Key 之间的选择顺序不保证。

Azure API Key 配置

提供 JSON 格式：

{
  "model_slug": "the-openrouter-model-slug",
  "endpoint_url": "https://<resource>.services.ai.azure.com/deployments/<model-id>/chat/completions?api-version=<api-version>",
  "api_key": "your-azure-api-key",
  "model_id": "the-azure-model-id"
}

多模型配置（数组形式）：

[
  {
    "model_slug": "mistralai/mistral-large",
    "endpoint_url": "https://example-project.openai.azure.com/openai/deployments/mistral-large/chat/completions?api-version=2024-08-01-preview",
    "api_key": "your-azure-api-key",
    "model_id": "mistral-large"
  },
  {
    "model_slug": "openai/gpt-5.2",
    "endpoint_url": "https://example-project.openai.azure.com/openai/deployments/gpt-5.2/chat/completions?api-version=2024-08-01-preview",
    "api_key": "your-azure-api-key",
    "model_id": "gpt-5.2"
  }
]

字段说明：model_slug 是 OpenRouter 的模型 ID；endpoint_url 在 Azure 门户的 "Overview" 中找到，末尾加 /chat/completions；model_id 是 Azure 中的部署名称。

AWS Bedrock API Key 配置

方式一：Bedrock API Keys（推荐）

直接提供 Bedrock API Key 字符串。注意：Bedrock API Key 绑定特定 AWS 区域，不能跨区域使用。

在 AWS 管理控制台生成 Bedrock API Key。

方式二：AWS 凭证 JSON

{
  "accessKeyId": "your-aws-access-key-id",
  "secretAccessKey": "your-aws-secret-access-key",
  "region": "your-aws-region"
}

所需 IAM 权限：

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "bedrock:InvokeModel",
        "bedrock:InvokeModelWithResponseStream"
      ],
      "Resource": "*"
    }
  ]
}

建议为 OpenRouter 专门创建一个权限最小化的 IAM 用户。

Google Vertex AI Key 配置

提供服务账号 JSON（含可选的 region 字段）：

{
  "type": "service_account",
  "project_id": "your-project-id",
  "private_key_id": "your-private-key-id",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
  "client_email": "your-service-account@your-project.iam.gserviceaccount.com",
  "client_id": "your-client-id",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/...",
  "universe_domain": "googleapis.com",
  "region": "global"
}

region 字段："global" 允许在任意可用区域运行；也可指定如 "us-central1"。所需权限：aiplatform.endpoints.predict（角色：roles/aiplatform.user）。

BYOK 问题排查

查看 Provider 响应

1. 前往 Activity 页面
2. 找到问题请求，点击查看详情
3. 点击"View Raw Metadata"
4. 查看 provider_responses 字段（含每次尝试的 provider 名和 HTTP 状态码）

常见错误码

状态码	含义	排查方向
400	请求格式错误	检查模型 ID 和 Key 配置格式
401	Key 无效或已撤销	在 provider 控制台验证 Key 是否有效
403	权限不足	AWS：检查 IAM 策略；Vertex：检查服务账号权限
429	超过速率限制	检查 provider 账户的限额设置
500	Provider 内部错误	通常是临时性问题，稍后重试

常见问题

Q: 使用 BYOK 后还会产生 OpenRouter 费用吗？

A: 会，但很少。费用为同等调用正常 OpenRouter 价格的 5%，用于平台路由和管理服务。每月前 100 万次 BYOK 请求免收此费用。

Q: BYOK Key 和 OpenRouter Key 哪个先用？

A: BYOK 始终优先。只有在你的 Key 遇到错误且未设置"Always use this key"时，才会 fallback 到 OpenRouter 共享容量。

Q: 可以为同一个 provider 配置多个 Key 吗？

A: 可以，所有 Key 都会参与路由，但多个 Key 之间的选择顺序不保证确定性。