TOPAPI DOCS
普通人也能照着做的接入文档A beginner-friendly setup guide
你不需要先理解所有技术名词。TopAPI 做的事很简单:把你手里的 API Key 填进工具里,再把工具的请求转到 TopAPI,就可以使用不同 AI 模型。 You do not need to understand every technical term first. TopAPI lets you put one API key into your tool and route model requests through TopAPI.
打开你要用的工具,找到“模型 / API / 自定义接口”设置,然后填三样东西:API Key、接口地址、模型名。后面每一段都会告诉你该填什么。 Open your tool, find the model/API/custom endpoint settings, then fill in three things: API key, endpoint, and model name. Each section below tells you exactly what to paste.
先选择你要接入哪个工具Choose the tool you use
不要从头读到尾。你用哪个工具,就点哪个入口;其他内容可以先不用看。 Do not read the whole page first. Pick your tool and follow that section only.
最推荐从这里开始,有一键安装命令。Best starting point. Includes one-line setup.
CLAUDE 我想配置 Claude CodeSet up Claude Code适合已经安装 Claude Code 的用户。For users who already have Claude Code.
GEMINI 我想配置 Gemini CLISet up Gemini CLI先安装 Node.js,再安装 Gemini CLI。Install Node.js first, then Gemini CLI.
DESKTOP APPS TRAE / OpenClaw / Hermes适合有图形界面或自定义模型设置的工具。For apps with custom model settings.
DEVELOPERS 我要在代码里调用 APICall the API in code这里是给开发者看的 curl 和 Node.js 示例。curl and Node.js examples for developers.
HELP 我看不懂或报错了I am stuck先看常见错误,通常是 Key、地址或模型名填错。Most issues are caused by key, endpoint, or model name.
所有工具都只是在填这三样东西Every tool needs these three fields
不同软件的按钮名字不一样,但本质都一样。看到类似“API Key、Base URL、Model”的输入框,就按下面填。 Different apps use different labels, but they all ask for the same three values.
这是你的通行证。在 TopAPI 控制台创建,然后把示例里的 YOUR_API_KEY 换成真实密钥。This is your password-like token. Create it in the TopAPI console and replace YOUR_API_KEY.
这是工具要连接到哪里。OpenAI / Codex 填 https://api.topopenai.com/v1;Claude 类工具通常填 https://api.topopenai.com。This tells the tool where to connect. OpenAI/Codex uses https://api.topopenai.com/v1; Claude-style tools usually use https://api.topopenai.com.
这是你要使用哪个 AI。先用示例里的 gpt-5.5 或 claude-opus-4-7 测试,能跑通后再换其他模型。This chooses the AI model. Start with gpt-5.5 or claude-opus-4-7, then switch later.
看不懂英文设置项时,只要找这几个词:API Key、Base URL、Endpoint、Model。它们基本就是上面三样东西。
If the app is in English, look for API Key, Base URL, Endpoint, and Model.
如果提示找不到 node 或 npm,再看这一段Read this only if node or npm is missing
Node.js 是很多命令行工具的运行环境。你不一定需要手动安装它:如果 Codex、Claude Code 或 Gemini CLI 已经能打开,可以直接跳到对应工具配置。 Node.js is the runtime used by many CLI tools. You may not need to install it manually. If Codex, Claude Code, or Gemini CLI already opens, skip to that tool.
最简单的判断方法:打开终端,输入下面的验证命令。如果能看到版本号,说明已经装好了。 The simplest check: run the verification command below. If you see version numbers, Node.js is already installed.
普通用户建议直接安装 Node.js LTS 版本。会用命令行工具的用户也可以选择 Chocolatey 或 Scoop。Most users should install Node.js LTS directly. Command-line users can use Chocolatey or Scoop.
choco install nodejs-lts
scoop install nodejs-lts
会用 Homebrew 就执行下面命令;不会用也可以安装 Node.js LTS 安装包。Use Homebrew if you have it, or install the Node.js LTS package.
brew install node
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs
curl -fsSL https://rpm.nodesource.com/setup_lts.x | sudo bash -
sudo yum install -y nodejs
node --version
npm --version
我用 Codex:复制一条命令开始Codex: start with one command
如果你只是想让 Codex 能连接 TopAPI,优先用一键脚本。脚本会帮你安装或配置 Codex,并把 TopAPI 的接口地址写进去。 If you only want Codex to connect through TopAPI, use the one-line setup first. It installs or configures Codex and writes the TopAPI endpoint.
macOS、Linux、WSL 用第一条;Windows PowerShell 用第二条。Use the first command for macOS, Linux, or WSL. Use the second for Windows PowerShell.
密钥来自 TopAPI 控制台,不要把它发给别人。The key comes from the TopAPI console. Do not share it.
如果 Codex 能正常回答,说明已经接入成功。If Codex answers normally, setup is complete.
curl -fsSL https://api.topopenai.com/install/codex.sh | sudo bash
irm https://api.topopenai.com/install/codex.ps1 | iex
mkdir -p ~/.codex
cat > ~/.codex/config.toml <<'EOF'
model = "gpt-5.5"
model_provider = "openai"
openai_base_url = "https://api.topopenai.com/v1"
cli_auth_credentials_store = "file"
forced_login_method = "api"
EOF
cat > ~/.codex/auth.json <<'EOF'
{"OPENAI_API_KEY":"YOUR_API_KEY"}
EOF
手动配置只在一键脚本失败时使用。复制前记得把 YOUR_API_KEY 换成控制台里的真实密钥。
Use manual config only if the installer fails. Replace YOUR_API_KEY with your real key before running it.
我用 Claude Code:地址不要带 /v1Claude Code: do not add /v1
Claude Code 用的是 Claude/Anthropic 这一路。这里最容易填错的是地址:Claude Code 填 https://api.topopenai.com,不要在末尾加 /v1。
Claude Code uses the Claude/Anthropic route. The common mistake is the endpoint: use https://api.topopenai.com, without /v1.
下面的命令只对当前终端生效。以后重新打开终端,可能需要再执行一次。The commands below apply to the current terminal session. You may need to run them again in a new terminal.
Windows 用 PowerShell;macOS、Linux 用 Bash / Zsh。Use PowerShell on Windows, and Bash/Zsh on macOS or Linux.
如果忘了替换,Claude Code 会提示认证失败。If you forget this, Claude Code will fail authentication.
$env:ANTHROPIC_BASE_URL = "https://api.topopenai.com"
$env:ANTHROPIC_AUTH_TOKEN = "YOUR_API_KEY"
$env:CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC = "1"
claude
export ANTHROPIC_BASE_URL="https://api.topopenai.com"
export ANTHROPIC_AUTH_TOKEN="YOUR_API_KEY"
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
claude
看到 Claude Code 能正常回复,就说明配置成功。如果报错,先检查三件事:Key 有没有替换、地址有没有多写 /v1、终端是不是重新打开过。
If Claude Code responds normally, setup worked. If it fails, check whether the key was replaced, whether /v1 was added by mistake, and whether you opened a new terminal.
我用 Gemini CLI:先确认 npm 能用Gemini CLI: make sure npm works first
Gemini CLI 通常通过 npm 安装。如果你执行 npm --version 能看到版本号,就可以继续下面步骤;如果不行,先回到 Node.js 那一段。
Gemini CLI is usually installed with npm. If npm --version shows a version number, continue. Otherwise, go back to the Node.js section.
先执行安装命令,再执行 gemini --version 确认安装成功。Run the install command, then verify with gemini --version.
下面命令里的 YOUR_API_KEY 必须换成真实密钥。Replace YOUR_API_KEY with your real key.
如果能返回中文回答,就说明链路已经通了。If you get a reply, the connection works.
npm install -g @google/gemini-cli
gemini --version
$env:GOOGLE_GEMINI_BASE_URL = "https://api.topopenai.com"
$env:GEMINI_API_KEY = "YOUR_API_KEY"
$env:GEMINI_MODEL = "gemini-3-pro-preview"
gemini -p "你好"
export GOOGLE_GEMINI_BASE_URL="https://api.topopenai.com"
export GEMINI_API_KEY="YOUR_API_KEY"
export GEMINI_MODEL="gemini-3-pro-preview"
gemini -p "你好"
我用 TRAE / OpenClaw / Hermes:按设置项填写TRAE / OpenClaw / Hermes: fill the settings
这类工具通常有图形界面,重点是找到“添加模型”“自定义模型”“API Provider”之类的入口。你不需要理解每个英文词,只要把对应字段填对。 These tools usually have settings screens. Look for add model, custom model, or API provider, then fill the matching fields.
入口通常是:设置 -> 模型 -> 添加模型 -> 自定义配置。Usually: Settings -> Models -> Add model -> Custom.
如果选择 OpenAI / Codex 类型:base_url = https://api.topopenai.com/v1,模型先填 gpt-5.5。For OpenAI/Codex mode: base_url = https://api.topopenai.com/v1, model gpt-5.5.
如果选择 Claude / Anthropic 类型:base_url = https://api.topopenai.com,模型先填 claude-opus-4-7。For Claude/Anthropic mode: base_url = https://api.topopenai.com, model claude-opus-4-7.
选择 OpenAI 模式时,用 OPENAI_API_KEY 和 https://api.topopenai.com/v1。In OpenAI mode, use OPENAI_API_KEY and https://api.topopenai.com/v1.
选择 Anthropic 模式时,用 ANTHROPIC_API_KEY 和 https://api.topopenai.com。In Anthropic mode, use ANTHROPIC_API_KEY and https://api.topopenai.com.
如果界面里有 OpenAI 通道,地址填带 /v1 的版本。If the app asks for an OpenAI endpoint, use the URL with /v1.
如果界面里有 Anthropic / Claude 通道,地址填不带 /v1 的版本。If it asks for Anthropic/Claude, use the URL without /v1.
只要是 TopAPI 控制台创建的 Key,就可以填到这些工具里。多个工具建议分开创建 Key,方便以后删除或限额。Any key created in the TopAPI console works here. Create separate keys for separate tools if possible.
判断应该用哪个地址:看到 OpenAI、Codex、ChatGPT、GPT,就用 https://api.topopenai.com/v1;看到 Claude、Anthropic,就用 https://api.topopenai.com。
Rule of thumb: OpenAI, Codex, ChatGPT, or GPT uses https://api.topopenai.com/v1; Claude or Anthropic uses https://api.topopenai.com.
export OPENAI_API_KEY="YOUR_API_KEY"
openclaw onboard --auth-choice custom-api-key \
--custom-base-url https://api.topopenai.com/v1 \
--custom-api-key-env OPENAI_API_KEY \
--custom-compatibility openai \
--custom-model gpt-5.5
export ANTHROPIC_API_KEY="YOUR_API_KEY"
openclaw onboard --auth-choice custom-api-key \
--custom-base-url https://api.topopenai.com \
--custom-api-key-env ANTHROPIC_API_KEY \
--custom-compatibility anthropic \
--custom-model claude-opus-4-7
还不确定怎么填?看这张速查表Still unsure? Use this quick table
如果某个工具只给你几个输入框,不知道填什么,按下面表格对照。最重要的是地址别选错。 If a tool only shows a few fields and you are unsure what to enter, use this table. The most important part is the endpoint.
base_url = https://api.topopenai.com/v1
OPENAI_API_KEY = YOUR_API_KEY
ANTHROPIC_BASE_URL = https://api.topopenai.com
ANTHROPIC_AUTH_TOKEN = YOUR_API_KEY
Codex 模型填 /v1 地址;Claude 模型填根地址。Use the /v1 endpoint for Codex models and the root endpoint for Claude models.
OpenAI 通道选择 https://api.topopenai.com/v1;Anthropic 通道选择 https://api.topopenai.com。Use https://api.topopenai.com/v1 for OpenAI mode and https://api.topopenai.com for Anthropic mode.
开发者 API 示例:普通用户可以跳过API examples for developers
这一段是给写代码的人看的。如果你只是配置 Codex、Claude Code、Gemini CLI、TRAE 这类工具,前面对应段落已经够用了。 This section is for people writing code. If you only configure Codex, Claude Code, Gemini CLI, or TRAE, the earlier sections are enough.
POST /v1/responses
POST /v1/chat/completions
POST /v1/messages
curl https://api.topopenai.com/v1/responses \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.5",
"input": "用中文简单介绍一下 TopAPI。"
}'
curl https://api.topopenai.com/v1/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.5",
"messages": [
{"role": "user", "content": "用一句话介绍 TopAPI。"}
]
}'
const response = await fetch("https://api.topopenai.com/v1/chat/completions", {
method: "POST",
headers: {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
},
body: JSON.stringify({
model: "gpt-5.5",
messages: [{ role: "user", content: "用一句话介绍 TopAPI。" }]
})
});
console.log(await response.json());
curl https://api.topopenai.com/v1/messages \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-opus-4-7",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "用中文简单介绍一下 TopAPI。"}
]
}'
curl https://api.topopenai.com/v1/images/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2",
"prompt": "生成一张极简风格的 TopAPI 产品图",
"size": "1024x1024"
}'
如果接口返回 API_KEY_REQUIRED 或 INVALID_API_KEY,先检查请求头、密钥是否完整、以及是否把示例里的 YOUR_API_KEY 替换成真实密钥。
If the API returns API_KEY_REQUIRED or INVALID_API_KEY, check the header, the key value, and whether YOUR_API_KEY was replaced.
看不懂或报错时,先按这里排查If you are stuck, check these first
工具里写 OpenAI、Codex、GPT、ChatGPT,就填 https://api.topopenai.com/v1。工具里写 Claude、Anthropic,就填 https://api.topopenai.com。OpenAI, Codex, GPT, or ChatGPT uses https://api.topopenai.com/v1. Claude or Anthropic uses https://api.topopenai.com.
先确认三点:已经把 YOUR_API_KEY 换成真实密钥;复制时没有多空格;这个 Key 来自当前 TopAPI 账号。Check that YOUR_API_KEY was replaced, no extra spaces were copied, and the key belongs to your current TopAPI account.
先不要纠结。OpenAI / Codex 先填 gpt-5.5;Claude 先填 claude-opus-4-7。跑通后再换控制台里的其他模型。Start simple: use gpt-5.5 for OpenAI/Codex and claude-opus-4-7 for Claude. Switch later.
先确认你复制到了正确的终端:Windows 用 PowerShell;macOS / Linux 用终端。如果提示 npm 不存在,回到 Node.js 段落。Make sure you are using the right terminal: PowerShell on Windows, Terminal on macOS/Linux. If npm is missing, read the Node.js section.
最小排错顺序:先换 Key,再换地址,最后换模型名。一次只改一项,方便知道是哪一步出问题。 Minimal debugging order: check the key, then the endpoint, then the model name. Change one thing at a time.