API 鉴权

TopAPIs 的 OpenAI 兼容接口使用 Bearer Token 鉴权。API Key 代表账号权限和可用额度，应按生产凭证管理。

请求头

http

Authorization: Bearer YOUR_API_KEY

JSON 请求还需要发送：

http

Content-Type: application/json

Bearer 与密钥之间必须有一个空格。不要将密钥放在 URL 查询参数中。

Gemini 原生 v1beta 接口使用 x-goog-api-key: YOUR_API_KEY，具体写法见 Gemini 图像生成。无论使用哪个请求头，都执行相同的密钥保护与日志脱敏规则。

环境变量

推荐使用 TOPAPIS_API_KEY 作为应用侧环境变量：

Linux / macOSPowerShell

bash

export TOPAPIS_API_KEY="YOUR_API_KEY"

powershell

$env:TOPAPIS_API_KEY = "YOUR_API_KEY"

应用启动时读取环境变量，在服务端构造鉴权头。浏览器前端、移动端安装包和公开仓库都不能安全保存长期密钥。

安全要求

为开发、测试和生产环境使用不同密钥。
只授予调用所需的模型和额度权限。
日志中隐藏 Authorization 请求头和密钥值。
密钥意外进入仓库、聊天记录或日志后，应立即撤销并重新创建。
定期轮换长期使用的密钥，并让应用支持无停机更新。

服务端示例

const apiKey = process.env.TOPAPIS_API_KEY

if (!apiKey) {
  throw new Error('TOPAPIS_API_KEY is not configured')
}

const response = await fetch('https://api.topapis.cn/v1/models', {
  headers: {
    Authorization: `Bearer ${apiKey}`,
  },
})

不要输出 apiKey，也不要把完整请求头附加到错误日志。

鉴权错误

状态码	含义	处理方式
`401`	密钥缺失、格式错误、无效或已撤销	检查环境变量与 Bearer 格式，必要时创建新密钥
`403`	已识别账号，但没有请求资源的权限	检查令牌、账号分组和模型授权

鉴权失败不应自动重试。只有在修正配置或权限后才重新发送请求。

验证配置

配置密钥后调用模型列表接口：

bash

curl --fail-with-body "https://api.topapis.cn/v1/models" \
  -H "Authorization: Bearer $TOPAPIS_API_KEY"

成功响应表示密钥格式有效；实际模型可用范围以返回的 data 数组为准。

API 鉴权 ​

请求头 ​

环境变量 ​

安全要求 ​

服务端示例 ​

鉴权错误 ​

验证配置 ​