Referência da API e setup
Uma chave de API ck_ funciona no Claude Code, OpenCode, Codex CLI, Gemini CLI, Cursor e via HTTP direto. Preços de tabela oficiais em uma única fatura — pague conforme o uso, sem assinatura.
1. Primeiros passos
Zenn.Engineering é um gateway de API drop-in para modelos da Anthropic, OpenAI e Google AI, além de geração de imagens. Você usa uma única chave com prefixo ck_ em todos os lugares — sem mudanças de código, basta apontar sua ferramenta para a nossa base URL.
Escolha um plano em /pricing, depois crie uma chave em /manage-api-keys.
Aponte sua ferramenta para https://zenn.engineering/api/v1.
Funciona com Claude Code, OpenCode, Codex CLI, Gemini CLI, Cursor e qualquer cliente compatível com OpenAI/Anthropic.
2. Base URLs
Uma chave, três base URLs compatíveis com protocolo (Anthropic / OpenAI / Gemini), além de um endpoint de geração de imagens.
| Surface | Base URL | Usar com |
|---|---|---|
| Compatível com Anthropic | https://zenn.engineering/api/v1 | Claude Code, Anthropic SDK, OpenCode (provider anthropic) |
| Compatível com OpenAI (Codex) | https://zenn.engineering/api/v1/codex | Codex CLI, OpenAI SDK, Cursor |
| Compatível com Gemini | https://zenn.engineering/api/v1/gemini | Gemini CLI, Google AI SDK |
| Geração de imagens | https://zenn.engineering/api/v1/images/generations | gpt-image-2 (payload compatível com OpenAI) |
3. Claude Code
CLI oficial da Anthropic para o Claude. Defina duas variáveis de ambiente e ele funciona como substituto drop-in.
Passo 1 — Configure o ambiente
Adicione ao seu shell profile (~/.zshrc ou ~/.bashrc):
export ANTHROPIC_BASE_URL=https://zenn.engineering/api/v1 export ANTHROPIC_API_KEY=ck_YOUR_API_KEY
Passo 2 — Reinicie e execute
# Default model (Sonnet 4.6) claude # Pick a different model claude --model claude-opus-4-7 claude --model claude-haiku-4-5
Como funciona
O Claude Code envia a chave de API pelo header x-api-key (nativo do Anthropic SDK) e adiciona /messages à base URL. Os headers anthropic-version e anthropic-beta são encaminhados upstream. Streaming é suportado via SSE.
4. OpenCode
Agente de IA para código multi-provider. Um único config JSON te dá Claude, GPT-5 e Gemini com uma só chave.
Passo 1 — Instalar
npm i -g opencode-ai
Passo 2 — Criar config
Edite ~/.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" }
}
}
}
}Passo 3 — Executar
opencode
5. Codex CLI
CLI oficial da OpenAI para a família GPT-5 / Codex. Defina duas variáveis de ambiente e aponte para a nossa base URL do Codex.
Configurar ambiente
export OPENAI_BASE_URL=https://zenn.engineering/api/v1/codex export OPENAI_API_KEY=ck_YOUR_API_KEY
Executar
# 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
O Codex CLI usa Authorization: Bearer e o formato OpenAI /chat/completions + /responses — ambos são suportados.
6. Gemini CLI
O Gemini CLI do Google envia a chave pelo header x-goog-api-key. O proxy aceita esse header de forma transparente.
Configurar ambiente
export GEMINI_BASE_URL=https://zenn.engineering/api/v1/gemini export GEMINI_API_KEY=ck_YOUR_API_KEY
Executar
gemini --model gemini-3.1-pro-preview gemini --model gemini-3-flash-preview
7. Cursor IDE
No Cursor → Settings → Models → "Custom OpenAI Model":
| Campo | Valor |
|---|---|
| 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 |
Clique em Verify depois de salvar — o Cursor vai chamar /models na base URL para confirmar que a chave funciona.
8. API direta (cURL)
Três formatos de protocolo, uma chave. Escolha o que seu cliente já usa.
Compatível com 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"}]
}'Compatível com 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. Geração de imagens
gpt-image-2 é o único modelo de imagem atualmente roteável pela API. Os tiers de resolução (1K / 2K / 4K) são cobrados a um preço único — veja Modelos para detalhes. Outros modelos de imagem, vídeo e áudio estão listados como Em breve.
Endpoint
POST https://zenn.engineering/api/v1/images/generations GET https://zenn.engineering/api/v1/images/generations (list models)
Gerar uma imagem
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
}'Comportamento assíncrono
DocsPage.imageGen.asyncBody
No chat do navegador
Abra /chat, escolha "GPT Image 2 — Image Generation" no model picker, envie um prompt, e a imagem é renderizada inline. O servidor faz o polling upstream para você e cobra 6 créditos ($0,06) por imagem.
10. Modelos e preços
Cobrança por créditos (1.000.000 créditos = $1,00). Os preços LLM são os preços de tabela oficiais por milhão de tokens; imagens são cobradas por geração. Modelos marcados como Em breve estão listados mas a API os rejeita até a ativação. Cada modelo é cobrado pelo preço de tabela oficial — o valor vem do multiplicador de créditos no momento da recarga (Pro 1×, Max 4×, Enterprise 6×). Consulte a seção 12 para detalhes dos planos.
Claude (Anthropic)
| Model ID | Entrada / MTok | Saída / MTok | Leitura de cache | Status |
|---|---|---|---|---|
| claude-opus-4-7 | $15.00 | $75.00 | $1.50 | No ar |
| claude-opus-4-6 | $15.00 | $75.00 | $1.50 | No ar |
| claude-sonnet-4-6 | $3.00 | $15.00 | $0.30 | No ar |
| claude-haiku-4-5 | $1.00 | $5.00 | $0.10 | No ar |
OpenAI / GPT
| Model ID | Entrada / MTok | Saída / MTok | Leitura de cache | Status |
|---|---|---|---|---|
| gpt-5.5 | $5.00 | $30.00 | $0.50 | No ar |
| gpt-5.5-instant | $5.00 | $30.00 | $0.50 | No ar |
| gpt-5.5-pro | $30.00 | $180.00 | $30.00 | No ar |
| gpt-5.4 | $5.00 | $22.50 | $0.50 | No ar |
| gpt-5.3-codex | $1.75 | $14.00 | $0.17 | No ar |
| gpt-5.2 | $1.75 | $14.00 | $0.17 | No ar |
Gemini (Google)
| Model ID | Entrada / MTok | Saída / MTok | Leitura de cache | Status |
|---|---|---|---|---|
| gemini-3.1-pro-preview | $4.00 | $18.00 | $0.40 | No ar |
| gemini-3-pro-preview | $4.00 | $18.00 | $0.40 | No ar |
| gemini-3-flash-preview | $0.50 | $3.00 | $0.05 | No ar |
DeepSeek / Moonshot / Zhipu
| Model ID | Entrada / MTok | Saída / MTok | Leitura de cache | Status |
|---|---|---|---|---|
| deepseek-v4-pro | $1.74 | $3.48 | $0.01 | No ar |
| deepseek-v4-flash | $0.14 | $0.28 | $0.0028 | No ar |
| kimi-k2.6 | $0.95 | $4.00 | $0.16 | No ar |
| glm-5.1 | $1.40 | $4.40 | $0.26 | No ar |
Imagem (no ar)
| Model ID | Créditos / imagem | Preço / imagem | Status |
|---|---|---|---|
| gpt-image-2 | 60000 | $0.06 | No ar |
Todos os modelos de imagem, vídeo e áudio são cobrados pelo preço de tabela oficial. Outros modelos de imagem (família Nano Banana, Gemini 3 Pro Image, Seedream) estão listados no catálogo mas atualmente Em breve — a API os rejeita até serem habilitados. Veja /models para o catálogo completo.
11. Autenticação
Todas as chaves de API usam o prefixo ck_. O proxy aceita todos os formatos de header de SDK padrão para que os clientes funcionem sem modificação.
| Header | Formato | Usado por |
|---|---|---|
| x-api-key | ck_... | Claude Code, Anthropic SDK |
| Authorization | Bearer ck_... | OpenCode, Codex CLI, OpenAI SDK, cURL |
| anthropic-api-key | ck_... | Header alternativo da Anthropic |
| x-goog-api-key | ck_... | Gemini CLI |
Headers encaminhados
anthropic-version (default 2023-06-01) e anthropic-beta são repassados. Streaming SSE é totalmente suportado.
12. Planos
Recarga única — sem assinatura. Cada recarga fixa um multiplicador de créditos (Pro 1×, Max 4×, Enterprise 6×) — seus créditos mantêm esse valor de multiplicador até serem gastos. Recargas seguintes podem ser de qualquer nível.
Preço padrão. Pague conforme o uso.
- · Todo LLM de fronteira a preço de tabela oficial
- · API compatível com OpenAI / Anthropic / Gemini
- · Limites de gasto por chave, analytics em tempo real
4× créditos — $100 compram $400 de uso a preço de tabela.
- · Tudo do Pro
- · 4× créditos por dólar na hora da recarga
- · Mesmo preço de tabela em todos os modelos
- · Fila prioritária + roteamento mais rápido
6× créditos — $2.000 compram $12.000 de uso + canal prioritário Anthropic Max.
- · Tudo do Max
- · 6× créditos por dólar na hora da recarga
- · Mesmo preço de tabela em todos os modelos
- · Canal prioritário Anthropic Max
- · Suporte dedicado, faturamento amigável para auditoria
Uma regra de preço, todos os modelos
- · Todo modelo de LLM, imagem, vídeo e áudio é cobrado pelo preço de tabela oficial mostrado em /models.
- · O valor do Max ($100 → 4×) e Enterprise ($2.000 → 6×) vem de créditos extras concedidos na hora da recarga, não de tiers de desconto por modelo.
- · Sem elegibilidade de bucket, sem letras miúdas por modelo — seus créditos funcionam igual no Claude Opus, GPT-5.5 e Gemini Flash.
Os multiplicadores se aplicam por recarga. Créditos Max existentes mantêm o valor de 4× até serem gastos — recarregue Pro depois e esses $10 dão 20M de créditos a 1×. Veja /pricing para o detalhamento completo.
13. Rate limits e erros
Rate limits por usuário
| Endpoint | Requisições / hora |
|---|---|
| /v1/messages, /v1/chat/completions, /v1/gemini | 1,000 |
| /v1/images/generations | 500 |
| /v1/responses, /v1/codex/* | 1,000 |
O status do rate limit é retornado nos headers da resposta: x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset.
Códigos de erro
| Status | Significado |
|---|---|
| 401 | Chave de API ausente / inválida |
| 402 | Créditos insuficientes — recarregue em /checkout |
| 403 | O tier não desbloqueia o modelo solicitado (ex.: Opus 4.7) |
| 429 | Rate limit por usuário atingido |
| 503 | Modelo está listado mas Em breve |
| 504 | Geração de imagem expirou (tente novamente) |
14. Em breve
Listados publicamente mas a API os rejeita até que a margem sob o modelo de multiplicador de créditos se estabilize:
Família 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.
Veja a listagem completa em /models. Entradas em breve retornam HTTP 503 da API; chamá-las hoje é um no-op que não cobra créditos.
Pronto para começar?
Uma chave funciona no Claude Code, OpenCode, Codex CLI, Gemini CLI e Cursor. Recarregue créditos e crie sua chave de API.