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

# 创建消息请求（Claude）

> Claude 原生的消息接口，适用于 Claude Code 等原生 Anthropic 客户端

## 简介

Claude 原生的消息接口，适用于 Claude Code 等原生 Anthropic 客户端。该接口遵循 Anthropic 的 API 规范，提供完整的 Claude 模型功能支持，包括扩展思考（Extended Thinking）、工具调用等高级特性。

如果您使用 OpenAI 兼容的客户端（如 OpenAI SDK），建议使用 `/v1/chat/completions` 接口。

## 认证

Bearer Token，如 `Bearer sk-xxxxxxxxxx`

## 请求参数

<ParamField body="model" type="string" required>
  Claude 模型标识，如 `claude-opus-4-8`
</ParamField>

<ParamField body="messages" type="array" required>
  对话消息列表，每个元素包含 `role`（user/assistant）和 `content`
</ParamField>

<ParamField body="max_tokens" type="integer" required>
  最大生成 token 数，必须大于 0
</ParamField>

<ParamField body="system" type="string | array">
  系统提示词，支持字符串格式或数组格式（用于 Prompt Caching）
</ParamField>

<ParamField body="stream" type="boolean">
  是否启用流式输出
</ParamField>

<ParamField body="temperature" type="number">
  采样温度，范围 0-1
</ParamField>

<ParamField body="top_p" type="number">
  核采样参数，范围 0-1
</ParamField>

<ParamField body="top_k" type="integer">
  Top-k 采样参数
</ParamField>

<ParamField body="stop_sequences" type="array">
  自定义停止序列
</ParamField>

<ParamField body="thinking" type="object">
  扩展思考配置，包含 `type` 和 `budget_tokens`
</ParamField>

<ParamField body="tools" type="array">
  工具定义列表
</ParamField>

## 基础示例

<Tabs>
  <Tab title="非流式请求">
    ```bash theme={null}
    curl -X POST "https://api.mixroute.ai/v1/messages" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -H "anthropic-version: 2023-06-01" \
      -d '{
        "model": "claude-opus-4-8",
        "max_tokens": 1024,
        "messages": [
          {"role": "user", "content": "请用中文简要介绍人工智能"}
        ]
      }'
    ```
  </Tab>

  <Tab title="流式请求（SSE）">
    ```bash theme={null}
    curl -X POST "https://api.mixroute.ai/v1/messages" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -H "anthropic-version: 2023-06-01" \
      -d '{
        "model": "claude-opus-4-8",
        "max_tokens": 1024,
        "stream": true,
        "messages": [
          {"role": "user", "content": "请用中文简要介绍人工智能"}
        ]
      }'
    ```
  </Tab>

  <Tab title="Python 示例">
    ```python theme={null}
    from anthropic import Anthropic

    client = Anthropic(
        api_key="sk-xxxxxxxxxx",
        base_url="https://api.mixroute.ai"
    )

    # 非流式
    message = client.messages.create(
        model="claude-opus-4-8",
        max_tokens=1024,
        messages=[
            {"role": "user", "content": "请用中文简要介绍人工智能"}
        ]
    )
    print(message.content[0].text)

    # 流式
    with client.messages.stream(
        model="claude-opus-4-8",
        max_tokens=1024,
        messages=[
            {"role": "user", "content": "请用中文简要介绍人工智能"}
        ]
    ) as stream:
        for text_block in stream.text_stream:
            print(text_block, end="")
    ```
  </Tab>
</Tabs>

## 高级功能

### 系统提示词

<Tabs>
  <Tab title="字符串格式">
    ```bash theme={null}
    curl -X POST "https://api.mixroute.ai/v1/messages" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -H "anthropic-version: 2023-06-01" \
      -d '{
        "model": "claude-opus-4-8",
        "max_tokens": 1024,
        "system": "你是一个专业的编程助手，擅长解释复杂的技术概念。",
        "messages": [
          {"role": "user", "content": "什么是递归？"}
        ]
      }'
    ```
  </Tab>

  <Tab title="数组格式">
    ```bash theme={null}
    curl -X POST "https://api.mixroute.ai/v1/messages" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -H "anthropic-version: 2023-06-01" \
      -d '{
        "model": "claude-opus-4-8",
        "max_tokens": 1024,
        "system": [
          {
            "type": "text",
            "text": "你是一个专业的编程助手，擅长解释复杂的技术概念。"
          }
        ],
        "messages": [
          {"role": "user", "content": "什么是递归？"}
        ]
      }'
    ```
  </Tab>
</Tabs>

### 扩展思考（Extended Thinking）

