# 认证

区分控制台登录认证与模型调用 API Key，正确配置 OpenAI 和 Anthropic 请求头。

## 两种认证场景 [#两种认证场景]

GFW 的认证按请求目标区分：

| 场景 | 地址示例 | 凭据 | 用途 |
| --- | --- | --- | --- |
| 控制台业务 | `https://api.gfw.net/api/v1/*` | 登录会话令牌 | 账户、Key、用量、订单和流水页面 |
| 模型调用 | `https://api.gfw.net/v1/*` | API Key | Chat、Responses、图片、视频等模型请求 |

控制台的登录会话只用于同源业务接口。应用调用模型时，应使用控制台创建的 API Key，不要把登录令牌当作模型凭据。

## 管理 API Key [#管理-api-key]

在控制台打开 **使用 → API 密钥**：

- 创建时填写 `name`，名称只用于识别用途。
- 当前控制台创建流程填写名称即可。Key 的额度、速率或有效期等限制若在页面或账户策略中出现，以实际页面和接口返回为准；不要假定未展示的选项已经生效。
- 列表显示 Key 前缀和状态。按控制台提供的操作撤销或删除 Key；撤销后不能继续用于模型调用。
- 完整 Key 不应再次暴露给浏览器之外的任何人。若需要恢复，后端可能返回“创建时未保存完整 Key”错误，此时只能重新创建。

```bash
export GFW_API_KEY='your-api-key'
```

应用启动时从环境变量读取它，不要把值硬编码在源码中。

## OpenAI 兼容请求 [#openai-兼容请求]

在 `/v1` 模型接口中使用 Bearer 认证。下面只展示请求头和最小请求体，响应内容为平台实际返回的数据。

```bash
curl -sS https://api.gfw.net/v1/chat/completions \
  -H "Authorization: Bearer ${GFW_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.7-max",
    "messages": [{"role": "user", "content": "你好"}]
  }'
```

`qwen3.7-max` 是模型目录中的公开 `model_code` 示例。实际可用性仍以请求当时的目录和你的账户权限为准。

## Anthropic Messages 请求 [#anthropic-messages-请求]

Anthropic 官方 SDK 使用根地址 `https://api.gfw.net`，SDK 会在根地址后请求 `/v1/messages`。直接调用时使用 `x-api-key` 和必需的 `anthropic-version` 请求头：

```bash
curl -sS https://api.gfw.net/v1/messages \
  -H "x-api-key: ${GFW_API_KEY}" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.7-max",
    "max_tokens": 256,
    "messages": [{"role": "user", "content": "你好"}]
  }'
```

该入口返回 Anthropic Messages 风格的响应。模型必须是可用于对话的模型；图片和视频模型应调用各自的 OpenAI 兼容端点。

## 认证失败与密钥保护 [#认证失败与密钥保护]

模型调用失败时，先按下面顺序检查：

1. URL 是否使用了模型 API 的 `/v1`，而不是控制台的 `/api/v1`。
2. Bearer 或 `x-api-key` 是否引用了当前环境中的 `GFW_API_KEY`。
3. Key 是否仍为启用状态，是否达到 Key 额度、速率或过期限制。
4. `model` 是否使用目录里的 `model_code`，而非供应商上游 ID。

不要记录完整请求头。排查日志只保留 Key 前缀、时间、模型代码、HTTP 状态和服务端返回的错误 `type/code`。


**提示**

收到 401 时不要尝试把控制台 JWT、浏览器 localStorage 内容或其他用户凭据放入模型请求。回到 **控制台 → 使用 → API 密钥** 创建或轮换 API Key。


## 相关链接 [#相关链接]

- [开始使用](/docs/quickstart)
- [模型目录与价格字段](/models)
- [Claude Code](/docs/claude-code)
- [Codex CLI](/docs/codex)