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

# Messages

> POST /v1/messages — the Claude native protocol endpoint

The Claude native protocol endpoint, fully compatible with Anthropic's official API, with advanced features not in the OpenAI protocol such as `cache_control` and `thinking`.

## Request

```bash theme={null}
curl https://openp.ai/v1/messages \
  -H "x-api-key: $OPENPAI_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-8",
    "max_tokens": 1024,
    "system": "You are a Python engineer",
    "messages": [
      {"role": "user", "content": "Write an LRU Cache in Python"}
    ]
  }'
```

### Headers

| Header              | Required | Description                                             |
| ------------------- | :------: | ------------------------------------------------------- |
| `x-api-key`         |     ✅    | The `sk-` key issued by OpenPAI                         |
| `anthropic-version` |     ✅    | API version, currently `2023-06-01`                     |
| `anthropic-beta`    |          | Experimental features, e.g. `prompt-caching-2024-07-31` |
| `Content-Type`      |     ✅    | `application/json`                                      |

### Body fields

| Field            | Type            | Required | Description                                                      |
| ---------------- | --------------- | :------: | ---------------------------------------------------------------- |
| `model`          | string          |     ✅    | Claude model ID                                                  |
| `messages`       | array           |     ✅    | Conversation history; `role` must alternate `user` / `assistant` |
| `max_tokens`     | integer         |     ✅    | Maximum output tokens                                            |
| `system`         | string \| array |          | System prompt; array form can carry `cache_control`              |
| `temperature`    | number          |          | 0-1                                                              |
| `top_p`          | number          |          |                                                                  |
| `top_k`          | integer         |          |                                                                  |
| `stop_sequences` | array           |          | Stop sequences                                                   |
| `stream`         | boolean         |          | SSE stream                                                       |
| `tools`          | array           |          | Tool definitions                                                 |
| `tool_choice`    | object          |          | `{type:"auto"}` / `{type:"any"}` / `{type:"tool",name:"x"}`      |
| `thinking`       | object          |          | `{ type:"enabled", budget_tokens: 8000 }`                        |
| `metadata`       | object          |          | `{ user_id: "..." }`                                             |

### content structure

Claude's `content` can be a string or a block array. Block types:

* `text` — plain text
* `image` — image (`source.type` is `base64` or `url`)
* `tool_use` — a model-initiated tool call (assistant message)
* `tool_result` — a tool's returned result (user message)
* `thinking` — a thinking block (thinking-mode response)
* `document` — documents like PDF

## Response

```json theme={null}
{
  "id": "msg_01...",
  "type": "message",
  "role": "assistant",
  "model": "claude-opus-4-8",
  "content": [
    {"type": "text", "text": "Sure, here's an LRU Cache implementation..."}
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 24,
    "output_tokens": 256,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0
  }
}
```

`stop_reason`: `end_turn` / `max_tokens` / `stop_sequence` / `tool_use`.

## Streaming response

With `stream: true`, events are pushed as SSE:

```
event: message_start
data: {"type":"message_start","message":{"id":"msg_...","role":"assistant","content":[],...}}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

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

event: content_block_stop
data: {"type":"content_block_stop","index":0}

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

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

## Thinking mode

`claude-sonnet-4-6` and `claude-haiku-4-5` use **extended thinking** (`thinking` + `budget_tokens`); `claude-opus-4-8` uses **adaptive thinking** (`effort`, defaults to `high`):

```json theme={null}
{
  "model": "claude-sonnet-4-6",
  "max_tokens": 4096,
  "thinking": { "type": "enabled", "budget_tokens": 8000 },
  "messages": [{"role": "user", "content": "Prove Goldbach's conjecture"}]
}
```

```json theme={null}
{
  "model": "claude-opus-4-8",
  "max_tokens": 4096,
  "effort": "high",
  "messages": [{"role": "user", "content": "Prove Goldbach's conjecture"}]
}
```

The response includes an extra `thinking` block:

```json theme={null}
{
  "content": [
    {"type": "thinking", "thinking": "<internal chain of thought>"},
    {"type": "text", "text": "<final answer>"}
  ]
}
```

See [Reasoning & thinking](/en/advanced/reasoning).

## Prompt caching

```json theme={null}
{
  "model": "claude-opus-4-8",
  "max_tokens": 1024,
  "system": [
    {
      "type": "text",
      "text": "<long 50000-char system prompt>",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [{"role": "user", "content": "..."}]
}
```

See [Cache billing](/en/pricing/cache-billing).

## Vision

```json theme={null}
{
  "model": "claude-opus-4-8",
  "max_tokens": 1024,
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "Describe this image"},
      {"type": "image", "source": {
        "type": "url",
        "url": "https://example.com/cat.png"
      }}
    ]
  }]
}
```

Or base64:

```json theme={null}
{"type": "image", "source": {
  "type": "base64",
  "media_type": "image/png",
  "data": "<base64>"
}}
```

## Tools

```json theme={null}
{
  "model": "claude-opus-4-8",
  "max_tokens": 1024,
  "tools": [{
    "name": "get_weather",
    "description": "Get weather",
    "input_schema": {
      "type": "object",
      "properties": {"city": {"type": "string"}},
      "required": ["city"]
    }
  }],
  "messages": [{"role": "user", "content": "Weather in Shanghai"}]
}
```

The assistant content in the response includes a `tool_use` block:

```json theme={null}
{
  "content": [{
    "type": "tool_use",
    "id": "toolu_01...",
    "name": "get_weather",
    "input": {"city": "Shanghai"}
  }],
  "stop_reason": "tool_use"
}
```

Return the execution result via a user message:

```json theme={null}
{
  "role": "user",
  "content": [{
    "type": "tool_result",
    "tool_use_id": "toolu_01...",
    "content": "Shanghai is 26°C and clear today"
  }]
}
```