鉴权

密钥在哪申领、三种等价的请求头写法，以及密钥失效时的排查顺序。

API 密钥#

全部端点共用一个密钥，以 sk-ar- 开头，在控制台的 API 密钥页申领。换模型、换端点都不用换密钥。

可调用 /v1/chat/completions、/v1/messages、/v1/images/generations、/v1/embeddings、/v1/rerank、/v1/videos、/v1/models。
一个密钥能用哪些模型由它自己的模型白名单决定，与前缀无关；被白名单挡掉时报 model_not_allowed，不是 401。

三种等价的请求头#

密钥须放在请求头中，不要置于 URL 查询串上——查询串会进入访问日志、浏览器历史与 Referer 头。下列三个请求头均被接受，取第一个非空者，优先顺序为 Authorization、X-Api-Key、api-key。

请求头	写法	为什么支持
`Authorization`	`Bearer sk-ar-...`	绝大多数 SDK 的默认形态
`X-Api-Key`	`sk-ar-...`（不带 Bearer）	Anthropic 官方 SDK 用这个头
`api-key`	`sk-ar-...`（不带 Bearer）	Azure OpenAI SDK 用这个头

三种写法同时支持，迁移时无需改动客户端代码：将 SDK 的 base URL 指向本平台、把密钥换成平台签发的即可。三种请求头对全部推理端点等价，包括 /v1/* 与 /api/v3/contents/generations/tasks。

先验证密钥可用#

在编写业务代码之前，建议先用一条不消耗额度的请求确认密钥可用。/v1/models 会返回该密钥可访问的模型清单，不产生费用。

密钥自检：能列出模型就说明鉴权通了

bash

curl https://ogrouter.ai/v1/models \  -H "Authorization: Bearer $AIROUTER_API_KEY"

拿到 200 与一份 data 数组即为正常。若是 401，跳到本页最后一节按现象对照排查。

在代码里带上密钥#

密钥从环境变量读，不要写进源码——提交进 Git 的密钥即使随后删掉也仍留在历史里，必须当作已泄漏处理。

先把密钥放进环境变量

bash

export AIROUTER_API_KEY="sk-ar-你的密钥"

Python：用 openai 库，只改两行

python

import osfrom openai import OpenAI
client = OpenAI(    api_key=os.environ["AIROUTER_API_KEY"],    base_url="https://ogrouter.ai/v1",)
print(client.models.list().data[0].id)

Node.js：同样只改 baseURL 与 apiKey

javascript

import OpenAI from 'openai';
const client = new OpenAI({  apiKey: process.env.AIROUTER_API_KEY,  baseURL: 'https://ogrouter.ai/v1',});
const models = await client.models.list();console.log(models.data[0].id);

Java：密钥放在请求头里，不写进源码

java

import java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse;
// 不装 SDK 也能调：密钥放在请求头，能列出模型就说明鉴权通了HttpRequest request = HttpRequest.newBuilder(URI.create("https://ogrouter.ai/v1/models"))    .header("Authorization", "Bearer " + System.getenv("AIROUTER_API_KEY"))    .GET()    .build();
HttpResponse<String> response = HttpClient.newHttpClient()    .send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode());System.out.println(response.body());

不装 SDK 也可以

所有端点均为标准的 HTTPS 与 JSON，使用 curl、requests、fetch 直接调用同样可行。本文档为每个端点都提供了 curl 示例，可直接参照。

鉴权失败的排查顺序#

401 仅表示该密钥当前无法通过鉴权，具体原因由响应体的 code 字段给出。

`code`	含义	怎么办
`missing_credential`	请求里没找到密钥	检查请求头名字是否拼错，以及是否被代理层剥掉了
`invalid_credential`	密钥不存在或已吊销	前往 API 密钥确认该密钥仍存在且处于启用状态
`ip_not_allowed`	来源 IP 不在密钥的白名单里	改白名单，或从允许的出口调用
`insufficient_quota`	余额或密钥配额不足	到钱包充值，或调高该密钥的额度上限

每个错误响应都带有 request_id。若无法自行排查，请将它连同大致的调用时间提交工单，平台据此可定位到具体的那一次调用。

轮换与吊销#

密钥明文只在创建时显示一次，平台不保存明文，事后无法找回。列表中只显示后四位，用于区分不同密钥。

按用途分开建密钥（线上、预发、本地各一个），泄漏时的爆炸半径就是一个环境而不是全部。
轮换顺序是先建新的、切流量、确认无误后再吊销旧的——反过来会有一段没有可用密钥的空窗。
一旦怀疑泄漏应立即吊销，不必等待排查结论。吊销即时生效，重建密钥的成本远低于额度被盗用的损失。

鉴权

密钥在哪申领、三种等价的请求头写法，以及密钥失效时的排查顺序。

API 密钥#

全部端点共用一个密钥，以 sk-ar- 开头，在控制台的 API 密钥页申领。换模型、换端点都不用换密钥。

可调用 /v1/chat/completions、/v1/messages、/v1/images/generations、/v1/embeddings、/v1/rerank、/v1/videos、/v1/models。
一个密钥能用哪些模型由它自己的模型白名单决定，与前缀无关；被白名单挡掉时报 model_not_allowed，不是 401。

三种等价的请求头#

请求头	写法	为什么支持
`Authorization`	`Bearer sk-ar-...`	绝大多数 SDK 的默认形态
`X-Api-Key`	`sk-ar-...`（不带 Bearer）	Anthropic 官方 SDK 用这个头
`api-key`	`sk-ar-...`（不带 Bearer）	Azure OpenAI SDK 用这个头

先验证密钥可用#

在编写业务代码之前，建议先用一条不消耗额度的请求确认密钥可用。/v1/models 会返回该密钥可访问的模型清单，不产生费用。

密钥自检：能列出模型就说明鉴权通了

bash

curl https://ogrouter.ai/v1/models \  -H "Authorization: Bearer $AIROUTER_API_KEY"

拿到 200 与一份 data 数组即为正常。若是 401，跳到本页最后一节按现象对照排查。

在代码里带上密钥#

密钥从环境变量读，不要写进源码——提交进 Git 的密钥即使随后删掉也仍留在历史里，必须当作已泄漏处理。

先把密钥放进环境变量

bash

export AIROUTER_API_KEY="sk-ar-你的密钥"

Python：用 openai 库，只改两行

python

import osfrom openai import OpenAI
client = OpenAI(    api_key=os.environ["AIROUTER_API_KEY"],    base_url="https://ogrouter.ai/v1",)
print(client.models.list().data[0].id)

Node.js：同样只改 baseURL 与 apiKey

javascript

import OpenAI from 'openai';
const client = new OpenAI({  apiKey: process.env.AIROUTER_API_KEY,  baseURL: 'https://ogrouter.ai/v1',});
const models = await client.models.list();console.log(models.data[0].id);

Java：密钥放在请求头里，不写进源码

java

import java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse;
// 不装 SDK 也能调：密钥放在请求头，能列出模型就说明鉴权通了HttpRequest request = HttpRequest.newBuilder(URI.create("https://ogrouter.ai/v1/models"))    .header("Authorization", "Bearer " + System.getenv("AIROUTER_API_KEY"))    .GET()    .build();
HttpResponse<String> response = HttpClient.newHttpClient()    .send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode());System.out.println(response.body());

不装 SDK 也可以

所有端点均为标准的 HTTPS 与 JSON，使用 curl、requests、fetch 直接调用同样可行。本文档为每个端点都提供了 curl 示例，可直接参照。

鉴权失败的排查顺序#

401 仅表示该密钥当前无法通过鉴权，具体原因由响应体的 code 字段给出。

`code`	含义	怎么办
`missing_credential`	请求里没找到密钥	检查请求头名字是否拼错，以及是否被代理层剥掉了
`invalid_credential`	密钥不存在或已吊销	前往 API 密钥确认该密钥仍存在且处于启用状态
`ip_not_allowed`	来源 IP 不在密钥的白名单里	改白名单，或从允许的出口调用
`insufficient_quota`	余额或密钥配额不足	到钱包充值，或调高该密钥的额度上限

每个错误响应都带有 request_id。若无法自行排查，请将它连同大致的调用时间提交工单，平台据此可定位到具体的那一次调用。

轮换与吊销#

密钥明文只在创建时显示一次，平台不保存明文，事后无法找回。列表中只显示后四位，用于区分不同密钥。

按用途分开建密钥（线上、预发、本地各一个），泄漏时的爆炸半径就是一个环境而不是全部。
轮换顺序是先建新的、切流量、确认无误后再吊销旧的——反过来会有一段没有可用密钥的空窗。
一旦怀疑泄漏应立即吊销，不必等待排查结论。吊销即时生效，重建密钥的成本远低于额度被盗用的损失。