协议与兼容性

Zivv 在同一服务地址上提供 OpenAI、Anthropic 和 Gemini 三种协议。Key 可以共用，但 Base URL、认证头和请求体格式不同。

总览

协议	Base URL	认证方式	主要端点	典型用途
OpenAI	https://zivv.pro/v1	Authorization: Bearer sk-...	/chat/completions、/responses、/images/*、/models	Codex、OpenAI SDK、支持自定义 OpenAI Base URL 的第三方客户端
Anthropic	https://zivv.pro	x-api-key: sk-...	/v1/messages、/v1/messages/count_tokens	Claude Code、Anthropic SDK
Gemini	https://zivv.pro/v1beta	x-goog-api-key: sk-...	/models/{model}:generateContent、:streamGenerateContent	Google Gen AI SDK、Gemini 原生客户端

OpenAI 协议

Chat Completions

适合大多数 OpenAI 兼容客户端和已有 SDK 项目：

POST https://zivv.pro/v1/chat/completions

Responses API

适合 Codex 和需要 input、多轮 response、视觉输入或工具调用的应用：

POST https://zivv.pro/v1/responses

Codex 使用 Responses API

Codex 自定义 Provider 应设置 wire_api = "responses"，Base URL 为 https://zivv.pro/v1。Cursor 与 Devin Desktop（原 Windsurf）的官方客户端能力会随版本变化，且当前官方文档未承诺任意自定义 Base URL 的稳定入口；请分别阅读 Cursor 兼容性说明 与 Devin Desktop 兼容性说明。

Images API

支持图片生成和图片编辑：

POST https://zivv.pro/v1/images/generations
POST https://zivv.pro/v1/images/edits

Anthropic 协议

Claude Code 和 Anthropic SDK 使用 Messages API：

POST https://zivv.pro/v1/messages
POST https://zivv.pro/v1/messages/count_tokens

请求通常需要：

x-api-key: sk-你的Key
anthropic-version: 2023-06-01
content-type: application/json

Gemini 协议

Gemini 原生端点把模型名放在 URL 中：

POST https://zivv.pro/v1beta/models/{model}:generateContent
POST https://zivv.pro/v1beta/models/{model}:streamGenerateContent?alt=sse

认证可使用：

x-goog-api-key: sk-你的Key

Base URL 常见误区

配置值	是否正确	说明
OpenAI：https://zivv.pro/v1	✓	SDK 会在后面拼接端点
OpenAI：https://zivv.pro	视客户端而定	若客户端自动添加 /v1 才可用
Anthropic：https://zivv.pro	✓	SDK 会请求 /v1/messages
Anthropic：https://zivv.pro/v1	通常不正确	可能拼成重复 /v1/v1/messages
Gemini：https://zivv.pro/v1beta	✓	模型路径追加在后面

功能兼容性

功能	OpenAI	Anthropic	Gemini
流式输出	✓	✓	✓
Tool / Function Calling	✓	✓	依模型和请求格式
视觉输入	Responses / Chat	Messages 内容块	原生 parts
图片生成	Images / Responses 工具	—	原生 response modalities
Token 预估	由客户端或模型响应统计	/messages/count_tokens	由响应 usage 统计
Codex CLI	推荐	—	—
Claude Code	—	推荐	—

具体字段和请求示例见 API 端点。

请求结构自动修正

Anthropic Messages 协议对请求结构校验严格，客户端历史管理稍有偏差就会整个请求被拒。 Zivv API 在转发前会检测并就地修正这类问题，所以同一份请求直连上游可能失败、经 Zivv 能成功。

完整清单（含哪些修正会改变语义）见 请求兼容性修正。