使用文档 | ZOOAPI OpenAI 兼容 API 接入指南

快速开始

本页适用于 ZOOAPI（在线注册即可使用的 AI API Router 服务）。

1. 注册并获取 ZOOAPI API Key

访问 manager.zooapi.ai 注册账号。
按提示完成邮箱验证与账户激活。
在邮箱查看系统给你创建的 ZOOAPI API Key。

2. 配置 Base URL

将你的 SDK 或应用中的 base_url 替换为 ZOOAPI 的 Base URL：

Base URL: https://api.zooapi.ai

3. 发出第一个请求（几种主流协议示例）

设置 API Key

# 将 YOUR_ZOOAPI_API_KEY 替换为你自己的 Key
export ZOOAPI_API_KEY="sk-xxxx"

3.1 OpenAI Responses API

curl

curl https://api.zooapi.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ZOOAPI_API_KEY" \
  -d '{
    "model": "gpt-5.6-sol",
    "input": "你好，ZOOAPI！请用一句话介绍你自己。"
  }'

3.2 OpenAI Chat Completions API

curl

curl https://api.zooapi.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ZOOAPI_API_KEY" \
  -d '{
    "model": "gpt-5.6-sol",
    "messages": [
      {
        "role": "user",
        "content": "你好，ZOOAPI！请用一句话介绍你自己。"
      }
    ]
  }'

3.3 Claude API

curl

curl https://api.zooapi.ai/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: $ZOOAPI_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-6",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": "你好，Claude！请用一句话介绍你自己。"
      }
    ]
  }'

3.4 Gemini API

curl

curl -X POST "https://api.zooapi.ai/v1beta/models/gemini-3-flash-preview:generateContent" \
  -H "x-goog-api-key: $ZOOAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "你好，Gemini！请用一句话介绍你自己。"
          }
        ]
      }
    ]
  }'

4. 查看用量与账单

在 manager.zooapi.ai 可查看：

实时用量与模型维度消耗
账单与充值记录

SDK 集成

ZOOAPI 的 API 设计与 OpenAI 和 Claude 的 SDK 完全兼容，使您可以轻松地将现有应用迁移过来，几乎无需更改代码。

OpenAI SDK 集成

您只需在初始化 OpenAI 客户端时，将 base_url 指向 ZOOAPI 的地址即可。

Python

import os
from openai import OpenAI

# 建议从环境变量读取您的 Key
client = OpenAI(
    api_key=os.environ.get("ZOOAPI_API_KEY"),
    base_url="https://api.zooapi.ai/v1",
)

chat_completion = client.chat.completions.create(
    model="gpt-5",
    messages=[
        {"role": "user", "content": "用 Python 写一个 Hello World"},
    ],
)

print(chat_completion.choices[0].message.content)

JavaScript / TypeScript

import OpenAI from "openai";

const openai = new OpenAI({
  apiKey: process.env.ZOOAPI_API_KEY, // 您的 ZOOAPI API Key
  baseURL: "https://api.zooapi.ai/v1",
});

async function main() {
  const chatCompletion = await openai.chat.completions.create({
    model: "gpt-5",
    messages: [
      { role: "user", content: "用 JavaScript 写一个 Hello World" },
    ],
  });

  console.log(chatCompletion.choices[0].message.content);
}

main();

Claude SDK 集成

同样地，对于 Claude 模型（如 Claude 系列），您只需修改 baseURL。

请注意，Claude 兼容的 baseURL 与 OpenAI 的略有不同，它不包含 /v1 后缀。

Python

import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ.get("ZOOAPI_API_KEY"),
    base_url="https://api.zooapi.ai/",
)

message = client.messages.create(
    model="claude-3-5-sonnet-latest",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "解释一下什么是“第一性原理”",
        }
    ],
)

print(message.content[0].text)

JavaScript / TypeScript

import Anthropic from "@anthropic-ai/sdk";

