x ZOOAPI
Developer Documentation

使用文档

ZOOAPI 保持 OpenAI 兼容的调用方式。注册控制台、创建 API KEY 后，将项目中的 Base URL 替换为 ZOOAPI 地址，即可通过统一入口调用 Claude、GPT、Gemini、图像和音频模型。

开始接入 → 进入控制台

快速开始

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

1. 注册并获取 ZOOAPI API Key

  1. 访问 manager.zooapi.ai 注册账号。
  2. 按提示完成邮箱验证与账户激活。
  3. 在邮箱查看系统给你创建的 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.3-codex",
    "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.3-codex",
    "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

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

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

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

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 地址的第三方客户端，集成方法都是类似的：

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

支持的模型服务商

ZOOAPI 当前支持以下 LLM 服务商。可在 模型列表页面 查看所有可用模型。

OpenAI

OpenAIplatform.openai.com/docs

Gemini

Geminiai.google.dev

Claude

Claudedocs.anthropic.com

AWS Bedrock

AWS Bedrockaws.amazon.com/bedrock

Vertex AI

Vertex AIcloud.google.com/vertex-ai

Azure AI

Azure AIlearn.microsoft.com

Doubao

Doubaovolcengine.com/doubao

Perplexity

Perplexitydocs.perplexity.ai

DeepSeek

DeepSeekapi-docs.deepseek.com

Grok AI

Grok AIdocs.x.ai

Cohere

Coheredocs.cohere.com

Mistral AI

Mistral AIdocs.mistral.ai

AI21

docs.ai21.com

Sophnet

Sophnetsophnet.com

ZOOAPI 平台支持上述 AI 服务提供商的模型。通过单一 API 密钥，您可以调用不同服务商的 AI 模型，实现灵活高效的人工智能应用开发。

Claude Code（API Key 接入）

Claude Code

使用 ZOOAPI 驱动 Claude Code

提示：如果你更偏好官方账号接入，而非 API Key，请参考 Claude Code 官方账号接入指南。

Claude Code 是 Claude 官方推出的一款强大的编码助手。它可以在您的终端中直接运行，帮助您编写、解释和重构代码。

默认情况下，使用 Claude Code 需要登录 Claude 官方账号并购买订阅。但它也支持通过配置 API 端点来使用，这使得它可以通过第三方 API Router 来驱动，从而利用您自己的 API 密钥进行调用。

系统要求

操作系统：

  • macOS 10.15+
  • Ubuntu 20.04+/Debian 10+
  • Windows 10+（支持 WSL 1、WSL 2 或 Git for Windows）

硬件：

  • 最小 4GB+ RAM
  • 需要网络连接用于认证和 AI 处理
  • 兼容的 Shell：Bash、Zsh 或 Fish

安装 Claude Code

官方推荐使用原生二进制安装，无需 Node.js 依赖，自带自动更新功能。

macOS/Linux 使用 Homebrew：

shell
brew install --cask claude-code

macOS/Linux/WSL 使用安装脚本：

shell
curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell：

PowerShell
irm https://claude.ai/install.ps1 | iex

Windows CMD：

CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

安装特定版本

shell
# 安装稳定版（默认）
curl -fsSL https://claude.ai/install.sh | bash

# 安装最新版
curl -fsSL https://claude.ai/install.sh | bash -s latest

# 安装特定版本（例如 1.0.58）
curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58

验证安装

shell
claude doctor

这将检查您的安装类型和版本信息。

配置 API 密钥和端点

使用环境变量：

shell
export ANTHROPIC_BASE_URL=https://api.zooapi.ai
export ANTHROPIC_AUTH_TOKEN=sk-xxxx

# 可选：自定义 Claude 默认模型映射（不配置也可正常使用）
export ANTHROPIC_DEFAULT_OPUS_MODEL=MiniMax-M2.5
export ANTHROPIC_DEFAULT_SONNET_MODEL=MiniMax-M2.5
export ANTHROPIC_DEFAULT_HAIKU_MODEL=MiniMax-M2.5

更新 Claude Code

自动更新：

  • Claude Code 会在启动时和定期检查更新
  • 更新会在后台自动下载和安装
  • 下次启动时生效

禁用自动更新：

shell
export DISABLE_AUTOUPDATER=1

手动更新：

shell
claude update

使用指南

配置完成后，您就可以直接在终端中使用 claude 命令与 AI 进行交互了。

