> ## Documentation Index
> Fetch the complete documentation index at: https://mixroute.ai/docs/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` 介面。

> [!NOTE]
>
> Claude Sonnet 5.5 預設開啟 adaptive；若需關閉回答前的思考，使用 thinking.type=between\_tools 和 high 或更低的 effort。工具選擇使用 tool\_choice.type=auto，不使用 any/tool；工具迴圈中完整保留思考塊和簽名。複用舊示例前請檢視 [Sonnet 5.5](/docs/zh-Hant/model-api/anthropic/claude-sonnet-5-5) 的模型限制。

## 認證

Bearer Token，如 `Bearer sk-xxxxxxxxxx`

## 請求參數

**model** `string` *required*

Claude 模型識別碼，如 `claude-opus-4-8`

**messages** `array` *required*

對話訊息列表，每個元素包含 `role`（user/assistant）和 `content`

**max\_tokens** `integer` *required*

最大生成 token 數，必須大於 0

**system** `string | array`

系統提示詞，支援字串格式或陣列格式（用於 Prompt Caching）

**stream** `boolean`

是否啟用串流輸出

**temperature** `number`

採樣溫度，範圍 0-1

**top\_p** `number`

核採樣參數，範圍 0-1

**top\_k** `integer`

Top-k 採樣參數

**stop\_sequences** `array`

自訂停止序列

**thinking** `object`

擴展思考設定，包含 `type` 和 `budget_tokens`

**tools** `array`

工具定義列表

## 基礎範例

**非串流請求**

```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": "請用中文簡要介紹人工智慧"}
    ]
  }'
```

**串流請求（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": "請用中文簡要介紹人工智慧"}
    ]
  }'
```

**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="")
```

## 進階功能

### 系統提示詞

**字串格式**

```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": "什麼是遞迴？"}
    ]
  }'
```

**陣列格式**

```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": "什麼是遞迴？"}
    ]
  }'
```

### 擴展思考（Extended Thinking）

**基礎用法**

```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": "給出一道中等難度的幾何題並分步解析"}
    ]
  }'
```

**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="")
```

### 工具呼叫（Tools）

**函式工具**

```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": "上海的天氣怎麼樣？"}
    ]
  }'
```

**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": "最近關於人工智慧的新聞有哪些？"}
    ]
  }'
```

### 多模態輸入（圖像）

```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。

**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": "請總結文件的主要觀點"}
    ]
  }'
```

**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": "請找出程式碼中的潛在問題"
          }
        ]
      }
    ]
  }'
```

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

## 回應格式

**非串流回應**

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

**串流回應**

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

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

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.