> ## 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>