新用户 3 分钟速通

目标：用最短路径完成“确认账户 → 创建密钥 → 选择分组 → 配置客户端 → 验证使用记录”。

适用前提

本流程适用于账户已经由管理员开通的用户。当前不开放匿名自助注册；尚无账户时，请通过 QQ 1286407148 联系管理员，并说明用途和所在国家或地区。

1. 登录并确认账户

账户可以正常进入控制台；
余额、已有服务或管理员授予的权限可用；
需要充值时，以控制台当前显示的充值入口和结算信息为准。

2. 创建 API 密钥

打开 API 密钥，创建一把仅供当前客户端使用的密钥：

名称填写设备或客户端，例如 Windows-Codex。
分组选择控制台中当前可用、且与客户端协议匹配的分组。
额度和有效期按用途设置；测试密钥不要长期、无限额使用。
创建后立即安全保存完整密钥，后续页面可能只显示脱敏值。

不要公开密钥

不要在截图、工单、浏览器前端代码、公开仓库或群聊中提交完整密钥。泄露后应立即撤销旧密钥并创建新密钥。

3. 选择接入方式

推荐优先级：

使用场景	推荐方式
Codex、Claude Code 等多个客户端之间切换	CCSwitch 一键导入
Codex CLI 或官方 Codex 扩展	Codex 配置
Claude Code CLI 或扩展	Claude Code 配置
OpenCode	OpenCode 配置
其他 VS Code AI 插件	VS Code 通用配置
自己编写的程序	API 与 SDK

手动配置 OpenAI 兼容客户端时通常需要：

字段	填写内容
Provider	`OpenAI Compatible`、`Custom OpenAI` 或同义选项
Base URL	`https://freedomz.cn/v1`
API Key	控制台创建的密钥
Model	从 `/v1/models` 实时返回值中选择

如果客户端会自动拼接 /v1，Base URL 改为 https://freedomz.cn。

4. 查询可用模型

bash

curl https://freedomz.cn/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

从返回结果的 data[].id 复制模型名称。模型与 Key 分组必须匹配，文档不维护容易过期的固定模型清单。

5. 发起一次最小请求

bash

curl https://freedomz.cn/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "从 /v1/models 获取的模型名称",
    "messages": [
      {
        "role": "user",
        "content": "请用一句话说明请求已成功。"
      }
    ]
  }'

Windows PowerShell 可使用：

powershell

$headers = @{
  Authorization = "Bearer $env:FREEDOMZ_API_KEY"
  "Content-Type" = "application/json"
}

$body = @{
  model = "从 /v1/models 获取的模型名称"
  messages = @(
    @{
      role = "user"
      content = "请用一句话说明请求已成功。"
    }
  )
} | ConvertTo-Json -Depth 5

Invoke-RestMethod `
  -Uri "https://freedomz.cn/v1/chat/completions" `
  -Method Post `
  -Headers $headers `
  -Body $body

先不要添加工具调用、图片、附件、代理或实验参数。最小请求成功后再逐项增加功能。

6. 核对使用记录

打开使用记录，确认刚才的请求已经出现，并核对：

请求时间与测试时间一致；
使用的密钥、模型和分组符合预期；
状态和计费数据正常。

客户端能回复但这里没有记录，通常表示客户端仍在使用官方登录、旧 Provider 或其他网关，并未经过 FreedomZ AI。

成功标志

/v1/models 返回模型列表；
最小请求返回 HTTP 200；
客户端可以正常显示回复；
控制台使用记录出现对应调用。

失败时先看

状态码	含义	首要处理
400	请求格式或参数错误	核对 JSON、模型名称和必填字段
401	密钥无效或认证失败	立即停止自动重试，检查密钥
403	内容、账户或策略拒绝	不要切换密钥连续重试
429	请求过快或资源暂不可用	指数退避并降低并发
余额不足	账户或密钥额度不可用	检查余额、密钥额度和订单状态
model not found	模型与分组不匹配	重新查询 `/v1/models`
5xx	网关或上游临时异常	稍后重试并保留请求 ID

完整处理顺序见故障排查。

新用户 3 分钟速通 ​

1. 登录并确认账户 ​

2. 创建 API 密钥 ​

3. 选择接入方式 ​

4. 查询可用模型 ​

5. 发起一次最小请求 ​

6. 核对使用记录 ​

成功标志 ​

失败时先看 ​