const anthropic = new Anthropic({
  apiKey: process.env.ZOOAPI_API_KEY, // 您的 ZOOAPI API Key
  baseURL: "https://api.zooapi.ai/",
});

async function main() {
  const message = await anthropic.messages.create({
    model: "claude-3-5-sonnet-latest",
    max_tokens: 1024,
    messages: [
      {
        role: "user",
        content: "解释一下什么是“第一性原理”",
      },
    ],
  });

  console.log(message.content[0].text);
}

main();

其他客户端和应用

对于任何支持自定义 OpenAI/Claude API 地址的第三方客户端，集成方法都是类似的：

找到设置中的 "API Key" 或类似选项，填入您的 sk-... Key。
找到 "API Base URL"、"Custom API Domain" 或 "Endpoint" 等选项，填入 https://api.zooapi.ai 或 https://api.zooapi.ai/v1（具体取决于客户端要求）。

Codex 是什么

Codex 是能够进入开发环境、阅读项目、修改文件并运行命令的编码代理。它不只是对话工具，更适合在明确范围内协助完成实际开发任务。

适合做什么

理解陌生项目的目录、启动方式和测试方式。
定位并修复 bug，修改代码、测试和文档。
审查改动、拆解任务，并在本地或云端并行探索方案。

不适合做什么

未理解项目就进行大范围重构。
直接操作生产数据库、服务器或凭据。
没有测试、确认或回滚方案的批量修改。

开始前请先确定入口、当前工作目录和可读写范围；在陌生仓库中避免授予全权限。

下载与安装

建议先安装 Codex CLI；需要图形界面时再打开桌面 App 或 IDE 扩展。

macOS、Linux 和 WSL

shell

curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex

# macOS 也可以使用 Homebrew
brew install --cask codex
codex app

Windows 原生

PowerShell

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
codex

# 可选：准备常用开发工具
winget install --id Git.Git
winget install --id OpenJS.NodeJS.LTS
winget install --id Python.Python.3

验证安装

shell

codex --version
codex

出现交互界面即表示 CLI 已可用。使用 WSL 时，建议将项目放在 WSL 文件系统中，例如 ~/code。

选择使用入口

不同入口适合不同的工作方式，选择会直接影响使用体验。

入口选择

CLI：适合在终端直接读写项目、运行命令、调整 sandbox、approval、model 或 profile。
App：适合图形化选择项目、并行管理多个任务、查看变更与 Git 状态。
IDE Extension：适合在 VS Code、Cursor 或 Windsurf 内解释、修改和 review 代码。
Web / Cloud：适合云端执行、生成 PR、远程任务和团队协作。

新手建议

希望少用命令行可以从 App 开始；开发者建议同时掌握 CLI。进入项目后再启动 Codex，能让它从正确的工作目录开始工作。

shell

cd your-project
codex

# 打开桌面 App
codex app

第一次使用

第一次不建议直接大改项目。先让 Codex 理解仓库，再安排范围小、可验证的任务。

先理解项目

提示词

请先不要修改文件。帮我解释这个项目的目录结构、启动方式和测试方式。

再执行最小改动

提示词

请找一个最小的可改进点，先说明方案，等我确认后再修改。

可以按方案修改。改完后运行相关测试，并告诉我修改了哪些文件。

高质量任务应明确：目标、范围、限制和验证方式。每轮改动后查看 diff，不要在未确认影响范围时继续扩大修改。

配置与登录

多数配置问题来自修改了错误的 config.toml，或环境变量未进入当前实际运行环境。

配置文件位置

macOS / Linux：~/.codex/config.toml
Windows 原生：%USERPROFILE%\.codex\config.toml
WSL2：使用 WSL 内自己的 ~/.codex/config.toml

Windows 与 WSL 是独立环境；仅在共享配置或切换环境时才需要设置 CODEX_HOME。

保守的默认配置

config.toml

approval_policy = "on-request"
sandbox_mode = "workspace-write"
preferred_auth_method = "apikey"

