Docs menu

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 anthropic package:
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.

StatusUsual causeWhat to do
401Wrong or revoked key, or the key is still an ANTHROPIC_API_KEY from elsewhereCheck the key, or create a new one in Keys
402No balance available for this modelTop up or buy a budget pack, see Balance
403The key's IP or model allowlist blocks the request, or its project is archivedChange the allowlist on the key, or restore the project
404A model name Cent AI does not have, or a base URL that ends in /v1Use a name from GET /v1/models and the base URL https://api.cent-ai.dev
429Over 600 requests per minute for the key, or a daily or monthly limit of the key or projectRead the message; see Rate limits
503 or a stream that stopsThe model is unavailable, did not start in time, or a stream hit its maximum durationSee 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.