草根 AI 帮助文档 CGAPI Docs · cgapi.top
CGAPI 使用文档

看懂账号、密钥和接入方式，快速用上 API。

这是一份给用户看的帮助文档。你只需要按步骤注册、创建密钥、填对 Base URL，再到模型广场复制可用模型名，就能接入常用客户端或代码项目。

5 分钟快速开始 选择接入工具 先看 /v1 规则
第一次使用

从注册、余额、API Key 到第一次请求，按顺序走一遍。

从这里开始
选择接入工具

CC Switch、Codex、Cherry Studio、Claude Code、OpenAI SDK 都可以按 OpenAI Compatible 方式接入。

查看接入教程
选择模型

先看清楚模型名、价格、供应商和能力标签，再把模型名填进工具或代码。

查看填写规则

文档目录

5 分钟快速开始 账号与密钥 模型与价格 /v1 规则 应用接入 API 示例 常见问题 FAQ

5 分钟快速开始

第一次用 CGAPI，照着这四步走即可。先调通，再选择更适合自己的模型和工具。

新用户优先
01

登录控制台

从官网进入控制台，注册或登录账号。邮箱验证码通过后再继续。

02

确认余额

看清楚余额、可用额度和模型广场。测试阶段先选价格较低、权限已开放的模型。

03

创建 API Key

创建一个 sk-... 密钥。密钥只给自己用，不要截图发给别人。

04

配置工具

Base URL 填 https://api2.cgapi.top/v1，API Key 填刚创建的密钥，模型名从模型广场复制。

成功标准：工具能返回模型列表，或使用模型广场中的某个可用模型发出一条短对话并正常得到回复。

账号、余额与 API Key

先看懂账号、余额和密钥，后面接入会顺很多。

用户视角

账号

账号用来登录控制台，查看余额、模型、密钥和调用记录。

  • 邮箱验证码收不到时，先检查垃圾箱或换一个常用邮箱。
  • 登录后再创建 API Key，不要直接在聊天工具里乱填。
  • 一个账号可以创建多个密钥，建议按用途区分。

余额和额度

余额会随着调用消耗。不同模型成本不同，实际扣费以控制台显示为准。

  • 测试阶段先用价格较低的模型。
  • 遇到余额不足，先回控制台看余额、额度和可用模型。
  • 高价模型、长上下文任务和大批量并发都会更快消耗余额。

API Key

API Key 就像你的调用密码，谁拿到它，谁就可能消耗你的额度。

  • 不要发群、不要截图、不要写进公开仓库。
  • 怀疑泄露时，删除旧 Key，再创建新 Key。
  • 复制后先保存到自己的密码工具或本地安全位置。

模型、价格与怎么选择

CGAPI 会持续接入不同供应商和不同能力的模型。正式使用时，不要记模型名，直接以控制台模型广场显示为准。

正式使用必看

模型名怎么填

打开控制台的模型广场，复制完整模型名，再粘贴到客户端或代码里的 model 字段。

  • 不要凭印象手打模型名。
  • 注意大小写、短横线、点号和版本号。
  • 如果模型不可用，先换一个模型广场里已开放的模型测试。

价格怎么看

模型广场里的价格通常按输入、输出、缓存等维度显示。输出通常比输入更贵，长文本和多轮对话会消耗更多。

  • 连通性测试用低价模型和短问题。
  • 正式任务再选择更强模型。
  • 高价模型适合复杂任务，不适合反复空跑测试。

按场景选择

不同模型适合不同场景。先按任务选能力，再看价格和响应速度。

  • 普通问答、摘要、改写：优先低价或标准模型。
  • 复杂推理、代码、长文档：选择能力更强的模型。
  • 图片、语音、工具调用：看模型广场的能力标签。
文档里的 your-model-name 是占位符。实际调用前，请到模型广场复制你账号可用的真实模型名。

/v1 到底什么时候带？

这一步最容易填错。判断方法很简单：填 Base URL 时带 /v1；填网站地址、控制台地址或 API 域名本身时不带。

重点标记

Base URL 带 /v1

在 CC Switch、Codex、Cherry Studio、OpenAI SDK、Claude Code、OpenClaw、Hermes 里，如果字段名是 Base URL、API Base、API Host、Endpoint，就填完整接口根地址。

  • 推荐填写：https://api2.cgapi.top/v1
  • 完整请求类似：https://api2.cgapi.top/v1/chat/completions
  • 模型列表类似：https://api2.cgapi.top/v1/models

网站地址不带 /v1

浏览器访问、登录控制台、复制官网链接时，不要把 /v1 加上。

  • 官网：https://www2.cgapi.top
  • 控制台：https://app2.cgapi.top
  • API 域名：https://api2.cgapi.top

不要重复加 /v1

如果你已经填了 https://api2.cgapi.top/v1，不要再手动追加一次 /v1。

  • 正确：https://api2.cgapi.top/v1
  • 错误：https://api2.cgapi.top/v1/v1
  • 错误：https://api2.cgapi.top/v1/v1/chat/completions
不确定时就看字段名：写“Base URL / API Base / Endpoint”通常带 /v1；写“网站地址 / 控制台地址 / 域名”通常不带。

应用接入教程

选择你正在用的工具，照着对应卡片填。核心只有两项：Base URL 和 API Key。

常用工具

CC Switch

重点推荐

