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

# 认证

> 黑胡子AI便利店 API 的 Bearer Token 鉴权和权限边界。

所有公开 API 都需要在请求头中携带 Bearer Token。Token 来源是平台 API Key。

```http theme={null}
Authorization: Bearer <token>
```

## 权限来源

API Key 只决定身份，实际能力还取决于它所属的分组和渠道配置：

* 文本接口需要分组可访问对应模型和渠道。
* GPT Image 2 接口需要开启图片生成能力。
* Claude Code Messages 需要开启对应的 Messages 调度能力。
* `/v1/models` 返回的是当前 Key 可见模型，不代表平台全量模型。

## 错误含义

| 状态码     | 常见原因              | 处理方式                             |
| ------- | ----------------- | -------------------------------- |
| 401     | Token 缺失、格式错误、已失效 | 检查 `Authorization` 请求头和 API Key。 |
| 403     | 分组没有对应能力          | 检查图片生成、Messages 调度或模型访问权限。       |
| 404     | 路径错误，或目标模型/渠道不可见  | 检查接口路径和 `/v1/models` 返回结果。       |
| 429     | 触发速率限制或并发限制       | 降低并发，稍后重试。                       |
| 500/503 | 上游或网关临时失败         | 记录请求信息后重试或联系管理员排查。               |