使用文档

快速开始

本页适用于 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（具体取决于客户端要求）。

支持的模型服务商

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

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

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

快速开始

1. 注册并获取 ZOOAPI API Key

2. 配置 Base URL

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

3.1 OpenAI Responses API

3.2 OpenAI Chat Completions API

3.3 Claude API

3.4 Gemini API

4. 查看用量与账单

SDK 集成

OpenAI SDK 集成

Python

JavaScript / TypeScript

Claude SDK 集成

Python

JavaScript / TypeScript

其他客户端和应用

支持的模型服务商

OpenAI

Gemini

Claude

AWS Bedrock

Vertex AI

Azure AI

Doubao

Perplexity

DeepSeek

Grok AI

Cohere

Mistral AI

AI21

Sophnet

Claude Code（API Key 接入）

使用 ZOOAPI 驱动 Claude Code

Linux / macOS

Windows CMD

Windows PowerShell

Grok CLI / OpenCode（API Key 接入）

Grok CLI（grok-4.5 / Responses）

OpenCode（Responses：gpt-5.6-sol）

Codex CLI / App（API Key 接入）

统一接入说明

推荐：Linux / macOS 一键配置

备用：单独配置文件

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

技术问题