自带密钥（BYOK）

使用你自己的模型服务提供商 API 密钥

自带 API 密钥

OpenRouter 既支持 OpenRouter 额度，也支持 自带服务提供商密钥（BYOK）。

当你使用 OpenRouter 额度时，各服务提供商的速率限制 由 OpenRouter 管理。

使用服务提供商密钥，可以通过你的服务提供商账户直接控制速率限制和成本。

你的服务提供商密钥会被安全加密，并用于所有路由到指定服务提供商的请求。

在 工作区 BYOK 设置 中管理密钥。

在 OpenRouter 上使用自定义服务提供商密钥的费用为 同一模型 / 服务提供商在 OpenRouter 上正常费用的 5%， 并从你的 OpenRouter 额度中扣除。 每月前 1M 次 BYOK 请求免收此费用。

密钥优先级与回退

每把 BYOK 密钥属于以下两个分区之一：

• 优先（Prioritized），按顺序尝试，然后再回退到 OpenRouter 端点。将主要服务提供商密钥放在此分区。
• 回退（Fallback），仅在 OpenRouter 端点 尝试完毕后按顺序使用。将你只想作为最后手段使用的备用密钥放在此分区。

你可以在服务提供商详情页 （例如 /workspaces/default/byok/openai） 上将密钥拖到不同分区。

默认情况下，如果两个分区中的所有密钥都遇到 速率限制或失败，OpenRouter 会回退到 使用共享的 OpenRouter 端点。

你可以在各个优先密钥上切换 「始终用于此服务提供商（Always use for this provider）」，以阻止任何回退到 OpenRouter 端点。启用后，OpenRouter 只会使用你的密钥向该服务提供商发送请求，这可能 会在密钥耗尽时导致速率限制错误， 但能确保所有请求都走你的账户。

当你为同一服务提供商配置了多把密钥时， OpenRouter 会按优先级顺序尝试它们（见 同一服务提供商的多把 BYOK 密钥）。 如果第一把密钥失败，它会继续尝试下一把 匹配的密钥，然后再回退到共享容量。

结合服务提供商排序使用 BYOK

当你把 BYOK 密钥与 服务提供商排序 结合使用时，OpenRouter 始终优先使用 BYOK 端点，无论该服务提供商在你指定的顺序中处于什么位置。所有 BYOK 端点耗尽后，OpenRouter 会按你指定的顺序回退到共享容量。

这意味着 BYOK 密钥实际上会覆盖初始路由尝试时的服务提供商排序。目前无法更改此行为。

例如，如果你有 Amazon Bedrock、Google Vertex AI 和 Anthropic 的 BYOK 密钥，并发送如下请求：

{
  "provider": {
    "allow_fallbacks": true,
    "order": ["amazon-bedrock", "google-vertex", "anthropic"]
  }
}

路由顺序将是：

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

部分 BYOK 与服务提供商排序

如果你只为排序中的部分服务提供商配置了 BYOK 密钥，仍会先尝试该 BYOK 服务提供商。例如，如果你指定 order: ["amazon-bedrock", "google-vertex"]，但只为 Google Vertex AI 配置了 BYOK 密钥：

{
  "provider": {
    "allow_fallbacks": true,
    "order": ["amazon-bedrock", "google-vertex"]
  }
}

路由顺序将是：

1. Google Vertex AI（你的 BYOK 密钥）
2. Amazon Bedrock（OpenRouter 的共享容量）
3. Google Vertex AI（OpenRouter 的共享容量）

请注意，即使 Amazon Bedrock 在 order 数组中排在第一位，Google Vertex AI 的 BYOK 端点仍会优先。

如果要完全阻止回退到 OpenRouter 端点， 请在 工作区 BYOK 设置 中为 BYOK 密钥启用 「始终用于此服务提供商」。

BYOK 与数据政策

