常见问题

基础问题

Zivv API 是什么？

Zivv API 是一个多模型 AI 接口服务，同时兼容 OpenAI、Anthropic 和 Gemini 三种协议格式。你可以用一个 API Key 接入 Claude Code、Codex、各协议 SDK，以及支持自定义 Base URL 的第三方客户端。

支持哪些客户端？

支持所有兼容 OpenAI Chat Completions API 或 Anthropic Messages API 的客户端，包括但不限于：

• Claude Code
• Codex CLI / 桌面端
• OpenAI、Anthropic 与 Google Gen AI SDK
• 支持自定义 Base URL 的第三方客户端
• Cursor / Windsurf（需先查看对应兼容性说明）
• OpenClaw
• Cherry Studio
• Chatbox
• BotGem
• OpenAI SDK（Python / Node.js）
• Anthropic SDK（Python / Node.js）

支持哪些模型？

详见 模型广场。

---

连接问题

提示 Unauthorized 怎么办？

1. 确认 API Key 正确，以 sk- 开头
2. 确认请求头格式：
   • OpenAI：Authorization: Bearer sk-xxx
   • Anthropic：x-api-key: sk-xxx
3. 确认 Key 没有过期或被禁用
4. 确认 Key 前后没有多余的空格

提示 Connection Refused 怎么办？

1. 确认 Base URL 使用 https://（不是 http://）
2. 检查网络连接是否正常
3. 用 curl https://zivv.pro/health 确认服务是否在线

收到 429 Too Many Requests 怎么办？

说明请求频率过高。建议：

• 降低请求频率
• 等待 Retry-After header 指示的时间后重试
• 在代码中实现退避重试逻辑

收到 502 / 503 怎么办？

这通常是上游模型暂时不可用。建议：

• 等待 1-2 分钟后重试
• 从模型广场复制另一个当前可用的模型 ID 后重试

---

使用问题

Base URL 应该带 /v1 吗？

取决于你使用的协议格式：

格式	Base URL
OpenAI（Codex、OpenAI SDK、兼容客户端）	https://zivv.pro/v1
Anthropic（Claude Code、Anthropic SDK）	https://zivv.pro
Gemini（Gemini CLI）	https://zivv.pro/v1beta

TIP

差异原因：Anthropic SDK 会自动拼接 /v1/messages，所以 Base URL 不带 /v1。OpenAI SDK 不会自动拼接，需要你提供完整的 /v1 路径。Gemini 协议使用 /v1beta 前缀。

Claude Code 应该使用哪个模型名？

以 模型广场 中当前可用的完整模型 ID 为准。Claude Code 的默认模型和别名会随客户端更新；默认模型失败时，请显式指定模型并检查 Key 分组：

claude --model "模型广场中的模型 ID"

max_tokens 有上限吗？

上限取决于模型、协议和当前网关限制。数值过大时可能被限制、调整或返回错误；请以模型广场、客户端要求和实际错误响应为准。

为什么同一份请求直连官方 400、经 Zivv 却成功？

Zivv API 在转发前会自动修正客户端请求里的常见结构问题（已废弃字段、没配对的 tool_use、空内容块、其他厂商的字段等），这些直连官方接口会让整个请求被拒。

这是有意提供的兼容层。完整清单见 请求兼容性修正——其中 少数几项会改变语义，那一节说明了原因和规避方式。

支持流式输出吗？

文本生成端点通常支持流式输出，在请求体中添加 "stream": true，或按 Gemini 协议使用 streamGenerateContent。模型列表、Token 计数、健康检查和异步任务查询等端点不使用 SSE。

支持图片生成吗？

支持。请在模型广场选择当前可用的图片模型；Gemini 原生协议会在响应 parts 的 inlineData 中返回 Base64 图片数据。

---

账户问题

怎么查看余额？

登录 Zivv 控制台 订阅页面即可查看。

怎么充值？

前往 订阅页面 充值，或联系管理员。

余额用完了会怎样？

API 请求会返回 403 Forbidden。充值后立即恢复。

API Key 丢失了怎么办？

API Key 只在创建时显示一次。如果丢失，需要在 令牌管理 页面重新创建一个新的 Key。旧的 Key 建议删除。