Docs menu

Docs / Integrations

Use Cent AI with Codex

Add Cent AI as a model provider in the Codex config file and keep your key in an environment variable.

Last updated

Tested with Codex v0.161.0 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.

Codex CLI speaks the OpenAI Responses format, so it connects to Cent AI at https://api.cent-ai.dev/v1 and adds /responses itself.

Prerequisites

  • A Cent AI account with balance. See Quickstart.
  • An API key from Keys. It looks like cai_<secret> and is shown once.
  • Codex CLI installed. The version we tested is at the end of this page.

Configure Codex

Codex reads custom providers from the user config file ~/.codex/config.toml (on Windows %USERPROFILE%\.codex\config.toml). A project's .codex/config.toml cannot define providers. Add:

model = "gpt-6-sol"
model_provider = "centai"

[model_providers.centai]
name = "Cent AI"
base_url = "https://api.cent-ai.dev/v1"
env_key = "CENT_AI_KEY"
wire_api = "responses"
FieldWhat it does
modelThe model for new sessions. Use a name exactly as listed by GET /v1/models.
model_providerSelects the centai provider defined below it.
base_urlCent AI's OpenAI base URL, with /v1.
env_keyThe environment variable that holds your key. Codex sends it as Authorization: Bearer.
wire_apiresponses, the format Codex uses.

The key stays out of the file. Set it in the environment, replacing YOUR_API_KEY with your key:

export CENT_AI_KEY="YOUR_API_KEY"

To keep it across terminals, add the same line to your shell profile, such as ~/.bashrc or your PowerShell $PROFILE.

Test it

Check the key and base URL with one Responses request:

curl https://api.cent-ai.dev/v1/responses \
  -H "Authorization: Bearer $CENT_AI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-6-sol","input":"Hello"}'

The response has usage.cost, the amount charged for this request in USD. Then start codex in the same terminal and 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

Codex sends a Session-Id header and a prompt_cache_key field that stay the same for the whole conversation, including when you resume it. 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 that CENT_AI_KEY is set in the terminal where you start Codex, and that env_key in config.toml names the same variable.

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 in config.toml. Add the address or the model to the key.

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. Wait for Retry-After, or spread parallel sessions 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. Codex only needs /v1/responses, 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 upstream_timeout or upstream_unavailable in the stream, see Stream timeout.