Docs menu

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"
VariableWhat it does
ANTHROPIC_BASE_URLSends Claude Code requests to Cent AI. Do not add /v1.
ANTHROPIC_AUTH_TOKENSends your key as Authorization: Bearer. ANTHROPIC_API_KEY also works and sends it as x-api-key; Cent AI accepts both.
ANTHROPIC_MODELThe model for the session. Use a name exactly as listed by GET /v1/models.
ANTHROPIC_DEFAULT_HAIKU_MODELThe 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 for Retry-After, or spread work over several keys.
  • rate_limited on a :free name: today's free pool is used up, or the event is off. Retry-After runs 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.