BYOK 端点受你的数据政策约束。自带密钥只会改变用于向上游请求做身份验证的凭据，不会改变你被允许路由到哪些端点。你的服务提供商、账户和护栏数据政策会在 创建 BYOK 端点之前 应用，因此 BYOK 只会路由到已经满足这些政策的端点。

这意味着 BYOK 密钥不会让服务提供商免受你的 零数据保留（ZDR，Zero Data Retention） 或 data_collection 限制。如果你强制执行 ZDR（通过 provider.zdr、账户隐私设置或护栏），而某服务提供商的端点会保留提示词，即使你提供了自己的密钥，该端点仍然不合格。

例如，如果你强制执行 ZDR，并发送一个本会使用某服务提供商 BYOK 密钥的请求，但该服务提供商的端点会保留提示词：

{
  "provider": {
    "zdr": true
  }
}

会在考虑你的 BYOK 密钥之前过滤掉会保留数据的端点；如果没有剩余符合 ZDR 的端点，请求就会失败，即使你持有该服务提供商的有效密钥。

要通过 BYOK 使用某服务提供商，请确保它被你的数据政策允许：该服务提供商的端点必须满足你已启用的任何 ZDR 或 data_collection 限制。参见 零数据保留 和 服务提供商路由。

BYOK 与护栏预算

默认情况下，BYOK 推理支出 不 计入 护栏 预算。只有 OpenRouter 额度支出会计入。这意味着即使已有大量 BYOK 用量，预算限额也可能看起来远未用尽。

要将 BYOK 支出计入护栏预算，请在护栏上启用 计入 BYOK 支出（Include BYOK spend）（或通过 管理 API 将 include_byok_in_budgets 设为 true）。启用后，OpenRouter 在该请求未使用你自己的服务提供商密钥时本会收取的金额，会与额度支出一并计入预算；合计达到限额后，护栏会阻止请求。

此开关适用于所有护栏预算，包括工作区默认护栏。对没有预算限额的护栏没有效果。

BYOK 与工作区预算

工作区预算 的行为相同，并且与护栏分开控制。默认情况下 BYOK 支出 不 计入工作区预算；请在工作区的预算设置中启用 计入 BYOK 支出，或在工作区预算端点上将 include_byok_in_budgets 设为 true。

该工作区设置会同时应用于该工作区的每个区间（日、周、月和终身）。

同一服务提供商的多把 BYOK 密钥

你可以为同一服务提供商配置多把 BYOK 密钥。所有匹配的密钥都会用于路由，每把密钥都会生成各自的端点副本，并在整个请求生命周期中绑定到该特定密钥。

优先级顺序

密钥按其分区内你定义的顺序尝试。 先尝试优先密钥，然后是 OpenRouter 端点，最后是回退密钥。你可以在服务提供商详情页 （例如 /workspaces/default/byok/openai） 上通过拖放重新排序密钥。 当某把密钥失败（例如速率限制或错误）时，OpenRouter 会继续尝试下一把匹配的密钥。

例如，如果你有三把 OpenAI 密钥：

• 优先分区：第一把密钥、第二把密钥
• 回退分区：备用密钥

OpenRouter 会尝试：第一把密钥，然后第二把密钥， 然后 OpenRouter 端点，然后备用密钥。

密钥筛选器

每把 BYOK 密钥都支持可选筛选器，用于控制何时使用它：

• 模型筛选器，将密钥限制为特定模型（例如仅将此密钥用于 openai/gpt-4o）。设置后，该密钥只用于列出的模型。同一服务提供商的其他模型会跳过此密钥。
• API 密钥筛选器，限制哪些 OpenRouter API 密钥可以使用此 BYOK 密钥。适用于将 BYOK 用量隔离到特定应用或环境。
• 成员筛选器，限制哪些工作区成员可以使用此 BYOK 密钥。适用于让不同团队成员访问不同的服务提供商账户。

筛选器在路由之前评估。只有当所有已启用的筛选器都匹配当前请求时，才会使用该密钥。如果未设置筛选器，该密钥对所有模型、API 密钥和成员可用。

