什麼是 Anthropic Messages API

Anthropic Messages API（端點路徑為 /v1/messages）是 Anthropic 官方提供的 RESTful API，用於與 Claude 系列模型進行對話互動。它採用「訊息」的結構來組織對話，每個請求包含一組 messages 陣列，Claude 會根據對話脈絡生成回應。

與直接使用 Claude 網頁介面或 Claude Code CLI 不同，Messages API 讓開發者能以程式化的方式呼叫 Claude，適合以下場景：

• 應用程式整合：在你的 Web App、Mobile App 或後端服務中嵌入 AI 功能
• 自動化工作流：搭配 CI/CD、排程任務或事件驅動架構進行批次處理
• 客製化體驗：透過 System Prompt 與參數調校，打造專屬的 AI 互動行為
• 多模態處理：傳送圖片、PDF 等非文字內容給 Claude 進行分析

API Key 取得與設定

取得 API Key

要使用 Anthropic Messages API，首先需要在 Anthropic Console 註冊帳號並建立 API Key：

1. 前往 console.anthropic.com 並完成註冊
2. 進入 Settings → API Keys 頁面
3. 點擊 Create Key，輸入名稱後產生金鑰
4. 立即複製並安全保存（金鑰只會顯示一次）

設定環境變數

取得 API Key 後，建議將它設定為環境變數，避免在程式碼中明文儲存：

# Linux / macOS
export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxxxxxxxxxxx"

# Windows PowerShell
$env:ANTHROPIC_API_KEY = "sk-ant-api03-xxxxxxxxxxxxxxxx"

# 或寫入 .env 檔案（搭配 dotenv 套件使用）
ANTHROPIC_API_KEY=sk-ant-api03-xxxxxxxxxxxxxxxx

⚠️ 安全提醒：永遠不要將 API Key 提交到 Git 儲存庫。請確保 .env 檔案已加入 .gitignore。

Messages API 基本呼叫

使用 curl 呼叫

最基本的方式是透過 curl 直接發送 HTTP 請求：

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-6-20250514",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": "請用一句話解釋什麼是 API"
      }
    ]
  }'

其中 anthropic-version 是必要的 Header，用於指定 API 版本。目前最新的穩定版本為 2023-06-01。

使用 Python SDK

Anthropic 官方提供了 Python SDK，讓呼叫更加簡潔：

# 安裝 SDK
pip install anthropic

# 基本呼叫
import anthropic

client = anthropic.Anthropic()  # 自動讀取 ANTHROPIC_API_KEY 環境變數

message = client.messages.create(
    model="claude-sonnet-4-6-20250514",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "請用一句話解釋什麼是 API"}
    ]
)

print(message.content[0].text)

使用 TypeScript SDK

前端或 Node.js 開發者可以使用 TypeScript SDK：

// 安裝 SDK
npm install @anthropic-ai/sdk

// 基本呼叫
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();  // 自動讀取 ANTHROPIC_API_KEY 環境變數

const message = await client.messages.create({
  model: "claude-sonnet-4-6-20250514",
  max_tokens: 1024,
  messages: [
    { role: "user", content: "請用一句話解釋什麼是 API" }
  ],
});

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

請求與回應格式

請求格式（Request）

一個完整的 Messages API 請求包含以下欄位：

回應格式（Response）

成功的 API 回應範例如下：

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "API（Application Programming Interface）是一組定義好的規則和協議，讓不同的軟體系統之間能夠互相溝通和交換資料。"
    }
  ],
  "model": "claude-sonnet-4-6-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 22,
    "output_tokens": 65,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0
  }
}

回應中的 usage 欄位特別重要，它記錄了此次請求消耗的 Token 數量，直接關係到 API 費用。stop_reason 則告訴你 Claude 停止生成的原因，常見值包括 end_turn（正常結束）、max_tokens（達到上限）和 stop_sequence（遇到停止序列）。

模型選擇

Anthropic 目前提供三個主要的 Claude 模型系列，各有不同的定位與適用場景：

選擇模型時，建議從 Claude Sonnet 4.6 開始，它在效能與成本之間取得了很好的平衡。如果需要處理高度複雜的任務（如大型程式碼分析、學術研究），再升級到 Opus；若追求極致速度與低成本，則可以選擇 Haiku。

Streaming 串流回應

預設情況下，Messages API 會等到 Claude 生成完整回應後才回傳結果。對於較長的回應，這可能需要等待數秒。串流（Streaming）模式可以讓回應即時逐步回傳，大幅提升使用者體驗。

Python 串流範例

import anthropic

client = anthropic.Anthropic()

# 使用 stream 參數
with client.messages.stream(
    model="claude-sonnet-4-6-20250514",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "請詳細解釋 RESTful API 的設計原則"}
    ]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

