# 身份认证

调用 Genesis 的 OpenAI 兼容接口前，需要先准备访问凭据，并在每个请求中携带认证 Header。本页适用于 `GET /models`、Chat Completions、Embeddings、Rerank 和 Responses；调用 Anthropic Messages 时，请以该接口页的认证要求为准，不要直接套用本页规则。

## 完成认证

1. 在 Genesis 控制台创建个人访问令牌，或创建服务账号并授予 Genesis 产品权限和所需模型范围。
2. 将令牌或服务账号 API Key 保存为本地环境变量或密钥管理服务中的密钥。
3. 在请求 Header 中设置 `Authorization: Bearer <ACCESS_TOKEN>`。
4. 调用 [获取可用模型](available-models.md)，确认当前凭据可以调用目标模型。

控制台中创建、授权、更新和禁用凭据的操作，请参阅 Genesis 指南中的[管理 Genesis 访问凭据](../../../../guides/genesis/api-keys.md)。

## 在请求中携带凭据

调用本页范围内的接口时，将个人访问令牌或服务账号 API Key 放入 `Authorization` Header：

```http
Authorization: Bearer <ACCESS_TOKEN>
```

`<ACCESS_TOKEN>` 是实际令牌或 API Key。一项请求只使用一种凭据。请从环境变量或密钥管理服务读取该值，不要将其写入源代码、镜像或日志。

例如，在本地终端中先设置环境变量：

```bash
export GENESIS_BASE_URL='<Genesis Base URL copied from the console>'
export GENESIS_ACCESS_TOKEN='<your-access-token>'
```

`GENESIS_BASE_URL` 使用当前环境 Genesis 控制台「使用」页提供的完整 Base URL。复制后保持版本路径不变；如果地址已经以 `/v1` 结尾，不要再次追加 `/v1`。

再在请求中引用它：

```bash
curl "$GENESIS_BASE_URL/models" \
  -H "Authorization: Bearer $GENESIS_ACCESS_TOKEN"
```

请求成功后会返回当前凭据可调用的模型列表。不要把控制台管理站点地址、其他环境地址或内部服务路径当作 Genesis Base URL。

## 选择凭据

| 凭据 | 适用场景 |
| --- | --- |
| 个人访问令牌 | 本地开发、命令行验证，或以本人身份运行的脚本。 |
| 服务账号 API Key | 应用、CI/CD 和生产自动化。服务账号必须已授予 Genesis 产品权限和所需模型范围。 |

个人访问令牌按当前用户的权限访问。服务账号不继承创建者的个人权限；如果服务账号无法调用某个模型，请检查其 Genesis 产品权限和模型范围。

## 安全保存凭据

- 本地开发时，将凭据保存为仅当前终端会话可见的环境变量，或使用本机密钥管理工具。
- 部署应用时，使用部署平台或密钥管理服务注入凭据。
- 不要将凭据放入源代码、前端代码、镜像、日志、工单或截图。
- 怀疑凭据泄露时，在 Genesis 指南的[管理 Genesis 访问凭据](../../../../guides/genesis/api-keys.md)中更新或禁用该凭据，并立即替换调用方保存的旧值。

## 认证失败时检查

1. 确认请求使用 `Authorization: Bearer <ACCESS_TOKEN>`，而不是将凭据放入请求体或查询参数。
2. 确认个人访问令牌未过期且未被禁用；使用服务账号时，确认对应 API Key 仍可用。
3. 确认服务账号已配置 Genesis 产品权限和目标模型范围。
4. 使用[获取可用模型](available-models.md)确认当前凭据可调用目标模型。

## 下一步

- [管理 Genesis 访问凭据](../../../../guides/genesis/api-keys.md)：创建个人访问令牌或服务账号，并配置 Genesis 模型权限。
- [获取可用模型](available-models.md)：确认当前凭据可调用的模型 ID。
- [文本对话](../openai-compatible/chat-completions/text-chat.md)：发送第一个 Chat Completions 请求。
- [多模态对话](../openai-compatible/chat-completions/multimodal-chat.md)：向支持视觉输入的模型发送图文消息。
- [Responses API](../openai-compatible/responses-api.md)：调用支持 Responses 形态的模型。