<Tabs>
  <Tab title="基础用法">
    ```bash theme={null}
    curl -X POST "https://api.mixroute.ai/v1/messages" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -H "anthropic-version: 2023-06-01" \
      -d '{
        "model": "claude-opus-4-8",
        "max_tokens": 16000,
        "thinking": {
          "type": "enabled",
          "budget_tokens": 10000
        },
        "messages": [
          {"role": "user", "content": "给出一道中等难度的几何题并分步解析"}
        ]
      }'
    ```
  </Tab>

  <Tab title="Python 示例">
    ```python theme={null}
    from anthropic import Anthropic

    client = Anthropic(
        api_key="sk-xxxxxxxxxx",
        base_url="https://api.mixroute.ai"
    )

    with client.messages.stream(
        model="claude-opus-4-8",
        max_tokens=16000,
        thinking={
            "type": "enabled",
            "budget_tokens": 10000
        },
        messages=[
            {"role": "user", "content": "给出一道中等难度的几何题并分步解析"}
        ]
    ) as stream:
        for event in stream:
            if event.type == "content_block_delta":
                if hasattr(event.delta, "thinking"):
                    print(f"[思考] {event.delta.thinking}", end="")
                elif hasattr(event.delta, "text"):
                    print(event.delta.text, end="")
    ```
  </Tab>
</Tabs>

### 工具调用（Tools）

<Tabs>
  <Tab title="函数工具">
    ```bash theme={null}
    curl -X POST "https://api.mixroute.ai/v1/messages" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -H "anthropic-version: 2023-06-01" \
      -d '{
        "model": "claude-opus-4-8",
        "max_tokens": 1024,
        "tools": [
          {
            "name": "get_weather",
            "description": "根据城市获取天气信息",
            "input_schema": {
              "type": "object",
              "properties": {
                "city": {
                  "type": "string",
                  "description": "城市名称"
                }
              },
              "required": ["city"]
            }
          }
        ],
        "messages": [
          {"role": "user", "content": "上海的天气怎么样？"}
        ]
      }'
    ```
  </Tab>

  <Tab title="Claude 官方网页搜索工具">
    ```bash theme={null}
    curl -X POST "https://api.mixroute.ai/v1/messages" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -H "anthropic-version: 2023-06-01" \
      -d '{
        "model": "claude-opus-4-8",
        "max_tokens": 4096,
        "tools": [
          {
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 5
          }
        ],
        "messages": [
          {"role": "user", "content": "最近关于人工智能的新闻有哪些？"}
        ]
      }'
    ```
  </Tab>
</Tabs>

### 多模态输入（图像）

```bash theme={null}
curl -X POST "https://api.mixroute.ai/v1/messages" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-8",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "image",
            "source": {
              "type": "base64",
              "media_type": "image/jpeg",
              "data": "base64_encoded_image_data"
            }
          },
          {
            "type": "text",
            "text": "请描述这张图片"
          }
        ]
      }
    ]
  }'
```

### Prompt Caching（提示词缓存）

通过缓存常用的上下文内容，可以显著降低成本和提升响应速度。缓存内容最小需要 1024 tokens。

<Tabs>
  <Tab title="System 缓存">
    ```bash theme={null}
    curl -X POST "https://api.mixroute.ai/v1/messages" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -H "anthropic-version: 2023-06-01" \
      -d '{
        "model": "claude-opus-4-8",
        "max_tokens": 1024,
        "system": [
          {
            "type": "text",
            "text": "你是专业的文档分析助手。以下是需要分析的文档内容：[长文本内容，至少1024 tokens]",
            "cache_control": {"type": "ephemeral"}
          }
        ],
        "messages": [
          {"role": "user", "content": "请总结文档的主要观点"}
        ]
      }'
    ```
  </Tab>

  <Tab title="Messages 缓存">
    ```bash theme={null}
    curl -X POST "https://api.mixroute.ai/v1/messages" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-xxxxxxxxxx" \
      -H "anthropic-version: 2023-06-01" \
      -d '{
        "model": "claude-opus-4-8",
        "max_tokens": 1024,
        "messages": [
          {
            "role": "user",
            "content": [
              {
                "type": "text",
                "text": "以下是需要分析的代码库：[大量代码内容，至少1024 tokens]",
                "cache_control": {"type": "ephemeral"}
              },
              {
                "type": "text",
                "text": "请找出代码中的潜在问题"
              }
            ]
          }
        ]
      }'
    ```
  </Tab>

  <Tab title="Python SDK 示例">
    ```python theme={null}
    from anthropic import Anthropic

    client = Anthropic(
        api_key="sk-xxxxxxxxxx",
        base_url="https://api.mixroute.ai"
    )

    # System 缓存
    message = client.messages.create(
        model="claude-opus-4-8",
        max_tokens=1024,
        system=[
            {
                "type": "text",
                "text": "你是专业的文档分析助手。以下是需要分析的文档内容：[长文本内容]",
                "cache_control": {"type": "ephemeral"}
            }
        ],
        messages=[
            {"role": "user", "content": "请总结文档的主要观点"}
        ]
    )

    # 查看缓存使用情况
    print(f"缓存创建 tokens: {message.usage.cache_creation_input_tokens}")
    print(f"缓存读取 tokens: {message.usage.cache_read_input_tokens}")
    ```
  </Tab>
</Tabs>

## 响应格式

