Anthropic-compatible Messages API

SoAI exposes an Anthropic-compatible Messages surface at POST /v1/messages and a model-aware token counter at POST /v1/messages/count_tokens. Use it for clients that speak the Anthropic Messages contract. It shares SoAI's model catalog and API-key policy; it does not provide a separate Anthropic-shaped Models endpoint.

Prepare and send requests

Every request must send anthropic-version: 2023-06-01. When API keys are required, send the SoAI key as x-api-key or Authorization: Bearer. If both credential headers are present, their values must match.

Create a message

curl http://127.0.0.1:5090/v1/messages \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: YOUR_SOAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "max_tokens": 256,
    "messages": [{"role": "user", "content": "Reply with one sentence."}]
  }'

model, at least one message, and a positive max_tokens value are required. The selected catalog model must support chat completions and every requested capability, such as images or tool calling.

Count input tokens

curl http://127.0.0.1:5090/v1/messages/count_tokens \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: YOUR_SOAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [{"role": "user", "content": "Count this input."}]
  }'

The response contains input_tokens. Counting resolves the same model, parameters, tools, system content, and request shape used for inference. SoAI rejects an incomplete or unsupported count rather than presenting it as authoritative.

Supported behavior, errors, and clients

Messages accepts text and supported image content blocks, system content, tools and tool choice, stop sequences, sampling fields, metadata user_id, supported thinking modes, structured JSON-schema output, and the supported context-management edit. Fields outside the implemented contract are rejected before inference. Use the live /v1/openapi.json schema for the current field types and the HTTP API reference for the current route inventory.

Streaming

Set "stream": true to receive Anthropic named Server-Sent Events. The sequence uses message, content-block, ping, delta, and stop event shapes. Do not parse it as OpenAI data: [DONE] streaming. Tool use, thinking, text, stop reason, and usage are projected into the corresponding Anthropic response fields.

Error handling

Missing or different anthropic-version is a bad request. Invalid content blocks, tool declarations, unsupported fields, incompatible model capabilities, authentication failures, rate limits, and provider failures use Anthropic-shaped error responses at this surface. Retry only a typed transient failure and honor retry guidance; correct validation or authentication errors before sending another request.

Client configuration

A client that appends /v1/messages expects the SoAI origin without /v1. For example, ANTHROPIC_BASE_URL for Claude Code is the server origin. See Using Claude Code with SoAI for its exact environment variables and the separate MCP connection.

Related documentation