Python中Claude API入門指南

本文是一份面向Python開發者的Claude API實用指南。你將學習如何從零開始設置環境、發送第一個請求，並掌握響應處理、系統提示和流式傳輸等關鍵概念，為構建生產級應用打下基礎。

環境準備與安裝

首先，你需要Python 3.9或更高版本，以及一個免費的Claude Console賬户。在Console的Settings > API Keys頁面生成API密鑰，並建議添加至少5美元的信用額度。安裝官方SDK只需一行命令：pip install anthropic。

務必通過環境變量管理API密鑰，而非硬編碼在代碼中。在終端執行export ANTHROPIC_API_KEY="YOUR-API-KEY-HERE"，或者使用python-dotenv將其寫入.env文件。SDK會自動從環境變量中讀取密鑰。

首次API調用

所有交互的入口是client.messages.create()方法。你需要提供三個參數：模型ID、max_tokens限制和消息列表。消息列表由字典組成，每個字典包含"role"和"content"鍵。

以下代碼讓Claude用一句話解釋“上下文窗口”：

import anthropic client = anthropic.Anthropic() response = client.messages.create( model="claude-sonnet-5", max_tokens=256, messages=[ {"role": "user", "content": "用一句話解釋什麼是上下文窗口？"} ] ) print(response.content[0].text)

max_tokens是輸出令牌數的硬上限，建議根據任務需求設置足夠大。消息列表必須以"user"角色開頭。

理解響應對象

messages.create()返回一個Message對象，包含多個重要字段：

• id: 消息唯一標識
• type: 固定為'message'
• role: 固定為'assistant'
• content: 文本塊列表（通常只有一個TextBlock）
• model: 使用的模型
• stop_reason: 停止原因，'end_turn'表示正常結束，'max_tokens'表示被限制截斷
• stop_sequence: 停止序列（通常為None）
• usage: 包含input_tokens和output_tokens，用於計費監控

通過response.content[0].text即可提取生成的文本。

使用系統提示

系統提示允許你為Claude設置持久角色、約束或上下文。通過最頂層的system參數傳入，而非放在消息列表中。例如：

response = client.messages.create( model="claude-sonnet-5", max_tokens=512, system="你是一名Python代碼審查員。僅回覆改進後的Python代碼，除非用户明確要求，否則不要解釋改動。", messages=[ {"role": "user", "content": "def get_user(id):\n db = connect()\n return db.query('SELECT * FROM users WHERE id=' + id)"} ] ) print(response.content[0].text)

系統提示在整個對話中保持權威性，因此角色指令、格式規則等只需設定一次。

流式響應

對於耗時較長的請求，流式傳輸可讓用户實時看到輸出。SDK通過client.messages.stream()實現，作為上下文管理器使用：

with client.messages.stream( model="claude-sonnet-5", max_tokens=512, messages=[ {"role": "user", "content": "請逐步説明Python列表容量不足時發生了什麼？"} ] ) as stream: for chunk in stream.text_stream: print(chunk, end="", flush=True)

上下文管理器確保連接正確關閉。如需獲取完整的Message對象（包含令牌計數），可在塊結束前調用stream.get_final_message()。

下一步

現在你已經掌握了核心概念：請求、結構化響應、系統提示和流式傳輸。接下來可以學習錯誤處理、令牌使用優化和多輪對話。由於API是無狀態的，每次請求都需要發送完整對話歷史。官方文檔提供了推薦做法。

API參考中還包含結構化輸出和工具使用等功能。祝探索愉快！