将筛选器与多把密钥结合

筛选器和多把密钥可以一起使用，以实现灵活的路由策略。例如：

• 密钥 A：OpenAI，模型筛选器 = [openai/gpt-4o]，已启用「始终用于此服务提供商」
• 密钥 B：OpenAI，无模型筛选器（匹配所有模型）

在此设置下：

• 针对 openai/gpt-4o 的请求会先尝试 密钥 A，若密钥 A 失败再尝试 密钥 B（由于密钥 A 启用了「始终用于此服务提供商」，会跳过共享容量）
• 针对其他 OpenAI 模型（例如 openai/gpt-4o-mini）的请求只使用 密钥 B，并以共享容量作为回退

密钥名称

每把密钥都可以有一个可选名称（例如「生产环境」「团队 A」「仅 GPT-4」），便于在同一服务提供商有多把密钥时进行整理。

Azure API 密钥

Azure 有两种资源类型，分别使用不同的域名：

• Azure AI Foundry，资源位于 *.services.ai.azure.com。使用模型目录，不需要按模型部署。
• Azure OpenAI，资源位于 *.openai.azure.com。需要显式的按模型部署。

Foundry 配置（推荐）

配置 Azure BYOK 最简单的方式是使用 Foundry 配置。提供你的 API 密钥、资源名称和资源类型：

[
  {
    "api_key": "your-azure-api-key",
    "resource_name": "your-resource-name",
    "resource_type": "ai_foundry"
  }
]

• api_key：你的 Azure API 密钥，可在 Azure 门户的「密钥和终结点」下找到。
• resource_name：Azure 资源的名称（终结点 URL 的子域部分）。
• resource_type：Azure AI Foundry 资源（*.services.ai.azure.com）为 "ai_foundry"，Azure OpenAI 资源（*.openai.azure.com）为 "openai"。省略时默认为 "openai"。

此配置适用于你 Azure 资源中的所有可用模型，无需按模型进行设置。

按部署配置（旧版）

若需要更多控制，你可以指定带完整端点 URL 的各个部署：

[
  {
    "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"
  }
]

每项按部署配置需要：

1. endpoint_url：包含 /chat/completions 和 API 版本的完整部署端点 URL。详情见 Azure Foundry 文档。
2. api_key：你的 Azure API 密钥。
3. model_id：Azure 中模型部署的名称。
4. model_slug：你希望此密钥用于的 OpenRouter 模型标识符。

你可以在同一数组中混合 Foundry 和按部署配置。当找到匹配的模型 slug 时，按部署配置优先。

AWS Bedrock API 密钥

要在 OpenRouter 上使用 Amazon Bedrock，你可以使用 Bedrock API 密钥或传统 AWS 凭据进行身份验证。

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

Amazon Bedrock API 密钥提供更简单的身份验证方式。只需将 Bedrock API 密钥作为字符串提供：

your-bedrock-api-key-here

注意： Bedrock API 密钥绑定到特定 AWS 区域，不能用于切换区域。如果需要在不同区域使用模型，请使用下面的 AWS 凭据选项。

你可以在 AWS Management Console 中生成 Bedrock API 密钥。更多信息见 Amazon Bedrock API 密钥文档。

选项 2：AWS 凭据

或者，你可以使用 JSON 格式的传统 AWS 凭据。此选项允许你指定区域，并提供更高灵活性：

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

你可以在 AWS 账户中找到这些值：

1. accessKeyId：这是你的 AWS Access Key ID。你可以在 AWS Management Console 的「安全凭证」下创建或查找访问密钥。

2. secretAccessKey：这是你的 AWS Secret Access Key，在创建访问密钥时提供。

3. region：部署 Amazon Bedrock 模型的 AWS 区域（例如 "us-east-1"、"us-west-2"）。

