创建消息

post /v1/messages

发送包含文本和/或图像内容的结构化输入消息列表，模型将生成对话中的下一条消息。

Messages API 可用于单次查询或无状态多轮对话。

在我们的用户指南中了解更多关于 Messages API 的信息

请求体参数

• max_tokens: number

  停止前要生成的最大 token 数量。

  请注意，我们的模型可能会在达到此最大值_之前_停止。此参数仅指定要生成的绝对最大 token 数量。

  设置为 0 可以填充提示缓存而不生成响应。

  不同模型对此参数有不同的最大值。详见模型了解详情。

• messages: array of MessageParam

  输入消息。

  我们的模型经过训练，可处理交替的 user 和 assistant 对话轮次。创建新 Message 时，您通过 messages 参数指定先前的对话轮次，然后模型生成对话中的下一条 Message。请求中连续的 user 或 assistant 轮次将被合并为单个轮次。

  每条输入消息必须是包含 role 和 content 的对象。您可以指定单条 user 角色消息，也可以包含多条 user 和 assistant 消息。

  如果最后一条消息使用 assistant 角色，响应内容将直接从该消息的内容继续。这可用于约束模型的部分响应。

  单条 user 消息示例：

  [{"role": "user", "content": "Hello, Claude"}]
  

  多轮对话示例：

  [
    {"role": "user", "content": "Hello there."},
    {"role": "assistant", "content": "Hi, I'm Claude. How can I help you?"},
    {"role": "user", "content": "Can you explain LLMs in plain English?"},
  ]
  

  Claude 部分填充响应示例：

  [
    {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"},
    {"role": "assistant", "content": "The best answer is ("},
  ]
  

  每条输入消息的 content 可以是单个 string 或内容块数组，每个块具有特定的 type。使用 string 作为 content 是包含一个类型为 "text" 的内容块的数组的简写。以下输入消息是等效的：

  {"role": "user", "content": "Hello, Claude"}
  

  {"role": "user", "content": [{"type": "text", "text": "Hello, Claude"}]}
  

  详见输入示例。

  请注意，如果您想包含系统提示，可以使用顶级 system 参数 -- Messages API 中输入消息没有 "system" 角色。

  单个请求最多可包含 100,000 条消息。

  • content: string or array of ContentBlockParam

    • string

    • array of ContentBlockParam

      • TextBlockParam object { text, type, cache_control, citations }

        • text: string

        • type: "text"

          • "text"

        • cache_control: optional CacheControlEphemeral

          在此内容块创建缓存控制断点。

          • type: "ephemeral"

            • "ephemeral"

          • ttl: optional "5m" or "1h"

            缓存控制断点的生存时间。

            这可能是以下值之一：

            • 5m: 5 minutes
            • 1h: 1 hour

            默认为 5m。

            • "5m"

            • "1h"

        • citations: optional array of TextCitationParam

          • CitationCharLocationParam object { cited_text, document_index, document_title, 3 more }

            • cited_text: string

            • document_index: number

            • document_title: string

            • end_char_index: number

            • start_char_index: number

            • type: "char_location"

              • "char_location"

          • CitationPageLocationParam object { cited_text, document_index, document_title, 3 more }

            • cited_text: string

            • document_index: number

            • document_title: string

            • end_page_number: number

            • start_page_number: number

            • type: "page_location"

              • "page_location"

          • CitationContentBlockLocationParam object { cited_text, document_index, document_title, 3 more }

            • cited_text: string

              引用块范围的完整文本，已连接。

              始终等于 content[start_block_index:end_block_index] 内容的连接。文本块是最小可引用单元；此字段永远不会是单个块的子字符串。不计入输出 token，在后续轮次中发回时也不计入输入 token。

            • document_index: number

            • document_title: string

            • end_block_index: number

              源 content 数组中引用块范围的排他性 0 基结束索引。

              始终大于 start_block_index；单块引用的 end_block_index = start_block_index + 1。

            • start_block_index: number

              源 content 数组中第一个引用块的 0 基索引。

            • type: "content_block_location"

              • "content_block_location"

          • CitationWebSearchResultLocationParam object { cited_text, encrypted_index, title, 2 more }

            • cited_text: string

            • encrypted_index: string

            • title: string

            • type: "web_search_result_location"

              • "web_search_result_location"

            • url: string

          • CitationSearchResultLocationParam object { cited_text, end_block_index, search_result_index, 4 more }

            • cited_text: string

              引用块范围的完整文本，已连接。

              始终等于 content[start_block_index:end_block_index] 内容的连接。文本块是最小可引用单元；此字段永远不会是单个块的子字符串。不计入输出 token，在后续轮次中发回时也不计入输入 token。

            • end_block_index: number

              源 content 数组中引用块范围的排他性 0 基结束索引。

              始终大于 start_block_index；单块引用的 end_block_index = start_block_index + 1。

            • search_result_index: number

              在请求中所有 search_result 内容块中引用搜索结果的 0 基索引，按其在消息和工具结果中出现的顺序排列。

              与 document_index 分开计数；服务器端 Web 搜索结果不包含在此计数中。

            • source: string

            • start_block_index: number

              源 content 数组中第一个引用块的 0 基索引。

            • title: string

            • type: "search_result_location"

              • "search_result_location"

      • ImageBlockParam object { source, type, cache_control }

        • source: Base64ImageSource or URLImageSource

          • Base64ImageSource object { data, media_type, type }

            • data: string

            • media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"

              • "image/jpeg"

              • "image/png"

              • "image/gif"

              • "image/webp"

            • type: "base64"

              • "base64"

          • URLImageSource object { type, url }

            • type: "url"

              • "url"

            • url: string

        • type: "image"

          • "image"

        • cache_control: optional CacheControlEphemeral

          在此内容块创建缓存控制断点。

      • DocumentBlockParam object { source, type, cache_control, 3 more }

        • source: Base64PDFSource or PlainTextSource or ContentBlockSource or URLPDFSource

          • Base64PDFSource object { data, media_type, type }

            • data: string

            • media_type: "application/pdf"

              • "application/pdf"

            • type: "base64"

              • "base64"

          • PlainTextSource object { data, media_type, type }

            • data: string

            • media_type: "text/plain"

              • "text/plain"

            • type: "text"

              • "text"

          • ContentBlockSource object { content, type }

            • content: string or array of ContentBlockSourceContent

              • string

              • ContentBlockSourceContent = array of ContentBlockSourceContent

                • TextBlockParam object { text, type, cache_control, citations }

                • ImageBlockParam object { source, type, cache_control }

            • type: "content"

              • "content"

          • URLPDFSource object { type, url }

            • type: "url"

              • "url"

            • url: string

        • type: "document"

          • "document"

        • cache_control: optional CacheControlEphemeral

          在此内容块创建缓存控制断点。

        • citations: optional CitationsConfigParam

          • enabled: optional boolean

        • context: optional string

        • title: optional string

      • SearchResultBlockParam object { content, source, title, 3 more }

        • content: array of TextBlockParam

          • text: string

          • type: "text"

          • cache_control: optional CacheControlEphemeral

            在此内容块创建缓存控制断点。

          • citations: optional array of TextCitationParam

        • source: string

        • title: string

        • type: "search_result"

          • "search_result"

        • cache_control: optional CacheControlEphemeral

          在此内容块创建缓存控制断点。

        • citations: optional CitationsConfigParam

      • ThinkingBlockParam object { signature, thinking, type }

        • signature: string

        • thinking: string

        • type: "thinking"

          • "thinking"

      • RedactedThinkingBlockParam object { data, type }

        • data: string

        • type: "redacted_thinking"

          • "redacted_thinking"

      • ToolUseBlockParam object { id, input, name, 3 more }

        • id: string

        • input: map[unknown]

        • name: string

        • type: "tool_use"

          • "tool_use"

        • cache_control: optional CacheControlEphemeral

          在此内容块创建缓存控制断点。

        • caller: optional DirectCaller or ServerToolCaller or ServerToolCaller20260120

          直接来自模型的工具调用。

          • DirectCaller object { type }

            直接来自模型的工具调用。

            • type: "direct"

              • "direct"

          • ServerToolCaller object { tool_id, type }

            由服务器端工具生成的工具调用。

            • tool_id: string

            • type: "code_execution_20250825"

              • "code_execution_20250825"

          • ServerToolCaller20260120 object { tool_id, type }

            • tool_id: string

            • type: "code_execution_20260120"

              • "code_execution_20260120"

      • ToolResultBlockParam object { tool_use_id, type, cache_control, 2 more }

        • tool_use_id: string

        • type: "tool_result"

          • "tool_result"

        • cache_control: optional CacheControlEphemeral

          在此内容块创建缓存控制断点。

        • content: optional string or array of TextBlockParam or ImageBlockParam or SearchResultBlockParam or 2 more

          • string

          • array of TextBlockParam or ImageBlockParam or SearchResultBlockParam or 2 more

            • TextBlockParam object { text, type, cache_control, citations }

            • ImageBlockParam object { source, type, cache_control }

            • SearchResultBlockParam object { content, source, title, 3 more }

            • DocumentBlockParam object { source, type, cache_control, 3 more }

            • ToolReferenceBlockParam object { tool_name, type, cache_control }

              可包含在 tool_result 内容中的工具引用块。

              • tool_name: string

              • type: "tool_reference"

                • "tool_reference"

              • cache_control: optional CacheControlEphemeral

                在此内容块创建缓存控制断点。

        • is_error: optional boolean

      • ServerToolUseBlockParam object { id, input, name, 3 more }

        • id: string

        • input: map[unknown]

        • name: "web_search" or "web_fetch" or "code_execution" or 4 more

          • "web_search"

          • "web_fetch"

          • "code_execution"

          • "bash_code_execution"

          • "text_editor_code_execution"

          • "tool_search_tool_regex"

          • "tool_search_tool_bm25"

        • type: "server_tool_use"

          • "server_tool_use"

        • cache_control: optional CacheControlEphemeral

          在此内容块创建缓存控制断点。

        • caller: optional DirectCaller or ServerToolCaller or ServerToolCaller20260120

          直接来自模型的工具调用。

          • DirectCaller object { type }

            直接来自模型的工具调用。

          • ServerToolCaller object { tool_id, type }

            由服务器端工具生成的工具调用。

          • ServerToolCaller20260120 object { tool_id, type }

      • WebSearchToolResultBlockParam object { content, tool_use_id, type, 2 more }

        • content: WebSearchToolResultBlockParamContent

          • WebSearchToolResultBlockItem = array of WebSearchResultBlockParam

            • encrypted_content: string

            • title: string

            • type: "web_search_result"

              • "web_search_result"

            • url: string

            • page_age: optional string

          • WebSearchToolRequestError object { error_code, type }

            • error_code: WebSearchToolResultErrorCode

              • "invalid_tool_input"

              • "unavailable"

              • "max_uses_exceeded"

              • "too_many_requests"

              • "query_too_long"

              • "request_too_large"

            • type: "web_search_tool_result_error"

              • "web_search_tool_result_error"

        • tool_use_id: string

        • type: "web_search_tool_result"

          • "web_search_tool_result"

        • cache_control: optional CacheControlEphemeral

          在此内容块创建缓存控制断点。

        • caller: optional DirectCaller or ServerToolCaller or ServerToolCaller20260120

          直接来自模型的工具调用。

          • DirectCaller object { type }

            直接来自模型的工具调用。

          • ServerToolCaller object { tool_id, type }

            由服务器端工具生成的工具调用。

          • ServerToolCaller20260120 object { tool_id, type }

      • WebFetchToolResultBlockParam object { content, tool_use_id, type, 2 more }

        • content: WebFetchToolResultErrorBlockParam or WebFetchBlockParam

          • WebFetchToolResultErrorBlockParam object { error_code, type }

            • error_code: WebFetchToolResultErrorCode

              • "invalid_tool_input"

              • "url_too_long"

              • "url_not_allowed"

              • "url_not_accessible"

              • "unsupported_content_type"

              • "too_many_requests"

              • "max_uses_exceeded"

              • "unavailable"

            • type: "web_fetch_tool_result_error"

              • "web_fetch_tool_result_error"

          • WebFetchBlockParam object { content, type, url, retrieved_at }

            • content: DocumentBlockParam

            • type: "web_fetch_result"

              • "web_fetch_result"

            • url: string

              获取的内容 URL

            • retrieved_at: optional string

              获取内容时的 ISO 8601 时间戳

        • tool_use_id: string

        • type: "web_fetch_tool_result"

          • "web_fetch_tool_result"

        • cache_control: optional CacheControlEphemeral

          在此内容块创建缓存控制断点。

        • caller: optional DirectCaller or ServerToolCaller or ServerToolCaller20260120

          直接来自模型的工具调用。

          • DirectCaller object { type }

            直接来自模型的工具调用。

          • ServerToolCaller object { tool_id, type }

            由服务器端工具生成的工具调用。

          • ServerToolCaller20260120 object { tool_id, type }

      • CodeExecutionToolResultBlockParam object { content, tool_use_id, type, cache_control }

        • content: CodeExecutionToolResultBlockParamContent

          PFC + web_search 结果的带加密标准输出的代码执行结果。

          • CodeExecutionToolResultErrorParam object { error_code, type }

            • error_code: CodeExecutionToolResultErrorCode

              • "invalid_tool_input"

              • "unavailable"

              • "too_many_requests"

              • "execution_time_exceeded"

            • type: "code_execution_tool_result_error"

              • "code_execution_tool_result_error"

          • CodeExecutionResultBlockParam object { content, return_code, stderr, 2 more }

            • content: array of CodeExecutionOutputBlockParam

              • file_id: string

              • type: "code_execution_output"

                • "code_execution_output"

            • return_code: number

            • stderr: string

            • stdout: string

            • type: "code_execution_result"

              • "code_execution_result"

          • EncryptedCodeExecutionResultBlockParam object { content, encrypted_stdout, return_code, 2 more }

            PFC + web_search 结果的带加密标准输出的代码执行结果。

            • content: array of CodeExecutionOutputBlockParam

              • file_id: string

              • type: "code_execution_output"

            • encrypted_stdout: string

            • return_code: number

            • stderr: string

            • type: "encrypted_code_execution_result"

              • "encrypted_code_execution_result"

        • tool_use_id: string

        • type: "code_execution_tool_result"

          • "code_execution_tool_result"

        • cache_control: optional CacheControlEphemeral

          在此内容块创建缓存控制断点。

      • BashCodeExecutionToolResultBlockParam object { content, tool_use_id, type, cache_control }

        • content: BashCodeExecutionToolResultErrorParam or BashCodeExecutionResultBlockParam

          • BashCodeExecutionToolResultErrorParam object { error_code, type }

            • error_code: BashCodeExecutionToolResultErrorCode

              • "invalid_tool_input"

              • "unavailable"

              • "too_many_requests"

              • "execution_time_exceeded"

              • "output_file_too_large"

            • type: "bash_code_execution_tool_result_error"

              • "bash_code_execution_tool_result_error"

          • BashCodeExecutionResultBlockParam object { content, return_code, stderr, 2 more }

            • content: array of BashCodeExecutionOutputBlockParam

              • file_id: string

              • type: "bash_code_execution_output"

                • "bash_code_execution_output"

            • return_code: number

            • stderr: string

            • stdout: string

            • type: "bash_code_execution_result"

              • "bash_code_execution_result"

        • tool_use_id: string

        • type: "bash_code_execution_tool_result"

          • "bash_code_execution_tool_result"

        • cache_control: optional CacheControlEphemeral

          在此内容块创建缓存控制断点。

      • TextEditorCodeExecutionToolResultBlockParam object { content, tool_use_id, type, cache_control }

        • content: TextEditorCodeExecutionToolResultErrorParam or TextEditorCodeExecutionViewResultBlockParam or TextEditorCodeExecutionCreateResultBlockParam or TextEditorCodeExecutionStrReplaceResultBlockParam

          • TextEditorCodeExecutionToolResultErrorParam object { error_code, type, error_message }

            • error_code: TextEditorCodeExecutionToolResultErrorCode

              • "invalid_tool_input"

              • "unavailable"

              • "too_many_requests"

              • "execution_time_exceeded"

              • "file_not_found"

            • type: "text_editor_code_execution_tool_result_error"

              • "text_editor_code_execution_tool_result_error"

            • error_message: optional string

          • TextEditorCodeExecutionViewResultBlockParam object { content, file_type, type, 3 more }

            • content: string

            • file_type: "text" or "image" or "pdf"

              • "text"

              • "image"

              • "pdf"

            • type: "text_editor_code_execution_view_result"

              • "text_editor_code_execution_view_result"

            • num_lines: optional number

            • start_line: optional number

            • total_lines: optional number

          • TextEditorCodeExecutionCreateResultBlockParam object { is_file_update, type }

            • is_file_update: boolean

            • type: "text_editor_code_execution_create_result"

              • "text_editor_code_execution_create_result"

          • TextEditorCodeExecutionStrReplaceResultBlockParam object { type, lines, new_lines, 3 more }

            • type: "text_editor_code_execution_str_replace_result"

              • "text_editor_code_execution_str_replace_result"

            • lines: optional array of string

            • new_lines: optional number

            • new_start: optional number

            • old_lines: optional number

            • old_start: optional number

        • tool_use_id: string

        • type: "text_editor_code_execution_tool_result"

          • "text_editor_code_execution_tool_result"

        • cache_control: optional CacheControlEphemeral

          在此内容块创建缓存控制断点。

      • ToolSearchToolResultBlockParam object { content, tool_use_id, type, cache_control }

        • content: ToolSearchToolResultErrorParam or ToolSearchToolSearchResultBlockParam

          • ToolSearchToolResultErrorParam object { error_code, type }

            • error_code: ToolSearchToolResultErrorCode

              • "invalid_tool_input"

              • "unavailable"

              • "too_many_requests"

              • "execution_time_exceeded"

            • type: "tool_search_tool_result_error"

              • "tool_search_tool_result_error"

          • ToolSearchToolSearchResultBlockParam object { tool_references, type }

            • tool_references: array of ToolReferenceBlockParam

              • tool_name: string

              • type: "tool_reference"

              • cache_control: optional CacheControlEphemeral

                在此内容块创建缓存控制断点。

            • type: "tool_search_tool_search_result"

              • "tool_search_tool_search_result"

        • tool_use_id: string

        • type: "tool_search_tool_result"

          • "tool_search_tool_result"

        • cache_control: optional CacheControlEphemeral

          在此内容块创建缓存控制断点。

      • ContainerUploadBlockParam object { file_id, type, cache_control }

        表示要上传到容器的文件的内容块 通过此块上传的文件将在容器的输入目录中可用。

        • file_id: string

        • type: "container_upload"

          • "container_upload"

        • cache_control: optional CacheControlEphemeral

          在此内容块创建缓存控制断点。

  • role: "user" or "assistant"

    • "user"

    • "assistant"

• model: Model

  将完成您的提示的模型。

  详见模型了解更多信息和选项。

  • "claude-opus-4-7" or "claude-mythos-preview" or "claude-opus-4-6" or 14 more

    将完成您的提示的模型。

    详见模型了解更多信息和选项。

    • "claude-opus-4-7"

      用于长时间运行的智能体和编程的前沿智能

    • "claude-mythos-preview"

      新一代智能，在编程和网络安全方面最强

    • "claude-opus-4-6"

      用于长时间运行的智能体和编程的前沿智能

    • "claude-sonnet-4-6"

      速度与智能的最佳组合

    • "claude-haiku-4-5"

      具有接近前沿智能的最快模型

    • "claude-haiku-4-5-20251001"

      具有接近前沿智能的最快模型

    • "claude-opus-4-5"

      结合最高智能与实用性能的高级模型

    • "claude-opus-4-5-20251101"

      结合最高智能与实用性能的高级模型

    • "claude-sonnet-4-5"

      用于智能体和编程的高性能模型

    • "claude-sonnet-4-5-20250929"

      用于智能体和编程的高性能模型

    • "claude-opus-4-1"

      用于专业复杂任务的卓越模型

    • "claude-opus-4-1-20250805"

      用于专业复杂任务的卓越模型

    • "claude-opus-4-0"

      用于复杂任务的强大模型

    • "claude-opus-4-20250514"

      用于复杂任务的强大模型

    • "claude-sonnet-4-0"

      具有扩展思考能力的高性能模型

    • "claude-sonnet-4-20250514"

      具有扩展思考能力的高性能模型

    • "claude-3-haiku-20240307"

      快速且经济高效的模型

  • string

• cache_control: optional CacheControlEphemeral

  顶级缓存控制自动将 cache_control 标记应用于请求中最后一个可缓存块。

• container: optional string

  用于跨请求复用的容器标识符。

• inference_geo: optional string

  指定推理处理的地理区域。如果未指定，则使用工作区的 default_inference_geo。

• metadata: optional Metadata

  描述请求元数据的对象。

  • user_id: optional string

    与请求关联的用户的外部标识符。

    这应该是 uuid、哈希值或其他不透明标识符。Anthropic 可能会使用此 ID 来帮助检测滥用行为。请勿包含任何可识别信息，如姓名、电子邮件地址或电话号码。

• output_config: optional OutputConfig

  模型输出的配置选项，例如输出格式。

  • effort: optional "low" or "medium" or "high" or 2 more

    所有可用的努力级别。

    • "low"

    • "medium"

    • "high"

    • "xhigh"

    • "max"

  • format: optional JSONOutputFormat

    用于指定 Claude 响应输出格式的模式。详见结构化输出

    • schema: map[unknown]

      格式的 JSON 模式

    • type: "json_schema"

      • "json_schema"

• service_tier: optional "auto" or "standard_only"

  确定此请求是使用优先容量（如果可用）还是标准容量。

  Anthropic 为您的 API 请求提供不同级别的服务。详见服务层级了解详情。

  • "auto"

  • "standard_only"

• stop_sequences: optional array of string

  将导致模型停止生成的自定义文本序列。

  我们的模型通常会在自然完成其轮次时停止，这将导致响应 stop_reason 为 "end_turn"。

  如果您希望模型在遇到自定义文本字符串时停止生成，可以使用 stop_sequences 参数。如果模型遇到自定义序列之一，响应 stop_reason 值将为 "stop_sequence"，响应 stop_sequence 值将包含匹配的停止序列。

• stream: optional boolean

  是否使用服务器发送事件增量式地流式传输响应。

  详见流式传输了解更多详情。

• system: optional string or array of TextBlockParam

  系统提示。

  系统提示是一种向 Claude 提供上下文和指令的方式，例如指定特定目标或角色。请参阅我们的系统提示指南。

  • string

  • array of TextBlockParam

    • text: string

    • type: "text"

    • cache_control: optional CacheControlEphemeral

      在此内容块创建缓存控制断点。

    • citations: optional array of TextCitationParam

• temperature: optional number

  注入响应的随机性程度。

  默认为 1.0。范围从 0.0 到 1.0。对于分析/多选任务使用接近 0.0 的 temperature，对于创意和生成任务使用接近 1.0 的 temperature。

  请注意，即使 temperature 为 0.0，结果也不会完全确定。

• thinking: optional ThinkingConfigParam

  启用 Claude 扩展思考的配置。

  启用后，响应包含 thinking 内容块，显示 Claude 在最终答案之前的思考过程。需要最少 1,024 个 token 的预算，并计入您的 max_tokens 限制。

  详见扩展思考了解更多详情。

  • ThinkingConfigEnabled object { budget_tokens, type, display }

    • budget_tokens: number

      确定 Claude 可用于其内部推理过程的 token 数量。较大的预算可以实现对复杂问题的更彻底分析，提高响应质量。

      必须 ≥1024 且小于 max_tokens。

      详见扩展思考了解更多详情。

    • type: "enabled"

      • "enabled"

    • display: optional "summarized" or "omitted"

      控制思考内容在响应中的显示方式。设置为 summarized 时，正常返回思考内容。设置为 omitted 时，思考内容被编辑但返回签名以保持多轮连续性。默认为 summarized。

      • "summarized"

      • "omitted"

  • ThinkingConfigDisabled object { type }

    • type: "disabled"

      • "disabled"

  • ThinkingConfigAdaptive object { type, display }

    • type: "adaptive"

      • "adaptive"

    • display: optional "summarized" or "omitted"

      控制思考内容在响应中的显示方式。设置为 summarized 时，正常返回思考内容。设置为 omitted 时，思考内容被编辑但返回签名以保持多轮连续性。默认为 summarized。

      • "summarized"

      • "omitted"

• tool_choice: optional ToolChoice

  模型应如何使用提供的工具。模型可以使用特定工具、任何可用工具、自行决定或完全不使用工具。

  • ToolChoiceAuto object { type, disable_parallel_tool_use }

    模型将自动决定是否使用工具。

    • type: "auto"

      • "auto"

    • disable_parallel_tool_use: optional boolean

      是否禁用并行工具使用。

      默认为 false。如果设置为 true，模型将最多输出一个工具使用。

  • ToolChoiceAny object { type, disable_parallel_tool_use }

    模型将使用任何可用工具。

    • type: "any"

      • "any"

    • disable_parallel_tool_use: optional boolean

      是否禁用并行工具使用。

      默认为 false。如果设置为 true，模型将恰好输出一个工具使用。

  • ToolChoiceTool object { name, type, disable_parallel_tool_use }

    模型将使用 tool_choice.name 指定的工具。

    • name: string

      要使用的工具的名称。

    • type: "tool"

      • "tool"

    • disable_parallel_tool_use: optional boolean

      是否禁用并行工具使用。

      默认为 false。如果设置为 true，模型将恰好输出一个工具使用。

  • ToolChoiceNone object { type }

    模型将不被允许使用工具。

    • type: "none"

      • "none"

• tools: optional array of ToolUnion

  模型可能使用的工具定义。

  如果您在 API 请求中包含 tools，模型可能会返回表示模型使用这些工具的 tool_use 内容块。然后，您可以使用模型生成的工具输入运行这些工具，并可选地使用 tool_result 内容块将结果返回给模型。

  有两种类型的工具：客户端工具和服务器端工具。以下描述的行为适用于客户端工具。有关服务器端工具，请参阅其各自的文档，因为每个工具都有自己的行为（例如 Web 搜索工具）。

  每个工具定义包括：

  • name: 工具名称。
  • description: 可选但强烈推荐的工具描述。
  • input_schema：工具 input 形状的 JSON schema，模型将在 tool_use 输出内容块中生成该形状。

  例如，如果您将 tools 定义为：

  [
    {
      "name": "get_stock_price",
      "description": "Get the current stock price for a given ticker symbol.",
      "input_schema": {
        "type": "object",
        "properties": {
          "ticker": {
            "type": "string",
            "description": "The stock ticker symbol, e.g. AAPL for Apple Inc."
          }
        },
        "required": ["ticker"]
      }
    }
  ]
  

  然后询问模型"今天标普 500 指数是多少？"，模型可能会在响应中生成如下 tool_use 内容块：

  [
    {
      "type": "tool_use",
      "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV",
      "name": "get_stock_price",
      "input": { "ticker": "^GSPC" }
    }
  ]
  

  然后您可以使用 {"ticker": "^GSPC"} 作为输入运行您的 get_stock_price 工具，并在后续 user 消息中将以下内容返回给模型：

  [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV",
      "content": "259.75 USD"
    }
  ]
  

  工具可用于包含运行客户端工具和函数的工作流，或更一般地说，当您希望模型生成特定 JSON 结构的输出时。

  详见我们的指南了解更多详情。

  • Tool object { input_schema, name, allowed_callers, 7 more }

    • input_schema: object { type, properties, required }

      此工具输入的 JSON schema。

      这定义了您的工具接受和模型将生成的 input 的形状。

      • type: "object"

        • "object"

      • properties: optional map[unknown]

      • required: optional array of string

    • name: string

      工具名称。

      这是模型和 tool_use 块中调用工具的方式。

    • allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

      • "direct"

      • "code_execution_20250825"

      • "code_execution_20260120"

    • cache_control: optional CacheControlEphemeral

      在此内容块创建缓存控制断点。

    • defer_loading: optional boolean

      如果为 true，工具不会包含在初始系统提示中。仅在通过工具搜索的 tool_reference 返回时加载。

    • description: optional string

      此工具的功能描述。

      工具描述应尽可能详细。模型拥有的关于工具功能和使用方式的信息越多，其表现就越好。您可以使用自然语言描述来强调工具输入 JSON 模式的重要方面。

    • eager_input_streaming: optional boolean

      为此工具启用即时输入流。当为 true 时，工具输入参数将在生成时增量流式传输，类型将即时推断，而不是缓冲完整的 JSON 输出。当为 false 时，即使细粒度工具流 beta 处于活动状态，也会禁用此工具的流。当为 null（默认）时，使用基于 beta 头的默认行为。

    • input_examples: optional array of map[unknown]

    • strict: optional boolean

      当为 true 时，保证对工具名称和输入进行模式验证

    • type: optional "custom"

      • "custom"

  • ToolBash20250124 object { name, type, allowed_callers, 4 more }

    • name: "bash"

      工具名称。

      这是模型和 tool_use 块中调用工具的方式。

      • "bash"

    • type: "bash_20250124"

      • "bash_20250124"

    • allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

      • "direct"

      • "code_execution_20250825"

      • "code_execution_20260120"

    • cache_control: optional CacheControlEphemeral

      在此内容块创建缓存控制断点。

    • defer_loading: optional boolean

      如果为 true，工具不会包含在初始系统提示中。仅在通过工具搜索的 tool_reference 返回时加载。

    • input_examples: optional array of map[unknown]

    • strict: optional boolean

      当为 true 时，保证对工具名称和输入进行模式验证

  • CodeExecutionTool20250522 object { name, type, allowed_callers, 3 more }

    • name: "code_execution"

      工具名称。

      这是模型和 tool_use 块中调用工具的方式。

      • "code_execution"

    • type: "code_execution_20250522"

      • "code_execution_20250522"

    • allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

      • "direct"

      • "code_execution_20250825"

      • "code_execution_20260120"

    • cache_control: optional CacheControlEphemeral

      在此内容块创建缓存控制断点。

    • defer_loading: optional boolean

      如果为 true，工具不会包含在初始系统提示中。仅在通过工具搜索的 tool_reference 返回时加载。

    • strict: optional boolean

      当为 true 时，保证对工具名称和输入进行模式验证

  • CodeExecutionTool20250825 object { name, type, allowed_callers, 3 more }

    • name: "code_execution"

      工具名称。

      这是模型和 tool_use 块中调用工具的方式。

      • "code_execution"

    • type: "code_execution_20250825"

      • "code_execution_20250825"

    • allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

      • "direct"

      • "code_execution_20250825"

      • "code_execution_20260120"

    • cache_control: optional CacheControlEphemeral

      在此内容块创建缓存控制断点。

    • defer_loading: optional boolean

      如果为 true，工具不会包含在初始系统提示中。仅在通过工具搜索的 tool_reference 返回时加载。

    • strict: optional boolean

      当为 true 时，保证对工具名称和输入进行模式验证

  • CodeExecutionTool20260120 object { name, type, allowed_callers, 3 more }

    具有 REPL 状态持久化的代码执行工具（守护进程模式 + gVisor 检查点）。

    • name: "code_execution"

      工具名称。

      这是模型和 tool_use 块中调用工具的方式。

      • "code_execution"

    • type: "code_execution_20260120"

      • "code_execution_20260120"

    • allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

      • "direct"

      • "code_execution_20250825"

      • "code_execution_20260120"

    • cache_control: optional CacheControlEphemeral

      在此内容块创建缓存控制断点。

    • defer_loading: optional boolean

      如果为 true，工具不会包含在初始系统提示中。仅在通过工具搜索的 tool_reference 返回时加载。

    • strict: optional boolean

      当为 true 时，保证对工具名称和输入进行模式验证

  • MemoryTool20250818 object { name, type, allowed_callers, 4 more }

    • name: "memory"

      工具名称。

      这是模型和 tool_use 块中调用工具的方式。

      • "memory"

    • type: "memory_20250818"

      • "memory_20250818"

    • allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

      • "direct"

      • "code_execution_20250825"

      • "code_execution_20260120"

    • cache_control: optional CacheControlEphemeral

      在此内容块创建缓存控制断点。

    • defer_loading: optional boolean

      如果为 true，工具不会包含在初始系统提示中。仅在通过工具搜索的 tool_reference 返回时加载。

    • input_examples: optional array of map[unknown]

    • strict: optional boolean

      当为 true 时，保证对工具名称和输入进行模式验证

  • ToolTextEditor20250124 object { name, type, allowed_callers, 4 more }

    • name: "str_replace_editor"

      工具名称。

      这是模型和 tool_use 块中调用工具的方式。

      • "str_replace_editor"

    • type: "text_editor_20250124"

      • "text_editor_20250124"

    • allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

      • "direct"

      • "code_execution_20250825"

      • "code_execution_20260120"

    • cache_control: optional CacheControlEphemeral

      在此内容块创建缓存控制断点。

    • defer_loading: optional boolean

      如果为 true，工具不会包含在初始系统提示中。仅在通过工具搜索的 tool_reference 返回时加载。

    • input_examples: optional array of map[unknown]

    • strict: optional boolean

      当为 true 时，保证对工具名称和输入进行模式验证

  • ToolTextEditor20250429 object { name, type, allowed_callers, 4 more }

    • name: "str_replace_based_edit_tool"

      工具名称。

      这是模型和 tool_use 块中调用工具的方式。

      • "str_replace_based_edit_tool"

    • type: "text_editor_20250429"

      • "text_editor_20250429"

    • allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

      • "direct"

      • "code_execution_20250825"

      • "code_execution_20260120"

    • cache_control: optional CacheControlEphemeral

      在此内容块创建缓存控制断点。

    • defer_loading: optional boolean

      如果为 true，工具不会包含在初始系统提示中。仅在通过工具搜索的 tool_reference 返回时加载。

    • input_examples: optional array of map[unknown]

    • strict: optional boolean

      当为 true 时，保证对工具名称和输入进行模式验证

  • ToolTextEditor20250728 object { name, type, allowed_callers, 5 more }

    • name: "str_replace_based_edit_tool"

      工具名称。

      这是模型和 tool_use 块中调用工具的方式。

      • "str_replace_based_edit_tool"

    • type: "text_editor_20250728"

      • "text_editor_20250728"

    • allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

      • "direct"

      • "code_execution_20250825"

      • "code_execution_20260120"

    • cache_control: optional CacheControlEphemeral

      在此内容块创建缓存控制断点。

    • defer_loading: optional boolean

      如果为 true，工具不会包含在初始系统提示中。仅在通过工具搜索的 tool_reference 返回时加载。

    • input_examples: optional array of map[unknown]

    • max_characters: optional number

      查看文件时显示的最大字符数。如果未指定，默认显示完整文件。

    • strict: optional boolean

      当为 true 时，保证对工具名称和输入进行模式验证

  • WebSearchTool20250305 object { name, type, allowed_callers, 7 more }

    • name: "web_search"

      工具名称。

      这是模型和 tool_use 块中调用工具的方式。

      • "web_search"

    • type: "web_search_20250305"

      • "web_search_20250305"

    • allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

      • "direct"

      • "code_execution_20250825"

      • "code_execution_20260120"

    • allowed_domains: optional array of string

      如果提供，只有这些域名会包含在结果中。不能与 blocked_domains 一起使用。

    • blocked_domains: optional array of string

      如果提供，这些域名永远不会出现在结果中。不能与 allowed_domains 一起使用。

    • cache_control: optional CacheControlEphemeral

      在此内容块创建缓存控制断点。

    • defer_loading: optional boolean

      如果为 true，工具不会包含在初始系统提示中。仅在通过工具搜索的 tool_reference 返回时加载。

    • max_uses: optional number

      工具在 API 请求中可使用的最大次数。

    • strict: optional boolean

      当为 true 时，保证对工具名称和输入进行模式验证

    • user_location: optional UserLocation

      用户位置参数。用于提供更相关的搜索结果。

      • type: "approximate"

        • "approximate"

      • city: optional string

        用户的城市。

      • country: optional string

        用户的两字母 ISO 国家代码。

      • region: optional string

        用户的区域。

      • timezone: optional string

        用户的 IANA 时区。

  • WebFetchTool20250910 object { name, type, allowed_callers, 8 more }

    • name: "web_fetch"

      工具名称。

      这是模型和 tool_use 块中调用工具的方式。

      • "web_fetch"

    • type: "web_fetch_20250910"

      • "web_fetch_20250910"

    • allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

      • "direct"

      • "code_execution_20250825"

      • "code_execution_20260120"

    • allowed_domains: optional array of string

      允许获取的域名列表

    • blocked_domains: optional array of string

      阻止获取的域名列表

    • cache_control: optional CacheControlEphemeral

      在此内容块创建缓存控制断点。

    • citations: optional CitationsConfigParam

      获取文档的引用配置。默认禁用引用。

    • defer_loading: optional boolean

      如果为 true，工具不会包含在初始系统提示中。仅在通过工具搜索的 tool_reference 返回时加载。

    • max_content_tokens: optional number

      在上下文中包含网页文本内容所使用的最大 token 数量。该限制是近似的，不适用于 PDF 等二进制内容。

    • max_uses: optional number

      工具在 API 请求中可使用的最大次数。

    • strict: optional boolean

      当为 true 时，保证对工具名称和输入进行模式验证

  • WebSearchTool20260209 object { name, type, allowed_callers, 7 more }

    • name: "web_search"

      工具名称。

      这是模型和 tool_use 块中调用工具的方式。

      • "web_search"

    • type: "web_search_20260209"

      • "web_search_20260209"

    • allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

      • "direct"

      • "code_execution_20250825"

      • "code_execution_20260120"

    • allowed_domains: optional array of string

      如果提供，只有这些域名会包含在结果中。不能与 blocked_domains 一起使用。

    • blocked_domains: optional array of string

      如果提供，这些域名永远不会出现在结果中。不能与 allowed_domains 一起使用。

    • cache_control: optional CacheControlEphemeral

      在此内容块创建缓存控制断点。

    • defer_loading: optional boolean

      如果为 true，工具不会包含在初始系统提示中。仅在通过工具搜索的 tool_reference 返回时加载。

    • max_uses: optional number

      工具在 API 请求中可使用的最大次数。

    • strict: optional boolean

      当为 true 时，保证对工具名称和输入进行模式验证

    • user_location: optional UserLocation

      用户位置参数。用于提供更相关的搜索结果。

  • WebFetchTool20260209 object { name, type, allowed_callers, 8 more }

    • name: "web_fetch"

      工具名称。

      这是模型和 tool_use 块中调用工具的方式。

      • "web_fetch"

    • type: "web_fetch_20260209"

      • "web_fetch_20260209"

    • allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

      • "direct"

      • "code_execution_20250825"

      • "code_execution_20260120"

    • allowed_domains: optional array of string

      允许获取的域名列表

    • blocked_domains: optional array of string

      阻止获取的域名列表

    • cache_control: optional CacheControlEphemeral

      在此内容块创建缓存控制断点。

    • citations: optional CitationsConfigParam

      获取文档的引用配置。默认禁用引用。

    • defer_loading: optional boolean

      如果为 true，工具不会包含在初始系统提示中。仅在通过工具搜索的 tool_reference 返回时加载。

    • max_content_tokens: optional number

      在上下文中包含网页文本内容所使用的最大 token 数量。该限制是近似的，不适用于 PDF 等二进制内容。

    • max_uses: optional number

      工具在 API 请求中可使用的最大次数。

    • strict: optional boolean

      当为 true 时，保证对工具名称和输入进行模式验证

  • WebFetchTool20260309 object { name, type, allowed_callers, 9 more }

    具有 use_cache 参数的 Web 获取工具，用于绕过缓存内容。

    • name: "web_fetch"

      工具名称。

      这是模型和 tool_use 块中调用工具的方式。

      • "web_fetch"

    • type: "web_fetch_20260309"

      • "web_fetch_20260309"

    • allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

      • "direct"

      • "code_execution_20250825"

      • "code_execution_20260120"

    • allowed_domains: optional array of string

      允许获取的域名列表

    • blocked_domains: optional array of string

      阻止获取的域名列表

    • cache_control: optional CacheControlEphemeral

      在此内容块创建缓存控制断点。

    • citations: optional CitationsConfigParam

      获取文档的引用配置。默认禁用引用。

    • defer_loading: optional boolean

      如果为 true，工具不会包含在初始系统提示中。仅在通过工具搜索的 tool_reference 返回时加载。

    • max_content_tokens: optional number

      在上下文中包含网页文本内容所使用的最大 token 数量。该限制是近似的，不适用于 PDF 等二进制内容。

    • max_uses: optional number

      工具在 API 请求中可使用的最大次数。

    • strict: optional boolean

      当为 true 时，保证对工具名称和输入进行模式验证

    • use_cache: optional boolean

      是否使用缓存内容。设置为 false 可绕过缓存并获取新内容。仅在用户明确请求新内容或获取快速变化的源时设置为 false。

  • ToolSearchToolBm25_20251119 object { name, type, allowed_callers, 3 more }

    • name: "tool_search_tool_bm25"

      工具名称。

      这是模型和 tool_use 块中调用工具的方式。

      • "tool_search_tool_bm25"

    • type: "tool_search_tool_bm25_20251119" or "tool_search_tool_bm25"

      • "tool_search_tool_bm25_20251119"

      • "tool_search_tool_bm25"

    • allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

      • "direct"

      • "code_execution_20250825"

      • "code_execution_20260120"

    • cache_control: optional CacheControlEphemeral

      在此内容块创建缓存控制断点。

    • defer_loading: optional boolean

      如果为 true，工具不会包含在初始系统提示中。仅在通过工具搜索的 tool_reference 返回时加载。

    • strict: optional boolean

      当为 true 时，保证对工具名称和输入进行模式验证

  • ToolSearchToolRegex20251119 object { name, type, allowed_callers, 3 more }

    • name: "tool_search_tool_regex"

      工具名称。

      这是模型和 tool_use 块中调用工具的方式。

      • "tool_search_tool_regex"

    • type: "tool_search_tool_regex_20251119" or "tool_search_tool_regex"

      • "tool_search_tool_regex_20251119"

      • "tool_search_tool_regex"

    • allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

      • "direct"

      • "code_execution_20250825"

      • "code_execution_20260120"

    • cache_control: optional CacheControlEphemeral

      在此内容块创建缓存控制断点。

    • defer_loading: optional boolean

      如果为 true，工具不会包含在初始系统提示中。仅在通过工具搜索的 tool_reference 返回时加载。

    • strict: optional boolean

      当为 true 时，保证对工具名称和输入进行模式验证

