API Reference e Setup
Una sola API key ck_ funziona su Claude Code, OpenCode, Codex CLI, Gemini CLI, Cursor e HTTP diretto. Listino ufficiale dei provider su una sola fattura — pay as you go, nessun abbonamento richiesto.
1. Per iniziare
Zenn.Ceo è un gateway API drop-in per i modelli Anthropic, OpenAI e Google AI, oltre alla generazione di immagini. Usi una sola key con prefisso ck_ ovunque — nessuna modifica al codice, basta puntare il tuo strumento al nostro baseURL.
Scegli un piano su /pricing, poi crea una key su /manage-api-keys.
Punta il tuo strumento a https://zenn.ceo/api/v1.
Funziona con Claude Code, OpenCode, Codex CLI, Gemini CLI, Cursor e qualsiasi client compatibile OpenAI/Anthropic.
2. Base URL
Una key, tre baseURL compatibili a livello di protocollo (Anthropic / OpenAI / Gemini), più un endpoint per la generazione di immagini.
| Surface | Base URL | Usa con |
|---|---|---|
| Compatibile Anthropic | https://zenn.ceo/api/v1 | Claude Code, Anthropic SDK, OpenCode (provider anthropic) |
| Compatibile OpenAI (Codex) | https://zenn.ceo/api/v1/codex | Codex CLI, OpenAI SDK, Cursor |
| Compatibile Gemini | https://zenn.ceo/api/v1/gemini | Gemini CLI, Google AI SDK |
| Generazione di immagini | https://zenn.ceo/api/v1/images/generations | gpt-image-2 (payload compatibile OpenAI) |
3. Claude Code
La CLI ufficiale di Anthropic per Claude. Imposta due variabili d'ambiente e funziona come sostituto drop-in.
Step 1 — Imposta l'ambiente
Aggiungi al profilo della tua shell (~/.zshrc o ~/.bashrc):
export ANTHROPIC_BASE_URL=https://zenn.ceo/api/v1 export ANTHROPIC_API_KEY=ck_YOUR_API_KEY
Step 2 — Riavvia ed esegui
# Default model (Sonnet 4.6) claude # Pick a different model claude --model claude-opus-4-7 claude --model claude-haiku-4-5
Come funziona
Claude Code invia l'API key tramite l'header x-api-key (nativo dell'Anthropic SDK) e aggiunge /messages al baseURL. Sia anthropic-version che anthropic-beta vengono inoltrati upstream. Lo streaming è supportato tramite SSE.
4. OpenCode
Agente AI di coding multi-provider. Una sola configurazione JSON ti dà Claude, GPT-5 e Gemini con un'unica key.
Step 1 — Installa
npm i -g opencode-ai
Step 2 — Crea la configurazione
Modifica ~/.config/opencode/opencode.json:
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"anthropic": {
"options": {
"baseURL": "https://zenn.ceo/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.ceo/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.ceo/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.ceo/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" }
}
}
}
}Step 3 — Esegui
opencode
5. Codex CLI
La CLI ufficiale di OpenAI per la famiglia GPT-5 / Codex. Imposta due variabili d'ambiente e punta al nostro baseURL Codex.
Imposta l'ambiente
export OPENAI_BASE_URL=https://zenn.ceo/api/v1/codex export OPENAI_API_KEY=ck_YOUR_API_KEY
Esegui
# 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 usa Authorization: Bearer e il formato OpenAI /chat/completions + /responses — entrambi sono supportati.
6. Gemini CLI
La Gemini CLI di Google invia la key tramite x-goog-api-key. Il proxy accetta quell'header in modo trasparente.
Imposta l'ambiente
export GEMINI_BASE_URL=https://zenn.ceo/api/v1/gemini export GEMINI_API_KEY=ck_YOUR_API_KEY
Esegui
gemini --model gemini-3.1-pro-preview gemini --model gemini-3-flash-preview
7. Cursor IDE
In Cursor → Settings → Models → "Custom OpenAI Model":
| Campo | Valore |
|---|---|
| Override OpenAI Base URL | https://zenn.ceo/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 |
Clicca Verify dopo aver salvato — Cursor chiamerà /models sul baseURL per confermare che la key funzioni.
8. API diretta (cURL)
Tre formati di protocollo, una sola key. Scegli quello che il tuo client già parla.
Compatibile Anthropic — /v1/messages
curl -X POST https://zenn.ceo/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"}]
}'Compatibile OpenAI — /v1/codex/chat/completions
curl -X POST https://zenn.ceo/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.ceo/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. Generazione di immagini
gpt-image-2 è attualmente l'unico modello di immagini instradabile via API. I tier di risoluzione (1K / 2K / 4K) sono fatturati a un prezzo unico — vedi Modelli per i dettagli. Altri modelli di immagini, video e audio sono elencati come In arrivo.
Endpoint
POST https://zenn.ceo/api/v1/images/generations GET https://zenn.ceo/api/v1/images/generations (list models)
Genera un'immagine
curl -X POST https://zenn.ceo/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
}'Comportamento asincrono
DocsPage.imageGen.asyncBody
Nella chat del browser
Apri /chat, seleziona "GPT Image 2 — Image Generation" dal model picker, invia un prompt e l'immagine viene renderizzata inline. Il server fa polling upstream al posto tuo e fattura 6 crediti ($0.06) per immagine.
10. Modelli e prezzi
Fatturazione a crediti (1.000.000 crediti = $1,00). I prezzi LLM sono quelli ufficiali del fornitore per milione di token; le immagini sono fatturate per generazione. I modelli contrassegnati In arrivo sono elencati ma l'API li rifiuta fino all'attivazione. Ogni modello viene fatturato al prezzo di listino ufficiale — il valore deriva dal moltiplicatore di crediti al momento della ricarica (Pro 1×, Max 4×, Enterprise 6×). Vedi la sezione 12 per i dettagli dei piani.
Claude (Anthropic)
| Model ID | Input / MTok | Output / MTok | Cache Read | Stato |
|---|---|---|---|---|
| claude-opus-4-7 | $15.00 | $75.00 | $1.50 | Live |
| claude-opus-4-6 | $15.00 | $75.00 | $1.50 | Live |
| claude-sonnet-4-6 | $3.00 | $15.00 | $0.30 | Live |
| claude-haiku-4-5 | $1.00 | $5.00 | $0.10 | Live |
OpenAI / GPT
| Model ID | Input / MTok | Output / MTok | Cache Read | Stato |
|---|---|---|---|---|
| gpt-5.5 | $5.00 | $30.00 | $0.50 | Live |
| gpt-5.5-instant | $5.00 | $30.00 | $0.50 | Live |
| gpt-5.5-pro | $30.00 | $180.00 | $30.00 | Live |
| gpt-5.4 | $5.00 | $22.50 | $0.50 | Live |
| gpt-5.3-codex | $1.75 | $14.00 | $0.17 | Live |
| gpt-5.2 | $1.75 | $14.00 | $0.17 | Live |
Gemini (Google)
| Model ID | Input / MTok | Output / MTok | Cache Read | Stato |
|---|---|---|---|---|
| gemini-3.1-pro-preview | $4.00 | $18.00 | $0.40 | Live |
| gemini-3-pro-preview | $4.00 | $18.00 | $0.40 | Live |
| gemini-3-flash-preview | $0.50 | $3.00 | $0.05 | Live |
DeepSeek / Moonshot / Zhipu
| Model ID | Input / MTok | Output / MTok | Cache Read | Stato |
|---|---|---|---|---|
| deepseek-v4-pro | $1.74 | $3.48 | $0.01 | Live |
| deepseek-v4-flash | $0.14 | $0.28 | $0.0028 | Live |
| kimi-k2.6 | $0.95 | $4.00 | $0.16 | Live |
| glm-5.1 | $1.40 | $4.40 | $0.26 | Live |
Immagini (live)
| Model ID | Crediti / immagine | Prezzo / immagine | Stato |
|---|---|---|---|
| gpt-image-2 | 60000 | $0.06 | Live |
Tutti i modelli di immagini, video e audio consumano al listino ufficiale. Altri modelli di immagini (famiglia Nano Banana, Gemini 3 Pro Image, Seedream) sono elencati nel catalogo ma attualmente In arrivo — l'API li rifiuta finché non sono abilitati. Vedi /models per il catalogo completo.
11. Autenticazione
Tutte le API key usano il prefisso ck_. Il proxy accetta tutti i formati di header standard degli SDK, così i client funzionano senza modifiche.
| Header | Formato | Usato da |
|---|---|---|
| x-api-key | ck_... | Claude Code, Anthropic SDK |
| Authorization | Bearer ck_... | OpenCode, Codex CLI, OpenAI SDK, cURL |
| anthropic-api-key | ck_... | Header Anthropic alternativo |
| x-goog-api-key | ck_... | Gemini CLI |
Header inoltrati
anthropic-version (default 2023-06-01) e anthropic-beta passano attraverso. Lo streaming SSE è pienamente supportato.
12. Piani
Ricarica una tantum — nessun abbonamento. Ogni ricarica fissa un moltiplicatore di crediti (Pro 1×, Max 4×, Enterprise 6×) — i tuoi crediti mantengono quel valore fino al consumo. Le ricariche successive possono essere di qualsiasi livello.
Prezzo standard. Pay-as-you-go.
- · Ogni LLM di frontiera al listino ufficiale
- · API compatibile OpenAI / Anthropic / Gemini
- · Limiti di spesa per key, analytics in tempo reale
4× crediti — $100 ti danno $400 di utilizzo a listino.
- · Tutto quello che c'è in Pro
- · 4× crediti per dollaro al momento del top-up
- · Stesso listino su ogni modello
- · Coda prioritaria + routing più veloce
6× crediti — $1,000 ti danno $6,000 di utilizzo + canale prioritario Anthropic Max.
- · Tutto quello che c'è in Max
- · 6× crediti per dollaro al momento del top-up
- · Stesso listino su ogni modello
- · Canale prioritario Anthropic Max
- · Supporto dedicato, fatturazione audit-friendly
Una regola di prezzo, ogni modello
- · Ogni modello LLM, immagini, video e audio consuma al listino ufficiale mostrato su /models.
- · Il valore di Max ($100 → 4×) e Enterprise ($1,000 → 6×) deriva dai crediti extra concessi al momento del top-up, non da tier di sconto per modello.
- · Nessun requisito di bucket, nessuna scritta in piccolo per modello — i tuoi crediti funzionano allo stesso modo su Claude Opus, GPT-5.5 e Gemini Flash.
I moltiplicatori si applicano per top-up. I crediti Max esistenti mantengono il loro valore 4× finché non li spendi — fai un top-up Pro dopo e quei $10 ti danno 20M crediti a 1×. Vedi /pricing per il dettaglio completo.
13. Rate limit ed errori
Rate limit per utente
| Endpoint | Richieste / ora |
|---|---|
| /v1/messages, /v1/chat/completions, /v1/gemini | 1,000 |
| /v1/images/generations | 500 |
| /v1/responses, /v1/codex/* | 1,000 |
Lo stato del rate limit è restituito negli header di risposta: x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset.
Codici di errore
| Status | Significato |
|---|---|
| 401 | API key mancante / non valida |
| 402 | Crediti insufficienti — fai un top-up su /checkout |
| 403 | Il tier non sblocca il modello richiesto (es. Opus 4.7) |
| 429 | Rate limit per utente raggiunto |
| 503 | Modello elencato ma In arrivo |
| 504 | Generazione di immagini in timeout (riprova) |
14. In arrivo
Elencati pubblicamente ma l'API li rifiuta finché il margine nel modello di moltiplicatore di crediti non si stabilizza:
Famiglia 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.
Vedi l'elenco completo su /models. Le voci in arrivo restituiscono HTTP 503 dall'API; chiamarle oggi è un no-op che non fattura crediti.
Pronto a iniziare?
Una sola key funziona su Claude Code, OpenCode, Codex CLI, Gemini CLI e Cursor. Fai un top-up di crediti e crea la tua API key.