可使用 ChatGPT 账号、OpenAI API Key 或自定义 provider 登录。排查时依次确认运行平台、实际读取的配置文件、当前 shell 环境变量，以及 profile 是否覆盖默认设置。

接入 ZOOAPI

通过统一 API、账号、额度和模型配置，将 Codex 接入 ZOOAPI。密钥仅应通过环境变量或安全的密钥管理工具注入。

基础配置

config.toml

model_provider = "xai"
model = "gpt-5.6-sol"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
preferred_auth_method = "apikey"

[model_providers.xai]
name = "xai"
base_url = "https://api.zooapi.ai"
wire_api = "responses"
requires_openai_auth = false
env_key = "XAI_API_KEY"

设置密钥并启动

shell / PowerShell

# Linux / macOS
export XAI_API_KEY="YOUR_XAI_ROUTER_KEY"
codex

# PowerShell
$env:XAI_API_KEY="YOUR_XAI_ROUTER_KEY"
codex

Codex 原生模型使用 wire_api = "responses"；使用 Chat 形态模型时请单独配置 provider 和 profile。

GPT Image 2 图片 API

Codex 可协助编写图片工作流；真正负责生成或编辑图片的是 gpt-image-2 与 Images API。它不能作为 Codex 的主模型配置。

生成图片

使用 POST /v1/images/generations，响应中的 data[0].b64_json 可解码为图片文件。

shell

export API_BASE_URL="https://api.zooapi.ai"
export XAI_API_KEY="YOUR_XAI_ROUTER_KEY"

curl --fail-with-body -sS "$API_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一张现代茶饮品牌的方形海报，玻璃杯、柚子切片、清爽白绿色背景",
    "n": 1,
    "size": "1024x1024",
    "quality": "low",
    "output_format": "png"
  }' > gpt-image-response.json

jq -er '.data[0].b64_json' gpt-image-response.json | base64 --decode > gpt-image.png

编辑图片

使用 POST /v1/images/edits 并以 multipart/form-data 上传 image[]。局部重绘可额外提供带 alpha 通道的 mask。

shell

curl --fail-with-body -sS "$API_BASE_URL/v1/images/edits" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -F 'model=gpt-image-2' \
  -F 'image[]=@gpt-image.png' \
  -F 'prompt=保留主体与构图，把背景改成雨夜霓虹街道' \
  -F 'size=1024x1024' \
  -F 'quality=low' \
  -F 'output_format=png' > gpt-image-edit-response.json

常用 size 包括 1024x1024、1536x1024、1024x1536；quality 可选 low、medium、high。上传原图和遮罩应保持格式与尺寸一致，单个文件小于 50 MB。

权限与安全

Codex 可以修改文件和执行命令，安全使用的核心是明确访问边界和人工确认点。

Sandbox 与 Approval

Sandbox：控制可访问范围与可写入范围。
Approval：控制命令和越界操作前是否需要确认。

shell

codex --sandbox workspace-write --ask-for-approval on-request

安全操作习惯

先计划、后修改；每轮检查 diff 并运行相关测试。
警惕删除、迁移、覆盖和提权命令。
通过环境变量或密钥管理工具保存密钥，绝不提交到仓库。
只在临时容器、可丢弃虚拟机或已有回滚方案的环境中使用 --yolo 或 danger-full-access。

常用工作流

Codex 的效果很大程度取决于任务描述是否清晰、可验证。

解释项目与定位问题

提示词

请先不要改文件。阅读这个仓库，说明目录结构、主要模块、启动命令、测试命令和最重要的配置文件。

这个问题是：用户点击保存后页面没有提示成功。请先定位原因，不要直接改。找到原因后给出修复方案和验证方式。

修改、测试与审查

提示词

按方案修改，只改必要文件。完成后运行相关测试，并总结 diff。

请为这个模块补充单元测试。优先覆盖边界条件，不改变生产逻辑。完成后运行测试。

请 review 当前未提交改动。优先指出 bug、回归风险、安全问题和缺失测试。不要改文件，先给我 findings。

