Set up in 2 minutes.
One key, four API formats. Claude Code, Codex CLI and Gemini clients work with no plugin and no workaround.
Step by step
Claude Code installed and pointing at LumiaRouter in four steps. Pick your system — the commands change, mainly on macOS, where the terminal is zsh.
- 1
Install Claude Code
Open Terminal (⌘ + Space, type "Terminal") and run the official installer. Works on Apple silicon (M1–M4) and Intel Macs, no Node needed.
$curl -fsSL https://claude.ai/install.sh | bash$brew install --cask claude-codeIf you use npm, do not run it with sudo. If you get EACCES, use the installer above instead.
- 2
Create your key
In the dashboard, under API keys, click "New key" and copy it. It starts with sk- and is shown only once.
Open dashboard - 3
Configure it permanently
macOS uses zsh, so the variables go in ~/.zshrc. Paste the whole block at once, replacing sk-YOUR_KEY with your key.
$echo 'export ANTHROPIC_BASE_URL=https://lumiarouter.com' >> ~/.zshrc $echo 'export ANTHROPIC_API_KEY=sk-YOUR_KEY' >> ~/.zshrc $source ~/.zshrc
The address is https://lumiarouter.com with no /v1 at the end. With /v1, Claude Code calls /v1/v1/messages and gets a 404.
- 4
Test it and start
The first command answers one line and exits — if you see a reply, everything works. The second opens Claude Code in your project folder. The first time it asks whether to use the key from the environment: answer Yes.
$claude -p "responda só: oi"$cd ~/projeto $claude --model claude-opus-5-5
Logged in with an Anthropic account before? Run /logout inside Claude Code, exit and open it again — otherwise it ignores the key from the environment.
Quick start
Paste your key and copy the ready-made command for your terminal.
Generated in your browser — the key never leaves it. Generate a key
$env:ANTHROPIC_BASE_URL = "/"
$env:ANTHROPIC_API_KEY = "sk-YOUR_KEY"
$env:ANTHROPIC_MODEL = "claude-sonnet-5"
$env:CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY = "1"
$env:CLAUDE_CODE_DISABLE_1M_CONTEXT = "1"
$env:CLAUDE_CODE_MAX_CONTEXT_TOKENS = ""
$env:ANTHROPIC_CUSTOM_MODEL_OPTION = ""
$env:ANTHROPIC_CUSTOM_MODEL_OPTION_NAME = ""
claudeEndpoints
| FORMAT | ENDPOINT | WHO SPEAKS IT |
|---|---|---|
| Anthropic Messages | /v1/messages | Claude Code, Anthropic SDK |
| OpenAI Responses | /v1/responses | Codex CLI |
| OpenAI Chat Completions | /v1/chat/completions | OpenAI SDK, Cursor, Continue, Aider, LangChain |
| Gemini GenerateContent | /v1beta/models/{model}:generateContent | Google Gen AI SDK and Gemini clients |
Authenticate with Authorization: Bearer sk-… or x-api-key: sk-… — the server accepts both, because each SDK sends a different one. The key is shown only once, in the dashboard, and your IP has to be allowed there.
The Gemini format also accepts x-goog-api-key and the ?key= query parameter, matching Google SDK conventions.
Claude Code
| VARIABLE | VALUE |
|---|---|
| ANTHROPIC_BASE_URL | https://lumiarouter.com |
| ANTHROPIC_API_KEY | sk-... |
ANTHROPIC_BASE_URL never ends in /v1. The SDK appends /v1/messages on its own, so pointing at …/v1 hits /v1/v1/messages and returns 404 — and the CLI complains about an "issue with the selected model", blaming the model for a URL mistake.$env:ANTHROPIC_BASE_URL = "/"
$env:ANTHROPIC_API_KEY = "sk-..."
claude --model claude-fable-5.2With the variables in your environment, every claude command talks to LumiaRouter — no extra flag and no config file.
Codex CLI
Claude in Codex, step by step
Prepare API access
In the dashboard, check your plan, create your key and authorize your IP using the email code. This authorizes its provider network (ASN), so IP changes within the same ASN do not require another approval. A chat subscription alone does not enable API access.
Open the Codex configuration
Use ~/.codex/config.toml on macOS/Linux or %USERPROFILE%\.codex\config.toml on Windows. Create the directory and file if missing. Back up existing settings; merge the example without duplicating entries. If CODEX_HOME is customized, use its config.toml.
Select LumiaRouter and a Claude model
Put model and model_provider at the top, before any [table]. The provider name must match [model_providers.lumiarouter]. LumiaRouter translates the Responses API used by Codex to the selected model. This does not make Claude an OpenAI model.
Set your key and start a new session
Copy the environment command from the generator. For permanent Windows variables, open a new terminal. Start codex in your project. Use /status to inspect the selected model; try a simple prompt before a larger task.
Use the exact model ID from the catalog. Model availability follows your plan. Keep /v1 in the Codex URL and wire_api = "responses". Do not use the Anthropic /v1/messages endpoint in Codex.
If Codex warns “Model metadata not found” or writes files through shell commands, download the catalog setup below, run node codex-setup.mjs and start a new Codex session. It configures the native patch capability and backs up config.toml while preserving your provider, model and permissions.
brew install --cask codexCodex ignores OPENAI_BASE_URL for the default provider: it needs its own provider in config.toml (~/.codex/config.toml, or %USERPROFILE%\.codex\config.toml on Windows).
model = "claude-sonnet-5"
model_provider = "lumiarouter"
[model_providers.lumiarouter]
name = "LumiaRouter"
base_url = "https://lumiarouter.com/v1"
env_key = "LUMIA_API_KEY"
wire_api = "responses"model and model_provider must come before [model_providers.lumiarouter]. After the table, the parser reads them as keys of that table and Codex silently falls back to the OpenAI provider.$env:LUMIA_API_KEY = "sk-..."
codexThe variable name is whatever you set in env_key. To switch models, change model at the top of the file.
SDK and cURL
base_url includes /v1; with Anthropic it does not — the SDK appends the path itself.from openai import OpenAI
client = OpenAI(base_url="https://lumiarouter.com/v1", api_key="sk-...")
r = client.chat.completions.create(
model="claude-fable-5.2",
messages=[{"role": "user", "content": "Explique RAG"}],
)
print(r.choices[0].message.content)In PowerShell, curl is an alias for Invoke-WebRequest and does not accept this syntax — use curl.exe, which ships with Windows 10 and 11.
Models
The id goes in the model field of requests and in the --model flag of the CLIs.
| ID | MODEL | CONTEXT | MINIMUM PLAN |
|---|---|---|---|
| claude-opus-5-5 | Claude Opus 5.5 | 256k | starter |
| claude-sonnet-5 | Claude Sonnet 5 | 256k | starter |
| claude-sonnet-5-5 | Claude Sonnet 5.5 | 256k | starter |
| claude-fable-5.2 | Claude Fable 5.2 | 256k | pro |
| z-ai/glm-5.3 | GLM 5.3 | 1,000k | starter |
| z-ai/glm-5.3-flash | GLM 5.3 Flash | 1,000k | starter |
| tencent/Hy4-preview | ![]() | 1,000k | starter |
| deepseek-ai/DeepSeek-V4.1-Flash-1017 | 1,000k | starter | |
| XiaomiMiMo/MiMo-V2.6-Pro | ![]() | 1,000k | starter |
| gpt-6-astra | GPT-6 Astra | 1,000k | max |
Tool calling
Works in all four formats — tool_use/tool_result on Anthropic, tool_calls on Chat Completions, function_call/function_call_output on the Responses API, functionCall/functionResponse on Gemini — with streaming: plain text arrives token by token and only the span of a call is held back until it closes.
Verified end to end with both real CLIs in a full cycle: run a failing test, read the file, fix it, run again and confirm it passes.
Common errors
| SYMPTOM | CAUSE | FIX |
|---|---|---|
| 404 | ANTHROPIC_BASE_URL ending in /v1 | Keep only the domain |
| 401 invalid or revoked | Wrong or revoked key, or pasted with a space | Generate a new one in the dashboard |
| 429 Plan window reached | your 5-hour or weekly usage window is exhausted | Wait for the window to reset, or move up a plan |
| 402 API access missing on this key | the key was created without API access | Create a new key under API access |
| 403 IP not authorized | IP not on the authorized list | Allow or renew under API keys |
| ConnectionRefused | URL with http:// or an explicit port | Use https://lumiarouter.com |
| Codex uses OpenAI, not LumiaRouter | model_provider declared after the table in the TOML | Move both keys to the top |
| issue with the selected model | Same cause as the 404 — the message misleads | Check the ANTHROPIC_BASE_URL |

