> ## 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 —— Claude 原生协议接口

Claude 原生协议接口,完全兼容 Anthropic 官方,可使用 `cache_control`、`thinking` 等 OpenAI 协议中没有的高级特性。

## 请求

```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": "你是 Python 工程师",
    "messages": [
      {"role": "user", "content": "用 Python 写一个 LRU Cache"}
    ]
  }'
```

### Header

| Header              |  必填 | 说明                                 |
| ------------------- | :-: | ---------------------------------- |
| `x-api-key`         |  ✅  | OpenPAI 颁发的 `sk-` 密钥               |
| `anthropic-version` |  ✅  | API 版本,目前用 `2023-06-01`            |
| `anthropic-beta`    |     | 实验特性,如 `prompt-caching-2024-07-31` |
| `Content-Type`      |  ✅  | `application/json`                 |

### Body 字段

| 字段               | 类型              |  必填 | 说明                                                          |
| ---------------- | --------------- | :-: | ----------------------------------------------------------- |
| `model`          | string          |  ✅  | Claude 模型 ID                                                |
| `messages`       | array           |  ✅  | 对话历史,`role` 只能 `user` / `assistant` 交替                      |
| `max_tokens`     | integer         |  ✅  | 最大输出 token                                                  |
| `system`         | string \| array |     | system prompt,数组形式可带 `cache_control`                        |
| `temperature`    | number          |     | 0-1                                                         |
| `top_p`          | number          |     |                                                             |
| `top_k`          | integer         |     |                                                             |
| `stop_sequences` | array           |     | 停止序列                                                        |
| `stream`         | boolean         |     | SSE 流                                                       |
| `tools`          | array           |     | 工具定义                                                        |
| `tool_choice`    | object          |     | `{type:"auto"}` / `{type:"any"}` / `{type:"tool",name:"x"}` |
| `thinking`       | object          |     | `{ type:"enabled", budget_tokens: 8000 }`                   |
| `metadata`       | object          |     | `{ user_id: "..." }`                                        |

### content 结构

Claude 的 `content` 可以是字符串或 block 数组,block 类型:

* `text` —— 普通文本
* `image` —— 图片(`source.type` 为 `base64` 或 `url`)
* `tool_use` —— 模型发起的工具调用(assistant 消息)
* `tool_result` —— 工具返回结果(user 消息)
* `thinking` —— 思考块(thinking 模式响应)
* `document` —— PDF 等文档

## 响应

```json theme={null}
{
  "id": "msg_01...",
  "type": "message",
  "role": "assistant",
  "model": "claude-opus-4-8",
  "content": [
    {"type": "text", "text": "好的,以下是 LRU Cache 实现..."}
  ],
  "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`。

## 流式响应

`stream: true` 时按 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":"你"}}

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"}
```

## 思考模式

`claude-sonnet-4-6`、`claude-haiku-4-5` 使用 **扩展思考**(`thinking` + `budget_tokens`);`claude-opus-4-8` 使用 **自适应思考**(`effort`,默认 `high`):

```json theme={null}
{
  "model": "claude-sonnet-4-6",
  "max_tokens": 4096,
  "thinking": { "type": "enabled", "budget_tokens": 8000 },
  "messages": [{"role": "user", "content": "证明哥德巴赫猜想"}]
}
```

```json theme={null}
{
  "model": "claude-opus-4-8",
  "max_tokens": 4096,
  "effort": "high",
  "messages": [{"role": "user", "content": "证明哥德巴赫猜想"}]
}
```

响应中会多出 `thinking` block:

```json theme={null}
{
  "content": [
    {"type": "thinking", "thinking": "<内部思考链>"},
    {"type": "text", "text": "<最终回答>"}
  ]
}
```

详见 [推理与思考](/advanced/reasoning)。

## 提示缓存

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

详见 [缓存计费](/pricing/cache-billing)。

## 视觉

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

或 base64:

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

## 工具

```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": "上海天气"}]
}
```

响应中 assistant content 会包含 `tool_use` block:

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

把执行结果通过 user 消息回传:

```json theme={null}
{
  "role": "user",
  "content": [{
    "type": "tool_result",
    "tool_use_id": "toolu_01...",
    "content": "上海今天 26°C,晴"
  }]
}
```