鉴权

两种 API Key、三种等价的请求头写法，以及密钥失效时的排查顺序。

两种密钥#

平台有两条产品线，各自签发不同前缀的密钥。前缀不只是标识，它决定了这把钥匙能开哪扇门。

前缀	可调用的端点	在哪申领
`sk-ar-`	模型调用：对话、图像、向量化、重排、视频	API 密钥
`sk-srp-`	搜索与阅读：搜索、网页正文、文档识别	搜索阅读

sk-ar- 可用于 /v1/chat/completions、/v1/messages、/v1/images/generations、/v1/embeddings、/v1/rerank、/v1/videos、/v1/models。
sk-srp- 可用于 /v1/search、/v1/reader、/v1/ocr。

两种密钥不通用

拿 sk-ar- 去调 /v1/search，或拿 sk-srp- 去调 /v1/chat/completions，都会得到 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 指过来、把 key 换成我们签发的，就能跑。

先验证密钥可用#

在写业务代码之前，先用一条不花钱的请求确认密钥是通的。/v1/models 返回这把密钥能用的模型清单，不消耗额度。

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

bash

curl https://ai.oceango.hk/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://ai.oceango.hk/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://ai.oceango.hk/v1',});
const models = await client.models.list();console.log(models.data[0].id);

不装 SDK 也可以

所有端点都是普通的 HTTPS 加 JSON，用 curl、requests、fetch 直接调完全没问题。本文档每个端点都给了 curl 示例，照抄即可。

鉴权失败的排查顺序#

401 只说明这把钥匙现在开不了这扇门，具体原因在响应体的 code 字段里。

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

每个错误响应都带 request_id。排查不出来时，把它连同大致时间发工单——我们靠它能定位到那一次具体调用。

轮换与吊销#

密钥明文只在创建那一刻显示一次，我们不保存明文，事后无法找回。列表里只能看到后四位，用来认出是哪一把。

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

鉴权

两种 API Key、三种等价的请求头写法，以及密钥失效时的排查顺序。

两种密钥#

平台有两条产品线，各自签发不同前缀的密钥。前缀不只是标识，它决定了这把钥匙能开哪扇门。

前缀	可调用的端点	在哪申领
`sk-ar-`	模型调用：对话、图像、向量化、重排、视频	API 密钥
`sk-srp-`	搜索与阅读：搜索、网页正文、文档识别	搜索阅读

sk-ar- 可用于 /v1/chat/completions、/v1/messages、/v1/images/generations、/v1/embeddings、/v1/rerank、/v1/videos、/v1/models。
sk-srp- 可用于 /v1/search、/v1/reader、/v1/ocr。

两种密钥不通用

三种等价的请求头#

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

支持三种是为了让你迁过来时不必改客户端代码：把 SDK 的 base URL 指过来、把 key 换成我们签发的，就能跑。

先验证密钥可用#

在写业务代码之前，先用一条不花钱的请求确认密钥是通的。/v1/models 返回这把密钥能用的模型清单，不消耗额度。

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

bash

curl https://ai.oceango.hk/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://ai.oceango.hk/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://ai.oceango.hk/v1',});
const models = await client.models.list();console.log(models.data[0].id);

不装 SDK 也可以

所有端点都是普通的 HTTPS 加 JSON，用 curl、requests、fetch 直接调完全没问题。本文档每个端点都给了 curl 示例，照抄即可。

鉴权失败的排查顺序#

401 只说明这把钥匙现在开不了这扇门，具体原因在响应体的 code 字段里。

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

每个错误响应都带 request_id。排查不出来时，把它连同大致时间发工单——我们靠它能定位到那一次具体调用。

轮换与吊销#

密钥明文只在创建那一刻显示一次，我们不保存明文，事后无法找回。列表里只能看到后四位，用来认出是哪一把。

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