本指南旨在為 Claude 提供使用 Claude API 的基礎知識。內容涵蓋模型 ID/基本 messages API、工具使用、串流、擴展思考的說明與範例,僅此而已。
Smartest model: Claude Opus 4.8: claude-opus-4-8
Smart model: Claude Sonnet 4.6: claude-sonnet-4-6
For fast, cost-effective tasks: Claude Haiku 4.5: claude-haiku-4-5-20251001import anthropic
import os
message = anthropic.Anthropic(
api_key=os.environ.get("ANTHROPIC_API_KEY")
).messages.create(
model="claude-opus-4-8",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message){
"id": "msg_01XFDUDYJgAACzvnptvVoYEL",
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "Hello!"
}
],
"model": "claude-opus-4-8",
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 12,
"output_tokens": 6
}
}Messages API 是無狀態的,這表示您每次都必須將完整的對話歷史傳送給 API。您可以使用此模式隨時間建立對話。較早的對話輪次不一定需要實際來自 Claude,您可以使用合成的 assistant 訊息。
import anthropic
message = anthropic.Anthropic().messages.create(
model="claude-opus-4-8",
max_tokens=1024,
messages=[
{"role": "user", "content": "Hello, Claude"},
{"role": "assistant", "content": "Hello!"},
{"role": "user", "content": "Can you describe LLMs to me?"},
],
)
print(message)您可以在輸入訊息清單的最後一個位置預先填入 Claude 回應的一部分。這可用於引導 Claude 的回應。以下範例使用 "max_tokens": 1 來從 Claude 取得單一選擇題答案。
message = anthropic.Anthropic().messages.create(
model="claude-sonnet-4-5",
max_tokens=1,
messages=[
{
"role": "user",
"content": "What is latin for Ant? (A) Apoidea, (B) Rhopalocera, (C) Formicidae",
},
{"role": "assistant", "content": "The answer is ("},
],
)
print(message.content[0].text)Claude 可以在請求中讀取文字和圖片。圖片支援 base64 和 url 兩種來源類型,以及 image/jpeg、image/png、image/gif 和 image/webp 媒體類型。
「Extended thinking」(擴展思考)有時可以幫助 Claude 處理非常困難的任務。在 Claude Opus 4.7 之前的模型上,啟用擴展思考時必須將 temperature 設為 1。
以下模型支援擴展思考:
claude-opus-4-7)claude-opus-4-6)claude-opus-4-5-20251101)claude-sonnet-4-6)claude-sonnet-4-5-20250929)claude-haiku-4-5-20251001)在 Claude Opus 4.8 和 Claude Opus 4.7 上,不支援手動擴展思考(type: enabled 搭配 budget_tokens 值),會回傳 400 錯誤。請改用自適應思考(type: adaptive)。
當擴展思考開啟時,Claude 會建立 thinking 內容區塊,在其中輸出其內部推理。API 回應將包含 thinking 內容區塊,後接 text 內容區塊。
import anthropic
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-4-8",
max_tokens=16000,
thinking={"type": "adaptive", "display": "summarized"},
messages=[
{
"role": "user",
"content": "Are there an infinite number of prime numbers such that n mod 4 == 3?",
}
],
)
# 回應將包含摘要後的思考區塊與文字區塊
for block in response.content:
if block.type == "thinking":
print(f"\nThinking summary: {block.thinking}")
elif block.type == "text":
print(f"\nResponse: {block.text}")使用手動擴展思考(type: enabled)時,budget_tokens 參數決定 Claude 可用於其內部推理過程的最大 token 數量。在 Claude 4 及更新的模型中,此限制適用於完整的思考 token,而非摘要輸出。較大的預算可透過對複雜問題進行更徹底的分析來提升回應品質。除非您使用交錯思考,否則 budget_tokens 必須小於 max_tokens,以便 Claude 在思考完成後有空間撰寫其回應。
擴展思考可與「tool use」(工具使用)一起使用,讓 Claude 能夠推理工具選擇和結果處理。
重要限制:
tool_choice: {"type": "auto"}(預設)或 tool_choice: {"type": "none"}。thinking 區塊傳回給 API。Claude 4 模型中的擴展思考搭配工具使用支援「interleaved thinking」(交錯思考),讓 Claude 能夠在工具呼叫之間進行思考。若要在 Claude 4、4.5 和 Sonnet 4.6 模型上啟用,請在您的 API 請求中加入 beta 標頭 interleaved-thinking-2025-05-14。
使用交錯思考時(且僅限交錯思考,不適用於一般擴展思考),budget_tokens 可以超過 max_tokens 參數,因為在此情況下 budget_tokens 代表單一 assistant 輪次內所有思考區塊的總預算。
對於 Claude Opus 4.8、Claude Opus 4.7 和 Claude Opus 4.6,使用自適應思考(thinking: {type: "adaptive"})時會自動啟用交錯思考,不需要 beta 標頭。Sonnet 4.6 同時支援搭配手動擴展思考的 interleaved-thinking-2025-05-14 beta 標頭以及自適應思考。
用戶端工具在 API 請求的 tools 頂層參數中指定。每個工具定義包含:
| 參數 | 說明 |
|---|---|
name | 工具的名稱。必須符合正規表示式 ^[a-zA-Z0-9_-]{1,64}$。 |
description | 工具功能、使用時機及行為方式的詳細純文字說明。 |
input_schema | 定義工具預期參數的 JSON Schema 物件。 |
{
"name": "get_weather",
"description": "Get the current weather in a given location",
"input_schema": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA"
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"],
"description": "The unit of temperature, either 'celsius' or 'fahrenheit'"
}
},
"required": ["location"]
}
}提供極為詳細的說明。 這是影響工具效能最重要的因素。您的說明應解釋工具的每個細節,包括:
對於複雜的工具,請考慮使用 input_examples。 對於具有巢狀物件、選用參數或格式敏感輸入的工具,您可以使用 input_examples 欄位(beta)提供具體範例。這有助於 Claude 理解預期的輸入模式。詳情請參閱提供工具使用範例。
良好工具說明的範例:
{
"name": "get_stock_price",
"description": "Retrieves the current stock price for a given ticker symbol. The ticker symbol must be a valid symbol for a publicly traded company on a major US stock exchange like NYSE or NASDAQ. The tool will return the latest trade price in USD. It should be used when the user asks about the current or most recent price of a specific stock. It will not provide any other information about the stock or company.",
"input_schema": {
"type": "object",
"properties": {
"ticker": {
"type": "string",
"description": "The stock ticker symbol, e.g. AAPL for Apple Inc."
}
},
"required": ["ticker"]
}
}您可以透過在 tool_choice 欄位中指定工具,強制 Claude 使用特定工具:
tool_choice = {"type": "tool", "name": "get_weather"}使用 tool_choice 參數時,有四個可能的選項:
auto 允許 Claude 決定是否呼叫任何提供的工具(預設)。any 告訴 Claude 必須使用其中一個提供的工具。tool 強制 Claude 始終使用特定工具。none 阻止 Claude 使用任何工具。工具不一定需要是用戶端函式。每當您希望模型回傳遵循所提供結構描述的 JSON 輸出時,都可以使用工具。
使用工具時,Claude 通常會展示其「chain of thought」(思維鏈),也就是它用來分解問題並決定使用哪些工具的逐步推理。
{
"role": "assistant",
"content": [
{
"type": "text",
"text": "<thinking>To answer this question, I will: 1. Use the get_weather tool to get the current weather in San Francisco. 2. Use the get_time tool to get the current time in the America/Los_Angeles timezone, which covers San Francisco, CA.</thinking>"
},
{
"type": "tool_use",
"id": "toolu_01A09q90qw90lq917835lq9",
"name": "get_weather",
"input": { "location": "San Francisco, CA" }
}
]
}預設情況下,Claude 可能會使用多個工具來回答使用者查詢。您可以透過設定 disable_parallel_tool_use=true 來停用此行為。
回應將具有 tool_use 的 stop_reason,以及一個或多個 tool_use 內容區塊,其中包含:
id:此特定工具使用區塊的唯一識別碼。name:正在使用的工具名稱。input:包含傳遞給工具之輸入的物件。當您收到工具使用回應時,您應該:
tool_use 區塊中擷取 name、id 和 input。tool_result 的新訊息來繼續對話:{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "15 degrees"
}
]
}max_tokens 停止原因如果 Claude 的回應因在工具使用期間達到 max_tokens 限制而被截斷,請使用較高的 max_tokens 值重試請求。
pause_turn 停止原因使用網頁搜尋等伺服器工具時,API 可能會回傳 pause_turn 停止原因。請在後續請求中將暫停的回應原樣傳回以繼續對話。
如果工具本身在執行期間擲回錯誤,請使用 "is_error": true 回傳錯誤訊息:
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "ConnectionError: the weather service API is not available (HTTP 500)",
"is_error": true
}
]
}如果 Claude 嘗試使用的工具無效(例如缺少必要參數),請在您的工具定義中使用更詳細的 description 值重試請求。
建立 Message 時,您可以設定 "stream": true,以使用「server-sent events」(伺服器傳送事件),即 SSE,逐步串流回應。
每個伺服器傳送事件都包含一個具名的事件類型和相關的 JSON 資料。每個串流使用以下事件流程:
message_start:包含一個 content 為空的 Message 物件。content_block_start、一個或多個 content_block_delta 事件,以及 content_block_stop。message_delta 事件,表示對最終 Message 物件的頂層變更。message_stop 事件。警告: message_delta 事件的 usage 欄位中顯示的 token 計數是_累計的_。
{
"type": "content_block_delta",
"index": 0,
"delta": { "type": "text_delta", "text": "Hello frien" }
}對於 tool_use 內容區塊,delta 是_部分 JSON 字串_:
{"type": "content_block_delta","index": 1,"delta": {"type": "input_json_delta","partial_json": "{\"location\": \"San Fra"}}}使用擴展思考搭配串流時:
{
"type": "content_block_delta",
"index": 0,
"delta": {
"type": "thinking_delta",
"thinking": "Let me solve this step by step..."
}
}event: message_start
data: {"type": "message_start", "message": {"id": "msg_1nZdL29xx5MUA1yADyHTEsnR8uuvGzszyY", "type": "message", "role": "assistant", "content": [], "model": "claude-opus-4-8", "stop_reason": null, "stop_sequence": null, "usage": {"input_tokens": 25, "output_tokens": 1}}}
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": "Hello"}}
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", "stop_sequence":null}, "usage": {"output_tokens": 15}}
event: message_stop
data: {"type": "message_stop"}Was this page helpful?
import anthropic
import base64
import httpx
# 選項 1:Base64 編碼的圖片
image_url = "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"
image_media_type = "image/jpeg"
image_data = base64.standard_b64encode(httpx.get(image_url).content).decode("utf-8")
message = anthropic.Anthropic().messages.create(
model="claude-opus-4-8",
max_tokens=1024,
messages=[
{
"role": "user",
"content": [
{
"type": "image",
"source": {
"type": "base64",
"media_type": image_media_type,
"data": image_data,
},
},
{"type": "text", "text": "What is in the above image?"},
],
}
],
)
print(message.content[0].text)
# 選項 2:URL 參照的圖片
message_from_url = anthropic.Anthropic().messages.create(
model="claude-opus-4-8",
max_tokens=1024,
messages=[
{
"role": "user",
"content": [
{
"type": "image",
"source": {
"type": "url",
"url": "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg",
},
},
{"type": "text", "text": "What is in the above image?"},
],
}
],
)
print(message_from_url.content[0].text)import anthropic
client = anthropic.Anthropic()
weather_tool = {
"name": "get_weather",
"description": "Get the current weather for a location.",
"input_schema": {
"type": "object",
"properties": {"location": {"type": "string", "description": "The city name."}},
"required": ["location"],
},
}
weather_data = {"temperature": 72}
# 第一個請求 - Claude 回應時包含思考內容與工具請求
response = client.messages.create(
model="claude-opus-4-8",
max_tokens=16000,
thinking={"type": "adaptive", "display": "summarized"},
tools=[weather_tool],
messages=[{"role": "user", "content": "What's the weather in Paris?"}],
)
# 擷取思考區塊與工具使用區塊
thinking_block = next(
(block for block in response.content if block.type == "thinking"), None
)
tool_use_block = next(
(block for block in response.content if block.type == "tool_use"), None
)
# 第二個請求 - 包含思考區塊與工具結果
continuation = client.messages.create(
model="claude-opus-4-8",
max_tokens=16000,
thinking={"type": "adaptive", "display": "summarized"},
tools=[weather_tool],
messages=[
{"role": "user", "content": "What's the weather in Paris?"},
# 請注意,thinking_block 與 tool_use_block 都一併傳入
{"role": "assistant", "content": [thinking_block, tool_use_block]},
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": tool_use_block.id,
"content": f"Current temperature: {weather_data['temperature']}°F",
}
],
},
],
)
for block in continuation.content:
if block.type == "text":
print(block.text)import anthropic
client = anthropic.Anthropic()
calculator_tool = {
"name": "calculator",
"description": "Perform arithmetic calculations.",
"input_schema": {
"type": "object",
"properties": {
"expression": {
"type": "string",
"description": "The math expression to evaluate.",
}
},
"required": ["expression"],
},
}
database_tool = {
"name": "database_query",
"description": "Query the product database.",
"input_schema": {
"type": "object",
"properties": {
"query": {"type": "string", "description": "The database query."}
},
"required": ["query"],
},
}
response = client.beta.messages.create(
model="claude-sonnet-4-6",
max_tokens=16000,
thinking={"type": "enabled", "budget_tokens": 10000},
tools=[calculator_tool, database_tool],
messages=[
{
"role": "user",
"content": "What's the total revenue if we sold 150 units of product A at $50 each?",
}
],
betas=["interleaved-thinking-2025-05-14"],
)
for block in response.content:
if block.type == "thinking":
print(f"Thinking: {block.thinking}")
elif block.type == "tool_use":
print(f"Tool call: {block.name}({block.input})")
elif block.type == "text":
print(f"Response: {block.text}")import anthropic
client = anthropic.Anthropic()
with client.messages.stream(
max_tokens=1024,
messages=[{"role": "user", "content": "Hello"}],
model="claude-opus-4-8",
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)