自由API 使用教程

适用站点：https://freeapi.club
最后更新：2026-09-23
本文档面向首次使用本站的开发者，从注册到跑通第一次请求约需 10 分钟。

一、这是什么

自由API 是一个 AI 模型 API 统一接入平台。它把多个上游 AI 服务的能力聚合在同一个接口后面：你只需要一个密钥、一个端点地址，就能调用 Claude、GPT、Gemini、Grok 等模型。

1.1 它解决什么问题

• 不用为每个模型单独开户。 避免分别申请账号、分别管理密钥、分别充值。
• 切换模型只改一个参数。 端点地址和密钥不变，换模型改 model 字段即可。
• 按实际用量计费。 按 Token 消耗扣减，控制台可查逐日、逐模型明细。
• 多上游自动调度。 单个通道异常时自动切换到其他通道，减少中断。

1.2 三点必须先知道的事

⚠️ 重要声明，请先读完再开始使用

1. 本站是第三方 API 转发服务，不是官方渠道。 本站与 Anthropic、OpenAI、Google、xAI 等模型提供方不存在代理、合作、授权或背书关系。文中出现的模型名称与商标归各自权利人所有。
2. 本站基于开源项目 sub2api 自行部署。 与该项目作者、贡献者、维护者无关联，本站的运营行为不代表该项目方。
3. 上游策略变动可能导致服务中断或功能变更。 请勿将本站用于生产关键业务，也不要通过本站处理不可恢复的数据。

1.3 支持的协议

具体能用哪些模型，取决于你的密钥所属分组。 请以控制台「API 密钥」页面显示的模型列表为准。

二、开通与配置

第 1 步：注册账号

1. 打开 https://freeapi.club
2. 点击「立即开始」进入注册页
3. 填写邮箱和密码完成注册

建议使用长期有效的邮箱。 后续重置密码、接收余额提醒与服务通知都会发到这个地址，临时邮箱会在需要时收不到信。

第 2 步：登录控制台

注册后登录，你会看到左侧导航：

第 3 步：创建 API 密钥

1. 进入「API 密钥」
2. 点击「创建密钥」
3. 选择分组——分组决定你的密钥能调用哪些模型，不确定选哪个就先看分组名称说明
4. 点击确认

⚠️ 密钥只在创建时完整显示一次。 请立即复制并保存到安全的地方。如果丢失，只能在控制台重新创建一个新密钥，旧密钥删除后立即失效。

第 4 步：确认余额

到「个人资料」查看当前余额。余额为 0 时所有 API 调用都会失败，这与密钥是否有效无关。

当前充值方式：客服人工充值（添加客服微信，发送注册邮箱与充值金额）。具体流程与到账时间见站内「公告」中的《充值流程与到账说明》。

第 5 步：配置客户端

推荐做法：让控制台帮你生成配置。

1. 进入「API 密钥」
2. 找到你的密钥，点击「使用密钥」
3. 弹窗中选择你要用的客户端和操作系统
4. 它会直接生成配置文件内容，复制即可用

支持自动生成配置的客户端：Claude Code、Codex CLI、Gemini CLI、Grok CLI、OpenCode。

这样做的原因很简单：不同客户端的配置字段在各版本间会变，弹窗里的模板是跟着本站当前版本同步维护的，比手动抄文档可靠。

三、API 调用方式

3.1 认证方式

把密钥放在请求头里，以下三种任选其一，效果相同：

服务端识别顺序：Authorization: Bearer → x-api-key → x-goog-api-key。

⚠️ 不要把密钥放进 URL 查询参数。 ?api_key= 与 ?key= 已被废弃，使用会直接返回 400 api_key_in_query_deprecated。密钥出现在 URL 里还可能被服务器日志、浏览器历史、中间代理记录到。

3.2 端点地址

根地址：https://freeapi.club

3.3 第一步永远先查模型列表

在写代码之前，先确认你的密钥能用哪些模型：

curl https://freeapi.club/v1/models \
  -H "Authorization: Bearer sk-你的密钥"

返回的 id 字段就是可以填进 model 参数的值。下面所有示例中的 <模型ID> 都请替换成这里查到的实际值。

3.4 curl 示例

Anthropic Messages（Claude 协议）

curl https://freeapi.club/v1/messages \
  -H "x-api-key: sk-你的密钥" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "<模型ID>",
    "max_tokens": 1024,
    "messages": [
      { "role": "user", "content": "用一句话解释什么是 API 网关" }
    ]
  }'

OpenAI Chat Completions（兼容协议）

curl https://freeapi.club/v1/chat/completions \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "content-type: application/json" \
  -d '{
    "model": "<模型ID>",
    "messages": [
      { "role": "user", "content": "用一句话解释什么是 API 网关" }
    ]
  }'

Gemini 原生协议

curl "https://freeapi.club/v1beta/models/<模型ID>:generateContent" \
  -H "x-goog-api-key: sk-你的密钥" \
  -H "content-type: application/json" \
  -d '{
    "contents": [
      { "parts": [ { "text": "用一句话解释什么是 API 网关" } ] }
    ]
  }'

3.5 客户端配置

下表是各客户端使用的环境变量名。值请从控制台「使用密钥」弹窗里复制，不要手抄本文档——端点地址以你控制台显示的为准。

