认证

两种认证场景复制章节链接

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

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

管理 API Key复制章节链接

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

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

export GFW_API_KEY='your-api-key'

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

OpenAI 兼容请求复制章节链接

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

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

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。

相关链接复制章节链接

• 开始使用
• 模型目录与价格字段
• Claude Code
• Codex CLI