<Tabs>
  <Tab title="非流式响应">
    ```json theme={null}
    {
      "id": "msg_xxx",
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "text",
          "text": "回复内容..."
        }
      ],
      "model": "claude-opus-4-8",
      "stop_reason": "end_turn",
      "usage": {
        "input_tokens": 25,
        "output_tokens": 100,
        "cache_creation_input_tokens": 0,
        "cache_read_input_tokens": 0
      }
    }
    ```
  </Tab>

  <Tab title="流式响应">
    ```text theme={null}
    event: message_start
    data: {"type":"message_start","message":{"id":"msg_xxx","type":"message","role":"assistant","content":[],"model":"claude-opus-4-8"}}

    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_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":100}}

    event: message_stop
    data: {"type":"message_stop"}
    ```
  </Tab>
</Tabs>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.mixroute.ai/v1/messages \
    --header 'Authorization: Bearer sk-xxxxxxxxxx' \
    --header 'Content-Type: application/json' \
    --header 'anthropic-version: 2023-06-01' \
    --data '{
      "model": "claude-opus-4-8",
      "max_tokens": 1024,
      "messages": [
        {"role": "user", "content": "请用中文简要介绍人工智能"}
      ]
    }'
  ```

  ```python Python theme={null}
  from anthropic import Anthropic

  client = Anthropic(
      api_key="sk-xxxxxxxxxx",
      base_url="https://api.mixroute.ai"
  )

  message = client.messages.create(
      model="claude-opus-4-8",
      max_tokens=1024,
      messages=[
          {"role": "user", "content": "请用中文简要介绍人工智能"}
      ]
  )
  print(message.content[0].text)
  ```

  ```javascript JavaScript theme={null}
  import Anthropic from '@anthropic-ai/sdk';

  const client = new Anthropic({
    apiKey: 'sk-xxxxxxxxxx',
    baseURL: 'https://api.mixroute.ai'
  });

  const message = await client.messages.create({
    model: 'claude-opus-4-8',
    max_tokens: 1024,
    messages: [
      { role: 'user', content: '请用中文简要介绍人工智能' }
    ]
  });
  console.log(message.content[0].text);
  ```

  ```php PHP theme={null}
  <?php
  $client = new GuzzleHttp\Client();
  $response = $client->post('https://api.mixroute.ai/v1/messages', [
      'headers' => [
          'Authorization' => 'Bearer sk-xxxxxxxxxx',
          'Content-Type' => 'application/json',
          'anthropic-version' => '2023-06-01',
      ],
      'json' => [
          'model' => 'claude-opus-4-8',
          'max_tokens' => 1024,
          'messages' => [
              ['role' => 'user', 'content' => '请用中文简要介绍人工智能']
          ]
      ]
  ]);
  echo $response->getBody();
  ```

  ```go Go theme={null}
  package main

  import (
      "bytes"
      "encoding/json"
      "net/http"
  )

  func main() {
      payload := map[string]interface{}{
          "model": "claude-opus-4-8",
          "max_tokens": 1024,
          "messages": []map[string]string{
              {"role": "user", "content": "请用中文简要介绍人工智能"},
          },
      }
      body, _ := json.Marshal(payload)
      req, _ := http.NewRequest("POST", "https://api.mixroute.ai/v1/messages", bytes.NewBuffer(body))
      req.Header.Set("Authorization", "Bearer sk-xxxxxxxxxx")
      req.Header.Set("Content-Type", "application/json")
      req.Header.Set("anthropic-version", "2023-06-01")
      http.DefaultClient.Do(req)
  }
  ```

  ```java Java theme={null}
  import java.net.http.*;
  import java.net.URI;

  HttpClient client = HttpClient.newHttpClient();
  String json = """
      {
          "model": "claude-opus-4-8",
          "max_tokens": 1024,
          "messages": [{"role": "user", "content": "请用中文简要介绍人工智能"}]
      }
      """;
  HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://api.mixroute.ai/v1/messages"))
      .header("Authorization", "Bearer sk-xxxxxxxxxx")
      .header("Content-Type", "application/json")
      .header("anthropic-version", "2023-06-01")
      .POST(HttpRequest.BodyPublishers.ofString(json))
      .build();
  HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
  System.out.println(response.body());
  ```

  ```ruby Ruby theme={null}
  require 'net/http'
  require 'json'

  uri = URI('https://api.mixroute.ai/v1/messages')
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true

  request = Net::HTTP::Post.new(uri)
  request['Authorization'] = 'Bearer sk-xxxxxxxxxx'
  request['Content-Type'] = 'application/json'
  request['anthropic-version'] = '2023-06-01'
  request.body = {
    model: 'claude-opus-4-8',
    max_tokens: 1024,
    messages: [{ role: 'user', content: '请用中文简要介绍人工智能' }]
  }.to_json

  response = http.request(request)
  puts response.body
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "id": "msg_xxx",
    "type": "message",
    "role": "assistant",
    "content": [
      {
        "type": "text",
        "text": "人工智能是研究、开发用于模拟、延伸和扩展人的智能的理论、方法、技术及应用系统的一门新的技术科学..."
      }
    ],
    "model": "claude-opus-4-8",
    "stop_reason": "end_turn",
    "stop_sequence": null,
    "usage": {
      "input_tokens": 25,
      "output_tokens": 100
    }
  }
  ```
</ResponseExample>