Loading...
    • 建構
    • 管理
    • 模型與定價
    • 客戶端 SDK
    • API 參考
    Search...
    ⌘K
    第一步
    Claude 簡介快速入門
    使用 Claude 建構
    功能概覽使用 Messages APIClaude API 技能處理停止原因
    模型功能
    延伸思考自適應思考效能任務預算(測試版)快速模式(測試版:研究預覽)結構化輸出引用串流訊息批次處理搜尋結果串流拒絕多語言支援嵌入
    工具
    概覽工具使用方式教學:建構工具代理程式定義工具處理工具呼叫並行工具使用Tool Runner(SDK)嚴格工具使用工具使用與提示快取伺服器工具疑難排解網路搜尋工具網頁擷取工具程式碼執行工具顧問工具記憶工具Bash 工具電腦使用工具文字編輯器工具
    工具基礎架構
    工具參考管理工具上下文工具組合工具搜尋程式化工具呼叫細粒度工具串流
    上下文管理
    上下文視窗壓縮上下文編輯提示快取Token 計數
    處理檔案
    Files APIPDF 支援圖像與視覺
    技能
    概覽快速入門最佳實踐企業技能API 中的技能
    MCP
    遠端 MCP 伺服器MCP 連接器
    提示工程
    概覽提示最佳實踐Console 提示工具
    測試與評估
    定義成功標準並建構評估在 Console 中使用評估工具降低延遲
    強化防護欄
    減少幻覺提高輸出一致性緩解越獄減少提示洩漏
    資源
    詞彙表
    發行說明
    Claude Platform
    Console
    Log in
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...

    Solutions

    • AI agents
    • Code modernization
    • Coding
    • Customer support
    • Education
    • Financial services
    • Government
    • Life sciences

    Partners

    • Amazon Bedrock
    • Google Cloud's Vertex AI

    Learn

    • Blog
    • Courses
    • Use cases
    • Connectors
    • Customer stories
    • Engineering at Anthropic
    • Events
    • Powered by Claude
    • Service partners
    • Startups program

    Company

    • Anthropic
    • Careers
    • Economic Futures
    • Research
    • News
    • Responsible Scaling Policy
    • Security and compliance
    • Transparency

    Learn

    • Blog
    • Courses
    • Use cases
    • Connectors
    • Customer stories
    • Engineering at Anthropic
    • Events
    • Powered by Claude
    • Service partners
    • Startups program

    Help and security

    • Availability
    • Status
    • Support
    • Discord

    Terms and policies

    • Privacy policy
    • Responsible disclosure policy
    • Terms of service: Commercial
    • Terms of service: Consumer
    • Usage policy
    Documentation

    Claude API 使用入門指南

    本指南旨在為 Claude 提供使用 Claude API 的基礎知識。它提供了模型 ID/基本消息 API、工具使用、流式傳輸、擴展思考的說明和示例,僅此而已。

    Was this page helpful?

    • 調用 API
    • 把話放在 Claude 的嘴裡
    • 控制 Claude 的輸出
    • JSON 輸出
    • 處理 max_tokens 停止原因
    • 處理 pause_turn 停止原因
    • 使用 SDK 進行流式傳輸
    • 內容塊 delta 類型

    Claude API 使用入門指南

    本指南旨在為 Claude 提供使用 Claude API 的基礎知識。它提供了模型 ID/基本消息 API、工具使用、流式傳輸、擴展思考的說明和示例,僅此而已。

    模型

    最智能的模型:Claude Opus 4.7:claude-opus-4-7
    智能模型:Claude Sonnet 4.6:claude-sonnet-4-6
    用於快速、經濟高效的任務:Claude Haiku 4.5:claude-haiku-4-5-20251001

    調用 API

    基本請求和響應

    import anthropic
    import os
    
    message = anthropic.Anthropic(
        api_key=os.environ.get("ANTHROPIC_API_KEY")
    ).messages.create(
        model="claude-opus-4-7",
        max_tokens=1024,
        messages=[{"role": "user", "content": "Hello, Claude"}],
    )
    print(message)
    Output
    {
      "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "text",
          "text": "Hello!"
        }
      ],
      "model": "claude-opus-4-7",
      "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-7",
        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 響應的一部分。這可用於塑造 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 ("},
        ],
    )

    視覺

    Claude 可以在請求中讀取文本和圖像。圖像支持 base64 和 url 源類型,以及 image/jpeg、image/png、image/gif 和 image/webp 媒體類型。

    擴展思考

    擴展思考有時可以幫助 Claude 完成非常困難的任務。在 Claude Opus 4.7 之前的模型上,啟用擴展思考時必須將溫度設置為 1。

    以下模型支持擴展思考:

    • Claude Opus 4.1(claude-opus-4-1-20250805)
    • Claude Opus 4(已棄用)(claude-opus-4-20250514)
    • Claude Sonnet 4.6(claude-sonnet-4-6)
    • Claude Sonnet 4.5(claude-sonnet-4-5-20250929)

    擴展思考的工作原理

    啟用擴展思考後,Claude 會創建 thinking 內容塊,其中輸出其內部推理。API 響應將包括 thinking 內容塊,然後是 text 內容塊。

    import anthropic
    
    client = anthropic.Anthropic()
    
    response = client.messages.create(
        model="claude-opus-4-7",
        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?",
            }
        ],
    )
    
    # The response will contain summarized thinking blocks and text blocks
    for block in response.content:
        if block.type == "thinking":
            print(f"\nThinking summary: {block.thinking}")
        elif block.type == "text":
            print(f"\nResponse: {block.text}")

    budget_tokens 參數決定了 Claude 允許用於其內部推理過程的最大令牌數。在 Claude 4 模型中,此限制適用於完整思考令牌,而不是摘要輸出。更大的預算可以通過為複雜問題啟用更徹底的分析來改進響應質量。一條規則:max_tokens 的值必須嚴格大於 budget_tokens 的值,以便 Claude 在思考完成後有空間寫出其響應。

    擴展思考與工具使用

    擴展思考可以與工具使用一起使用,允許 Claude 推理工具選擇和結果處理。

    重要限制:

    1. 工具選擇限制: 僅支持 tool_choice: {"type": "auto"}(默認)或 tool_choice: {"type": "none"}。
    2. 保留思考塊: 在工具使用期間,您必須將 thinking 塊傳回 API 以獲取最後的助手消息。

    保留思考塊

    交錯思考

    Claude 4 模型中的擴展思考與工具使用支持交錯思考,這使 Claude 能夠在工具調用之間進行思考。要在 Claude 4、4.5 和 Sonnet 4.6 模型上啟用,請將 beta 標頭 interleaved-thinking-2025-05-14 添加到您的 API 請求中。

    使用交錯思考,並且僅使用交錯思考(不是常規擴展思考),budget_tokens 可以超過 max_tokens 參數,因為在這種情況下 budget_tokens 代表一個助手輪次內所有思考塊的總預算。

    對於 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"]
      }
    }

    控制 Claude 的輸出

    強制工具使用

    您可以通過在 tool_choice 字段中指定工具來強制 Claude 使用特定工具:

    tool_choice = {"type": "tool", "name": "get_weather"}

    使用 tool_choice 參數時,有四個可能的選項:

    • auto 允許 Claude 決定是否調用任何提供的工具(默認)。
    • any 告訴 Claude 它必須使用提供的工具之一。
    • tool 強制 Claude 始終使用特定工具。
    • none 防止 Claude 使用任何工具。

    JSON 輸出

    工具不一定需要是客戶端函數。您可以在任何時候使用工具,只要您希望模型返回遵循提供的架構的 JSON 輸出。

    思考鏈

    使用工具時,Claude 通常會顯示其「思考鏈」,即它用來分解問題並決定使用哪些工具的逐步推理。

    {
      "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:包含傳遞給工具的輸入的對象。

    當您收到工具使用響應時,您應該:

    1. 從 tool_use 塊中提取 name、id 和 input。
    2. 在您的代碼庫中運行與該工具名稱對應的實際工具。
    3. 通過發送帶有 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 值重試請求。

    流式傳輸消息

    創建消息時,您可以設置 "stream": true 以使用服務器發送事件 (SSE) 增量流式傳輸響應。

    使用 SDK 進行流式傳輸

    事件類型

    每個服務器發送事件都包括一個命名事件類型和相關的 JSON 數據。每個流使用以下事件流:

    1. message_start:包含具有空 content 的 Message 對象。
    2. 一系列內容塊,每個都有 content_block_start、一個或多個 content_block_delta 事件和 content_block_stop。
    3. 一個或多個 message_delta 事件,指示對最終 Message 對象的頂級更改。
    4. 最終的 message_stop 事件。

    警告: message_delta 事件的 usage 字段中顯示的令牌計數是_累積的_。

    內容塊 delta 類型

    文本 delta

    {
      "type": "content_block_delta",
      "index": 0,
      "delta": { "type": "text_delta", "text": "Hello frien" }
    }

    輸入 JSON delta

    對於 tool_use 內容塊,delta 是_部分 JSON 字符串_:

    {"type": "content_block_delta","index": 1,"delta": {"type": "input_json_delta","partial_json": "{\"location\": \"San Fra"}}

    思考 delta

    使用擴展思考進行流式傳輸時:

    {
      "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-7", "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"}
    import anthropic
    import base64
    import httpx
    
    # Option 1: Base64-encoded image
    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-7",
        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?"},
                ],
            }
        ],
    )
    
    # Option 2: URL-referenced image
    message_from_url = anthropic.Anthropic().messages.create(
        model="claude-opus-4-7",
        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?"},
                ],
            }
        ],
    )
    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}
    
    # First request - Claude responds with thinking and tool request
    response = client.messages.create(
        model="claude-opus-4-7",
        max_tokens=16000,
        thinking={"type": "adaptive", "display": "summarized"},
        tools=[weather_tool],
        messages=[{"role": "user", "content": "What's the weather in Paris?"}],
    )
    
    # Extract thinking block and tool use block
    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
    )
    
    # Second request - Include thinking block and tool result
    continuation = client.messages.create(
        model="claude-opus-4-7",
        max_tokens=16000,
        thinking={"type": "adaptive", "display": "summarized"},
        tools=[weather_tool],
        messages=[
            {"role": "user", "content": "What's the weather in Paris?"},
            # Notice that the thinking_block is passed in as well as the 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",
                    }
                ],
            },
        ],
    )
    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"],
    )
    import anthropic
    
    client = anthropic.Anthropic()
    
    with client.messages.stream(
        max_tokens=1024,
        messages=[{"role": "user", "content": "Hello"}],
        model="claude-opus-4-7",
    ) as stream:
        for text in stream.text_stream:
            print(text, end="", flush=True)