# 开始使用

创建 API Key，并用 OpenAI 兼容接口完成第一次 GFW 调用。

## 接入前准备 [#接入前准备]

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

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

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

## 创建 API Key [#创建-api-key]

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

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

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

## 发起第一次调用 [#发起第一次调用]

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

```bash
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 [#使用-sdk]

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



**Python**


```python
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)
```



**Node.js**


```javascript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.GFW_API_KEY,
  baseURL: "https://api.gfw.net/v1",
});

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




## 检查模型与排查问题 [#检查模型与排查问题]

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

```bash
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 后再提交排查信息。


**提示**

示例中的 `your-api-key` 是占位符。不要在文档、截图、Issue 或聊天中粘贴真实 API Key。


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

- [认证与 Key 管理](/docs/authentication)
- [模型与价格字段](/models)
- [OpenAI 兼容 API](/docs/openai-api)
- [Anthropic Messages 接入](/docs/anthropic-api)