长任务模板

提示词

目标：把旧的支付回调处理迁移到新的 handler。
范围：只改 api/handler/payment* 和相关测试。
限制：不改数据库结构，不改外部接口字段。
验证：运行 payment 相关测试，并说明没有覆盖的风险。

进阶能力

先稳定完成小任务，再逐步采用适合团队和长任务的高级能力。

能力概览

Goals：为长时间、多步骤任务明确目标、预算与完成条件。
Skills：将说明、参考资料和脚本沉淀为可复用的任务能力。
Plugins：包含 skills、命令、MCP 配置、hooks 和资源文件的扩展包。
Subagents：为 review、测试补全或安全检查等复杂任务分配并行角色。
MCP：连接外部工具、数据源或内部系统；需要访问私有系统时再按需配置。

采用建议

先为重复工作流建立清晰的提示词和验证标准，再考虑 Skills、Plugins 或 MCP。每增加一个外部能力，都应最小化权限范围并确认其数据访问边界。

Claude Code（API Key 接入）

使用 ZOOAPI 驱动 Claude Code

Claude Code 通过环境变量接入 ZOOAPI。请先在终端设置变量，再执行 claude。

请将示例中的 sk-xxxx 替换为你自己的 ZOOAPI API Key；不要将密钥提交到代码仓库或共享给他人。

Linux / macOS

shell

export ANTHROPIC_AUTH_TOKEN="sk-xxxx"
export ANTHROPIC_BASE_URL="https://api.zooapi.ai"
# 可选：自定义 Claude 默认模型映射
export ANTHROPIC_DEFAULT_OPUS_MODEL="gpt-5.6-sol"
export ANTHROPIC_DEFAULT_SONNET_MODEL="gpt-5.6-terra"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="gpt-5.6-luna"

claude

Windows CMD

CMD

set ANTHROPIC_AUTH_TOKEN=sk-xxxx
set ANTHROPIC_BASE_URL=https://api.zooapi.ai
set ANTHROPIC_DEFAULT_OPUS_MODEL=gpt-5.6-sol
set ANTHROPIC_DEFAULT_SONNET_MODEL=gpt-5.6-terra
set ANTHROPIC_DEFAULT_HAIKU_MODEL=gpt-5.6-luna

claude

Windows PowerShell

PowerShell

$env:ANTHROPIC_AUTH_TOKEN="sk-xxxx"
$env:ANTHROPIC_BASE_URL="https://api.zooapi.ai"
$env:ANTHROPIC_DEFAULT_OPUS_MODEL="gpt-5.6-sol"
$env:ANTHROPIC_DEFAULT_SONNET_MODEL="gpt-5.6-terra"
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL="gpt-5.6-luna"

claude

验证命令：claude。

Grok CLI / OpenCode（API Key 接入）

Grok CLI 和 OpenCode 均可通过 ZOOAPI 的 Responses 兼容接口接入。以下示例使用 https://api.zooapi.ai 与你的 ZOOAPI API Key。

请将示例中的 sk-xxxx 替换为你自己的 ZOOAPI API Key；密钥只应保存在本机环境变量或受保护的配置文件中。

Grok CLI（grok-4.5 / Responses）

配置文件为 ~/.grok/config.toml；Windows 路径为 %USERPROFILE%\.grok\config.toml。

Linux / macOS 安装或更新：

shell

curl -fsSL https://x.ai/cli/install.sh | bash
grok update
grok --version

写入 ~/.grok/config.toml：

~/.grok/config.toml

[models]
default = "grok-4.5"

[endpoints]
models_base_url = "https://api.zooapi.ai"

[model."grok-4.5"]
model = "grok-4.5"
name = "Grok 4.5"
api_key = "sk-xxxx"
api_backend = "responses"
context_window = 500000
supports_backend_search = true

[session]
auto_compact_threshold_percent = 80

[ui]
max_thoughts_width = 120
yolo = true
compact_mode = false
permission_mode = "always-approve"

