Claude API Python 入門：安裝 SDK、第一個請求、流式輸出與多輪對話

本文根據 Claude API 官方文檔（快速開始、Python SDK、Working with messages、Streaming）整理，核對日期 2026-10-07。示例代碼基於官方示例改寫；模型 ID 會更新，以官方 Models overview 為準。

適用於誰

• 會一點 Python，想在自己的腳本或後端裏調用 Claude 的開發者；
• 搜「claude api python」「python sdk example」「tutorial」的人；
• 從 OpenAI API 遷移過來，想知道 Claude 的寫法有什麼不同的人。

還沒有 API Key 的，先看本站《Claude API Key 怎麼獲取：Claude Console 創建密鑰、充值與用量查看》。

結論先說

1. 安裝：pip install anthropic，要求 Python 3.10 及以上。
2. 把 API Key 設成環境變量 ANTHROPIC_API_KEY，SDK 會自動讀取，代碼裏不用寫密鑰。
3. 核心只有一個調用：client.messages.create(model=..., max_tokens=..., messages=[...])；max_tokens 是必填的。
4. Messages API 是無狀態的：多輪對話要每次把完整歷史一起發過去。
5. 回覆在 message.content（一個內容塊列表）裏，用量在 message.usage 裏；長回覆用流式輸出體驗更好。

步驟

1. 準備環境

bash
export ANTHROPIC_API_KEY="你的API Key"     # Windows PowerShell: $env:ANTHROPIC_API_KEY="你的API Key"

mkdir claude-quickstart && cd claude-quickstart
python3 -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install anthropic

官方建議本地開發時可以用 python-dotenv 把密鑰放進 .env 文件，並確保 .env 不進版本控制。

2. 第一個請求

新建 quickstart.py：

python
import anthropic

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

message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1000,
    messages=[
        {"role": "user", "content": "用三句話解釋什麼是向量數據庫"}
    ],
)

for block in message.content:
    if block.type == "text":
        print(block.text)

print(message.usage)        # 例如 Usage(input_tokens=25, output_tokens=180)
print(message.stop_reason)  # end_turn 表示正常結束；max_tokens 表示被長度上限截斷

運行 python quickstart.py。要點：

• content 是一個內容塊列表，普通回答是 type == "text" 的塊；用到工具、思考等功能時還會出現其他類型的塊，所以按類型取文本更穩妥；
• stop_reason 是 max_tokens 時說明回答被截斷了，調大 max_tokens 或讓模型寫短一點。

3. 加上系統提示詞（system）

系統提示詞用頂層的 system 參數，不放進 messages：

python
message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    system="你是一名耐心的 Python 老師，回答要配一個最小可運行的例子，用中文回答。",
    messages=[{"role": "user", "content": "列表推導式怎麼用？"}],
)

4. 多輪對話：每次發送完整歷史

官方說明 Messages API 是無狀態的，伺服器不記得上一輪說了什麼，你要自己儲存歷史，每次連同新問題一起發送（user 和 assistant 交替）：

python
messages = [
    {"role": "user", "content": "你好，Claude"},
    {"role": "assistant", "content": "你好！有什麼可以幫你？"},
    {"role": "user", "content": "能給我介紹一下大語言模型嗎？"},
]
reply = client.messages.create(model="claude-opus-5-5", max_tokens=1024, messages=messages)

一個可以直接運行的命令行聊天小程式（示例代碼）：

python
import anthropic

client = anthropic.Anthropic()
history = []

while True:
    user_input = input("你：").strip()
    if user_input in ("exit", "quit"):
        break
    history.append({"role": "user", "content": user_input})

    reply = client.messages.create(
        model="claude-opus-5-5",
        max_tokens=1024,
        system="你是一個簡潔的中文助手。",
        messages=history,
    )
    text = "".join(b.text for b in reply.content if b.type == "text")
    print("Claude：", text)
    history.append({"role": "assistant", "content": text})