Claude Code（macOS / Linux）示例

export ANTHROPIC_BASE_URL="<控制台显示的端点地址>"
export ANTHROPIC_AUTH_TOKEN="sk-你的密钥"

Claude Code（Windows PowerShell）示例

$env:ANTHROPIC_BASE_URL="<控制台显示的端点地址>"
$env:ANTHROPIC_AUTH_TOKEN="sk-你的密钥"

自建应用 / OpenAI SDK

任何兼容 OpenAI 协议的 SDK，只需要改两个地方：base_url 改成 https://freeapi.club/v1，api_key 换成你的密钥。

from openai import OpenAI

client = OpenAI(
    base_url="https://freeapi.club/v1",
    api_key="sk-你的密钥",
)

resp = client.chat.completions.create(
    model="<模型ID>",
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)

四、常见使用场景

4.1 编程助手（最常见）

把 Claude Code、Codex CLI、Gemini CLI 等工具的端点指向本站，用统一余额调用多个模型。切换模型时只需改客户端里的模型名，不用重新申请账号。

配置走控制台「使用密钥」弹窗，选对应客户端即可。

4.2 自建应用接入

适合已经用 OpenAI SDK 写的应用：改 base_url 和 api_key 两处，其余代码不用动。这也是为什么本站同时提供 OpenAI 兼容协议和 Anthropic 原生协议——你可以按现有代码选成本最低的那条路。

4.3 批量文本处理

对大量文本做分类、摘要、抽取、翻译等任务时，建议：

• 先用 /v1/messages/count_tokens 估算输入规模，避免批量跑一半额度不够
• 控制并发，不要一上来就开几百个线程——超出并发上限会返回 429
• 把失败请求记录下来批量重试，而不是让整个任务中断

4.4 图像与视频生成

图像/视频任务耗时较长，建议走异步接口，避免长时间占用连接导致超时：

1. POST /v1/images/generations/async 提交任务，拿到 task_id
2. 轮询 GET /v1/images/tasks/{task_id} 直到完成
3. 需要一次提交大量图片时，使用批量接口 /v1/images/batches

4.5 团队共用与成本核算

• 为每个成员或每个项目单独创建密钥，不要共用一把
• 用「使用记录」按密钥、按模型查用量，定位成本来源
• 密钥可单独设置额度与过期时间，方便给临时协作者
• 成员不再需要时，直接删除对应密钥即可

五、常见问题排查

排查第一步

先用一条 curl 确认问题出在服务端还是客户端。 如果 curl 能通、客户端不通，问题就在客户端配置；两边都不通，再往下查。

curl https://freeapi.club/v1/models -H "Authorization: Bearer sk-你的密钥"

错误码对照

分场景排查

① 余额明明有，但一直报错

先确认报错是 429 额度已用完 还是别的。前者是密钥级别的额度用完，不一定等同于账户余额为 0——检查「API 密钥」页面上这把密钥自己的额度设置。

② 认证通过，但模型报不存在

大概率是分组权限问题，而不是模型 ID 写错。用 /v1/models 列出你实际可用的模型，对比一下你填的 ID。

③ 输出到一半中断 / 超时

• 文本任务：多为上游网络波动，重试一次通常可恢复
• 长文本或图像视频任务：改用异步接口，不要一直挂着连接
• 降低 max_tokens 或缩短输入，先验证是不是长度触发的

④ 流式输出卡住

确认客户端开启了流式（stream: true），并且中间没有反向代理提前缓冲响应。如果用 Nginx 之类的反向代理转发，注意关闭响应缓冲。

⑤ 用量对不上

以控制台「使用记录」为准，它记录的是逐条请求的 Token 与费用。如果某条请求计费异常，请把请求时间、使用的密钥、模型名三项一并发给客服，这样才能定位到具体记录。

⑥ 密钥泄露了怎么办

立即到「API 密钥」页面删除该密钥并创建新密钥。删除即时生效，不用等。之后检查「使用记录」确认有无异常消耗。

六、安全与合规

6.1 密钥安全

• 密钥等同于你的账户凭证，不要提交到公开代码仓库、不要写在客户端代码里、不要发给他人
• 用环境变量或密钥管理服务存放，不要硬编码
• 一个项目一把密钥，泄露时影响范围可控
• 定期检查「使用记录」，关注异常时间段的消耗

6.2 使用限制

禁止以下行为，违者可能被限流或封禁，剩余额度不予退还：

• 转售、共享、分发 API 密钥
• 基于本站搭建面向第三方的公开中转服务
• 批量注册账号、刷取额度或优惠
• 生成违法有害内容，或用于诈骗、钓鱼等用途
• 对本站或上游接口进行扫描、渗透、攻击
• 通过多账号拆分绕过并发与速率限制

6.3 风险提示

• 本站为第三方服务，不承诺具体可用率。上游策略调整、网络波动都可能导致服务中断或降速。
• 请不要将本站用于医疗、金融、法律等需要专业资质或高可靠性的场景。
• 服务条款、使用政策等完整约定见登录页《服务条款》与《使用政策》，以其内容为准。

七、获取帮助

⚠️ 防冒充提醒：本站不会以"升级套餐""补差价""系统维护"等理由主动要求你转账。如遇此类情况，请先通过官方渠道核实。

附录：术语表