验证配置与请求：

shell

grok inspect
grok models
grok --model grok-4.5 --output-format json -p '只输出 YAI_GROK_OK'

安全提示：yolo = true 与 permission_mode = "always-approve" 会允许 Grok 自动执行工具调用，仅应在可信项目与运行环境中启用。Linux / macOS 建议执行 chmod 600 ~/.grok/config.toml。

OpenCode（Responses：gpt-5.6-sol）

全局配置文件为 ~/.config/opencode/opencode.jsonc；Windows 路径为 %USERPROFILE%\.config\opencode\opencode.jsonc。

opencode.jsonc

{
  "$schema": "https://opencode.ai/config.json",
  "model": "openai/gpt-5.6-sol",
  "small_model": "openai/gpt-5.6-sol",
  "provider": {
    "openai": {
      "options": {
        "baseURL": "https://api.zooapi.ai",
        "apiKey": "{env:XAI_API_KEY}"
      },
      "models": {
        "gpt-5.6-sol": {
          "headers": {
            "originator": "opencode"
          }
        }
      }
    }
  },
  "agent": {
    "title": { "options": { "reasoningEffort": "none" } },
    "build": { "variant": "xhigh", "options": { "reasoningSummary": "detailed", "textVerbosity": "high" } },
    "plan": { "variant": "xhigh", "options": { "reasoningSummary": "detailed", "textVerbosity": "high" } }
  },
  "permission": {
    "*": "allow",
    "external_directory": "allow",
    "doom_loop": "allow"
  }
}

Linux / macOS：

shell

export XAI_API_KEY="sk-xxxx"
opencode debug config
opencode run "你好"

Windows CMD：

CMD

set XAI_API_KEY=sk-xxxx
opencode debug config
opencode run "你好"

Windows PowerShell：

PowerShell

$env:XAI_API_KEY="sk-xxxx"
opencode debug config
opencode run "你好"

Codex CLI / App（API Key 接入）

统一接入说明

Codex 现已仅支持 wire_api = "responses"。请配置 ~/.codex/config.toml 与 ~/.codex/auth.json；Windows 路径分别为 %USERPROFILE%\.codex\config.toml 与 %USERPROFILE%\.codex\auth.json。

请将示例中的 sk-xxxx 替换为你自己的 ZOOAPI API Key。配置文件中包含密钥时，请避免提交到代码仓库，并限制本机文件权限。

推荐：Linux / macOS 一键配置

shell

[ -e ~/.codex ] && mv ~/.codex ~/.codex.bk; mkdir -p ~/.codex

cat > ~/.codex/config.toml <<'EOF'
model_provider = "xai"
model = "gpt-5.6-sol"
model_reasoning_effort = "xhigh"
plan_mode_reasoning_effort = "xhigh"
model_reasoning_summary = "none"
model_context_window = 1050000
model_auto_compact_token_limit = 945000
stream_idle_timeout_ms = 900000
approval_policy = "never"
sandbox_mode = "danger-full-access"
suppress_unstable_features_warning = true

[model_providers.xai]
name = "OpenAI"
base_url = "https://api.zooapi.ai"
wire_api = "responses"
experimental_bearer_token = "sk-xxxx"
requires_openai_auth = true

[features]
goals = true
remote_connections = true
EOF

cat > ~/.codex/auth.json <<'EOF'
{
  "OPENAI_API_KEY": "sk-xxxx"
}
EOF

chmod 600 ~/.codex/auth.json

上述配置会将同一个 ZOOAPI API Key 写入 experimental_bearer_token 与 auth.json。

备用：单独配置文件

~/.codex/config.toml

model_provider = "xai"
model = "gpt-5.6-sol"
model_reasoning_effort = "xhigh"
plan_mode_reasoning_effort = "xhigh"
model_reasoning_summary = "none"
model_context_window = 1050000
model_auto_compact_token_limit = 945000
stream_idle_timeout_ms = 900000
approval_policy = "never"
sandbox_mode = "danger-full-access"
suppress_unstable_features_warning = true

