AI Gateway API Key 怎么配置？
简答：先确认你手里的 Key 属于网关访问凭证还是上游模型供应商凭证，再按服务商给出的 Base URL、认证头和模型名配置。最小闭环是：保存 Key → 设置 Base URL → 发一次最小请求 → 根据 401、403、404 或模型不存在分流排查；不要直接猜测是否要加 /v1。
定义：AI Gateway API Key 是客户端访问网关或由网关代为访问上游模型的认证凭证，具体放在 Authorization、x-api-key、api-key 或服务商自定义请求头中，取决于网关接口规范。
先试这一步：三类凭证和三个配置项不要混用
本文是第三方 AI API 接入指南，不代表任何具体 AI Gateway 服务的官方文档。不同网关的控制台字段、认证头和请求路径可能不同；如果你使用的是某个具体平台，应优先以该平台控制台显示的示例和当前文档为准。
| 配置项 | 它解决什么问题 | 填写依据 | 常见错误 |
|---|---|---|---|
| 网关访问 Key | 证明客户端有权限调用网关 | 网关控制台生成的运行时 Key、API Key 或访问令牌 | 误填成 OpenAI、Anthropic 等上游 Key |
| 上游供应商 Key | 让网关访问具体模型供应商 | 供应商后台生成的 API Key，或由网关的 BYOK 功能托管 | 已经启用 BYOK，却仍发送过期或占位的上游 Key |
| Base URL | 决定请求发往哪个网关和接口族 | 服务商给出的完整基础地址 | 重复拼接 /v1，或把完整请求路径当成 Base URL |
| 模型名 | 决定网关路由到哪个已注册模型 | 网关模型列表、控制台示例或 API 返回结果 | 使用供应商原名，但网关要求 provider/model 格式 |
例如，Vercel AI Gateway 的官方示例使用 AI_GATEWAY_API_KEY，并把 OpenAI SDK 的 baseURL 指向带 /v1 的地址；Azure AI Gateway 的示例则要求复制控制台提供的精确 Base URL，并使用运行时访问 Key。两者不能互相套用。参考：Vercel AI Gateway 认证文档、Azure AI Gateway 快速入门。
配置流程：从创建 Key 到首次成功请求
- 确认 Key 的来源。在控制台查找 API Keys、Runtime access keys、Gateway keys 或类似入口。如果页面只允许添加 Provider Key，那通常是在配置 BYOK，不一定等于客户端调用网关所需的访问 Key。
- 复制完整 Base URL。不要凭经验补充
/v1。有的 OpenAI 兼容网关把/v1放在 Base URL 中，有的服务商要求客户端自动拼接，有的则使用包含账号、网关名和供应商名的完整路径。官方 Azure 文档明确建议直接复制网关概览页显示的 Base URL。 - 确认认证头。常见形式包括
Authorization: Bearer YOUR_GATEWAY_KEY、x-api-key: YOUR_GATEWAY_KEY和api-key: YOUR_GATEWAY_KEY。不要把这三个头同时发送，也不要把供应商认证头误当作网关认证头。 - 确认模型名。优先从模型列表、控制台调用示例或网关的模型管理页复制。模型字段可能是
gpt-...、claude-...，也可能是带供应商前缀的provider/model，不能仅凭模型品牌猜测。 - 发最小请求。先关闭流式输出，使用短文本和低复杂度请求验证认证、路径和模型路由。成功判定应同时包括 HTTP 2xx、响应中存在可读文本，以及返回的模型字段或用量字段符合该接口文档。
如果网关支持 BYOK，通常流程是先在控制台安全保存供应商 Key，再让应用只携带网关认证信息。Cloudflare AI Gateway 的官方说明就是这种模式：应用删除硬编码的供应商 Key，网关从已保存的 Provider Key 中取用；但该行为只适用于其规定的接口和配置，不能推断到所有网关。参考：Cloudflare AI Gateway BYOK 文档。
环境变量与 OpenAI 兼容请求示例
下面的变量名是通用占位写法，不代表所有平台都要求使用这些名称。请把尖括号内容替换成控制台实际值，并避免把真实 Key 写进 Git、前端代码、截图、日志或命令历史。
Bash 或 zsh
export AI_GATEWAY_BASE_URL="https://your-gateway.example/v1"export AI_GATEWAY_API_KEY="REPLACE_WITH_GATEWAY_KEY"export AI_GATEWAY_MODEL="REPLACE_WITH_MODEL_NAME"
PowerShell
$env:AI_GATEWAY_BASE_URL = "https://your-gateway.example/v1"$env:AI_GATEWAY_API_KEY = "REPLACE_WITH_GATEWAY_KEY"$env:AI_GATEWAY_MODEL = "REPLACE_WITH_MODEL_NAME"
OpenAI 兼容 SDK
import OpenAI from "openai";const client = new OpenAI({ apiKey: process.env.AI_GATEWAY_API_KEY, baseURL: process.env.AI_GATEWAY_BASE_URL});const result = await client.chat.completions.create({ model: process.env.AI_GATEWAY_MODEL, messages: [{ role: "user", content: "Reply with OK" }]});
官方兼容示例表明，部分网关可以通过替换 OpenAI SDK 的 Base URL 接入；但 SDK 具体会拼接哪些路径，仍取决于该网关是否严格实现对应 API。参考：Vercel AI Gateway SDK 与 API 文档。
cURL 最小请求：先验证路径，再判断认证问题
不要把下面地址直接当成所有网关的固定路径。将 REQUEST_URL 替换成服务商文档中明确给出的 Chat Completions 或其他兼容端点；如果 Base URL 已经包含 /v1，就检查请求路径是否会再次添加 /v1。
curl "$REQUEST_URL" \ -H "Authorization: Bearer $AI_GATEWAY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model":"REPLACE_WITH_MODEL_NAME","messages":[{"role":"user","content":"Reply with OK"}],"stream":false}'
如果文档要求 x-api-key，将认证行改为 -H "x-api-key: $AI_GATEWAY_API_KEY"；如果要求 api-key，则改为 -H "api-key: $AI_GATEWAY_API_KEY"。Cloudflare 的官方文档还区分了标准 REST API 的 Authorization 与其特定网关端点使用的 cf-aig-authorization，这说明认证头不能脱离端点单独判断。参考：Cloudflare Authenticated Gateway 文档。
Base URL 是否需要 /v1：用路径表判断，不靠猜
| 你拿到的地址 | 客户端 Base URL 通常怎么填 | 下一步怎么验证 |
|---|---|---|
| 文档明确写 OpenAI-compatible base URL，并以 /v1 结尾 | 通常直接填该地址，不再手动追加 /v1 | 查看 SDK 实际请求路径，确认没有出现 /v1/v1 |
| 文档给的是完整的 /chat/completions 地址 | 不要直接把完整端点当 Base URL，按 SDK 要求拆分 | 用 cURL 直接请求该完整端点，再决定 SDK 配置 |
| 文档给的是网关根地址，另列出 Messages 或 OpenAI 路径 | 按具体 SDK 的接口规范填写 | 分别验证 Anthropic Messages 或 OpenAI Chat Completions 路径 |
| 控制台只显示一条完整调用示例 | 优先照示例调用，不自行改写路径 | 成功后再抽取 Base URL 供 SDK 使用 |
最可靠的判定方法是：先复制官方 cURL 示例成功调用，再观察它的完整 URL、认证头和模型字段；然后只替换客户端，不同时修改 URL、Key、模型和请求格式。一次改一个变量，才能知道问题来自哪里。
401、403、404 和模型不存在：按顺序排查
- 401 Unauthorized：先检查 Key 是否为空、是否复制了前后空格、认证头名称是否正确、Key 是否属于当前网关。若启用了 BYOK，再检查是否错误地发送了无效的供应商认证头；部分 BYOK 实现会在存在供应商头时优先转发该值。
- 403 Forbidden：Key 可能有效但没有调用权限，或网关要求额外的项目、租户、来源域名或运行时权限。回到控制台确认 Key 的作用域和资产访问范围，不要通过重复重试解决权限问题。
- 404 Not Found：优先检查 Base URL、供应商路径、API 版本和是否重复添加
/v1。如果根路径能返回信息但完整端点 404，通常是接口族或路径不匹配；应对照该网关的 OpenAI、Anthropic 或其他接口文档。 - 模型不存在：模型名可能未注册、大小写不同、需要供应商前缀，或当前 Key 无权访问。先查询模型列表或复制控制台示例，不要把公开模型名直接当成网关模型名。
- 429 或超时：先确认不是余额、权限或模型错误。只有文档明确说明是临时限流时，才根据
Retry-After、允许的重试次数和总时限退避；未知错误不要无限重试。
Key 安全：能配置成功，还要避免泄露
- 服务端读取环境变量，浏览器端不要直接暴露长期网关 Key。
.env文件加入忽略规则，提交前检查 Git diff、CI 日志和错误追踪平台。- 测试 Key 与生产 Key 分开，按最小权限和最小可用范围创建。
- 怀疑泄露时先撤销或轮换旧 Key，再检查调用日志；不要只修改本地环境变量。
- 如果使用 BYOK，确认网关是否支持密钥轮换、别名、撤销和使用记录，并按该平台文档操作。
例如 Cloudflare 的 BYOK 文档说明可在控制台查看 Key 的状态和最近使用情况，并支持替换或删除已保存的供应商 Key；这是该平台的能力，不应当作所有 AI Gateway 的通用承诺。
常见问题
AI Gateway API Key 和 OpenAI API Key 是同一个东西吗？
通常不是。网关访问 Key 用来认证客户端到网关的请求；OpenAI、Anthropic 等供应商 Key 用来认证网关到上游供应商的请求。启用 BYOK 后，上游 Key 可能由网关托管，但具体规则取决于平台。
Base URL 一定要加 /v1 吗？
不一定。只有服务商文档或控制台示例明确要求时才添加。先复制官方完整请求验证，再根据 SDK 的路径拼接规则配置；重点防止 /v1/v1 和把 /chat/completions 重复拼接。
Authorization、x-api-key 和 api-key 应该选哪个？
选接口文档明确规定的那个，不要同时发送。Anthropic 风格接口常见 x-api-key，部分 OpenAI 兼容接口使用 Authorization: Bearer，部分 Azure 相关接口使用 api-key；网关可能另有自定义头。
为什么 Key 正确仍然返回 401？
按顺序检查 Key 是否属于当前网关、环境变量是否真正加载、认证头名称和 Bearer 格式是否正确、请求是否发到了正确端点，以及是否误带了无效的上游供应商 Key。
模型名应该填供应商名称还是网关名称？
以网关模型列表或调用示例为准。有的平台接受原始模型名，有的平台要求 provider/model 格式，也有平台使用自定义部署名。模型不存在时不要只更换 Key，应先核对模型注册信息。
能不能把 API Key 写在前端代码里？
不建议。浏览器代码、打包文件、网络请求和错误日志都可能暴露长期凭证。更安全的方式是由后端读取环境变量，再由后端调用网关；如果必须公开调用，应使用平台提供的短期令牌或受限凭证。
相关阅读
参考资料
- Vercel AI Gateway：Authentication & BYOK（vercel.com）
- Vercel AI Gateway：SDKs & APIs（vercel.com）
- Cloudflare AI Gateway：BYOK（Store Keys）
- Cloudflare AI Gateway：Authenticated Gateway
- Microsoft Learn：创建 AI Gateway tier 并完成调用