帮助文档
从注册、创建 Key 到接入 Claude Code 和各类 SDK，常见问题与排错方法都在这里。
完整文档站
更全面的接入指南、模型说明与最佳实践，尽在独立文档站。
Base URL
https://your-domain.comOpenAI 认证方式
Authorization: Bearer sk-xxxAnthropic 认证方式
x-api-key: sk-xxx快速入门
4 步开始使用 Zivv API。
注册并充值
注册 Zivv 账号，先小额充值，用真实任务测试模型和费用。
创建 API Key 并选择分组
进入「API Key 管理」页面创建 sk- 开头的 Key。用 Claude Code 请选择「Claude MAX」分组，其他场景按需要的模型选择分组。
配置 Base URL
Claude Code 与 Anthropic SDK 使用主域名（不加 /v1）；OpenAI SDK、Codex、Cursor 等 OpenAI 兼容工具使用 /v1 地址。
开始调用
沿用现有代码，只替换 Base URL 和 API Key。调用后可在控制台用量页面查看每次请求的记录与扣费。
| Anthropic 协议（Claude Code） | https://your-domain.com |
| OpenAI 兼容协议 | https://your-domain.com/v1 |
Claude Code 接入
Claude Code 是我们的主打场景。创建 Claude MAX 分组的 Key 后，按你的系统任选一种方式配置。
export ANTHROPIC_BASE_URL=https://your-domain.com
export ANTHROPIC_AUTH_TOKEN=sk-your-key
claude接入要点
- check_circleANTHROPIC_BASE_URL 只写主域名，不要加 /v1。
- check_circleKey 填在 ANTHROPIC_AUTH_TOKEN 中，修改后重新打开终端再启动 claude。
- check_circle之前登录过官方账号的，如出现认证冲突提示，先在 Claude Code 中执行 /logout。
- check_circle在 Claude Code 中执行 /status，确认 API 地址已指向 Zivv。
- check_circle控制台「API Key 管理」页面支持一键导入 CC Switch，免手动配置。
分组说明
每个 Key 创建时选择一个分组，分组决定可用模型、计费倍率和上游线路。
Claude MAX 分组
专为 Claude Code 打造：独家自研号池 + 官方 Claude Max 订阅账号，直连 Anthropic 官方，无速率限制。
info仅支持原生 Anthropic 协议（/v1/messages），请在 Claude Code 或 Anthropic SDK 中使用。
其他分组
覆盖 GPT、Gemini 等模型，按模型与倍率划分，适合 OpenAI 兼容工具、SDK 与桌面客户端。
info每个分组包含哪些模型、倍率多少，以模型广场为准。
前往模型广场arrow_forward计费说明
按量计费，用多少扣多少。
计费公式
费用 = Token 用量 × 模型官方单价 × 分组倍率。输入与输出分别计算，流式与非流式一致。
¥1 = $1 结算
余额按人民币 1:1 折算美元价格，充值即用，无需按实时汇率换汇。
无月费
没有月费、最低消费和隐藏费用，余额不过期。
明细可查
控制台用量页面可按 Key、模型、时间查看每次请求的 Token 与扣费。
错误排查
按状态码定位问题，大部分接入问题都能在这里解决。
| 状态码 | 含义 | 处理方法 |
|---|---|---|
| 401 | Key 无效 | 检查 Key 是否复制完整、有无多余空格、是否已被删除。不要把登录密码当作 API Key。 |
| 402 | 余额不足 | 到控制台充值，并检查 Key 本身是否设置了额度上限。团队 Key 扣的是团队所有者的余额。 |
| 403 | 无权调用 | Key 所在分组不包含该模型，或协议不匹配（如在 OpenAI 兼容客户端里使用 Claude MAX 分组）。换用匹配的分组或客户端。 |
| 404 | 地址或模型不对 | OpenAI 兼容工具需要 /v1，Claude Code 不加 /v1。模型名请从模型广场复制。 |
| 429 | 请求暂时受限 | 降低并发后稍后重试；持续出现请查看状态页或联系支持。 |
| 5xx | 上游繁忙或异常 | 通常短时间内自动恢复，稍后重试即可。持续出现请查看状态页。 |
常见问题
需要每个模型单独创建 Key 吗？expand_more
不需要。同一个 Key 可以调用所在分组内的所有模型。如果要同时用 Claude Code 和 GPT 类工具，建议分别创建 Key，方便区分用量。
为什么网页能登录，工具却提示 401？expand_more
网页登录和 API Key 是两套凭证。工具中要填写「API Key 管理」页面创建的 sk- Key，而不是账号密码。
Claude Code 里能切换模型吗？expand_more
可以。在 Claude Code 中使用 /model 切换 Opus / Sonnet / Haiku，扣费按实际使用的模型计算。
怎么确认请求真的走了 Zivv？expand_more
调用后到控制台用量页面查看，能看到对应时间、模型和扣费记录即说明已接入成功。
Key 泄露了怎么办？expand_more
立即在「API Key 管理」页面删除该 Key 并新建一个。不要把 Key 写进公开仓库、截图或前端代码。
团队可以共用余额吗？expand_more
可以。创建团队后为成员分发 Key，所有消费从团队所有者余额扣除，并可设置团队与成员预算。
API 参考
端点、代码示例、客户端配置与请求参数。
API 端点
Zivv API 同时支持 OpenAI、Anthropic 和 Gemini 协议格式。
| 方法 | 端点 | 说明 |
|---|---|---|
| POST | /v1/chat/completions | Chat Completions（OpenAI 格式，支持流式输出） |
| POST | /v1/messages | Messages（Anthropic 格式，支持流式输出） |
| POST | /v1/responses | Responses（OpenAI Responses API，Codex CLI 使用） |
| POST | /v1/images/generations | 图片生成（支持流式 SSE 输出） |
| POST | /v1/gemini/{model}:{method} | Gemini 原生协议透传（generateContent / streamGenerateContent） |
| GET | /v1/models | 获取可用模型列表 |
代码示例
直接替换 Base URL 即可使用，无需修改其他代码。
curl https://your-domain.com/v1/chat/completions \
-H "Authorization: Bearer sk-your-key" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-sonnet-5",
"messages": [{"role": "user", "content": "Hello!"}]
}'客户端配置指南
主流 AI 工具和 SDK 的配置方法。Claude Code 见上方「Claude Code 接入」。
将以下内容写入 ~/.codex/config.toml，并把 Key 设置到 ZIVV_API_KEY 环境变量。控制台「API Key 管理」页面可一键生成完整脚本。
model_provider = "zivv"
model = "gpt-5.5"
[model_providers.zivv]
name = "zivv"
base_url = "https://your-domain.com/v1"
env_key = "ZIVV_API_KEY"
wire_api = "responses"请求参数
按协议分类的支持参数。选择协议查看对应参数。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| model | string | 是 | 模型 ID，如 claude-sonnet-5 |
| messages | array | 是 | 消息对象数组，包含 role 和 content |
| stream | boolean | 否 | 是否开启流式输出，默认 false |
| temperature | number | 否 | 采样温度，0-2 |
| top_p | number | 否 | 核采样参数 |
| max_tokens | number | 否 | 最大输出 token 数 |
| max_completion_tokens | number | 否 | max_tokens 的替代写法，效果相同 |
| tools | array | 否 | 函数工具定义，用于 tool use |
| tool_choice | string|object | 否 | 工具选择策略：auto / required / none / 指定工具 |
图片生成
使用 Images API 调用 gpt-image-2 生成图片，支持流式 SSE 输出。
代码示例
curl https://your-domain.com/v1/images/generations \
-H "Authorization: Bearer sk-your-key" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2",
"prompt": "A cute cat wearing sunglasses on a beach",
"stream": true,
"size": "1024x1024",
"quality": "high"
}'SSE 流式响应格式
开启 stream 后，服务端通过 SSE 分块返回生成进度和最终图片（base64）。
event: progress
data: {"type":"progress","progress":25}
event: progress
data: {"type":"progress","progress":50}
event: progress
data: {"type":"progress","progress":75}
event: result
data: {"type":"result","index":0,"b64_json":"iVBORw0KGgo..."}
event: done
data: [DONE]Responses API
OpenAI Responses API（/v1/responses）是 gpt-5.5 等新模型的原生接口，支持视觉理解和图片生成。
视觉理解 & 图片生成
Responses API 同时支持图片输入（视觉理解）和图片生成（通过 image_generation 工具）。
# Vision: send image to gpt-5.5
curl https://your-domain.com/v1/responses \
-H "Authorization: Bearer sk-your-key" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.5",
"input": [
{
"role": "user",
"content": [
{ "type": "input_text", "text": "What is in this image?" },
{ "type": "input_image", "image_url": "https://example.com/photo.jpg" }
]
}
]
}'
# Image generation via Responses API
curl https://your-domain.com/v1/responses \
-H "Authorization: Bearer sk-your-key" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.5",
"input": "Generate an image of a sunset over mountains",
"tools": [{ "type": "image_generation" }]
}'chat/completions vs responses 对比
| chat/completions | responses | |
|---|---|---|
| 请求字段 | messages | input |
| 图片类型 | image_url | input_image |
| 图片 URL 格式 | {url: "..."} | "..." |
| 图片生成 | ❌ | image_generation tool |
| 响应结构 | choices[].message | output[] |
| 多轮对话 | ❌ | previous_response_id |
仍然没解决？
带上时间、使用的工具、模型名称和错误信息联系我们（不要发送完整 Key）。
准备好了吗？
创建账号，几秒钟即可获取 API Key。