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"
| Field | What it does |
|---|---|
model | The model for new sessions. Use a name exactly as listed by GET /v1/models. |
model_provider | Selects the centai provider defined below it. |
base_url | Cent AI's OpenAI base URL, with /v1. |
env_key | The environment variable that holds your key. Codex sends it as Authorization: Bearer. |
wire_api | responses, 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 forRetry-After, or spread parallel sessions 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. 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.