TypeScript 串流範例

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const stream = client.messages.stream({
  model: "claude-sonnet-4-6-20250514",
  max_tokens: 1024,
  messages: [
    { role: "user", content: "請詳細解釋 RESTful API 的設計原則" }
  ],
});

for await (const event of stream) {
  if (event.type === "content_block_delta" && event.delta.type === "text_delta") {
    process.stdout.write(event.delta.text);
  }
}

串流模式在以下場景特別有用：聊天介面需要即時顯示回應、長文本生成需要給使用者即時回饋、以及需要在回應過程中進行前端處理的應用。

多模態輸入：圖片與 PDF

Claude 不只能處理文字，還支援圖片和 PDF 等多模態輸入。你可以透過 Base64 編碼或 URL 的方式傳送圖片，讓 Claude 進行視覺理解與分析。

傳送圖片

import anthropic
import base64

client = anthropic.Anthropic()

# 方法一：Base64 編碼
with open("screenshot.png", "rb") as f:
    image_data = base64.standard_b64encode(f.read()).decode("utf-8")

message = client.messages.create(
    model="claude-sonnet-4-6-20250514",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": "image/png",
                        "data": image_data
                    }
                },
                {
                    "type": "text",
                    "text": "請描述這張圖片的內容"
                }
            ]
        }
    ]
)

# 方法二：URL 方式
message = client.messages.create(
    model="claude-sonnet-4-6-20250514",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://example.com/image.png"
                    }
                },
                {
                    "type": "text",
                    "text": "這張圖表顯示了什麼趨勢？"
                }
            ]
        }
    ]
)

傳送 PDF 文件

Claude 也支援 PDF 文件的解析與理解：

import anthropic
import base64

client = anthropic.Anthropic()

with open("report.pdf", "rb") as f:
    pdf_data = base64.standard_b64encode(f.read()).decode("utf-8")

message = client.messages.create(
    model="claude-sonnet-4-6-20250514",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {
                        "type": "base64",
                        "media_type": "application/pdf",
                        "data": pdf_data
                    }
                },
                {
                    "type": "text",
                    "text": "請摘要這份文件的重點"
                }
            ]
        }
    ]
)

支援的圖片格式包括 JPEG、PNG、GIF、WebP，單張圖片建議不超過 5MB。PDF 文件則支援最多數百頁的內容。

System Prompt：定義 Claude 的行為

System Prompt 是控制 Claude 回應風格、角色設定與行為規範的核心機制。它會在對話開始前設定 Claude 的「角色」，影響後續所有回應的風格與內容。

import anthropic

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-sonnet-4-6-20250514",
    max_tokens=1024,
    system="你是一位資深的台灣軟體工程師，專精於 Python 和 TypeScript。回答時請使用繁體中文，並提供實際的程式碼範例。遇到最佳實踐相關的問題時，請同時說明為什麼這樣做比較好。",
    messages=[
        {"role": "user", "content": "如何在 Python 中安全地處理 API 金鑰？"}
    ]
)

善用 System Prompt 的幾個技巧：明確定義角色與專業領域、指定回應的語言和格式、設定安全邊界限制回應範圍、以及提供特定的指示來引導輸出品質。

Temperature 與 Max Tokens

Temperature（溫度）

temperature 控制回應的隨機性與創造性，範圍從 0.0 到 1.0：

Max Tokens

max_tokens 是必填參數，用於限制 Claude 回應的最大長度。這一點與 OpenAI API 不同，Anthropic 要求開發者必須明確指定此值。

# 不同場景的 max_tokens 建議值
# 簡短回答（分類、是否判斷）：256 ~ 512
# 一般對話：1024 ~ 2048
# 長文生成（文章、報告）：4096 ~ 8192
# 完整程式碼生成：8192 ~ 16384

message = client.messages.create(
    model="claude-sonnet-4-6-20250514",
    max_tokens=4096,
    temperature=0.3,  # 較低溫度適合技術內容
    messages=[
        {"role": "user", "content": "請撰寫一個 FastAPI 的 CRUD 範例"}
    ]
)

注意：如果回應被截斷（stop_reason 為 max_tokens），表示你設定的值太小。可以透過檢查 stop_reason 來判斷是否需要調高。

錯誤處理

在生產環境中使用 API 時，完善的錯誤處理至關重要。以下是常見的錯誤類型與處理方式：

Python 錯誤處理範例

import anthropic
import time

client = anthropic.Anthropic()