歷史越長，每次請求的輸入 token 越多、費用越高。長對話可以考慮只保留最近若干輪，或者用提示詞緩存降低重複部分的成本（詳見本站《Claude 提示詞緩存（Prompt Caching）入門：緩存時間、價格倍率與命中率》）。

5. 流式輸出

回覆較長時，用流式輸出邊生成邊顯示。SDK 提供了更方便的 messages.stream 幫助方法：

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)
    print()
    final = stream.get_final_message()   # 結束後拿到完整的 message 對象
    print(final.usage)

也可以用 client.messages.create(..., stream=True) 自己遍歷原始事件，內存佔用更小，但不會幫你拼出最終消息。

6. 異步調用

python
import asyncio
from anthropic import AsyncAnthropic

client = AsyncAnthropic()

async def main():
    message = await client.messages.create(
        model="claude-opus-5-5",
        max_tokens=1024,
        messages=[{"role": "user", "content": "你好"}],
    )
    print(message.content)

asyncio.run(main())

7. 錯誤處理、重試與超時

python
import anthropic

try:
    message = client.messages.create(
        model="claude-opus-5-5",
        max_tokens=1024,
        messages=[{"role": "user", "content": "你好"}],
    )
except anthropic.APIConnectionError as e:
    print("連不上伺服器", e.__cause__)
except anthropic.RateLimitError:
    print("觸發速率限制（429），稍後重試")
except anthropic.APIStatusError as e:
    print("其他錯誤", e.status_code)

官方 SDK 的預設行為：連接錯誤、408、409、429 和 5xx 預設自動重試 2 次（指數退避），可以用 Anthropic(max_retries=0) 修改；請求預設超時 10 分鐘，可以用 Anthropic(timeout=20.0) 修改。每個響應都有 _request_id，反饋問題時附上它。

從 OpenAI 遷移要注意的幾點

• 系統提示詞用頂層 system 參數，而不是 role: "system" 的第一條消息（官方說明 system 消息不能作為 messages 的第一條）；
• max_tokens 必填；
• 回覆是內容塊列表，不是單個字符串；
• 官方說明 Claude 4.6 及以後的模型不支持「預填充（prefill）回覆開頭」，用了會返回 400 錯誤，需要固定輸出格式時改用結構化輸出或在系統提示詞裏說明。

常見問題

Q：報 401 / AuthenticationError？

API Key 沒設定、寫錯或已被刪除。確認環境變量 ANTHROPIC_API_KEY 在運行腳本的終端裏生效（新開的終端要重新設定）。

Q：報「credit balance is too low」之類的錯誤？

Console 的預付費額度用完了，到 Console 的 Settings → Billing 補充。

Q：模型名該寫什麼？

用官方 Models overview 頁列出的 API ID。各模型的定位和區別詳見本站《Claude 模型有哪些、有什麼區別：Opus、Sonnet、Haiku 怎麼選（2026）》。

Q：想讓 Claude 調用我自己的函數怎麼辦？

用工具調用（Tool Use），詳見本站《Claude Tool Use（工具調用 / Function Calling）入門：定義工具與返回 tool_result》。想做能自己讀文件、跑命令的智能體，可以看 Claude Agent SDK。

Q：Claude API 在中國大陸能用嗎？

Claude API 只在 Anthropic 支持的國家和地區提供，中國大陸目前不在列表中（https://www.anthropic.com/supported-countries ），請遵守所在地法律和服務條款。

參考資料

• Get started with Claude（官方）：https://platform.claude.com/docs/en/get-started
• Python SDK（官方）：https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/python
• Working with the Messages API（官方）：https://platform.claude.com/docs/en/build-with-claude/working-with-messages
• Streaming messages（官方）：https://platform.claude.com/docs/en/build-with-claude/streaming
• Models overview（官方）：https://platform.claude.com/docs/en/about-claude/models/overview