Docs menu

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.

TopicBehaviour
anthropic-versionAccepted and passed through
anthropic-betaPassed through when present
cache_controlPassed 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_tokensintegeroptional

  • messagesobject[]required

  • modelstringrequired

  • streambooleanoptional

  • systemobjectoptional

  • thinkingobjectoptional

  • toolsobject[]optional

Responses

  • 200Message, or an SSE stream of Anthropic events; usage.cost is in the last message_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_tokensintegeroptional

  • messagesobject[]required

  • modelstringrequired

  • streambooleanoptional

  • systemobjectoptional

  • thinkingobjectoptional

  • toolsobject[]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.