Docs / SDKs
Use Cent AI with the Anthropic Python SDK
Point the anthropic Python package at Cent AI, send Messages requests 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
anthropicpackage:
pip install anthropic
Set up the client
Use the base URL https://api.cent-ai.dev, without /v1, and your Cent AI key. The SDK adds /v1/messages itself. Cent AI accepts the key in x-api-key and in Authorization: Bearer.
import os
from anthropic import Anthropic
client = Anthropic(
base_url="https://api.cent-ai.dev",
api_key=os.environ["CENT_AI_KEY"],
)
The SDK also reads both values from environment variables, so code that calls Anthropic() without arguments works unchanged. Replace YOUR_API_KEY with your key:
export ANTHROPIC_BASE_URL=https://api.cent-ai.dev
export ANTHROPIC_API_KEY="YOUR_API_KEY"
Send a request
Use a model name from the models page. max_tokens is required by the Messages format.
m = client.messages.create(
model="claude-opus-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello"}],
)
for block in m.content:
if block.type == "text":
print(block.text)
system, tools, thinking and cache_control are sent to the model as is. See Messages and Prompt caching.
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.
print(m.usage.input_tokens, m.usage.cache_read_input_tokens, m.usage.output_tokens)
print(getattr(m.usage, "cost", None)) # "0.003210000"
print(m.usage.model_extra) # {"cost": "0.003210000"}
In this format input_tokens does not include cache tokens.
Streaming
In a stream, the cost is in the usage of the last message_delta event. Read it from the raw events of create(..., stream=True):
stream = client.messages.create(
model="claude-opus-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello"}],
stream=True,
)
cost = None
for event in stream:
if event.type == "content_block_delta" and event.delta.type == "text_delta":
print(event.delta.text, end="")
elif event.type == "message_delta":
cost = getattr(event.usage, "cost", cost)
print("\ncost:", cost)
The client.messages.stream(...) helper builds a final message for you, but it is not guaranteed to copy cost into it. When you need the cost, iterate over the events and read message_delta as above. 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.messages.with_raw_response.create(
model="claude-opus-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello"}],
)
print(raw.headers.get("x-request-id"))
m = raw.parse()
Troubleshooting
Errors on /v1/messages use the Anthropic shape: the error type follows the HTTP status and the message says what happened.
| Status | Usual cause | What to do |
|---|---|---|
| 401 | Wrong or revoked key, or the key is still an ANTHROPIC_API_KEY from elsewhere | Check the key, or create a new one in Keys |
| 402 | No balance available for this model | Top up or buy a budget pack, see Balance |
| 403 | The key's IP or model allowlist blocks the request, or its project is archived | Change the allowlist on the key, or restore the project |
| 404 | A model name Cent AI does not have, or a base URL that ends in /v1 | Use a name from GET /v1/models and the base URL https://api.cent-ai.dev |
| 429 | Over 600 requests per minute for the key, or a daily or monthly limit of the key or project | Read the message; see Rate limits |
| 503 or a stream that stops | The model is unavailable, did not start in time, or a stream hit its maximum duration | See 5xx errors and Stream timeout |
The SDK raises anthropic.AuthenticationError, anthropic.RateLimitError and other anthropic.APIStatusError subclasses for these statuses, and retries some of them on its own. All codes are listed in Errors.