确保你的 AWS IAM 用户或角色具有访问 Amazon Bedrock 服务所需的权限。至少需要以下权限：

• bedrock:InvokeModel
• bedrock:InvokeModelWithResponseStream（用于流式响应）

示例 IAM 策略：

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

为提高安全性，我们建议创建权限受限的专用 IAM 用户，专门用于 OpenRouter。

更多信息见 AWS Bedrock API 入门 文档、IAM 权限设置 指南，或 AWS Bedrock API 参考。

Google Vertex API 密钥

要在 OpenRouter 上使用 Google Vertex AI，你需要以 JSON 格式提供 Google Cloud 服务账号密钥。服务账号密钥应包含所有标准 Google Cloud 服务账号字段，并可选用可选的 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/your-service-account@your-project.iam.gserviceaccount.com",
  "universe_domain": "googleapis.com",
  "region": "global"
}

你可以在 Google Cloud Console 中找到这些值：

1. 服务账号密钥：打开 Google Cloud Console，前往「IAM 和管理」>「服务账号」，选择你的服务账号，然后创建 / 下载 JSON 密钥。

2. region（可选）：指定 Vertex AI 部署的区域。使用 "global" 允许请求在任何可用区域运行，或指定具体区域，例如 "us-central1" 或 "europe-west1"。

确保你的服务账号具有访问 Vertex AI 服务所需的权限：

• aiplatform.endpoints.predict

示例 IAM 策略：

{
  "bindings": [
    {
      "role": "roles/aiplatform.user",
      "members": [
        "serviceAccount:your-service-account@your-project.iam.gserviceaccount.com"
      ]
    }
  ]
}

更多信息见 Google Cloud Vertex AI 文档 和 服务账号设置指南。

调试 BYOK 问题

如果 BYOK 请求失败，你可以在活动页面查看服务提供商响应来调试问题。

查看服务提供商响应

1. 在 OpenRouter 控制台中打开 活动页面。
2. 找到要调试的生成记录并点击以查看详情。
3. 点击「查看原始元数据（View Raw Metadata）」以 JSON 格式显示原始元数据。
4. 在 JSON 中查找 provider_responses 字段，它显示每次服务提供商尝试的 HTTP 状态码。

provider_responses 字段包含路由期间每次尝试的服务提供商响应数组。每条记录包括服务提供商名称和 HTTP 状态码，可帮助你识别权限问题、速率限制或其他错误。

常见 BYOK 错误代码

调试 BYOK 问题时，请在服务提供商响应中留意这些常见 HTTP 状态码：

• 400 Bad Request：请求格式对该服务提供商无效。请检查模型和密钥配置是否正确。
• 401 Unauthorized：你的 API 密钥无效或已被撤销。请在服务提供商控制台中验证密钥。
• 403 Forbidden：你的 API 密钥没有访问所请求资源的权限。对于 AWS Bedrock，请确保 IAM 策略包含所需的 bedrock:InvokeModel 权限。对于 Google Vertex，请验证服务账号具有 aiplatform.endpoints.predict 权限。
• 429 Too Many Requests：你已达到服务提供商账户的速率限制。请检查服务提供商的速率限制设置，或等待后再重试。
• 500 Server Error：服务提供商遇到内部错误。这通常是服务提供商侧的临时问题。

调试权限问题

如果 BYOK 遇到 403 错误，问题通常与权限有关。对于 AWS Bedrock，请验证：

1. 你的 IAM 用户 / 角色具有 bedrock:InvokeModel 和 bedrock:InvokeModelWithResponseStream 权限。
2. 你尝试访问的模型已在指定区域的 AWS 账户中启用。
3. 你的凭据（访问密钥和密钥）正确且处于活动状态。

对于 Google Vertex，请验证服务账号具有 aiplatform.endpoints.predict 权限。

你可以先在服务提供商自己的控制台（AWS Console、Google Cloud Console 等）中尝试调用该模型，直接测试服务提供商权限。