def call_claude_with_retry(messages, max_retries=3):
    """帶有重試機制的 API 呼叫"""
    for attempt in range(max_retries):
        try:
            response = client.messages.create(
                model="claude-sonnet-4-6-20250514",
                max_tokens=1024,
                messages=messages
            )
            return response
        except anthropic.RateLimitError:
            wait_time = 2 ** attempt  # 指數退避：1, 2, 4 秒
            print(f"速率限制，等待 {wait_time} 秒後重試...")
            time.sleep(wait_time)
        except anthropic.APIStatusError as e:
            print(f"API 錯誤 {e.status_code}: {e.message}")
            if e.status_code >= 500:
                time.sleep(2 ** attempt)
                continue
            raise  # 4xx 錯誤不重試
        except anthropic.APIConnectionError:
            print("連線失敗，檢查網路狀態...")
            time.sleep(2 ** attempt)
    
    raise Exception("已達最大重試次數")

# 使用範例
result = call_claude_with_retry([
    {"role": "user", "content": "Hello, Claude!"}
])

費用計算

Anthropic API 採用按量付費（Pay-as-you-go）模式，依照輸入與輸出的 Token 數量分別計費。以下是截至 2026 年的最新定價：

費用估算範例

假設使用 Claude Sonnet 4.6，一次對話輸入 1,000 tokens、輸出 500 tokens，則費用為：

# 費用計算公式
# 費用 = (輸入 tokens × 輸入單價) + (輸出 tokens × 輸出單價)

# 範例：Claude Sonnet 4.6
input_tokens = 1000
output_tokens = 500

input_cost = (input_tokens / 1_000_000) * 3.00   # $0.003
output_cost = (output_tokens / 1_000_000) * 15.00  # $0.0075
total_cost = input_cost + output_cost               # $0.0105

# 每次對話約 $0.01（不到新台幣 1 元）
# 每天 100 次對話 ≈ $1.05/天 ≈ 約 NT$34/天

節省成本的技巧

• Prompt Caching：啟用快取功能，重複使用的 System Prompt 或長文本可節省最高 90% 的輸入成本
• Batch API：使用批次 API 處理非即時任務，可享 50% 折扣
• 選擇合適的模型：不需要最強能力時，使用 Haiku 可大幅降低成本
• 精簡 Prompt：避免在每次請求中傳送不必要的上下文
• 設定合理的 max_tokens：根據實際需求設定，避免浪費

多輪對話

Messages API 透過 messages 陣列來管理對話歷史。每次請求時，你需要將完整的對話紀錄傳送給 API，Claude 才能理解上下文：

import anthropic

client = anthropic.Anthropic()

# 維護對話歷史
conversation = []

def chat(user_message):
    """多輪對話函式"""
    conversation.append({
        "role": "user",
        "content": user_message
    })
    
    response = client.messages.create(
        model="claude-sonnet-4-6-20250514",
        max_tokens=1024,
        system="你是一位友善的繁體中文 AI 助理。",
        messages=conversation
    )
    
    assistant_message = response.content[0].text
    conversation.append({
        "role": "assistant",
        "content": assistant_message
    })
    
    return assistant_message

# 多輪對話範例
print(chat("我想學 Python，該從哪裡開始？"))
print(chat("你剛才提到的第一點，可以再詳細說明嗎？"))
print(chat("有推薦的學習資源嗎？"))

注意：每次請求都會將完整的對話歷史作為輸入 Token 計費，因此長對話的成本會逐漸增加。在生產環境中，建議實作對話長度的管理機制，例如定期摘要或截斷較舊的訊息。

延伸閱讀

本篇文章涵蓋了 Anthropic Messages API 的基礎使用方式。要更深入地掌握 API 的各項功能，以下資源值得進一步探索：

• Anthropic Messages API 官方文件 — 完整的 API 參考與參數說明
• Messages API 範例集 — 官方提供的各種使用情境範例
• Python SDK GitHub — 官方 Python SDK 原始碼與文件
• TypeScript SDK GitHub — 官方 TypeScript SDK 原始碼與文件
• Tool Use（Function Calling） — 讓 Claude 呼叫外部工具的進階功能
• Prompt Caching — 快取機制的詳細說明與最佳實踐

總結

Anthropic Messages API 提供了一套設計清晰、功能完整的介面來與 Claude 模型互動。從最基本的文字對話、串流回應、多模態輸入，到 System Prompt 的角色設定與參數調校，每個功能都有其明確的使用場景。

對於剛入門的開發者，建議按照以下步驟開始：先在 Anthropic Console 取得 API Key，使用 Python 或 TypeScript SDK 發送第一個請求，觀察回應結構與 Token 使用量，然後逐步加入 System Prompt、調整 Temperature，最後根據實際需求啟用串流或多模態功能。

隨著你對 API 越來越熟悉，可以進一步探索 Tool Use（Function Calling）、Prompt Caching、Batch API 等進階功能，打造更強大且更具成本效益的 AI 應用。

ㄚ槌

blog.che-ya.com