Claude Messages

Call Claude models with the native Anthropic Messages format.

POST /v1/messages

The Claude Messages endpoint keeps Anthropic’s native request shape, which suits migrations that already use a Claude SDK or native prompt structure. Traffic is routed in Claude relay format and dispatched to the matching upstream by channel.

The default example model is .

Available models

Model	Description
	Latest Claude Opus 5 series
	Claude Sonnet 5 series
	Claude Opus 4.7
	Claude Opus 4.6 thinking mode
	Claude Opus 4.5
	Claude Sonnet 4.6
	Claude Haiku 4.5 lightweight model
	Claude 5 series

Headers

Name	Type	Required	Description
	string	Yes	Request authentication. Use a Bearer Token, for example:
	string	No	Native Claude auth header; can replace , for example:
	string	No	Native Claude version header; use with , for example:
	string	Yes	Request content type; must be

Request body

Name	Type	Required	Description
	string	Yes	Claude model name; default example ; see Available models above
	integer	Yes	Maximum output tokens. Required by the official API; generation stops when this count is reached ( is )
	array	Yes	Conversation messages; roles must alternate between and
	string | array	No	System prompt. Claude does not use a role message—pass it via this field; when an array is passed, items are content blocks and may include
	boolean	No	Whether to enable SSE streaming; default
	number	No	Sampling temperature, range –, default ; prefer tuning only one of or
	number	No	Nucleus sampling; prefer not adjusting together with
	integer	No	Top-K sampling; sample only from the K highest-probability tokens
	array	No	Custom stop sequences; generation stops when any sequence is produced; the sequence is not included in the output
	array	No	Tool definitions
	object	No	Controls tool selection strategy
	object	No	Extended thinking config; only for models with thinking capability
	object	No	Request metadata
	string	No	Service capacity tier: (default) /
	object	No	Structured output config; can be a JSON Schema
	object	No	Context management config; array defines edit policies
	array	No	MCP connector server list
	string	No	Container ID; can reuse a code-execution container returned by a previous response
	string	No	Inference region restriction, e.g. means run inference in the US only

messages item

Name	Type	Required	Description
	string	Yes	Message role: or
	string | array	Yes	Plain string, or content block array. Common types: , ( supports / ), , , ,

tools item

Name	Type	Required	Description
	string	Yes	Tool name
	string	No	Tool description to help the model decide when to call it
	object	Yes	JSON Schema for tool parameters, typically

tool_choice

Name	Type	Required	Description
	string	Yes	(default; model decides) / (must call a tool) / (force a specific tool) / (disallow tools)
	string	Conditional	When is , the tool name to force
	boolean	No	Set to to disallow calling multiple tools in parallel in one reply

thinking

Name	Type	Required	Description
	string	Yes	to turn thinking on, to turn it off
	integer	No	Thinking token budget; must be less than

metadata

Name	Type	Required	Description
	string	No	Stable end-user identifier (prefer an irreversible ID or hash) for abuse detection

Request example

Basic request

curl -X POST https://octopusx.ai/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "system": "You are a rigorous technical advisor.",
    "messages": [
      {
        "role": "user",
        "content": "Explain why an API gateway needs rate limiting."
      }
    ]
  }'

Multimodal input

curl -X POST https://octopusx.ai/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "image",
            "source": {
              "type": "url",
              "url": "https://example.com/diagram.png"
            }
          },
          {
            "type": "text",
            "text": "Based on this architecture diagram, explain which layer rate limiting should sit on."
          }
        ]
      }
    ]
  }'

Tool calling

curl -X POST https://octopusx.ai/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "tools": [
      {
        "name": "get_weather",
        "description": "Get the weather for a given city",
        "input_schema": {
          "type": "object",
          "properties": {
            "city": { "type": "string" }
          },
          "required": ["city"]
        }
      }
    ],
    "tool_choice": { "type": "auto" },
    "messages": [
      {
        "role": "user",
        "content": "Check the weather in Shanghai today."
      }
    ]
  }'

Response example

200 - Non-streaming

{
  "id": "msg_abc123",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-4-6",
  "content": [
    {
      "type": "text",
      "text": "Rate limiting at an API gateway protects upstream services from traffic spikes, prevents resource exhaustion, and helps deliver stable quality of service across users."
    }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 32,
    "output_tokens": 45
  }
}

200 - Streaming

Streaming responses use text/event-stream. Common event types include , , , , , and .

event: message_start
data: {"type":"message_start","message":{"id":"msg_abc123","type":"message","role":"assistant","model":"claude-sonnet-4-6","content":[],"stop_reason":null,"usage":{"input_tokens":32,"output_tokens":0}}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Rate limiting"}}

event: message_stop
data: {"type":"message_stop"}

Response fields

Name	Type	Description
	string	Message ID
	string	Object type; always
	string	Message role; always
	string	Model that generated the response
	array	Content blocks; common blocks include (e.g. ) and
	string	Stop reason, e.g. , , ,
	object	Token usage; includes ,

Related endpoints

• Text APIs overview
• Error codes