开始使用

接入前准备复制章节链接

GFW 有两套用途不同的地址：

• 控制台业务接口：页面登录、API Key 管理、模型目录、用量和账单使用业务域名下的 /api/v1。浏览器会用登录会话访问它。
• 模型调用接口：应用使用 API Key 访问 https://api.gfw.net/v1。它兼容 OpenAI 风格的模型接口，不需要把控制台登录令牌放进应用请求。

你需要一个已登录的 GFW 账户、一个 API Key，以及一个在当前模型目录中处于可用状态的 model_code。下面以目录中的 deepseek-v4-pro 为例；模型和价格会变化，接入前应在模型库或模型目录重新确认。

创建 API Key复制章节链接

1. 登录 GFW，打开控制台。
2. 进入 使用 → API 密钥，点击 创建密钥。
3. 填写容易区分用途的名称，例如 local-dev 或 production-api，然后创建。
4. 立即复制返回的完整 Key，并放入本机的密钥管理器或环境变量。控制台列表只显示掩码后的前缀。

export GFW_API_KEY='your-api-key'

不要把真实 Key 写入 Git、前端代码、日志或提交记录。Key 只应在服务端或本地进程环境中读取。

发起第一次调用复制章节链接

先用一个最小的聊天请求验证网络、认证和模型名称。以下响应是格式示意，不是实测输出；id、时间和文本会因请求而不同。

curl -sS https://api.gfw.net/v1/chat/completions \
  -H "Authorization: Bearer ${GFW_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-pro",
    "messages": [
      {"role": "user", "content": "用一句话介绍 GFW。"}
    ]
  }'

成功响应通常遵循 OpenAI Chat Completions 结构，可从 choices[0].message.content 读取文本，并从 usage 读取本次返回的 Token 用量。调用是否产生扣费、最终扣费金额以及退款，以控制台的实际流水和用量记录为准。

使用 SDK复制章节链接

GFW 的 OpenAI 兼容入口是 https://api.gfw.net/v1，因此可以把官方 OpenAI SDK 的 base_url 指向该地址。先安装 SDK，再从环境变量读取 Key。

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["GFW_API_KEY"],
    base_url="https://api.gfw.net/v1",
)

response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[{"role": "user", "content": "你好"}],
)
print(response.choices[0].message.content)

检查模型与排查问题复制章节链接

可以先查询公开模型目录，确认 model_code、模型类型和能力字段。生产环境请使用实际部署域名；测试目录地址仅用于查看测试环境数据。

curl -sS https://test.gfw.net/api/v1/models \
  -H "Accept: application/json"

常见问题：

• 401：检查是否发送 Authorization: Bearer ${GFW_API_KEY}，以及 Key 是否已撤销或复制不完整。
• 模型不存在或不可用：使用模型目录里的 model_code，不要使用上游厂商的内部模型 ID。
• 余额或限额问题：在控制台查看 财务、API Key 的限制和用量明细；不要依据一次请求的预估值判断最终结算。
• 返回 4xx/5xx：保留 HTTP 状态、响应体和请求时间，隐藏 Key 后再提交排查信息。

相关链接复制章节链接

• 认证与 Key 管理
• 模型与价格字段
• OpenAI 兼容 API
• Anthropic Messages 接入