> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openp.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 鉴权

> 三套协议端点的鉴权头格式与示例

OpenPAI 的所有 API 都需要鉴权。鉴权信息携带在 **请求头(Header)** 中,不要放在 URL query 里。

## OpenAI 兼容协议

```
Authorization: Bearer sk-XXXXXXXXXXXXXXXX
```

```bash theme={null}
curl https://openp.ai/v1/chat/completions \
  -H "Authorization: Bearer $OPENPAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.5","messages":[{"role":"user","content":"hi"}]}'
```

## Claude Messages 协议

```
x-api-key: sk-XXXXXXXXXXXXXXXX
anthropic-version: 2023-06-01
```

```bash theme={null}
curl https://openp.ai/v1/messages \
  -H "x-api-key: $OPENPAI_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model":"claude-opus-4-8",
    "max_tokens":1024,
    "messages":[{"role":"user","content":"hi"}]
  }'
```

<Note>SDK 通常会自动添加 `anthropic-version`,直接用 SDK 时无需手填。</Note>

## Gemini 原生协议

```
x-goog-api-key: sk-XXXXXXXXXXXXXXXX
```

```bash theme={null}
curl "https://openp.ai/v1beta/models/gemini-3.1-pro-preview:generateContent" \
  -H "x-goog-api-key: $OPENPAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents":[{"role":"user","parts":[{"text":"hi"}]}]
  }'
```

Gemini 也兼容 query 参数式鉴权(`?key=sk-...`),但 **不建议** 这种方式 —— URL 会被代理日志记录。

## 失败示例

| 状态                       | 原因                          |
| ------------------------ | --------------------------- |
| `401 invalid_api_key`    | 密钥不存在 / 被禁用 / 格式错误 / 末尾包含换行 |
| `401 expired_api_key`    | 令牌已过期                       |
| `403 insufficient_quota` | 账户或令牌额度不足                   |
| `403 ip_not_allowed`     | 来源 IP 不在该令牌白名单              |
| `403 model_not_allowed`  | 该令牌没有调用此模型的权限               |

排查方法:

1. 复制 `X-OpenPAI-Request-Id` 头。
2. 控制台 → **日志** → 搜索该 Request ID,查看失败原因详情。

## 密钥保管

* **不要** 把密钥提交到 Git 或粘贴到聊天 / Issue。
* 使用环境变量 / Secret Manager 注入。
* 怀疑泄露立即在控制台禁用并重新生成。
* 为不同应用 / 环境创建独立令牌,便于细粒度追踪。