示例 1：编写代码

shell
claude "write a python flask app with a single endpoint that returns hello world"

示例 2：解释代码

shell
cat my_script.js | claude "explain this javascript code"

示例 3：交互式会话

shell
claude

Gemini CLI（API Key 接入）

Gemini CLI

使用 ZOOAPI 驱动 Gemini CLI

提示：如果你更偏好官方账号接入的方式，可参考 Claude Code 或 OpenAI Codex 官方账号接入指南。

Gemini CLI 是 Google 官方出品的命令行工具，让您可以直接在终端中与强大的 Gemini 系列模型进行交互。

准备工作

在开始之前，请确保您已经拥有：

  • 已安装 Node.js（版本需 >= 18）和 npm。

第一步：安装 Gemini CLI

首先，使用 npm 在您的系统上全局安装 Gemini CLI。请打开终端并运行以下命令：

shell
npm install -g @google/gemini-cli

安装成功后，您就可以在终端的任何位置使用 gemini 命令了。

第二步：配置环境变量

配置环境变量是让 Gemini CLI 通过 ZOOAPI 运行的关键一步。这里需要设置两个变量：一个用于指定 API 的接入点，另一个用于存放您的 API Key。

将以下两行命令添加到您的 shell 配置文件中，例如 ~/.zshrc 或 ~/.bashrc。

shell
export GOOGLE_GEMINI_BASE_URL="https://api.zooapi.ai"
export GEMINI_API_KEY="sk-xxxx"

添加完成后，执行 source ~/.zshrc（或您对应的配置文件）或重启终端，以使配置生效。

第三步：开始使用

所有配置都已就绪！现在，您可以直接在终端中启动 Gemini CLI 了。

shell
gemini

程序启动后，您可以直接开始提问。由于环境变量已经配置完成，Gemini CLI 会自动使用您的 ZOOAPI API Key 并通过 ZOOAPI 进行连接，无需任何额外的手动认证步骤。

plain
You: >> 编写一个python函数，计算斐波那契数列

Codex CLI / App（API Key 接入）

Codex CLI / App

使用 ZOOAPI 驱动 Codex CLI / App

Codex 客户端支持两种 wire 协议：responses 与 chat。完成 ~/.codex/config.toml 和 ZOOAPI_API_KEY 配置后，Codex App 可直接复用同一套连接参数。

准备工作

  • 已安装 Codex CLI
  • 已在邮箱收到系统创建的 ZOOAPI API Key
  • Linux/macOS 配置路径：~/.codex/config.toml
  • Windows 配置路径：%USERPROFILE%\.codex\config.toml

提示：注册并登录 manager.zooapi.ai 后，进入「账户充值」页面即可查看包月购买选项与价格。

方案 A：wire_api = "responses"（推荐 Codex 模型）

~/.codex/config.toml
# ~/.codex/config.toml
model_provider = "xai"
model = "gpt-5.3-codex"
approval_policy = "never"
sandbox_mode = "danger-full-access"
network_access = true
preferred_auth_method = "apikey"

[model_providers.xai]
name = "xai"
base_url = "https://api.zooapi.ai"
wire_api = "responses"
requires_openai_auth = false
env_key = "ZOOAPI_API_KEY"
shell
export ZOOAPI_API_KEY="sk-xxxx"
codex --yolo

方案 B：wire_api = "chat"（适配 OpenAI Chat 形态模型）

~/.codex/config.toml
# ~/.codex/config.toml
[model_providers.xai]
name = "xai"
base_url = "https://api.zooapi.ai"
env_key = "ZOOAPI_API_KEY"
wire_api = "chat"
requires_openai_auth = false

[profiles.minimax]
model = "MiniMax-M2.5"
model_provider = "xai"
shell
export ZOOAPI_API_KEY="sk-xxxx"
codex --profile minimax

Windows 启动示例

CMD
:: 配置文件路径
:: %USERPROFILE%\.codex\config.toml

set ZOOAPI_API_KEY=sk-xxxx

:: responses
codex

:: chat
codex --profile minimax
PowerShell
# 配置文件路径
# $env:USERPROFILE\.codex\config.toml

$env:ZOOAPI_API_KEY="sk-xxxx"

# responses
codex

# chat
codex --profile minimax

验证命令

  • codex（responses）
  • codex --profile minimax（chat）

技术问题

为什么有些 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，因此建议降低并发并做指数退避。