把 CGAPI 当作一个 OpenAI Compatible Provider 添加。

  • 打开 Provider / API 配置页面。
  • 新增 OpenAI Compatible 或 Custom OpenAI 服务。
  • Base URL：https://api2.cgapi.top/v1
  • API Key：填控制台创建的 sk-...。
  • 模型名：从控制台模型广场复制完整模型名。
  • 保存后先发一句短测试，确认能正常返回。

Codex

代码场景

适合代码、脚本、工程任务。使用 OpenAI 兼容配置时，重点看 base URL 和 key。

  • Provider 类型选择 OpenAI Compatible 或自定义 OpenAI。
  • Base URL / API Base：https://api2.cgapi.top/v1
  • API Key：填 sk-...。
  • 模型名以控制台模型广场可用项为准。
  • 先用简单问题测试，再接入正式任务。

Cherry Studio

新手友好

图形界面清楚，适合第一次配置 API。

  • 进入模型服务商设置。
  • 新增 OpenAI 兼容服务。
  • Base URL：https://api2.cgapi.top/v1
  • API Key：填控制台创建的密钥。
  • 保存后先测试模型列表，再用模型广场里的可用模型发送一句短对话。

Claude Code / OpenClaw / Hermes

同类配置

界面不同，但配置思路一致。

  • 选择 OpenAI compatible 或 custom provider。
  • Base URL：https://api2.cgapi.top/v1
  • API Key：填 sk-...。
  • 模型名以控制台模型广场实际可用项为准。

OpenAI SDK

开发者

代码里把客户端的 base URL 指向 CGAPI，即可复用 OpenAI 风格调用。

  • Python 和 JavaScript 示例见下一节。
  • 不要把 Key 写死到前端网页。
  • 服务端读取环境变量更安全。

curl

快速验证

不确定工具是否配置对时，用 curl 先验证 Key、Base URL 和模型是否可用。

  • 先请求 /v1/models 看密钥是否有效。
  • 再请求 /v1/chat/completions 看模型是否能回复。
  • 失败时按“常见问题排查”处理。

API 基础与示例

先用最小请求调通，再把它接进你的应用或工作流。示例里的模型名是占位符，请换成模型广场中你账号可用的真实模型名。

可复制示例
curl · macOS / LinuxBase URL: https://api2.cgapi.top/v1
curl https://api2.cgapi.top/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-model-name",
    "messages": [
      {"role": "user", "content": "用一句话介绍 CGAPI"}
    ]
  }'
curl.exe · Windows PowerShell先替换 Key 和模型名
curl.exe https://api2.cgapi.top/v1/chat/completions ^
  -H "Authorization: Bearer sk-your-api-key" ^
  -H "Content-Type: application/json" ^
  -d "{\"model\":\"your-model-name\",\"messages\":[{\"role\":\"user\",\"content\":\"只回复 OK\"}],\"max_tokens\":20}"
Python · OpenAI SDKAuthorization: Bearer
from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api2.cgapi.top/v1",
)

response = client.chat.completions.create(
    model="your-model-name",
    messages=[
        {"role": "user", "content": "写一个三步接入说明"}
    ],
)

print(response.choices[0].message.content)
JavaScript · OpenAI SDKNode.js
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk-your-api-key",
  baseURL: "https://api2.cgapi.top/v1",
});

const response = await client.chat.completions.create({
  model: "your-model-name",
  messages: [
    { role: "user", content: "给我一个 API 接入检查清单" }
  ],
});

console.log(response.choices[0].message.content);
模型列表测试验证 Key 和网关是否可用
curl https://api2.cgapi.top/v1/models \
  -H "Authorization: Bearer sk-your-api-key"

常见问题排查

遇到错误先看状态码，再按“原因 + 下一步”处理。

少走弯路
401 Unauthorized

密钥无效或没传

检查请求头是否包含 Authorization: Bearer sk-...。如果 Key 已删除或复制不完整，重新创建。

403 Forbidden

当前账号没有权限

可能是模型未开放、账号分组无权限，或该模型需要更高权限。先换一个模型广场里明确可用的低价模型测试。

429 Too Many Requests

请求太频繁

降低并发、增加重试间隔。测试时不要同时开太多任务。

Insufficient Balance

余额或额度不足

进入控制台查看余额。高成本模型消耗更快，测试阶段先用低成本模型。

Model Not Available

模型不可用或名字填错

模型名称以控制台模型广场可见项为准。建议直接复制完整模型名，注意大小写、短横线、点号和版本号。

Timeout / 5xx

请求超时或服务暂时异常

稍后重试，或换一个可用模型。持续出现时先看是否所有模型都失败。

FAQ

先回答最容易卡住新用户的问题。

持续补充

这是聊天网站吗？

不是。CGAPI 主要提供 API 接入能力。聊天、写作、代码等体验通常在 CC Switch、Codex、Cherry Studio、Claude Code、OpenAI SDK 或其他客户端里完成。

Base URL 应该填哪里？

支持 OpenAI Compatible API 的客户端，一般都有 Base URL、API Host 或 Endpoint 字段，填 https://api2.cgapi.top/v1。

为什么模型名称会变？

模型可用性取决于平台配置、供应商状态和账号权限。实际可用模型以控制台模型广场为准。

能不能把 Key 放前端？

不要。前端网页里的 Key 会被用户看到。正式应用应在服务端保存 Key，并由服务端转发请求。