Loading...
  • 构建
  • 管理
  • 模型与定价
  • 客户端 SDK
  • API 参考
Search...
⌘K
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、工具使用、流式传输、扩展思考的解释和示例,仅此而已。

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 媒体类型。

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-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?"},
            ],
        }
    ],
)

# 选项 2:URL 引用的图像
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?"},
            ],
        }
    ],
)

扩展思考

扩展思考有时可以帮助 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?",
        }
    ],
)

# 响应将包含总结的思考块和文本块
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 以获取最后的助手消息。

保留思考块

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-7",
    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-7",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    tools=[weather_tool],
    messages=[
        {"role": "user", "content": "What's the weather in Paris?"},
        # 注意思考块与工具使用块一起传入
        {"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",
                }
            ],
        },
    ],
)

交错思考

Claude 4 模型中的扩展思考与工具使用支持交错思考,这使 Claude 能够在工具调用之间进行思考。要在 Claude 4、4.5 和 Sonnet 4.6 模型上启用,请将 beta 标头 interleaved-thinking-2025-05-14 添加到您的 API 请求中。

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"],
)

使用交错思考,且仅使用交错思考(不是常规扩展思考),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 进行流式传输

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)

事件类型

每个服务器发送事件都包括一个命名事件类型和关联的 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"}

Was this page helpful?

  • 调用 API
  • 为 Claude 预填充响应
  • 控制 Claude 的输出
  • JSON 输出
  • 处理 max_tokens 停止原因
  • 处理 pause_turn 停止原因
  • 使用 SDK 进行流式传输
  • 内容块 delta 类型