مرجع API و راهاندازی
یک کلید API ck_ در Claude Code، OpenCode، Codex CLI، Gemini CLI، Cursor و HTTP مستقیم کار میکند. قیمتگذاری فهرست رسمی ارائهدهنده در یک صورتحساب — پرداخت بهازای مصرف، بدون نیاز به اشتراک.
1. شروع به کار
Zenn.Engineering یک دروازه API جایگزین برای مدلهای Anthropic، OpenAI و Google AI، بهعلاوه تولید تصویر است. شما از یک کلید با پیشوند ck_ در همه جا استفاده میکنید — بدون تغییر کد، فقط ابزار خود را به baseURL ما متصل کنید.
یک طرح را در /pricing انتخاب کنید، سپس یک کلید در /manage-api-keys ایجاد کنید.
ابزار خود را به https://zenn.engineering/api/v1 متصل کنید.
با Claude Code، OpenCode، Codex CLI، Gemini CLI، Cursor و هر کلاینت سازگار با OpenAI/Anthropic کار میکند.
2. baseURLها
یک کلید، سه baseURL سازگار با پروتکل (Anthropic / OpenAI / Gemini)، بهعلاوه یک نقطه پایانی تولید تصویر.
| سطح | baseURL | استفاده با |
|---|---|---|
| سازگار با Anthropic | https://zenn.engineering/api/v1 | Claude Code، Anthropic SDK، OpenCode (ارائهدهنده anthropic) |
| سازگار با 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 (payload سازگار با OpenAI) |
3. Claude Code
CLI رسمی Anthropic برای Claude. دو متغیر محیطی تنظیم کنید و بهعنوان جایگزین مستقیم کار میکند.
گام 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 کلید API را از طریق هدر x-api-key (بومی Anthropic SDK) ارسال میکند و /messages را به baseURL اضافه میکند. هر دو هدر anthropic-version و anthropic-beta به upstream فوروارد میشوند. استریم از طریق SSE پشتیبانی میشود.
4. OpenCode
عامل کدنویسی AI چندارائهدهنده. یک پیکربندی JSON به شما 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
CLI رسمی OpenAI برای خانواده GPT-5 / Codex. دو متغیر محیطی تنظیم کنید و به baseURL Codex ما متصل شوید.
تنظیم محیط
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 و شکل /chat/completions + /responses از OpenAI استفاده میکند — هر دو پشتیبانی میشوند.
6. Gemini CLI
Gemini CLI گوگل کلید را از طریق x-goog-api-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 به /models روی baseURL درخواست میفرستد تا کارکرد کلید را تأیید کند.
8. API مستقیم (cURL)
سه شکل پروتکل، یک کلید. هر کدام را که کلاینت شما از قبل صحبت میکند انتخاب کنید.
سازگار با 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) با یک قیمت ثابت محاسبه میشوند — برای جزئیات به Models مراجعه کنید. سایر مدلهای تصویر، ویدیو و صدا بهعنوان بهزودی فهرست شدهاند.
نقطه پایانی
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" را از انتخابگر مدل انتخاب کنید، یک prompt ارسال کنید و تصویر بهصورت inline رندر میشود. سرور برای شما upstream را polling میکند و 6 اعتبار (0.06 دلار) بهازای هر تصویر صورتحساب میکند.
10. مدلها و قیمتگذاری
صورتحساب مبتنی بر اعتبار (۱٬۰۰۰٬۰۰۰ اعتبار = ۱٫۰۰ دلار). قیمتهای LLM همان قیمت رسمی ارائهدهنده برای هر میلیون توکن است؛ تصویر بر اساس هر تولید. مدلهای دارای برچسب بهزودی فهرست شدهاند اما API تا فعالسازی آنها را رد میکند. هر مدل بر اساس قیمت رسمی محاسبه میشود — ارزش از ضریب اعتبار در زمان شارژ میآید (Pro 1×، Max 4×، Enterprise 6×). برای جزئیات پلانها بخش ۱۲ را ببینید.
Claude (Anthropic)
| شناسه مدل | ورودی / 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
| شناسه مدل | ورودی / 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)
| شناسه مدل | ورودی / 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
| شناسه مدل | ورودی / 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 | فعال |
تصویر (فعال)
| شناسه مدل | اعتبار / تصویر | قیمت / تصویر | وضعیت |
|---|---|---|---|
| gpt-image-2 | 60000 | $0.06 | فعال |
همه مدلهای تصویر، ویدیو و صدا با قیمت رسمی فهرست مصرف میشوند. سایر مدلهای تصویر (خانواده Nano Banana، Gemini 3 Pro Image، Seedream) در کاتالوگ فهرست شدهاند اما در حال حاضر بهزودی هستند — API آنها را تا فعال شدن رد میکند. برای کاتالوگ کامل به /models مراجعه کنید.
11. احراز هویت
همه کلیدهای API از پیشوند 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 پیشرو با قیمت رسمی فهرست
- · API سازگار با OpenAI / Anthropic / Gemini
- · محدودیت هزینه بهازای هر کلید، تحلیل بلادرنگ
4 برابر اعتبار — 200 دلار 800 دلار مصرف با قیمت فهرست میخرد.
- · همه چیز در Pro
- · 4 برابر اعتبار بهازای هر دلار در زمان شارژ
- · همان قیمت فهرست روی هر مدل
- · صف اولویتدار + مسیریابی سریعتر
6 برابر اعتبار — 2,000 دلار 12,000 دلار مصرف + کانال اولویتدار Anthropic Max میخرد.
- · همه چیز در Max
- · 6 برابر اعتبار بهازای هر دلار در زمان شارژ
- · همان قیمت فهرست روی هر مدل
- · کانال اولویتدار Anthropic Max
- · پشتیبانی اختصاصی، صدور صورتحساب سازگار با ممیزی
یک قانون قیمتگذاری، هر مدل
- · هر مدل LLM، تصویر، ویدیو و صدا با قیمت رسمی فهرست نمایشدادهشده در /models مصرف میشود.
- · ارزش Max (200 دلار ← 4×) و Enterprise (2,000 دلار ← 6×) از اعتبار اضافی اعطاشده در زمان شارژ ناشی میشود، نه از سطوح تخفیف بهازای هر مدل.
- · بدون واجد شرایط بودن سطل، بدون متن ریز بهازای هر مدل — اعتبارات شما یکسان روی Claude Opus، GPT-5.5 و Gemini Flash کار میکند.
ضرایب بهازای هر شارژ اعمال میشوند. اعتبارات Max موجود ارزش 4 برابری خود را تا زمان مصرف حفظ میکنند — پس از آن Pro را شارژ کنید و آن 20 دلار 20M اعتبار با ضریب 1× اعطا میکند. برای تفکیک کامل به /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 گمشده / نامعتبر |
| 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 برمیگردانند؛ فراخوانی آنها امروز یک عمل بیاثر است که اعتباری صورتحساب نمیکند.
آماده شروع هستید؟
یک کلید در Claude Code، OpenCode، Codex CLI، Gemini CLI و Cursor کار میکند. اعتبار شارژ کنید و کلید API خود را ایجاد کنید.
