POST /v1/messages

Anthropic-compatible Messages API with aliases, streaming, tools, vision, caching, and thinking.

No current prepared translation is available. The English source is shown without machine translation.

Authentication

x-api-key: mg_live_...
anthropic-version: 2023-06-01
content-type: application/json

Bearer authentication is also accepted.

Request

curl https://api.model-gate.com/v1/messages \
  -H "x-api-key: mg_live_..." \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4.6",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Write a short release note."}
    ]
  }'

Response

{
  "id": "msg_example",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-4.6",
  "content": [{"type": "text", "text": "This release improves documentation and model routing."}],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 11,
    "output_tokens": 9,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0
  }
}

Streaming

Add "stream": true. Model Gate forwards Anthropic-compatible SSE events and records the final token usage for billing.

Aliases and accounting

If an alias is supplied, it is replaced with the canonical model before the request is queued or sent upstream. Pricing, usage cost, request history, and model restrictions use the canonical model.

Status	Meaning	Action
`400`	Invalid request	Check the request body and model ID.
`401`	Invalid or frozen key	Verify or rotate the API key.
`429`	Rate or concurrency limit exceeded	Respect `Retry-After` and retry with backoff.
`5xx`	Temporary upstream or gateway error	Retry idempotent requests with exponential backoff.

Session ID

Use a stable JSON session_id or X-Session-ID header for every turn of this conversation. Priority is session_id → X-Session-ID → recognized session in metadata.user_id → prompt_cache_key → opening conversation content. The identity layer is independent of provider type. Keeping the same ID does not guarantee a cache hit or disable eligible failover. See conversation identity and sticky routing for automatic fallback, scope, limits and the difference from idempotency and stored context.

The same identity is retained for streaming and for asynchronous submission where this endpoint supports it. Do not send a new paid POST merely to test a session after a timeout; check the existing request first.

An existing recognized metadata session is used without a mismatch error; an ordinary metadata.user_id is preserved, not treated as a conversation. Higher-priority explicit fields win. See the linked identity reference for formats and upstream transport limits.

A recognized metadata session takes precedence over a cache hint. Automatic identity ignores known cache_control decorations and equivalent single-text wrappers without changing the model request. A separately configured, compatible upstream session-header transport does not occupy ordinary metadata.user_id; this capability is configured by the operator, not selected by the client.