Docs / SDKs
Use Cent AI with the OpenAI Python SDK
Point the openai Python package at Cent AI, send a request and read the cost of each call.
Last updated
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.
Prerequisites
- A Cent AI account with balance. See Balance.
- An API key from Keys. It looks like
cai_<secret>and is shown once. - Python with the
openaipackage:
pip install openai
Set up the client
Use the base URL https://api.cent-ai.dev/v1 and your Cent AI key. The SDK adds /chat/completions and /responses itself.
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.cent-ai.dev/v1",
api_key=os.environ["CENT_AI_KEY"],
)
The SDK also reads both values from environment variables, so code that calls OpenAI() without arguments works unchanged. Replace YOUR_API_KEY with your key:
export OPENAI_BASE_URL=https://api.cent-ai.dev/v1
export OPENAI_API_KEY="YOUR_API_KEY"
Send a request
Chat Completions and Responses both work with the same client. Use a model name from the models page.
r = client.chat.completions.create(
model="glm-5.3",
messages=[{"role": "user", "content": "Hello"}],
)
print(r.choices[0].message.content)
Parameters such as temperature, tools and response_format are sent to the model as is. A parameter the model does not support comes back as an error from the model.
Read the cost
Cent AI adds cost to the standard usage object: the amount charged for the request in USD, as a string with 9 decimal places. The SDK keeps fields it does not know, so you can read it as an attribute. getattr keeps type checkers quiet; usage.model_extra returns every extra field as a dict.
r = client.chat.completions.create(
model="glm-5.3",
messages=[{"role": "user", "content": "Hello"}],
)
print(r.usage.prompt_tokens, r.usage.completion_tokens)
print(getattr(r.usage, "cost", None)) # "0.000363000"
print(r.usage.model_extra) # {"cost": "0.000363000"}
On Responses, the cost is in r.usage the same way.
Streaming
For Chat Completions, ask for usage in the stream with stream_options. The last chunk before the stream ends has an empty choices list and carries usage, including cost.
stream = client.chat.completions.create(
model="glm-5.3",
messages=[{"role": "user", "content": "Hello"}],
stream=True,
stream_options={"include_usage": True},
)
for chunk in stream:
if chunk.choices:
print(chunk.choices[0].delta.content or "", end="")
if chunk.usage:
print("\ncost:", getattr(chunk.usage, "cost", None))
Without stream_options.include_usage, a Chat Completions stream has no usage chunk and no cost. The charge is still recorded on the Requests page. Requests that can take longer than 100 seconds must stream; see Long streaming.
Check the request
Open the Requests page in the dashboard. Each request shows its tokens per rate, the rates used and the cost. The x-request-id response header is the same ID. To read it from the SDK:
raw = client.chat.completions.with_raw_response.create(
model="glm-5.3",
messages=[{"role": "user", "content": "Hello"}],
)
print(raw.headers.get("x-request-id"))
r = raw.parse()
Troubleshooting
| Status and code | Usual cause | What to do |
|---|---|---|
401 invalid_api_key | Wrong or revoked key, or the key is still an OPENAI_API_KEY from elsewhere | Check the key, or create a new one in Keys |
402 insufficient_balance | No balance available for this model | Top up or buy a budget pack, see Balance |
403 ip_not_allowed, model_not_allowed | The key's IP or model allowlist blocks the request | Change the allowlist on the key |
404 model_not_found | A model name Cent AI does not have | Use a name from GET /v1/models |
| 404 without that code | The base URL is missing /v1 | Set the base URL to https://api.cent-ai.dev/v1 |
429 rate_limited | Over 600 requests per minute for the key | Wait for Retry-After, see Rate limits |
429 key_limit_exceeded, project_budget_exceeded | A daily or monthly limit of the key or project was reached | Raise the limit or wait until the time in the message |
501 not_available_yet | An endpoint that is not open yet, such as embeddings | Use chat models; see Errors |
503 upstream_timeout or a stream that stops | The model did not start in time, or a stream hit its maximum duration | See Stream timeout |
The SDK raises openai.AuthenticationError, openai.RateLimitError and other openai.APIStatusError subclasses for these statuses, and retries some of them on its own. All codes are listed in Errors.