端点与协议

这是全站最重要的一页。 绝大多数「填了地址却报错」的问题，都出在协议选错或 /v1 多加/少加。

ZiAI 提供的端点

ZiAI 是大模型 API 网关，同一域名下对外提供多种协议端点：

协议 / 用途	路径	完整地址	谁在用
OpenAI Chat Completions	/v1/chat/completions	https://api.ziai.lol/v1/chat/completions	ChatBox、CherryStudio、WorkBuddy、ZCode（OpenAI）
OpenAI Responses	/v1/responses	https://api.ziai.lol/v1/responses	Codex
Anthropic Messages	/v1/messages	https://api.ziai.lol/v1/messages	Claude Code、CherryStudio（Anthropic）、ZCode（Anthropic）
OpenAI Embeddings	/v1/embeddings	https://api.ziai.lol/v1/embeddings	向量检索 / RAG 类应用
模型列表	/v1/models	https://api.ziai.lol/v1/models	核对可用模型 ID

模型列表由部署决定

端点是固定的，但每个端点上有哪些模型可用，取决于站长配置了哪些渠道。 所以任何文档（包括本站）给出的模型 ID 都可能与你实际能用的不同 —— 请用下面的方法实时查询。

/v1 到底加不加？

不同客户端对「地址栏」的定义不一样：有的要你填基础地址（它自己拼路径），有的要你填到 /v1，还有的要填完整端点。照下表填即可：

客户端	字段名	应该填	说明
ChatBox	API 主机	https://api.ziai.lol	不带 /v1；「API 路径」留空用默认值
CherryStudio	API 地址	https://api.ziai.lol/v1	自定义服务商选 OpenAI 兼容，填到 /v1 层级
WorkBuddy	URL	https://api.ziai.lol/v1	带 /v1；非标准前缀需开「自定义协议」
ZCode	OpenAI 接口地址	https://api.ziai.lol/v1	带 /v1
ZCode	Anthropic 接口地址	https://api.ziai.lol	不带 /v1
Codex	base_url	https://api.ziai.lol/v1	带 /v1
Claude Code	ANTHROPIC_BASE_URL	https://api.ziai.lol	不带 /v1，客户端自行拼 /v1/messages
CC-Switch	Base URL	按所选应用而定	Claude 填不带 /v1 的根地址，Codex 填带 /v1 的地址

两种 404，成因相反

• 多加了 /v1 → 实际请求变成 /v1/v1/chat/completions → 404。常见于给 Claude Code 填了带 /v1 的地址，或在 ChatBox 里把「API 主机」和「API 路径」都填全。
• 少加了 /v1 → 实际请求变成 /chat/completions → 404。常见于 Codex / WorkBuddy / ZCode 只填了根域名。

两种都报 404，但修法相反。用下面的 curl 命令可以直接区分：能通的那个地址就是正确形态。

会自动拼路径的客户端（如 ChatBox 的默认 API 路径）反而要填不带 /v1 的根地址 —— 这类客户端会自己补上版本路径。具体以各客户端页面的说明与「检测 / 检查」按钮结果为准。

逐个协议验证

三条命令分别验证三种协议。建议全部跑一遍 —— 这样你能立刻知道 ZiAI 对你的密钥开放了哪些能力，之后配客户端不会踩空。

1. OpenAI Chat Completions

curl https://api.ziai.lol/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{"model":"模型ID","messages":[{"role":"user","content":"你好"}]}'

成功返回中含 choices[0].message.content。

2. OpenAI Responses（Codex 专用）

curl https://api.ziai.lol/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{"model":"模型ID","input":"你好"}'

成功返回中含 output 数组与 status: "completed"。

这条命令不通怎么办

/v1/responses 是否可用，取决于 ZiAI 上游渠道是否支持 Responses 协议。 若返回 404 或「模型不支持」，Codex 仍可通过 CC-Switch 的本地协议转换接入 —— 见 CC-Switch：上游格式怎么选。

3. Anthropic Messages（Claude Code 专用）

curl https://api.ziai.lol/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model":"模型ID","max_tokens":1024,"messages":[{"role":"user","content":"你好"}]}'

x-api-key 与 Authorization: Bearer 两种鉴权头 ZiAI 都接受：

鉴权头	谁会发出	说明
x-api-key: sk-...	Anthropic 官方 SDK 默认；Claude Code 设置 ANTHROPIC_API_KEY 时	Anthropic 原生格式
Authorization: Bearer sk-...	Claude Code 设置 ANTHROPIC_AUTH_TOKEN 时	网关/中转站普遍认这个，推荐

Claude Code 必须用 AUTH_TOKEN

Claude Code 的 ANTHROPIC_API_KEY 与 ANTHROPIC_AUTH_TOKEN 发出的请求头完全不同。 接中转站请用 ANTHROPIC_AUTH_TOKEN（发 Authorization: Bearer）； 只设 ANTHROPIC_API_KEY 时可能得到 401，且报错信息不会告诉你原因。 主流网关与配置工具普遍采用的也是 ANTHROPIC_AUTH_TOKEN。

查询可用模型

1. 命令行查询（最准确）

   curl -s https://api.ziai.lol/v1/models \
     -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

   装了 jq 的话，只列出模型 ID：

   curl -s https://api.ziai.lol/v1/models \
     -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
     | jq -r '.data[].id'

   Windows PowerShell：

   (Invoke-RestMethod -Uri "https://api.ziai.lol/v1/models" `
     -Headers @{ Authorization = "Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" }).data.id

2. 控制台查询

   • 操练场 https://api.ziai.lol/console/playground：左侧模型下拉框即为当前密钥可用模型，还能直接对话测试；
   • 模型广场 / 定价：查看每个模型的计价与状态（入口名称随版本不同）。

3. 复制模型 ID 时逐字核对

   模型 ID 的大小写、短横线、日期后缀都必须完全一致。 gpt-5.2 与 GPT-5.2、claude-sonnet-4-5 与 claude-sonnet-4.5 是不同的 ID。 建议直接从操练场或 /v1/models 复制粘贴，不要手打。

模型 ID 会被站长映射

ZiAI 支持模型重定向（例如把 gpt-4o 映射到实际上游的另一个模型）。 因此你在客户端里填的 ID 可能与实际上游模型名不同 —— 以 ZiAI 控制台展示的 ID 为准，不要凭印象填官方名称。

流式输出

所有聊天端点都支持 SSE 流式（请求体加 "stream": true）。若客户端出现「长时间无输出，最后一次性全部出现」，通常是中间层缓冲了 SSE，用下面命令可确认：

curl -N https://api.ziai.lol/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{"model":"模型ID","stream":true,"messages":[{"role":"user","content":"数到10"}]}'

-N 关闭 curl 缓冲。若这里能逐行输出 data: 事件，说明 ZiAI 侧流式正常，问题在客户端或本地代理。

下一步

• 配置速查表 —— 按客户端查字段
• 常见报错速查 —— 按报错码定位
• 协议不匹配详解 —— 三种协议的完整对照