DOCUMENTATION

Set up in 2 minutes.

One key, four API formats. Claude Code, Codex CLI and Gemini clients work with no plugin and no workaround.

Claude CodeCodex CLIAnthropic SDKOpenAI SDKGoogle SDK
zsh

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. 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.

    zsh
    curl -fsSL https://claude.ai/install.sh | bash
    
    Homebrew
    brew install --cask claude-code
    

    If you use npm, do not run it with sudo. If you get EACCES, use the installer above instead.

  2. 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. 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.

    ~/.zshrc
    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. 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.

    Quick test
    claude -p "responda só: oi"
    
    Open in your project
    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.

VARIABLE GENERATOR

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         = ""
claude

Endpoints

FORMATENDPOINTWHO SPEAKS IT
Anthropic Messages/v1/messagesClaude Code, Anthropic SDK
OpenAI Responses/v1/responsesCodex CLI
OpenAI Chat Completions/v1/chat/completionsOpenAI SDK, Cursor, Continue, Aider, LangChain
Gemini GenerateContent/v1beta/models/{model}:generateContentGoogle 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.

These endpoints — and therefore Claude Code and Codex — are included in every plan. With a key that has no API access the response is 402 with instructions in the body. Create the key under API access.

Claude Code

VARIABLEVALUE
ANTHROPIC_BASE_URLhttps://lumiarouter.com
ANTHROPIC_API_KEYsk-...
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.2

With 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

  1. 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.

  2. 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.

  3. 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.

  4. 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 codex

Codex 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"
Order matters in TOML: 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-..."
codex

The variable name is whatever you set in env_key. To switch models, change model at the top of the file.

SDK and cURL

The two SDKs use opposite conventions: with OpenAI the 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.

IDMODELCONTEXTMINIMUM PLAN
claude-opus-5-5Claude Opus 5.5256kstarter
claude-sonnet-5Claude Sonnet 5256kstarter
claude-sonnet-5-5Claude Sonnet 5.5256kstarter
claude-fable-5.2Claude Fable 5.2256kpro
z-ai/glm-5.3GLM 5.31,000kstarter
z-ai/glm-5.3-flashGLM 5.3 Flash1,000kstarter
tencent/Hy4-previewHunyuan Hy4 Preview1,000kstarter
deepseek-ai/DeepSeek-V4.1-Flash-1017DeepSeek V4.1 Flash1,000kstarter
XiaomiMiMo/MiMo-V2.6-ProMiMo V2.6 Pro1,000kstarter
gpt-6-astraGPT-6 Astra1,000kmax

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

SYMPTOMCAUSEFIX
404ANTHROPIC_BASE_URL ending in /v1Keep only the domain
401 invalid or revokedWrong or revoked key, or pasted with a spaceGenerate a new one in the dashboard
429 Plan window reachedyour 5-hour or weekly usage window is exhaustedWait for the window to reset, or move up a plan
402 API access missing on this keythe key was created without API accessCreate a new key under API access
403 IP not authorizedIP not on the authorized listAllow or renew under API keys
ConnectionRefusedURL with http:// or an explicit portUse https://lumiarouter.com
Codex uses OpenAI, not LumiaRoutermodel_provider declared after the table in the TOMLMove both keys to the top
issue with the selected modelSame cause as the 404 — the message misleadsCheck the ANTHROPIC_BASE_URL