[model_providers.xai]
name = "OpenAI"
base_url = "https://api.zooapi.ai"
wire_api = "responses"
experimental_bearer_token = "sk-xxxx"
requires_openai_auth = true

[features]
goals = true
remote_connections = true

~/.codex/auth.json

{
  "OPENAI_API_KEY": "sk-xxxx"
}

Windows：创建配置目录并打开文件

CMD：

CMD

if not exist "%USERPROFILE%\.codex" mkdir "%USERPROFILE%\.codex"
notepad "%USERPROFILE%\.codex\config.toml"
notepad "%USERPROFILE%\.codex\auth.json"

codex

PowerShell：

PowerShell

New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex" | Out-Null
notepad "$env:USERPROFILE\.codex\config.toml"
notepad "$env:USERPROFILE\.codex\auth.json"

codex

打开文件后，分别粘贴上方 TOML 与 JSON 内容并保存，再运行 codex 验证配置。

技术问题

为什么有些 API 调用会报 404 Not Found 错误？

这通常是因为您的 base_url 配置不正确。许多库（如 LangChain）要求 base_url 必须包含 /v1 后缀，而不仅仅是域名。请检查配置是否为 https://api.zooapi.ai/v1（针对 OpenAI 兼容接口）。

为什么会报 401: Incorrect API key provided... 错误？

这个错误通常表明请求被发送到了 OpenAI 的官方服务器，而不是 ZOOAPI 对应的代理服务。请确认您不仅配置了 API Key，也已经将 API 请求地址（base_url）修改为 https://api.zooapi.ai。

如果我使用的开源项目不支持配置 `base_url` 怎么办？

在这种情况下，您需要找到该项目的源代码，并将其中的 API 请求地址从 api.openai.com 硬编码修改为 api.zooapi.ai。

为什么调用用户管理 API（如 /x-users）会提示 401 Unauthorized?

为了防止滥用，调用核心管理 API（如创建或管理子账户）对调用者账户的余额有最低要求。通常，您的账户余额需要大于 $100 才能获得相应调用权限。

创建子账户需要满足什么条件?

创建子账户通常需要满足两个条件：父账户余额需要大于 $100；为新创建的子账户进行的首次充值额度不能低于 $2。

为什么我的账户还有余额，但提示 "Insufficient balance"?

为了防止透支和资产损失，当账户余额低于 $1 时，系统会禁止新的 API 调用。请及时充值。

为什么会报 429 Too many requests / Rate limit XXX reached?

这表示命中了当前账户或模型的限流窗口，常见原因包括 RPM、RPH、RPD、TPM、TPH、TPD。如果报错里明确写的是 RPH，则表示该模型的每小时请求数已到上限。

降低并发并加入指数退避重试。
先区分具体 reason：RPM/RPH/RPD/TPM/TPH/TPD。
将负载分散到不同时段或模型。
联系管理员提升对应额度或模型配额。

RPH 是 300，为什么只成功了 40 次?

RPH 统计的是进入该窗口判断的尝试请求数，而用量统计只记录成功的请求。并发、自动重试或在触发阈值前失败的请求，都可能消耗 RPH，但不会进入成功用量统计。

并发请求会全部被拦截吗？触发后要等多久?

不会整批拦截，系统对每个请求单独判断：达到上限之前的请求会成功，超过上限的会返回 429。

RPM/TPM：通常约 1 分钟。
RPH/TPH：通常约 1 小时。
RPD/TPD：自然日额度，到服务端当天结束后恢复。

为什么我感觉限额一直不清零?

先看报错里的 reason：RPM/RPH/TPM/TPH 通常表示还在短窗口或 cooldown 内；RPD/TPD 表示当日额度已经用完，需要等服务端业务日期切到下一天。持续重试本身也可能刷新 cooldown，因此建议降低并发并做指数退避。