# Anthropic 格式

> 使用 LLMoxy 提供的 Anthropic Messages API，呼叫 Claude 模型並支援 x-api-key 鑑權。

LLMoxy 提供完全相容的 Anthropic Messages API 介面，專為 Claude 系列模型最佳化。使用 Anthropic 官方 SDK 的使用者只需修改 `base_url`即可切換。

## Base URL

```txt
https://llmoxy.com/v1
```

## 鑑權方式

支援兩種鑑權方式：

### 方式一：x-api-key（推薦）

```http
x-api-key: YOUR_API_KEY
```

### 方式二：Authorization

```http
Authorization: Bearer YOUR_API_KEY
```

## Messages API

Claude 的核心對話介面。

### 請求地址

```txt
POST /v1/messages
```

### 請求範例

```bash
curl https://llmoxy.com/v1/messages \
-H "content-type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"messages": [
{
"role": "user",
"content": "用Python寫一個二分查找演算法"
}
]
}'
```

### 請求參數

| 參數 | 類型 | 必填 | 說明 |
| --- | --- | --- | --- |
| model | string | 是 | 模型名稱 |
| messages | array | 是 | 對話訊息列表 |
| max_tokens | integer | 是 | 最大生成 token 數 |
| system | string | 否 | 系統提示詞 |
| temperature | number | 否 | 溫度參數，0–1 |
| top_p | number | 否 | 核取樣參數 |
| stream | boolean | 否 | 是否流式輸出 |
| stop_sequences | array | 否 | 停止序列 |

### 訊息格式

與 OpenAI 不同，Anthropic 格式的系統提示詞是獨立參數：

```json
{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"system": "你是一個Python程式設計專家",
"messages": [
{
"role": "user",
"content": "寫一個快速排序"
},
{
"role": "assistant",
"content": "好的，我來寫一個Python的快速排序..."
},
{
"role": "user",
"content": "加上詳細註解"
}
]
}
```

> **注意**
> - messages 中只能包含 `user` 和 `assistant` 角色
> - 必須以 `user` 訊息開頭
> - `user` 和 `assistant` 訊息必須交替出現

### 響應格式

```json
{
"id": "msg_123",
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "這是Claude的回覆內容"
}
],
"model": "claude-opus-5-5",
"stop_reason": "end_turn",
"usage": {
"input_tokens": 25,
"output_tokens": 150
}
}
```

## 流式輸出

設定 `stream: true`啟用流式輸出：

```bash
curl https://llmoxy.com/v1/messages \
-H "content-type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"messages": [{"role": "user", "content": "你好"}],
"stream": true
}'
```

### 流式響應格式

```txt
event: message_start
data: {"type":"message_start","message":{"id":"msg_123",...}}

event: content_block_delta
data: {"type":"content_block_delta","delta":{"type":"text_delta","text":"你"}}

event: content_block_delta
data: {"type":"content_block_delta","delta":{"type":"text_delta","text":"好"}}

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

## 支援的模型

| 模型 | 說明 | 可用分組 |
| --- | --- | --- |
| claude-fable-5-2 | 最強效能 | Claude |
| claude-opus-5-5 | 均衡之選 | Claude |

> **TIP**
> 具體可用模型以 [官網模型廣場](https://llmoxy.com/) 為準。

## 多模態支援

Claude 支援圖像輸入：

```json
{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"messages": [
{
"role": "user",
"content": [
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/jpeg",
"data": "/9j/4AAQSkZJRg..."
}
},
{
"type": "text",
"text": "這張圖片裡有什麼？"
}
]
}
]
}
```

支援的圖片格式：JPEG、PNG、GIF、WebP，單張最大 5MB。

## 程式碼範例

### Python（官方 SDK）

```python
from anthropic import Anthropic

client = Anthropic(
api_key="YOUR_API_KEY",
base_url="https://llmoxy.com/v1"
)

message = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[
{"role": "user", "content": "寫一個Python裝飾器"}
]
)

print(message.content[0].text)
```

### Python（流式）

```python
with client.messages.stream(
model="claude-opus-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": "寫一篇文章"}]
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)
```

### Node.js（官方 SDK）

```js
import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({
apiKey: 'YOUR_API_KEY',
baseURL: 'https://llmoxy.com/v1'
});

const message = await client.messages.create({
model: 'claude-opus-5-5',
max_tokens: 1024,
messages: [
{ role: 'user', content: '寫一個快速排序' }
]
});

console.log(message.content[0].text);
```

### cURL

```bash
curl https://llmoxy.com/v1/messages \
-H "content-type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "Hello, Claude!"}
]
}'
```

## 錯誤處理

### 錯誤響應格式

```json
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "錯誤描述"
}
}
```

### 常見錯誤類型

| 錯誤類型 | 說明 |
| --- | --- |
| invalid_request_error | 請求參數錯誤 |
| authentication_error | 鑑權失敗 |
| permission_error | 權限不足 |
| not_found_error | 資源不存在 |
| rate_limit_error | 請求頻率超限 |
| api_error | 內部錯誤 |
| overloaded_error | 服務過載 |

### 錯誤處理範例

```python
from anthropic import Anthropic, APIError

client = Anthropic(
api_key="YOUR_API_KEY",
base_url="https://llmoxy.com/v1"
)

try:
message = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello"}]
)
except APIError as e:
print(f"錯誤類型: {e.type}")
print(f"錯誤訊息: {e.message}")
```

## 進階用法

### 1. 系統提示詞

```python
message = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
system="你是一個Python專家，擅長資料分析和機器學習。",
messages=[
{"role": "user", "content": "如何使用pandas處理缺失值？"}
]
)
```

### 2. 多輪對話

```python
conversation = [
{"role": "user", "content": "寫一個使用者類別"},
{"role": "assistant", "content": "好的，我來寫一個User類別..."},
{"role": "user", "content": "加上密碼加密功能"}
]

message = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=conversation
)
```

### 3. 圖像分析

```python
import base64

with open("image.jpg", "rb") as f:
image_data = base64.b64encode(f.read()).decode()

message = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": [
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/jpeg",
"data": image_data
}
},
{
"type": "text",
"text": "分析這張架構圖"
}
]
}
]
)
```

## 最佳實踐

### 1. 合理設定 max_tokens

不同模型的最大輸出不同：Opus 32K、Sonnet 64K、Haiku 8K。根據實際需要設定，避免浪費。

### 2. 使用 system 參數設定提示詞

將角色定義放在 `system`參數中，而非 messages 裡：

```python
# ✅ 推薦
message = client.messages.create(
system="你是一個Python專家",
messages=[{"role": "user", "content": "寫程式碼"}],
...
)

# ❌ 不推薦
message = client.messages.create(
messages=[{"role": "user", "content": "你是Python專家。寫程式碼"}],
...
)
```

### 3. 處理長對話

Claude 擁有 200K 上下文視窗，但建議定期總結對話、移除不重要的歷史訊息，以節省 Token 消耗。

### 4. 實現重試機制

```python
from tenacity import retry, stop_after_attempt, wait_exponential

@retry(
stop=stop_after_attempt(3),
wait=wait_exponential(multiplier=1, min=4, max=10)
)
def call_claude():
return client.messages.create(...)
```

## 下一步

- [分組與計價](https://tw.llmoxy.com/docs/get-started/recharge-and-pricing) — 了解費用詳情
- [取得支援](mailto:contact@llmoxy.com) — 遇到問題聯絡我們

本文是 https://tw.llmoxy.com/docs/api-reference/anthropic-format 的 markdown 版本。
