API 参考与接入指南
一把 ck_ API Key 通用于 Claude Code、OpenCode、Codex CLI、Gemini CLI、Cursor 与原生 HTTP。官方厂商目录价合并出账——按量付费,无需订阅。
1. 快速开始
Zenn.Engineering 是面向 Anthropic、OpenAI、Google AI 模型及图像生成的即插即用 API 网关。一把以 ck_ 开头的 Key 通用全部场景——无需修改代码,只需将工具指向我们的 baseURL。
在 /pricing 选择套餐,然后到 /manage-api-keys 创建 Key。
将工具指向 https://zenn.engineering/api/v1。
可与 Claude Code、OpenCode、Codex CLI、Gemini CLI、Cursor 以及任意 OpenAI/Anthropic 兼容客户端协同使用。
2. Base URL
一把 Key,三种协议兼容的 baseURL(Anthropic / OpenAI / Gemini),外加一个图像生成接口。
| 接入面 | Base URL | 适配工具 |
|---|---|---|
| Anthropic 兼容 | https://zenn.engineering/api/v1 | Claude Code、Anthropic SDK、OpenCode(anthropic provider) |
| OpenAI 兼容(Codex) | https://zenn.engineering/api/v1/codex | Codex CLI、OpenAI SDK、Cursor |
| Gemini 兼容 | https://zenn.engineering/api/v1/gemini | Gemini CLI、Google AI SDK |
| 图像生成 | https://zenn.engineering/api/v1/images/generations | gpt-image-2(OpenAI 兼容请求体) |
3. Claude Code
Anthropic 官方 Claude CLI。设置两个环境变量即可作为即插即用替代方案使用。
步骤 1 — 设置环境变量
添加到您的 shell 配置文件(~/.zshrc 或 ~/.bashrc):
export ANTHROPIC_BASE_URL=https://zenn.engineering/api/v1 export ANTHROPIC_API_KEY=ck_YOUR_API_KEY
步骤 2 — 重启并运行
# Default model (Sonnet 4.6) claude # Pick a different model claude --model claude-opus-4-7 claude --model claude-haiku-4-5
工作原理
Claude Code 通过 x-api-key 头部传递 API Key(Anthropic SDK 原生方式),并在 baseURL 后追加 /messages。anthropic-version 与 anthropic-beta 头部均会透传至上游。支持基于 SSE 的流式输出。
4. OpenCode
多厂商 AI 编码 Agent。一份 JSON 配置即可通过单一 Key 调用 Claude、GPT-5 与 Gemini。
步骤 1 — 安装
npm i -g opencode-ai
步骤 2 — 创建配置
编辑 ~/.config/opencode/opencode.json:
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"anthropic": {
"options": {
"baseURL": "https://zenn.engineering/api/v1",
"apiKey": "ck_YOUR_API_KEY"
},
"models": {
"claude-opus-4-7": { "name": "Claude Opus 4.7" },
"claude-sonnet-4-6": { "name": "Claude Sonnet 4.6" },
"claude-haiku-4-5": { "name": "Claude Haiku 4.5" }
}
},
"zenn-codex": {
"npm": "@ai-sdk/openai-compatible",
"name": "Zenn Codex",
"options": {
"baseURL": "https://zenn.engineering/api/v1/codex",
"apiKey": "ck_YOUR_API_KEY"
},
"models": {
"gpt-5.5": { "name": "GPT-5.5" },
"gpt-5.5-pro": { "name": "GPT-5.5 Pro" },
"gpt-5.5-instant": { "name": "GPT-5.5 Instant" },
"gpt-5.4": { "name": "GPT-5.4" },
"gpt-5.3-codex": { "name": "GPT-5.3 Codex" }
}
},
"zenn-gemini": {
"npm": "@ai-sdk/openai-compatible",
"name": "Zenn Gemini",
"options": {
"baseURL": "https://zenn.engineering/api/v1/gemini",
"apiKey": "ck_YOUR_API_KEY"
},
"models": {
"gemini-3.1-pro-preview": { "name": "Gemini 3.1 Pro" },
"gemini-3-pro-preview": { "name": "Gemini 3 Pro" },
"gemini-3-flash-preview": { "name": "Gemini 3 Flash" }
}
},
"zenn-chinese": {
"npm": "@ai-sdk/openai-compatible",
"name": "Zenn Chinese (DeepSeek / Moonshot / Zhipu)",
"options": {
"baseURL": "https://zenn.engineering/api/v1/codex",
"apiKey": "ck_YOUR_API_KEY"
},
"models": {
"deepseek-v4-pro": { "name": "DeepSeek V4 Pro" },
"deepseek-v4-flash": { "name": "DeepSeek V4 Flash" },
"kimi-k2.6": { "name": "Kimi K2.6" },
"glm-5.1": { "name": "GLM-5.1" }
}
}
}
}步骤 3 — 运行
opencode
5. Codex CLI
OpenAI 官方面向 GPT-5 / Codex 系列的 CLI。设置两个环境变量并指向我们的 Codex baseURL 即可。
设置环境变量
export OPENAI_BASE_URL=https://zenn.engineering/api/v1/codex export OPENAI_API_KEY=ck_YOUR_API_KEY
运行
# Default codex # Pick a model codex --model gpt-5.5 codex --model gpt-5.5-pro codex --model gpt-5.5-instant codex --model gpt-5.3-codex # Chinese coding models (via OpenAI-compatible /v1/codex) codex --model deepseek-v4-pro codex --model kimi-k2.6 codex --model glm-5.1
Codex CLI 使用 Authorization: Bearer,以及 OpenAI 的 /chat/completions + /responses 形态——两者均受支持。
6. Gemini CLI
Google Gemini CLI 通过 x-goog-api-key 传递 Key。代理透明地接受该头部。
设置环境变量
export GEMINI_BASE_URL=https://zenn.engineering/api/v1/gemini export GEMINI_API_KEY=ck_YOUR_API_KEY
运行
gemini --model gemini-3.1-pro-preview gemini --model gemini-3-flash-preview
7. Cursor IDE
在 Cursor → Settings → Models → "Custom OpenAI Model" 中:
| 字段 | 取值 |
|---|---|
| Override OpenAI Base URL | https://zenn.engineering/api/v1/codex |
| OpenAI API Key | ck_YOUR_API_KEY |
| Add custom models | gpt-5.5, gpt-5.5-pro, gpt-5.5-instant, gpt-5.4, gpt-5.3-codex, deepseek-v4-pro, kimi-k2.6, glm-5.1 |
保存后点击 Verify——Cursor 会请求 baseURL 上的 /models 以确认 Key 可用。
8. 直接调用 API(cURL)
三种协议形态,一把 Key。选择您客户端已支持的形态即可。
Anthropic 兼容 — /v1/messages
curl -X POST https://zenn.engineering/api/v1/messages \
-H "x-api-key: ck_YOUR_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-sonnet-4-6",
"max_tokens": 1024,
"messages": [{"role": "user", "content": "Hello, Claude"}]
}'OpenAI 兼容 — /v1/codex/chat/completions
curl -X POST https://zenn.engineering/api/v1/codex/chat/completions \
-H "Authorization: Bearer ck_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.5",
"messages": [{"role": "user", "content": "Hello, GPT-5.5"}],
"stream": true
}'Gemini — /v1/gemini/chat/completions
curl -X POST https://zenn.engineering/api/v1/gemini/chat/completions \
-H "Authorization: Bearer ck_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-3.1-pro-preview",
"messages": [{"role": "user", "content": "Hello, Gemini"}]
}'9. 图像生成
gpt-image-2 是当前唯一可通过 API 调用的图像模型。分辨率档位(1K / 2K / 4K)按统一固定价格计费——详见模型列表。其他图像、视频、音频模型暂列为即将上线。
接口地址
POST https://zenn.engineering/api/v1/images/generations GET https://zenn.engineering/api/v1/images/generations (list models)
生成图像
curl -X POST https://zenn.engineering/api/v1/images/generations \
-H "Authorization: Bearer ck_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2",
"prompt": "A cinematic photo of a small red apple on a marble countertop",
"n": 1
}'异步行为
DocsPage.imageGen.asyncBody
在浏览器对话中使用
打开 /chat,在模型选择器中挑选 "GPT Image 2 — Image Generation",发送提示词,图像即在页面内呈现。服务端会代为轮询上游,每张图像计费 6 额度($0.06)。
10. 模型与定价
按额度计费(1,000,000 额度 = $1.00)。LLM 价格采用每百万 tokens 的官方厂商目录价;图像按次计费。标记为 即将上线 的模型已列出但 API 在启用前会拒绝调用。所有模型均按官方目录价计费——增值来自充值时的额度倍率(Pro 1×、Max 4×、Enterprise 6×)。详见第 12 节套餐说明。
Claude(Anthropic)
| 模型 ID | 输入 / MTok | 输出 / MTok | 缓存读取 | 状态 |
|---|---|---|---|---|
| claude-opus-4-7 | $15.00 | $75.00 | $1.50 | 已上线 |
| claude-opus-4-6 | $15.00 | $75.00 | $1.50 | 已上线 |
| claude-sonnet-4-6 | $3.00 | $15.00 | $0.30 | 已上线 |
| claude-haiku-4-5 | $1.00 | $5.00 | $0.10 | 已上线 |
OpenAI / GPT
| 模型 ID | 输入 / MTok | 输出 / MTok | 缓存读取 | 状态 |
|---|---|---|---|---|
| gpt-5.5 | $5.00 | $30.00 | $0.50 | 已上线 |
| gpt-5.5-instant | $5.00 | $30.00 | $0.50 | 已上线 |
| gpt-5.5-pro | $30.00 | $180.00 | $30.00 | 已上线 |
| gpt-5.4 | $5.00 | $22.50 | $0.50 | 已上线 |
| gpt-5.3-codex | $1.75 | $14.00 | $0.17 | 已上线 |
| gpt-5.2 | $1.75 | $14.00 | $0.17 | 已上线 |
Gemini(Google)
| 模型 ID | 输入 / MTok | 输出 / MTok | 缓存读取 | 状态 |
|---|---|---|---|---|
| gemini-3.1-pro-preview | $4.00 | $18.00 | $0.40 | 已上线 |
| gemini-3-pro-preview | $4.00 | $18.00 | $0.40 | 已上线 |
| gemini-3-flash-preview | $0.50 | $3.00 | $0.05 | 已上线 |
DeepSeek / Moonshot / Zhipu
| 模型 ID | 输入 / MTok | 输出 / MTok | 缓存读取 | 状态 |
|---|---|---|---|---|
| deepseek-v4-pro | $1.74 | $3.48 | $0.01 | 已上线 |
| deepseek-v4-flash | $0.14 | $0.28 | $0.0028 | 已上线 |
| kimi-k2.6 | $0.95 | $4.00 | $0.16 | 已上线 |
| glm-5.1 | $1.40 | $4.40 | $0.26 | 已上线 |
图像(已上线)
| 模型 ID | 额度 / 图 | 价格 / 图 | 状态 |
|---|---|---|---|
| gpt-image-2 | 60000 | $0.06 | 已上线 |
全部图像、视频与音频模型按官方目录价扣费。其他图像模型(Nano Banana 系列、Gemini 3 Pro Image、Seedream)已列入目录但当前为即将上线——API 在启用前会拒绝调用。完整目录见 /models。
11. 鉴权
全部 API Key 均以 ck_ 为前缀。代理兼容所有标准 SDK 头部格式,客户端无需任何改动即可使用。
| 头部 | 格式 | 使用方 |
|---|---|---|
| x-api-key | ck_... | Claude Code、Anthropic SDK |
| Authorization | Bearer ck_... | OpenCode、Codex CLI、OpenAI SDK、cURL |
| anthropic-api-key | ck_... | 备用 Anthropic 头部 |
| x-goog-api-key | ck_... | Gemini CLI |
透传头部
anthropic-version(默认 2023-06-01)与 anthropic-beta 均会透传。完整支持 SSE 流式输出。
12. 套餐
一次性充值——无需订阅。每次充值锁定一个额度倍率(Pro 1×、Max 4×、Enterprise 6×)——这部分额度直到用完为止保留该倍率价值。后续充值可以选择任意档位。
标准定价。按量付费。
- · 全部前沿 LLM,均按官方目录价
- · 兼容 OpenAI / Anthropic / Gemini 协议的 API
- · 分 Key 消费上限,实时分析
4× 额度——$100 即可购得 $400 目录价用量。
- · 包含 Pro 全部权益
- · 充值时每美元享 4× 额度
- · 全部模型同价,均为目录价
- · 优先队列 + 更快路由
6× 额度——$1,000 即可购得 $6,000 用量 + Anthropic Max 优先通道。
- · 包含 Max 全部权益
- · 充值时每美元享 6× 额度
- · 全部模型同价,均为目录价
- · Anthropic Max 优先通道
- · 专属支持,审计友好的发票
一套定价规则,通用全部模型
- · 全部 LLM、图像、视频、音频模型均按 /models 上的官方目录价扣费。
- · Max($100 → 4×)与 Enterprise($1,000 → 6×)的价值来自充值时额外发放的额度,而非分模型的折扣层级。
- · 没有分组准入,没有分模型小字——您的额度在 Claude Opus、GPT-5.5 与 Gemini Flash 上一视同仁。
倍率按充值次数计算。已有的 Max 额度在用尽前继续保留 4× 价值——之后充值 Pro,$10 仍按 1× 发放 20M 额度。完整说明见 /pricing。
13. 限流与错误码
用户级限流
| 接口 | 请求 / 小时 |
|---|---|
| /v1/messages, /v1/chat/completions, /v1/gemini | 1,000 |
| /v1/images/generations | 500 |
| /v1/responses, /v1/codex/* | 1,000 |
限流状态会通过响应头返回:x-ratelimit-limit、x-ratelimit-remaining、x-ratelimit-reset。
错误码
| 状态码 | 含义 |
|---|---|
| 401 | 缺失 / 无效的 API Key |
| 402 | 额度不足——请前往 /checkout 充值 |
| 403 | 当前等级未解锁该模型(例如 Opus 4.7) |
| 429 | 触发用户级限流 |
| 503 | 模型已展示但暂为即将上线 |
| 504 | 图像生成超时(请重试) |
14. 即将上线
已公开列出,但 API 在信用倍率模式下的利润率稳定之前会拒绝调用:
Nano Banana 系列、Gemini 3 Pro Image、Seedream、GPT-4o Image、Imagen。
Veo 3.1、Kling 3.0、Seedance 2.0、HappyHorse 1.0、MiniMax Hailuo、Vidu Q3、WAN 2.6。
Fish Audio TTS、Voice Clone、ASR。
完整列表见 /models。即将上线的条目通过 API 调用会返回 HTTP 503;当前调用为空操作,不会扣除额度。
准备好开始了吗?
一把 Key 通用 Claude Code、OpenCode、Codex CLI、Gemini CLI 与 Cursor。充值额度并创建您的 API Key。
