> ## Documentation Index
> Fetch the complete documentation index at: https://doc.octopusx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Messages API

> Call Claude models using Anthropic Messages native format.

# Claude Messages API

The Claude Messages API preserves Anthropic's native request structure and is suitable for migrating existing Claude SDK-based services or services using native prompt structures. Requests will be routed into the Claude relay format and dispatched to the corresponding upstream based on the channel.

## Authentication

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

You can also use Claude native request headers:

```http theme={null}
x-api-key: YOUR_API_KEY
anthropic-version: 2023-06-01
```

## Request Body

<ParamField body="model" type="string" required>
  Claude model name.
</ParamField>

<ParamField body="messages" type="array<object>" required>
  Array of conversation messages. In Claude's native format, message roles are typically `user` or `assistant`.
</ParamField>

<ParamField body="system" type="string | array<object>">
  System prompt. Claude does not use `system` role messages; instead, system instructions are passed through this field.
</ParamField>

<ParamField body="max_tokens" type="integer">
  Maximum number of output tokens. Most Claude requests should pass this explicitly.
</ParamField>

<ParamField body="stream" type="boolean">
  Whether to enable SSE streaming output.
</ParamField>

<ParamField body="temperature" type="number">
  Sampling temperature.
</ParamField>

<ParamField body="top_p" type="number">
  Top-p sampling parameter.
</ParamField>

<ParamField body="top_k" type="integer">
  Top-K sampling parameter.
</ParamField>

<ParamField body="stop_sequences" type="array<string>">
  Stop sequences.
</ParamField>

<ParamField body="tools" type="array<object>">
  Claude tool list, typically including `name`, `description`, and `input_schema`.
</ParamField>

<ParamField body="tool_choice" type="object">
  Controls the tool selection strategy, for example `{ "type": "tool", "name": "get_weather" }`.
</ParamField>

<ParamField body="thinking" type="object">
  Extended thinking configuration, for example `{ "type": "enabled", "budget_tokens": 10000 }`.
</ParamField>

<ParamField body="metadata" type="object">
  Business-side metadata, such as `user_id`.
</ParamField>

## Request Example

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

### Multimodal Input

```bash theme={null}
curl -X POST https://octopusx.ai/v1/messages \
  -H "x-api-key: YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "image",
            "source": {
              "type": "url",
              "url": "https://.../architecture.png"
            }
          },
          { "type": "text", "text": "What risk points are there in this architecture diagram?" }
        ]
      }
    ]
  }'
```

### Tool Calling

```bash theme={null}
curl -X POST https://octopusx.ai/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
      { "role": "user", "content": "Is Shanghai suitable for cycling today?" }
    ],
    "tools": [
      {
        "name": "get_weather",
        "description": "Query city weather",
        "input_schema": {
          "type": "object",
          "properties": {
            "city": { "type": "string" }
          },
          "required": ["city"]
        }
      }
    ]
  }'
```

## Response Example

<ResponseExample>
  ```json 200 - non-streaming theme={null}
  {
    "id": "msg_abc123",
    "type": "message",
    "role": "assistant",
    "model": "claude-sonnet-4-20250514",
    "content": [
      {
        "type": "text",
        "text": "API gateway rate limiting can protect upstream services, prevent sudden traffic from exhausting resources, and provide stable service quality for different users."
      }
    ],
    "stop_reason": "end_turn",
    "usage": {
      "input_tokens": 32,
      "output_tokens": 45
    }
  }
  ```

  ```text 200 - streaming theme={null}
  event: message_start
  data: {"type":"message_start","message":{"id":"msg_abc123","type":"message","role":"assistant","content":[],"model":"claude-sonnet-4-20250514"}}

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

  event: message_delta
  data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":45}}

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

  ```json 400 theme={null}
  {
    "error": {
      "message": "field model is required",
      "type": "invalid_request_error",
      "param": "",
      "code": "invalid_request"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "message": "Invalid API key provided",
      "type": "invalid_request_error",
      "param": "",
      "code": "invalid_api_key"
    }
  }
  ```

  ```json 402 theme={null}
  {
    "error": {
      "message": "User quota is insufficient",
      "type": "new_api_error",
      "param": "",
      "code": "insufficient_user_quota"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "message": "The current request rate is too high, please try again later",
      "type": "new_api_error",
      "param": "",
      "code": "too_many_requests"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "message": "bad response body",
      "type": "new_api_error",
      "param": "",
      "code": "bad_response_body"
    }
  }
  ```
</ResponseExample>

## Related APIs

* [Chat Completions API (default non-streaming)](./chat-completions-non-stream)
* [Chat Completions API (default streaming)](./chat-completions-stream)
* [Model List](./models)