• top_k: optional number

  仅从每个后续 token 的前 K 个选项中采样。

  用于消除"长尾"低概率响应。在此了解更多技术细节。

  仅建议高级用例使用。

• top_p: optional number

  使用核采样。

  在核采样中，我们按概率递减顺序计算所有选项的累积分布，并在达到 top_p 指定的特定概率时截断。

  仅建议高级用例使用。

返回值

• Message object { id, container, content, 7 more }

  • id: string

    唯一对象标识符。

    ID 的格式和长度可能会随时间变化。

  • container: Container

    请求中使用的容器信息（用于代码执行工具）

    • id: string

      此请求中使用的容器标识符

    • expires_at: string

      容器将过期的时间。

  • content: array of ContentBlock

    模型生成的内容。

    这是一个内容块数组，每个块都有一个 type 来决定其形状。

    Example:

    [{"type": "text", "text": "Hi, I'm Claude."}]
    

    如果请求输入 messages 以 assistant 轮次结束，则响应 content 将直接从该轮次继续。您可以使用此来约束模型的输出。

    例如，如果输入 messages 为：

    [
      {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"},
      {"role": "assistant", "content": "The best answer is ("}
    ]
    

    则响应 content 可能为：

    [{"type": "text", "text": "B)"}]
    

    • TextBlock object { citations, text, type }

      • citations: array of TextCitation

        支持文本块的引用。

        返回的引用类型取决于被引用文档的类型。引用 PDF 会产生 page_location， plain text results in char_location, and content document results in content_block_location.

        • CitationCharLocation object { cited_text, document_index, document_title, 4 more }

          • cited_text: string

          • document_index: number

          • document_title: string

          • end_char_index: number

          • file_id: string

          • start_char_index: number

          • type: "char_location"

            • "char_location"

        • CitationPageLocation object { cited_text, document_index, document_title, 4 more }

          • cited_text: string

          • document_index: number

          • document_title: string

          • end_page_number: number

          • file_id: string

          • start_page_number: number

          • type: "page_location"

            • "page_location"

        • CitationContentBlockLocation object { cited_text, document_index, document_title, 4 more }

          • cited_text: string

            引用块范围的完整文本，已连接。

            始终等于 content[start_block_index:end_block_index] 内容的连接。文本块是最小可引用单元；此字段永远不会是单个块的子字符串。不计入输出 token，在后续轮次中发回时也不计入输入 token。

          • document_index: number

          • document_title: string

          • end_block_index: number

            源 content 数组中引用块范围的排他性 0 基结束索引。

            始终大于 start_block_index；单块引用的 end_block_index = start_block_index + 1。

          • file_id: string

          • start_block_index: number

            源 content 数组中第一个引用块的 0 基索引。

          • type: "content_block_location"

            • "content_block_location"

        • CitationsWebSearchResultLocation object { cited_text, encrypted_index, title, 2 more }

          • cited_text: string

          • encrypted_index: string

          • title: string

          • type: "web_search_result_location"

            • "web_search_result_location"

          • url: string

        • CitationsSearchResultLocation object { cited_text, end_block_index, search_result_index, 4 more }

          • cited_text: string

            引用块范围的完整文本，已连接。

            始终等于 content[start_block_index:end_block_index] 内容的连接。文本块是最小可引用单元；此字段永远不会是单个块的子字符串。不计入输出 token，在后续轮次中发回时也不计入输入 token。

          • end_block_index: number

            源 content 数组中引用块范围的排他性 0 基结束索引。

            始终大于 start_block_index；单块引用的 end_block_index = start_block_index + 1。

          • search_result_index: number

            在请求中所有 search_result 内容块中引用搜索结果的 0 基索引，按其在消息和工具结果中出现的顺序排列。

            与 document_index 分开计数；服务器端 Web 搜索结果不包含在此计数中。

          • source: string

          • start_block_index: number

            源 content 数组中第一个引用块的 0 基索引。

          • title: string

          • type: "search_result_location"

            • "search_result_location"

      • text: string

      • type: "text"

        • "text"

    • ThinkingBlock object { signature, thinking, type }

      • signature: string

      • thinking: string

      • type: "thinking"

        • "thinking"

    • RedactedThinkingBlock object { data, type }

      • data: string

      • type: "redacted_thinking"

        • "redacted_thinking"

    • ToolUseBlock object { id, caller, input, 2 more }

      • id: string

      • caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120

        直接来自模型的工具调用。

        • DirectCaller object { type }

          直接来自模型的工具调用。

          • type: "direct"

            • "direct"

        • ServerToolCaller object { tool_id, type }

          由服务器端工具生成的工具调用。

          • tool_id: string

          • type: "code_execution_20250825"

            • "code_execution_20250825"

        • ServerToolCaller20260120 object { tool_id, type }

          • tool_id: string

          • type: "code_execution_20260120"

            • "code_execution_20260120"

      • input: map[unknown]

      • name: string

      • type: "tool_use"

        • "tool_use"

    • ServerToolUseBlock object { id, caller, input, 2 more }

      • id: string

      • caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120

        直接来自模型的工具调用。

        • DirectCaller object { type }

          直接来自模型的工具调用。

        • ServerToolCaller object { tool_id, type }

          由服务器端工具生成的工具调用。

        • ServerToolCaller20260120 object { tool_id, type }

      • input: map[unknown]

      • name: "web_search" or "web_fetch" or "code_execution" or 4 more

        • "web_search"

        • "web_fetch"

        • "code_execution"

        • "bash_code_execution"

        • "text_editor_code_execution"

        • "tool_search_tool_regex"

        • "tool_search_tool_bm25"

      • type: "server_tool_use"

        • "server_tool_use"

    • WebSearchToolResultBlock object { caller, content, tool_use_id, type }

      • caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120

        直接来自模型的工具调用。

        • DirectCaller object { type }

          直接来自模型的工具调用。

        • ServerToolCaller object { tool_id, type }

          由服务器端工具生成的工具调用。

        • ServerToolCaller20260120 object { tool_id, type }

      • content: WebSearchToolResultBlockContent

        • WebSearchToolResultError object { error_code, type }

          • error_code: WebSearchToolResultErrorCode

            • "invalid_tool_input"

            • "unavailable"

            • "max_uses_exceeded"

            • "too_many_requests"

            • "query_too_long"

            • "request_too_large"

          • type: "web_search_tool_result_error"

            • "web_search_tool_result_error"

        • array of WebSearchResultBlock

          • encrypted_content: string

          • page_age: string

          • title: string

          • type: "web_search_result"

            • "web_search_result"

          • url: string

      • tool_use_id: string

      • type: "web_search_tool_result"

        • "web_search_tool_result"

    • WebFetchToolResultBlock object { caller, content, tool_use_id, type }

      • caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120

        直接来自模型的工具调用。

        • DirectCaller object { type }

          直接来自模型的工具调用。

        • ServerToolCaller object { tool_id, type }

          由服务器端工具生成的工具调用。

        • ServerToolCaller20260120 object { tool_id, type }

      • content: WebFetchToolResultErrorBlock or WebFetchBlock

        • WebFetchToolResultErrorBlock object { error_code, type }

          • error_code: WebFetchToolResultErrorCode

            • "invalid_tool_input"

            • "url_too_long"

            • "url_not_allowed"

            • "url_not_accessible"

            • "unsupported_content_type"

            • "too_many_requests"

            • "max_uses_exceeded"

            • "unavailable"

          • type: "web_fetch_tool_result_error"

            • "web_fetch_tool_result_error"

        • WebFetchBlock object { content, retrieved_at, type, url }

          • content: DocumentBlock

            • citations: CitationsConfig

              文档的引用配置

              • enabled: boolean

            • source: Base64PDFSource or PlainTextSource

              • Base64PDFSource object { data, media_type, type }

                • data: string

                • media_type: "application/pdf"

                  • "application/pdf"

                • type: "base64"

                  • "base64"

              • PlainTextSource object { data, media_type, type }

                • data: string

                • media_type: "text/plain"

                  • "text/plain"

                • type: "text"

                  • "text"

            • title: string

              文档标题

            • type: "document"

              • "document"

          • retrieved_at: string

            获取内容时的 ISO 8601 时间戳

          • type: "web_fetch_result"

            • "web_fetch_result"

          • url: string

            获取的内容 URL

      • tool_use_id: string

      • type: "web_fetch_tool_result"

        • "web_fetch_tool_result"

    • CodeExecutionToolResultBlock object { content, tool_use_id, type }

      • content: CodeExecutionToolResultBlockContent

        PFC + web_search 结果的带加密标准输出的代码执行结果。

        • CodeExecutionToolResultError object { error_code, type }

          • error_code: CodeExecutionToolResultErrorCode

            • "invalid_tool_input"

            • "unavailable"

            • "too_many_requests"

            • "execution_time_exceeded"

          • type: "code_execution_tool_result_error"

            • "code_execution_tool_result_error"

        • CodeExecutionResultBlock object { content, return_code, stderr, 2 more }

          • content: array of CodeExecutionOutputBlock

            • file_id: string

            • type: "code_execution_output"

              • "code_execution_output"

          • return_code: number

          • stderr: string

          • stdout: string

          • type: "code_execution_result"

            • "code_execution_result"

        • EncryptedCodeExecutionResultBlock object { content, encrypted_stdout, return_code, 2 more }

          PFC + web_search 结果的带加密标准输出的代码执行结果。

          • content: array of CodeExecutionOutputBlock

            • file_id: string

            • type: "code_execution_output"

          • encrypted_stdout: string

          • return_code: number

          • stderr: string

          • type: "encrypted_code_execution_result"

            • "encrypted_code_execution_result"

      • tool_use_id: string

      • type: "code_execution_tool_result"

        • "code_execution_tool_result"

    • BashCodeExecutionToolResultBlock object { content, tool_use_id, type }

      • content: BashCodeExecutionToolResultError or BashCodeExecutionResultBlock

        • BashCodeExecutionToolResultError object { error_code, type }

          • error_code: BashCodeExecutionToolResultErrorCode

            • "invalid_tool_input"

            • "unavailable"

            • "too_many_requests"

            • "execution_time_exceeded"

            • "output_file_too_large"

          • type: "bash_code_execution_tool_result_error"

            • "bash_code_execution_tool_result_error"

        • BashCodeExecutionResultBlock object { content, return_code, stderr, 2 more }

          • content: array of BashCodeExecutionOutputBlock

            • file_id: string

            • type: "bash_code_execution_output"

              • "bash_code_execution_output"

          • return_code: number

          • stderr: string

          • stdout: string

          • type: "bash_code_execution_result"

            • "bash_code_execution_result"

      • tool_use_id: string

      • type: "bash_code_execution_tool_result"

        • "bash_code_execution_tool_result"

    • TextEditorCodeExecutionToolResultBlock object { content, tool_use_id, type }

      • content: TextEditorCodeExecutionToolResultError or TextEditorCodeExecutionViewResultBlock or TextEditorCodeExecutionCreateResultBlock or TextEditorCodeExecutionStrReplaceResultBlock

        • TextEditorCodeExecutionToolResultError object { error_code, error_message, type }

          • error_code: TextEditorCodeExecutionToolResultErrorCode

            • "invalid_tool_input"

            • "unavailable"

            • "too_many_requests"

            • "execution_time_exceeded"

            • "file_not_found"

          • error_message: string

          • type: "text_editor_code_execution_tool_result_error"

            • "text_editor_code_execution_tool_result_error"

        • TextEditorCodeExecutionViewResultBlock object { content, file_type, num_lines, 3 more }

          • content: string

          • file_type: "text" or "image" or "pdf"

            • "text"

            • "image"

            • "pdf"

          • num_lines: number

          • start_line: number

          • total_lines: number

          • type: "text_editor_code_execution_view_result"

            • "text_editor_code_execution_view_result"

        • TextEditorCodeExecutionCreateResultBlock object { is_file_update, type }

          • is_file_update: boolean

          • type: "text_editor_code_execution_create_result"

            • "text_editor_code_execution_create_result"

        • TextEditorCodeExecutionStrReplaceResultBlock object { lines, new_lines, new_start, 3 more }

          • lines: array of string

          • new_lines: number

          • new_start: number

          • old_lines: number

          • old_start: number

          • type: "text_editor_code_execution_str_replace_result"

            • "text_editor_code_execution_str_replace_result"

      • tool_use_id: string

      • type: "text_editor_code_execution_tool_result"

        • "text_editor_code_execution_tool_result"

    • ToolSearchToolResultBlock object { content, tool_use_id, type }

      • content: ToolSearchToolResultError or ToolSearchToolSearchResultBlock

        • ToolSearchToolResultError object { error_code, error_message, type }

          • error_code: ToolSearchToolResultErrorCode

            • "invalid_tool_input"

            • "unavailable"

            • "too_many_requests"

            • "execution_time_exceeded"

          • error_message: string

          • type: "tool_search_tool_result_error"

            • "tool_search_tool_result_error"

        • ToolSearchToolSearchResultBlock object { tool_references, type }

          • tool_references: array of ToolReferenceBlock

            • tool_name: string

            • type: "tool_reference"

              • "tool_reference"

          • type: "tool_search_tool_search_result"

            • "tool_search_tool_search_result"

      • tool_use_id: string

      • type: "tool_search_tool_result"

        • "tool_search_tool_result"

    • ContainerUploadBlock object { file_id, type }

      上传到容器的文件的响应模型。

      • file_id: string

      • type: "container_upload"

        • "container_upload"

  • model: Model

    将完成您的提示的模型。

    详见模型了解更多信息和选项。

    • "claude-opus-4-7" or "claude-mythos-preview" or "claude-opus-4-6" or 14 more

      将完成您的提示的模型。

      详见模型了解更多信息和选项。

      • "claude-opus-4-7"

        用于长时间运行的智能体和编程的前沿智能

      • "claude-mythos-preview"

        新一代智能，在编程和网络安全方面最强

      • "claude-opus-4-6"

        用于长时间运行的智能体和编程的前沿智能

      • "claude-sonnet-4-6"

        速度与智能的最佳组合

      • "claude-haiku-4-5"

        具有接近前沿智能的最快模型

      • "claude-haiku-4-5-20251001"

        具有接近前沿智能的最快模型

      • "claude-opus-4-5"

        结合最高智能与实用性能的高级模型

      • "claude-opus-4-5-20251101"

        结合最高智能与实用性能的高级模型

      • "claude-sonnet-4-5"

        用于智能体和编程的高性能模型

      • "claude-sonnet-4-5-20250929"

        用于智能体和编程的高性能模型

      • "claude-opus-4-1"

        用于专业复杂任务的卓越模型

      • "claude-opus-4-1-20250805"

        用于专业复杂任务的卓越模型

      • "claude-opus-4-0"

        用于复杂任务的强大模型

      • "claude-opus-4-20250514"

        用于复杂任务的强大模型

      • "claude-sonnet-4-0"

        具有扩展思考能力的高性能模型

      • "claude-sonnet-4-20250514"

        具有扩展思考能力的高性能模型

      • "claude-3-haiku-20240307"

        快速且经济高效的模型

    • string

  • role: "assistant"

    生成消息的对话角色。

    这将始终为 "assistant"。

    • "assistant"

  • stop_details: RefusalStopDetails

    关于拒绝的结构化信息。

    • category: "cyber" or "bio"

      触发拒绝的策略类别。

      当拒绝未映射到命名类别时为 null。

      • "cyber"

      • "bio"

    • explanation: string

      拒绝的人类可读解释。

      此文本不保证稳定。当该类别没有可用解释时为 null。

    • type: "refusal"

      • "refusal"

  • stop_reason: StopReason

    停止的原因。

    这可能是以下值之一：

    • "end_turn": 模型到达自然停止点
    • "max_tokens": 我们超过了请求的 max_tokens 或模型的最大值
    • "stop_sequence": 生成了您提供的自定义 stop_sequences 之一
    • "tool_use": 模型调用了一个或多个工具
    • "pause_turn": 我们暂停了一个长时间运行的轮次。您可以在后续请求中原样提供响应，让模型继续。
    • "refusal": 当流式分类器介入处理潜在策略违规时

    在非流式模式下，此值始终非空。在流式模式下，message_start 事件中为 null，其他情况下非空。

    • "end_turn"

    • "max_tokens"

    • "stop_sequence"

    • "tool_use"

    • "pause_turn"

    • "refusal"

  • stop_sequence: string

    生成了哪个自定义停止序列（如果有）。

    如果生成了您的自定义停止序列之一，此值将为非空字符串。

  • type: "message"

    对象类型。

    对于消息，始终为 "message"。

    • "message"

  • usage: Usage

    计费和速率限制使用情况。

    Anthropic 的 API 按 token 计数计费和限制速率，因为 token 代表了我们系统的底层成本。

    在底层，API 将请求转换为适合模型的格式。然后模型的输出经过解析阶段，成为 API 响应。因此，usage 中的 token 计数不会与 API 请求或响应的确切可见内容一一对应。

    例如，即使 Claude 返回空字符串响应，output_tokens 也不会为零。

    请求中的总输入 token 数是 input_tokens、cache_creation_input_tokens 和 cache_read_input_tokens 的总和。

    • cache_creation: CacheCreation

      按 TTL 分解的缓存 token

      • ephemeral_1h_input_tokens: number

        用于创建 1 小时缓存条目的输入 token 数量。

      • ephemeral_5m_input_tokens: number

        用于创建 5 分钟缓存条目的输入 token 数量。

    • cache_creation_input_tokens: number

      用于创建缓存条目的输入 token 数量。

    • cache_read_input_tokens: number

      从缓存中读取的输入 token 数量。

    • inference_geo: string

      此请求执行推理的地理区域。

    • input_tokens: number

      使用的输入 token 数量。

    • output_tokens: number

      使用的输出 token 数量。

    • server_tool_use: ServerToolUsage

      服务器工具请求数量。

      • web_fetch_requests: number

        Web 获取工具请求数量。

      • web_search_requests: number

        Web 搜索工具请求数量。

    • service_tier: "standard" or "priority" or "batch"

      请求是否使用了优先级、标准或批处理层级。

      • "standard"

      • "priority"

      • "batch"

Example

curl https://api.anthropic.com/v1/messages \
    -H 'Content-Type: application/json' \
    -H 'anthropic-version: 2023-06-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY" \
    --max-time 600 \
    -d "{
          \"max_tokens\": 1024,
          \"messages\": [
            {
              \"content\": \"Hello, world\",
              \"role\": \"user\"
            }
          ],
          \"model\": \"claude-opus-4-6\",
          \"system\": [
            {
              \"text\": \"Today's date is 2024-06-01.\",
              \"type\": \"text\"
            }
          ],
          \"temperature\": 1,
          \"thinking\": {
            \"type\": \"adaptive\"
          },
          \"tools\": [
            {
              \"input_schema\": {
                \"type\": \"object\",
                \"properties\": {
                  \"location\": \"bar\",
                  \"unit\": \"bar\"
                },
                \"required\": [
                  \"location\"
                ]
              },
              \"name\": \"name\"
            }
          ],
          \"top_k\": 5,
          \"top_p\": 0.7
        }"

响应

{
  "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
  "container": {
    "id": "id",
    "expires_at": "2019-12-27T18:11:19.117Z"
  },
  "content": [
    {
      "citations": [
        {
          "cited_text": "cited_text",
          "document_index": 0,
          "document_title": "document_title",
          "end_char_index": 0,
          "file_id": "file_id",
          "start_char_index": 0,
          "type": "char_location"
        }
      ],
      "text": "Hi! My name is Claude.",
      "type": "text"
    }
  ],
  "model": "claude-opus-4-6",
  "role": "assistant",
  "stop_details": {
    "category": "cyber",
    "explanation": "explanation",
    "type": "refusal"
  },
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "type": "message",
  "usage": {
    "cache_creation": {
      "ephemeral_1h_input_tokens": 0,
      "ephemeral_5m_input_tokens": 0
    },
    "cache_creation_input_tokens": 2051,
    "cache_read_input_tokens": 2051,
    "inference_geo": "inference_geo",
    "input_tokens": 2095,
    "output_tokens": 503,
    "server_tool_use": {
      "web_fetch_requests": 2,
      "web_search_requests": 0
    },
    "service_tier": "standard"
  }
}