接入概览
CZL AI 是兼容 OpenAI 协议的多模型 API 网关:一个 API Key 即可调用 GPT、Claude、Gemini 等模型,同时提供 Claude Messages 与 Gemini 原生接口,现有 SDK 与工具只需改 Base URL 和 Key。
准备工作
- 登录后在「控制台 → Key」创建 API Key(形如
sk-...),Key 只在服务端或本机使用,不要写进前端代码或提交到代码仓库
- 在「价格」页确认要用的模型名称与价格,请求里的
model 与价格页一致
- 账户余额或套餐额度不足时请求返回 402,充值或购买套餐后即可继续
Base URL
| 协议 |
Base URL |
说明 |
| OpenAI 兼容 |
https://ai.czl.net/v1 |
OpenAI SDK、Codex、OpenCode 等,base_url 带 /v1 |
| Claude Messages |
https://ai.czl.net |
Anthropic SDK、Claude Code,填根地址,SDK 自己拼 /v1/messages |
| Gemini 原生 |
https://ai.czl.net |
Google GenAI SDK、Gemini CLI,路径为 /v1beta/models/{model}:generateContent |
鉴权
所有接口用 API Key 鉴权,以下三种写法任选其一:
| 写法 |
适用 |
Authorization: Bearer sk-your-api-key |
OpenAI 兼容接口(推荐,所有接口通用) |
x-api-key: sk-your-api-key |
Claude Messages(Anthropic SDK 默认写法) |
x-goog-api-key: sk-your-api-key 或 ?key=sk-your-api-key |
Gemini 原生接口 |
第一个请求
curl "https://ai.czl.net/v1/chat/completions" \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o-mini",
"messages": [{ "role": "user", "content": "你好" }]
}'
用 OpenAI 官方 SDK 时只改 base_url 与 api_key:
from openai import OpenAI
client = OpenAI(base_url="https://ai.czl.net/v1", api_key="sk-your-api-key")
resp = client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)
模型列表
GET https://ai.czl.net/v1/models 返回当前 Key 可用的模型,格式与 OpenAI 一致。
流式输出
请求体带 "stream": true 时以 SSE(text/event-stream)逐段返回,格式与各协议官方一致:Chat Completions 以 data: [DONE] 结束,Responses 与 Claude Messages 按事件类型推送。客户端按官方 SDK 的流式接口读取即可;自己解析时要按行处理,忽略空行与以 : 开头的注释行。
请求追踪
每个响应都带响应头 x-czlai-request-id,错误信息的 message 末尾也会附带 (request id: ...)。反馈问题时请提供这个 ID、请求时间与脱敏后的请求体。
错误响应
错误响应 Content-Type: application/json,格式遵循 OpenAI 错误协议:
{
"error": {
"code": "model_not_found",
"message": "The model 'gpt-6' does not exist or you do not have access to it. (request id: 20260825103012486311207xKqBd2Nc)",
"type": "czlai_error"
}
}
type = czlai_error:错误由网关判定,message 是英文完整句,可直接展示或据此修正请求
type = system_error:模型侧失败,message 为统一提示、code 不保证稳定,排障以 HTTP 状态码与 x-czlai-request-id 为准
- 少数模型在生成失败时仍返回 200、body 却是 error JSON,网关原样透传,所以稳妥做法是同时检查 body 里有没有
error 字段
常见错误码
| HTTP |
error.code |
含义 |
| 400 |
czlai_error / invalid_request 等 |
请求体解析失败或参数非法,message 为具体原因,原样重试不会成功 |
| 401 |
— |
API Key 无效、已过期或已停用 |
| 402 |
insufficient_user_quota |
余额或套餐额度不足 |
| 402 |
insufficient_organization_quota |
组织 Key:组织余额不足,需组织管理员充值或转入 |
| 402 |
organization_member_limit_exceeded |
组织 Key:你本月在该组织的可用额度已用完 |
| 403 |
organization_access_denied |
组织 Key:你已不是该组织成员,或是只读成员 |
| 403 |
organization_inactive |
组织 Key:组织已停用或已解散 |
| 403 |
organization_key_disabled |
组织 Key:这把 Key 已被组织管理员停用组织付费 |
| 403 |
— |
当前账号等级无权访问 |
| 404 |
model_not_found |
模型不存在,或当前账号无权访问 |
| 400 |
context_length_exceeded |
输入超过模型上下文长度,需要截断或压缩上下文 |
| 429 |
— |
触发速率限制 |
| 503 |
model_unavailable |
模型当前不可用,稍后重试可能成功 |
| 503 |
endpoint_not_supported |
该模型不支持这个接口 |
| 504 |
gateway_timeout |
网关未能在重试预算内完成请求 |
| 其余 4xx / 5xx |
不固定 |
模型侧失败,状态码为原始状态码 |
401 / 403 / 429 由鉴权与限流层返回,响应体不带 code 字段。
重试建议
| 状态码 |
建议 |
| 400 / 404 |
请求本身的问题,先修正请求,重试不会改变结果 |
| 401 / 402 / 403 |
分别对应换 Key、充值、联系客服,不要重试 |
| 429 |
指数退避后重试 |
| 503 / 5xx / 504 |
可以退避重试,见下方超时提醒 |
超时类错误(524 / 504 / 408)只说明客户端没有拿到响应,请求本身可能已经被完整处理并计费。对图像生成这类高成本请求,重试前先评估重复执行的代价。
计费
按模型价格与实际用量(token、张数、秒数等)在请求结束后一次性结算,价格见「价格」页。有可用套餐时优先扣套餐额度,不足时扣余额;余额低于 $0.05 且没有可用套餐时新请求返回 402。
Markdown 原文