Docs / Integrations
Use Cent AI with Claude Code
Point Claude Code at Cent AI with two environment variables and pick a model by name.
Last updated
Tested with Claude Code v2.1.323 on 2026-11-13
Your setup
Fills in YOUR_API_KEY in the code on this page. The key stays in this tab: it is never sent and never saved.
Claude Code speaks the Anthropic Messages format, so it connects to Cent AI at https://api.cent-ai.dev and adds /v1/messages itself.
Prerequisites
- A Cent AI account with balance. See Quickstart.
- An API key from Keys. It looks like
cai_<secret>and is shown once. - Claude Code installed. The version we tested is at the end of this page.
Configure Claude Code
Set the base URL, your key and the model. Replace YOUR_API_KEY with your key.
export ANTHROPIC_BASE_URL="https://api.cent-ai.dev"
export ANTHROPIC_AUTH_TOKEN="YOUR_API_KEY"
export ANTHROPIC_MODEL="claude-opus-5"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="claude-haiku-5.5"
| Variable | What it does |
|---|---|
ANTHROPIC_BASE_URL | Sends Claude Code requests to Cent AI. Do not add /v1. |
ANTHROPIC_AUTH_TOKEN | Sends your key as Authorization: Bearer. ANTHROPIC_API_KEY also works and sends it as x-api-key; Cent AI accepts both. |
ANTHROPIC_MODEL | The model for the session. Use a name exactly as listed by GET /v1/models. |
ANTHROPIC_DEFAULT_HAIKU_MODEL | The model Claude Code uses for background tasks such as session titles. Set it to a Cent AI model name too, or those requests fail with 404 model_not_found. |
Shell variables last for one terminal. To keep them, put the same values in the env block of ~/.claude/settings.json (on Windows %USERPROFILE%\.claude\settings.json):
{
"env": {
"ANTHROPIC_BASE_URL": "https://api.cent-ai.dev",
"ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY",
"ANTHROPIC_MODEL": "claude-opus-5",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-5.5"
}
}
Do not put the key in a project's .claude/settings.json: that file is usually committed to the repository.
In the VS Code extension, set the same variables in claudeCode.environmentVariables in your VS Code user settings.
Test it
Check the key and base URL before you open Claude Code:
curl https://api.cent-ai.dev/v1/messages \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{"model":"claude-opus-5","max_tokens":16,"messages":[{"role":"user","content":"Hello"}]}'
The response has usage.cost, the amount charged for this request in USD. Then start claude from the same terminal and run /status: the Anthropic base URL line shows https://api.cent-ai.dev. Send a prompt. Each turn appears on the Requests page of the dashboard with its tokens per rate and its cost. See Request cost.
Cache continuity
Claude Code sends a session ID header, X-Claude-Code-Session-Id, and a metadata.user_id field that stay the same for the whole conversation. Cent AI uses that signal to send every turn of the conversation to the route that served the previous turn, so the model's cache can be hit. You do not add anything to your configuration for this.
Cent AI does not promise a cache hit rate. Cache tokens are charged only when the model reports them. See Prompt caching.
Troubleshooting
To look up a failed request, find the x-request-id of the response on the Requests page. All codes are in 4xx errors and 5xx errors.
401 invalid_api_key
The key is wrong, cut off, revoked, or a management key (cai_mgmt_…). Check the value of ANTHROPIC_AUTH_TOKEN, then run /status to see which credential Claude Code is using. If it shows a claude.ai login instead, the variable did not reach the session.
402 insufficient_balance
The balance available for this model is empty, or the model is not in your budget pack. Top up or buy a pack. See Balance.
403 ip_not_allowed or model_not_allowed
The key has an IP allowlist without your address, or a model allowlist without the model Claude Code asked for. Remember the background model in ANTHROPIC_DEFAULT_HAIKU_MODEL: it must be on the allowlist too.
404 model_not_found
The model name is not one Cent AI serves. Copy the exact name from Models or GET /v1/models; names from other providers, such as gpt-4o-mini, are not aliases. A :free name works only for today's event model (see Free tokens daily); on any other model, including a previous day's event model, it returns 404.
429 rate_limited, key_limit_exceeded or project_budget_exceeded
rate_limited: more than 600 requests per minute on this key. Claude Code with many subagents can reach it. Wait forRetry-After, or spread work over several keys.rate_limitedon a:freename: today's free pool is used up, or the event is off.Retry-Afterruns to 00:00 UTC; the model's own name stays available at its normal price.key_limit_exceeded: the daily or monthly limit you set on the key was reached.project_budget_exceeded: the budget of the key's project was reached.
501 not_available_yet
The endpoint is not open yet. Claude Code only needs /v1/messages, which is available, so this usually means a wrong base URL.
Stream timeout
Long turns stream with : keepalive every 15 seconds. If a turn stops with timeout_error or api_error in the stream, see Stream timeout.