Docs / API
Messages
POST /v1/messages in the Anthropic format, for Anthropic SDKs and tools such as Claude Code.
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.
Endpoint
POST https://api.cent-ai.dev/v1/messages
x-api-key: cai_<secret>
anthropic-version: 2023-06-01
Content-Type: application/json
The endpoint follows the Anthropic Messages format. Anthropic SDKs add /v1/messages themselves, so their base URL is https://api.cent-ai.dev, without /v1. Authorization: Bearer works as well as x-api-key.
Request
model, messages, system, max_tokens (required by the format), stream, tools and thinking are sent to the model as is.
| Topic | Behaviour |
|---|---|
anthropic-version | Accepted and passed through |
anthropic-beta | Passed through when present |
cache_control | Passed through unchanged, see Prompt caching |
Example
curl https://api.cent-ai.dev/v1/messages \
-H "x-api-key: $CENT_AI_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{"model":"claude-opus-5","max_tokens":1024,"messages":[{"role":"user","content":"Hello"}]}'
Tools that read Anthropic environment variables use the same two values:
export ANTHROPIC_BASE_URL=https://api.cent-ai.dev
export ANTHROPIC_API_KEY="YOUR_API_KEY"
Response
{
"id": "msg_01Xyz",
"type": "message",
"role": "assistant",
"model": "claude-opus-5",
"content": [{"type": "text", "text": "Hello!"}],
"stop_reason": "end_turn",
"usage": {
"input_tokens": 1200,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 8800,
"output_tokens": 410,
"cost": "0.003210000"
}
}
In this format input_tokens does not include cache tokens. cache_read_input_tokens is charged at the cache read rate and cache_creation_input_tokens at the cache write rate. When the model reports cache writes per lifetime (cache_creation.ephemeral_5m_input_tokens, cache_creation.ephemeral_1h_input_tokens), both are billed at the input rate.
Streaming
With "stream": true you receive the standard Anthropic events. The last message_delta carries usage.cost:
event: message_start
data: {"type":"message_start","message":{"id":"msg_01Xyz","type":"message","role":"assistant","model":"claude-opus-5","content":[],"usage":{"input_tokens":1200,"cache_read_input_tokens":8800,"output_tokens":1}}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hello"}}
event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":410,"cost":"0.003210000"}}
event: message_stop
data: {"type":"message_stop"}
Errors in this format
Errors on /v1/messages use the Anthropic shape:
{"type": "error", "error": {"type": "authentication_error", "message": "Invalid API key. Check the key or create a new one in the dashboard."}}
The type follows the status: 400 and 402 invalid_request_error, 401 authentication_error, 403 permission_error, 404 not_found_error, 413 request_too_large, 429 rate_limit_error, upstream_timeout timeout_error, other 5xx api_error. See Errors.
Counting tokens
POST /v1/messages/count_tokens returns {"input_tokens": N} and is not charged. When the model cannot count, Cent AI estimates with a tokenizer. It counts toward the key's rate limit.
Contract
POST/v1/messages
Messages (Anthropic format)
Auth · API key (Bearer or x-api-key)
Request body
max_tokensintegeroptionalmessagesobject[]requiredmodelstringrequiredstreambooleanoptionalsystemobjectoptionalthinkingobjectoptionaltoolsobject[]optional
Responses
- 200Message, or an SSE stream of Anthropic events;
usage.costis in the lastmessage_delta. - 400Error in the Anthropic shape.
- 401Error in the Anthropic shape.
- 402Error in the Anthropic shape.
- 403Error in the Anthropic shape.
- 404Error in the Anthropic shape.
- 413Error in the Anthropic shape.
- 429Error in the Anthropic shape.
- 500Error in the Anthropic shape.
- 503Error in the Anthropic shape.
Response headers
x-request-id
POST/v1/messages/count_tokens
Count input tokens (not billed)
Auth · API key (Bearer or x-api-key)
Request body
max_tokensintegeroptionalmessagesobject[]requiredmodelstringrequiredstreambooleanoptionalsystemobjectoptionalthinkingobjectoptionaltoolsobject[]optional
Responses
- 200Token count.
- 401Error in the Anthropic shape.
- 404Error in the Anthropic shape.
- 429Error in the Anthropic shape.
Response headers
x-request-id
Generated from the OpenAPI contract.