消息

创建消息

post /v1/messages

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

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

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

请求头参数

• "anthropic-beta": optional array of AnthropicBeta

  可选的请求头，用于指定您要使用的 beta 版本。

  • string

  • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 more

    • "message-batches-2024-09-24"

    • "prompt-caching-2024-07-31"

    • "computer-use-2024-10-22"

    • "computer-use-2025-01-24"

    • "pdfs-2024-09-25"

    • "token-counting-2024-11-01"

    • "token-efficient-tools-2025-02-19"

    • "output-128k-2025-02-19"

    • "files-api-2025-04-14"

    • "mcp-client-2025-04-04"

    • "mcp-client-2025-11-20"

    • "dev-full-thinking-2025-05-14"

    • "interleaved-thinking-2025-05-14"

    • "code-execution-2025-05-22"

    • "extended-cache-ttl-2025-04-11"

    • "context-1m-2025-08-07"

    • "context-management-2025-06-27"

    • "model-context-window-exceeded-2025-08-26"

    • "skills-2025-10-02"

    • "fast-mode-2026-02-01"

    • "output-300k-2026-03-24"

    • "user-profiles-2026-03-24"

    • "advisor-tool-2026-03-01"

    • "managed-agents-2026-04-01"

    • "cache-diagnosis-2026-04-07"

请求体参数

• max_tokens: number

  停止生成前的最大 token 数。

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

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

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

• messages: array of BetaMessageParam

  输入消息。

  我们的模型经过训练，可以处理交替的 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 BetaContentBlockParam

    • string

    • array of BetaContentBlockParam

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

        • text: string

        • type: "text"

          • "text"

        • cache_control: optional BetaCacheControlEphemeral

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

          • type: "ephemeral"

            • "ephemeral"

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

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

            可以是以下值之一：

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

            默认为 5m。

            • "5m"

            • "1h"

        • citations: optional array of BetaTextCitationParam

          • BetaCitationCharLocationParam 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"

          • BetaCitationPageLocationParam 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"

          • BetaCitationContentBlockLocationParam 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"

          • BetaCitationWebSearchResultLocationParam 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

          • BetaCitationSearchResultLocationParam 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"

      • BetaImageBlockParam object { source, type, cache_control }

        • source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource

          • BetaBase64ImageSource 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"

          • BetaURLImageSource object { type, url }

            • type: "url"

              • "url"

            • url: string

          • BetaFileImageSource object { file_id, type }

            • file_id: string

            • type: "file"

              • "file"

        • type: "image"

          • "image"

        • cache_control: optional BetaCacheControlEphemeral

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

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

        • source: BetaBase64PDFSource or BetaPlainTextSource or BetaContentBlockSource or 2 more

          • BetaBase64PDFSource object { data, media_type, type }

            • data: string

            • media_type: "application/pdf"

              • "application/pdf"

            • type: "base64"

              • "base64"

          • BetaPlainTextSource object { data, media_type, type }

            • data: string

            • media_type: "text/plain"

              • "text/plain"

            • type: "text"

              • "text"

          • BetaContentBlockSource object { content, type }

            • content: string or array of BetaContentBlockSourceContent

              • string

              • BetaContentBlockSourceContent = array of BetaContentBlockSourceContent

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

                • BetaImageBlockParam object { source, type, cache_control }

            • type: "content"

              • "content"

          • BetaURLPDFSource object { type, url }

            • type: "url"

              • "url"

            • url: string

          • BetaFileDocumentSource object { file_id, type }

            • file_id: string

            • type: "file"

              • "file"

        • type: "document"

          • "document"

        • cache_control: optional BetaCacheControlEphemeral

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

        • citations: optional BetaCitationsConfigParam

          • enabled: optional boolean

        • context: optional string

        • title: optional string

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

        • content: array of BetaTextBlockParam

          • text: string

          • type: "text"

          • cache_control: optional BetaCacheControlEphemeral

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

          • citations: optional array of BetaTextCitationParam

        • source: string

        • title: string

        • type: "search_result"

          • "search_result"

        • cache_control: optional BetaCacheControlEphemeral

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

        • citations: optional BetaCitationsConfigParam

      • BetaThinkingBlockParam object { signature, thinking, type }

        • signature: string

        • thinking: string

        • type: "thinking"

          • "thinking"

      • BetaRedactedThinkingBlockParam object { data, type }

        • data: string

        • type: "redacted_thinking"

          • "redacted_thinking"

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

        • id: string

        • input: map[unknown]

        • name: string

        • type: "tool_use"

          • "tool_use"

        • cache_control: optional BetaCacheControlEphemeral

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

        • caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

          模型直接发起的工具调用。

          • BetaDirectCaller object { type }

            模型直接发起的工具调用。

            • type: "direct"

              • "direct"

          • BetaServerToolCaller object { tool_id, type }

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

            • tool_id: string

            • type: "code_execution_20250825"

              • "code_execution_20250825"

          • BetaServerToolCaller20260120 object { tool_id, type }

            • tool_id: string

            • type: "code_execution_20260120"

              • "code_execution_20260120"

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

        • tool_use_id: string

        • type: "tool_result"

          • "tool_result"

        • cache_control: optional BetaCacheControlEphemeral

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

        • content: optional string or array of BetaTextBlockParam or BetaImageBlockParam or BetaSearchResultBlockParam or 2 more

          • string

          • array of BetaTextBlockParam or BetaImageBlockParam or BetaSearchResultBlockParam or 2 more

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

            • BetaImageBlockParam object { source, type, cache_control }

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

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

            • BetaToolReferenceBlockParam object { tool_name, type, cache_control }

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

              • tool_name: string

              • type: "tool_reference"

                • "tool_reference"

              • cache_control: optional BetaCacheControlEphemeral

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

        • is_error: optional boolean

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

        • id: string

        • input: map[unknown]

        • name: "advisor" or "web_search" or "web_fetch" or 5 more

          • "advisor"

          • "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 BetaCacheControlEphemeral

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

        • caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

          模型直接发起的工具调用。

          • BetaDirectCaller object { type }

            模型直接发起的工具调用。

          • BetaServerToolCaller object { tool_id, type }

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

          • BetaServerToolCaller20260120 object { tool_id, type }

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

        • content: BetaWebSearchToolResultBlockParamContent

          • ResultBlock = array of BetaWebSearchResultBlockParam

            • encrypted_content: string

            • title: string

            • type: "web_search_result"

              • "web_search_result"

            • url: string

            • page_age: optional string

          • BetaWebSearchToolRequestError object { error_code, type }

            • error_code: BetaWebSearchToolResultErrorCode

              • "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 BetaCacheControlEphemeral

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

        • caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

          模型直接发起的工具调用。

          • BetaDirectCaller object { type }

            模型直接发起的工具调用。

          • BetaServerToolCaller object { tool_id, type }

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

          • BetaServerToolCaller20260120 object { tool_id, type }

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

        • content: BetaWebFetchToolResultErrorBlockParam or BetaWebFetchBlockParam

          • BetaWebFetchToolResultErrorBlockParam object { error_code, type }

            • error_code: BetaWebFetchToolResultErrorCode

              • "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"

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

            • content: BetaRequestDocumentBlock

            • type: "web_fetch_result"

              • "web_fetch_result"

            • url: string

              Fetched content URL

            • retrieved_at: optional string

              ISO 8601 timestamp when the content was retrieved

        • tool_use_id: string

        • type: "web_fetch_tool_result"

          • "web_fetch_tool_result"

        • cache_control: optional BetaCacheControlEphemeral

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

        • caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

          模型直接发起的工具调用。

          • BetaDirectCaller object { type }

            模型直接发起的工具调用。

          • BetaServerToolCaller object { tool_id, type }

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

          • BetaServerToolCaller20260120 object { tool_id, type }

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

        • content: BetaAdvisorToolResultErrorParam or BetaAdvisorResultBlockParam or BetaAdvisorRedactedResultBlockParam

          • BetaAdvisorToolResultErrorParam object { error_code, type }

            • error_code: "max_uses_exceeded" or "prompt_too_long" or "too_many_requests" or 3 more

              • "max_uses_exceeded"

              • "prompt_too_long"

              • "too_many_requests"

              • "overloaded"

              • "unavailable"

              • "execution_time_exceeded"

            • type: "advisor_tool_result_error"

              • "advisor_tool_result_error"

          • BetaAdvisorResultBlockParam object { text, type }

            • text: string

            • type: "advisor_result"

              • "advisor_result"

          • BetaAdvisorRedactedResultBlockParam object { encrypted_content, type }

            • encrypted_content: string

              由先前响应生成的不透明数据块；必须原样来回传输。

            • type: "advisor_redacted_result"

              • "advisor_redacted_result"

        • tool_use_id: string

        • type: "advisor_tool_result"

          • "advisor_tool_result"

        • cache_control: optional BetaCacheControlEphemeral

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

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

        • content: BetaCodeExecutionToolResultBlockParamContent

          代码执行结果，包含用于 PFC + web_search 结果的加密标准输出。

          • BetaCodeExecutionToolResultErrorParam object { error_code, type }

            • error_code: BetaCodeExecutionToolResultErrorCode

              • "invalid_tool_input"

              • "unavailable"

              • "too_many_requests"

              • "execution_time_exceeded"

            • type: "code_execution_tool_result_error"

              • "code_execution_tool_result_error"

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

            • content: array of BetaCodeExecutionOutputBlockParam

              • file_id: string

              • type: "code_execution_output"

                • "code_execution_output"

            • return_code: number

            • stderr: string

            • stdout: string

            • type: "code_execution_result"

              • "code_execution_result"

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

            代码执行结果，包含用于 PFC + web_search 结果的加密标准输出。

            • content: array of BetaCodeExecutionOutputBlockParam

              • 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 BetaCacheControlEphemeral

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

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

        • content: BetaBashCodeExecutionToolResultErrorParam or BetaBashCodeExecutionResultBlockParam

          • BetaBashCodeExecutionToolResultErrorParam object { error_code, type }

            • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more

              • "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"

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

            • content: array of BetaBashCodeExecutionOutputBlockParam

              • 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 BetaCacheControlEphemeral

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

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

        • content: BetaTextEditorCodeExecutionToolResultErrorParam or BetaTextEditorCodeExecutionViewResultBlockParam or BetaTextEditorCodeExecutionCreateResultBlockParam or BetaTextEditorCodeExecutionStrReplaceResultBlockParam

          • BetaTextEditorCodeExecutionToolResultErrorParam object { error_code, type, error_message }

            • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more

              • "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

          • BetaTextEditorCodeExecutionViewResultBlockParam 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

          • BetaTextEditorCodeExecutionCreateResultBlockParam object { is_file_update, type }

            • is_file_update: boolean

            • type: "text_editor_code_execution_create_result"

              • "text_editor_code_execution_create_result"

          • BetaTextEditorCodeExecutionStrReplaceResultBlockParam 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 BetaCacheControlEphemeral

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

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

        • content: BetaToolSearchToolResultErrorParam or BetaToolSearchToolSearchResultBlockParam

          • BetaToolSearchToolResultErrorParam object { error_code, type }

            • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"

              • "invalid_tool_input"

              • "unavailable"

              • "too_many_requests"

              • "execution_time_exceeded"

            • type: "tool_search_tool_result_error"

              • "tool_search_tool_result_error"

          • BetaToolSearchToolSearchResultBlockParam object { tool_references, type }

            • tool_references: array of BetaToolReferenceBlockParam

              • tool_name: string

              • type: "tool_reference"

              • cache_control: optional BetaCacheControlEphemeral

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

            • 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 BetaCacheControlEphemeral

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

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

        • id: string

        • input: map[unknown]

        • name: string

        • server_name: string

          MCP 服务器的名称

        • type: "mcp_tool_use"

          • "mcp_tool_use"

        • cache_control: optional BetaCacheControlEphemeral

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

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

        • tool_use_id: string

        • type: "mcp_tool_result"

          • "mcp_tool_result"

        • cache_control: optional BetaCacheControlEphemeral

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

        • content: optional string or array of BetaTextBlockParam

          • string

          • BetaMCPToolResultBlockParamContent = array of BetaTextBlockParam

            • text: string

            • type: "text"

            • cache_control: optional BetaCacheControlEphemeral

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

            • citations: optional array of BetaTextCitationParam

        • is_error: optional boolean

      • BetaContainerUploadBlockParam object { file_id, type, cache_control }

        A content block that represents a file to be uploaded to the container Files uploaded via this block will be available in the container's input directory.

        • file_id: string

        • type: "container_upload"

          • "container_upload"

        • cache_control: optional BetaCacheControlEphemeral

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

      • BetaCompactionBlockParam object { content, type, cache_control, encrypted_content }

        A compaction block containing summary of previous context.

        Users should round-trip these blocks from responses to subsequent requests to maintain context across compaction boundaries.

        When content is None, the block represents a failed compaction. The server treats these as no-ops. Empty string content is not allowed.

        • content: string

          Summary of previously compacted content, or null if compaction failed

        • type: "compaction"

          • "compaction"

        • cache_control: optional BetaCacheControlEphemeral

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

        • encrypted_content: optional string

          Opaque metadata from prior compaction, to be round-tripped verbatim

  • role: "user" or "assistant"

    • "user"

    • "assistant"

• model: Model

  将完成您的提示的模型。

  See models for additional details and options.

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

    将完成您的提示的模型。

    See models for additional details and options.

    • "claude-opus-4-7"

      Frontier intelligence for long-running agents and coding

    • "claude-mythos-preview"

      New class of intelligence, strongest in coding and cybersecurity

    • "claude-opus-4-6"

      Frontier intelligence for long-running agents and coding

    • "claude-sonnet-4-6"

      Best combination of speed and intelligence

    • "claude-haiku-4-5"

      Fastest model with near-frontier intelligence

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

      Fastest model with near-frontier intelligence

    • "claude-opus-4-5"

      Premium model combining maximum intelligence with practical performance

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

      Premium model combining maximum intelligence with practical performance

    • "claude-sonnet-4-5"

      High-performance model for agents and coding

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

      High-performance model for agents and coding

    • "claude-opus-4-1"

      Exceptional model for specialized complex tasks

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

      Exceptional model for specialized complex tasks

    • "claude-opus-4-0"

      Powerful model for complex tasks

    • "claude-opus-4-20250514"

      Powerful model for complex tasks

    • "claude-sonnet-4-0"

      High-performance model with extended thinking

    • "claude-sonnet-4-20250514"

      High-performance model with extended thinking

    • "claude-3-haiku-20240307"

      Fast and cost-effective model

  • string

• cache_control: optional BetaCacheControlEphemeral

  Top-level cache control automatically applies a cache_control marker to the last cacheable block in the request.

• container: optional BetaContainerParams or string

  Container identifier for reuse across requests.

  • BetaContainerParams object { id, skills }

    Container parameters with skills to be loaded.

    • id: optional string

      Container id

    • skills: optional array of BetaSkillParams

      List of skills to load in the container

      • skill_id: string

        技能 ID

      • type: "anthropic" or "custom"

        技能类型 - 'anthropic'（内置）或 'custom'（用户自定义）

        • "anthropic"

        • "custom"

      • version: optional string

        技能版本或 'latest' 表示最新版本

  • string

• context_management: optional BetaContextManagementConfig

  Context management configuration.

  This allows you to control how Claude manages context across multiple requests, such as whether to clear function results or not.

  • edits: optional array of BetaClearToolUses20250919Edit or BetaClearThinking20251015Edit or BetaCompact20260112Edit

    List of context management edits to apply

    • BetaClearToolUses20250919Edit object { type, clear_at_least, clear_tool_inputs, 3 more }

      • type: "clear_tool_uses_20250919"

        • "clear_tool_uses_20250919"

      • clear_at_least: optional BetaInputTokensClearAtLeast

        Minimum number of tokens that must be cleared when triggered. Context will only be modified if at least this many tokens can be removed.

        • type: "input_tokens"

          • "input_tokens"

        • value: number

      • clear_tool_inputs: optional boolean or array of string

        Whether to clear all tool inputs (bool) or specific tool inputs to clear (list)

        • boolean

        • array of string

      • exclude_tools: optional array of string

        Tool names whose uses are preserved from clearing

      • keep: optional BetaToolUsesKeep

        Number of tool uses to retain in the conversation

        • type: "tool_uses"

          • "tool_uses"

        • value: number

      • trigger: optional BetaInputTokensTrigger or BetaToolUsesTrigger

        Condition that triggers the context management strategy

        • BetaInputTokensTrigger object { type, value }

          • type: "input_tokens"

            • "input_tokens"

          • value: number

        • BetaToolUsesTrigger object { type, value }

          • type: "tool_uses"

            • "tool_uses"

          • value: number

    • BetaClearThinking20251015Edit object { type, keep }

      • type: "clear_thinking_20251015"

        • "clear_thinking_20251015"

      • keep: optional BetaThinkingTurns or BetaAllThinkingTurns or "all"

        Number of most recent assistant turns to keep thinking blocks for. Older turns will have their thinking blocks removed.

        • BetaThinkingTurns object { type, value }

          • type: "thinking_turns"

            • "thinking_turns"

          • value: number

        • BetaAllThinkingTurns object { type }

          • type: "all"

            • "all"

        • "all"

          • "all"

    • BetaCompact20260112Edit object { type, instructions, pause_after_compaction, trigger }

      Automatically compact older context when reaching the configured trigger threshold.

      • type: "compact_20260112"

        • "compact_20260112"

      • instructions: optional string

        Additional instructions for summarization.

      • pause_after_compaction: optional boolean

        Whether to pause after compaction and return the compaction block to the user.

      • trigger: optional BetaInputTokensTrigger

        When to trigger compaction. Defaults to 150000 input tokens.

• diagnostics: optional BetaDiagnosticsParam

  Request-level diagnostics. Currently carries the previous response id for prompt-cache divergence reporting.

  • previous_message_id: optional string

    此客户端先前 /v1/messages 响应中的 id（msg_...）。服务器将该请求的提示指纹与此请求进行比较，并在提示缓存前缀无法重用时返回 diagnostics.cache_miss_reason。在第一轮传递 null 以在没有先前消息可比较的情况下选择加入。

• inference_geo: optional string

  Specifies the geographic region for inference processing. If not specified, the workspace's default_inference_geo is used.

• mcp_servers: optional array of BetaRequestMCPServerURLDefinition

  MCP servers to be utilized in this request

  • name: string

  • type: "url"

    • "url"

  • url: string

  • authorization_token: optional string

  • tool_configuration: optional BetaRequestMCPServerToolConfiguration

    • allowed_tools: optional array of string

    • enabled: optional boolean

• metadata: optional BetaMetadata

  描述请求元数据的对象。

  • user_id: optional string

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

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

• output_config: optional BetaOutputConfig

  Configuration options for the model's output, such as the output format.

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

    All possible effort levels.

    • "low"

    • "medium"

    • "high"

    • "xhigh"

    • "max"

  • format: optional BetaJSONOutputFormat

    A schema to specify Claude's output format in responses. See structured outputs

    • schema: map[unknown]

      The JSON schema of the format

    • type: "json_schema"

      • "json_schema"

  • task_budget: optional BetaTokenTaskBudget

    User-configurable total token budget across contexts.

    • total: number

      Total token budget across all contexts in the session.

    • type: "tokens"

      预算类型。目前仅支持 'tokens'。

      • "tokens"

    • remaining: optional number

      Remaining tokens in the budget. Use this to track usage across contexts when implementing compaction client-side. Defaults to total if not provided.

• output_format: optional BetaJSONOutputFormat

  Deprecated: Use output_config.format instead. See structured outputs

  A schema to specify Claude's output format in responses. This parameter will be removed in a future release.

• service_tier: optional "auto" or "standard_only"

  Determines whether to use priority capacity (if available) or standard capacity for this request.

  Anthropic offers different levels of service for your API requests. See service-tiers for details.

  • "auto"

  • "standard_only"

• speed: optional "standard" or "fast"

  此请求的推理速度模式。"fast" 启用高输出 token/秒推理。

  • "standard"

  • "fast"

• stop_sequences: optional array of string

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

  Our models will normally stop when they have naturally completed their turn, which will result in a response stop_reason of "end_turn".

  If you want the model to stop generating when it encounters custom strings of text, you can use the stop_sequences parameter. If the model encounters one of the custom sequences, the response stop_reason value will be "stop_sequence" and the response stop_sequence value will contain the matched stop sequence.

• stream: optional boolean

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

  See streaming for details.

• system: optional string or array of BetaTextBlockParam

  System prompt.

  系统提示是向 Claude 提供上下文和指令的一种方式，例如指定特定目标或角色。 See our guide to system prompts.

  • string

  • array of BetaTextBlockParam

    • text: string

    • type: "text"

    • cache_control: optional BetaCacheControlEphemeral

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

    • citations: optional array of BetaTextCitationParam

• temperature: optional number

  注入响应的随机性程度。

  默认为 1.0。范围从 0.0 到 1.0。 Use temperature closer to 0.0 for analytical / multiple choice, and closer to 1.0 for creative and generative tasks.

  Note that even with temperature of 0.0, the results will not be fully deterministic.

• thinking: optional BetaThinkingConfigParam

  Configuration for enabling Claude's extended thinking.

  When enabled, responses include thinking content blocks showing Claude's thinking process before the final answer. Requires a minimum budget of 1,024 tokens and counts towards your max_tokens limit.

  See extended thinking for details.

  • BetaThinkingConfigEnabled object { budget_tokens, type, display }

    • budget_tokens: number

      Determines how many tokens Claude can use for its internal reasoning process. Larger budgets can enable more thorough analysis for complex problems, improving response quality.

      Must be ≥1024 and less than max_tokens.

      See extended thinking for details.

    • type: "enabled"

      • "enabled"

    • display: optional "summarized" or "omitted"

      Controls how thinking content appears in the response. When set to summarized, thinking is returned normally. When set to omitted, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to summarized.

      • "summarized"

      • "omitted"

  • BetaThinkingConfigDisabled object { type }

    • type: "disabled"

      • "disabled"

  • BetaThinkingConfigAdaptive object { type, display }

    • type: "adaptive"

      • "adaptive"

    • display: optional "summarized" or "omitted"

      Controls how thinking content appears in the response. When set to summarized, thinking is returned normally. When set to omitted, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to summarized.

      • "summarized"

      • "omitted"

• tool_choice: optional BetaToolChoice

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

  • BetaToolChoiceAuto object { type, disable_parallel_tool_use }

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

    • type: "auto"

      • "auto"

    • disable_parallel_tool_use: optional boolean

      Whether to disable parallel tool use.

      Defaults to false. If set to true, the model will output at most one tool use.

  • BetaToolChoiceAny object { type, disable_parallel_tool_use }

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

    • type: "any"

      • "any"

    • disable_parallel_tool_use: optional boolean

      Whether to disable parallel tool use.

      Defaults to false. If set to true, the model will output exactly one tool use.

  • BetaToolChoiceTool object { name, type, disable_parallel_tool_use }

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

    • name: string

      要使用的工具的名称。

    • type: "tool"

      • "tool"

    • disable_parallel_tool_use: optional boolean

      Whether to disable parallel tool use.

      Defaults to false. If set to true, the model will output exactly one tool use.

  • BetaToolChoiceNone object { type }

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

    • type: "none"

      • "none"

• tools: optional array of BetaToolUnion

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

  If you include tools in your API request, the model may return tool_use content blocks that represent the model's use of those tools. You can then run those tools using the tool input generated by the model and then optionally return results back to the model using tool_result content blocks.

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

  Each tool definition includes:

  • name: Name of the tool.
  • description: Optional, but strongly-recommended description of the tool.
  • input_schema: JSON schema for the tool input shape that the model will produce in tool_use output content blocks.

  For example, if you defined tools as:

  [
    {
      "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"]
      }
    }
  ]
  

  And then asked the model "What's the S&P 500 at today?", the model might produce tool_use content blocks in the response like this:

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

  You might then run your get_stock_price tool with {"ticker": "^GSPC"} as an input, and return the following back to the model in a subsequent user message:

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

  Tools can be used for workflows that include running client-side tools and functions, or more generally whenever you want the model to produce a particular JSON structure of output.

  See our guide for more details.

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

    • input_schema: object { type, properties, required }

      JSON schema for this tool's input.

      This defines the shape of the input that your tool accepts and that the model will produce.

      • type: "object"

        • "object"

      • properties: optional map[unknown]

      • required: optional array of string

    • name: string

      Name of the tool.

      This is how the tool will be called by the model and in tool_use blocks.

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

      • "direct"

      • "code_execution_20250825"

      • "code_execution_20260120"

    • cache_control: optional BetaCacheControlEphemeral

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

    • defer_loading: optional boolean

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    • description: optional string

      Description of what this tool does.

      工具描述应尽可能详细。模型获得的关于工具是什么以及如何使用它的信息越多，其表现就越好。您可以使用自然语言描述来强化工具输入 JSON 模式的重要方面。

    • eager_input_streaming: optional boolean

      Enable eager input streaming for this tool. When true, tool input parameters will be streamed incrementally as they are generated, and types will be inferred on-the-fly rather than buffering the full JSON output. When false, streaming is disabled for this tool even if the fine-grained-tool-streaming beta is active. When null (default), uses the default behavior based on beta headers.

    • input_examples: optional array of map[unknown]

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

    • type: optional "custom"

      • "custom"

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

    • name: "bash"

      Name of the tool.

      This is how the tool will be called by the model and in tool_use blocks.

      • "bash"

    • type: "bash_20241022"

      • "bash_20241022"

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

      • "direct"

      • "code_execution_20250825"

      • "code_execution_20260120"

    • cache_control: optional BetaCacheControlEphemeral

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

    • defer_loading: optional boolean

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    • input_examples: optional array of map[unknown]

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

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

    • name: "bash"

      Name of the tool.

      This is how the tool will be called by the model and in tool_use blocks.

      • "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 BetaCacheControlEphemeral

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

    • defer_loading: optional boolean

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    • input_examples: optional array of map[unknown]

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

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

    • name: "code_execution"

      Name of the tool.

      This is how the tool will be called by the model and in tool_use blocks.

      • "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 BetaCacheControlEphemeral

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

    • defer_loading: optional boolean

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

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

    • name: "code_execution"

      Name of the tool.

      This is how the tool will be called by the model and in tool_use blocks.

      • "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 BetaCacheControlEphemeral

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

    • defer_loading: optional boolean

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

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

    Code execution tool with REPL state persistence (daemon mode + gVisor checkpoint).

    • name: "code_execution"

      Name of the tool.

      This is how the tool will be called by the model and in tool_use blocks.

      • "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 BetaCacheControlEphemeral

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

    • defer_loading: optional boolean

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

  • BetaToolComputerUse20241022 object { display_height_px, display_width_px, name, 7 more }

    • display_height_px: number

      显示器的高度（像素）。

    • display_width_px: number

      显示器的宽度（像素）。

    • name: "computer"

      Name of the tool.

      This is how the tool will be called by the model and in tool_use blocks.

      • "computer"

    • type: "computer_20241022"

      • "computer_20241022"

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

      • "direct"

      • "code_execution_20250825"

      • "code_execution_20260120"

    • cache_control: optional BetaCacheControlEphemeral

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

    • defer_loading: optional boolean

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    • display_number: optional number

      The X11 display number (e.g. 0, 1) for the display.

    • input_examples: optional array of map[unknown]

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

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

    • name: "memory"

      Name of the tool.

      This is how the tool will be called by the model and in tool_use blocks.

      • "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 BetaCacheControlEphemeral

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

    • defer_loading: optional boolean

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    • input_examples: optional array of map[unknown]

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

  • BetaToolComputerUse20250124 object { display_height_px, display_width_px, name, 7 more }

    • display_height_px: number

      显示器的高度（像素）。

    • display_width_px: number

      显示器的宽度（像素）。

    • name: "computer"

      Name of the tool.

      This is how the tool will be called by the model and in tool_use blocks.

      • "computer"

    • type: "computer_20250124"

      • "computer_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 BetaCacheControlEphemeral

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

    • defer_loading: optional boolean

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    • display_number: optional number

      The X11 display number (e.g. 0, 1) for the display.

    • input_examples: optional array of map[unknown]

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

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

    • name: "str_replace_editor"

      Name of the tool.

      This is how the tool will be called by the model and in tool_use blocks.

      • "str_replace_editor"

    • type: "text_editor_20241022"

      • "text_editor_20241022"

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

      • "direct"

      • "code_execution_20250825"

      • "code_execution_20260120"

    • cache_control: optional BetaCacheControlEphemeral

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

    • defer_loading: optional boolean

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    • input_examples: optional array of map[unknown]

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

  • BetaToolComputerUse20251124 object { display_height_px, display_width_px, name, 8 more }

    • display_height_px: number

      显示器的高度（像素）。

    • display_width_px: number

      显示器的宽度（像素）。

    • name: "computer"

      Name of the tool.

      This is how the tool will be called by the model and in tool_use blocks.

      • "computer"

    • type: "computer_20251124"

      • "computer_20251124"

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

      • "direct"

      • "code_execution_20250825"

      • "code_execution_20260120"

    • cache_control: optional BetaCacheControlEphemeral

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

    • defer_loading: optional boolean

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    • display_number: optional number

      The X11 display number (e.g. 0, 1) for the display.

    • enable_zoom: optional boolean

      Whether to enable an action to take a zoomed-in screenshot of the screen.

    • input_examples: optional array of map[unknown]

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

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

    • name: "str_replace_editor"

      Name of the tool.

      This is how the tool will be called by the model and in tool_use blocks.

      • "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 BetaCacheControlEphemeral

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

    • defer_loading: optional boolean

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    • input_examples: optional array of map[unknown]

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

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

    • name: "str_replace_based_edit_tool"

      Name of the tool.

      This is how the tool will be called by the model and in tool_use blocks.

      • "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 BetaCacheControlEphemeral

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

    • defer_loading: optional boolean

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    • input_examples: optional array of map[unknown]

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

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

    • name: "str_replace_based_edit_tool"

      Name of the tool.

      This is how the tool will be called by the model and in tool_use blocks.

      • "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 BetaCacheControlEphemeral

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

    • defer_loading: optional boolean

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    • input_examples: optional array of map[unknown]

    • max_characters: optional number

      Maximum number of characters to display when viewing a file. If not specified, defaults to displaying the full file.

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

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

    • name: "web_search"

      Name of the tool.

      This is how the tool will be called by the model and in tool_use blocks.

      • "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

      If provided, only these domains will be included in results. Cannot be used alongside blocked_domains.

    • blocked_domains: optional array of string

      If provided, these domains will never appear in results. Cannot be used alongside allowed_domains.

    • cache_control: optional BetaCacheControlEphemeral

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

    • defer_loading: optional boolean

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    • max_uses: optional number

      Maximum number of times the tool can be used in the API request.

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

    • user_location: optional BetaUserLocation

      Parameters for the user's location. Used to provide more relevant search results.

      • type: "approximate"

        • "approximate"

      • city: optional string

        用户的城市。

      • country: optional string

        用户的两位 ISO 国家代码。

      • region: optional string

        用户的地区。

      • timezone: optional string

        The IANA timezone of the user.

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

    • name: "web_fetch"

      Name of the tool.

      This is how the tool will be called by the model and in tool_use blocks.

      • "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

      List of domains to allow fetching from

    • blocked_domains: optional array of string

      List of domains to block fetching from

    • cache_control: optional BetaCacheControlEphemeral

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

    • citations: optional BetaCitationsConfigParam

      Citations configuration for fetched documents. Citations are disabled by default.

    • defer_loading: optional boolean

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    • max_content_tokens: optional number

      通过在上下文中包含网页文本内容使用的最大 token 数。此限制是近似值，不适用于二进制内容（如 PDF）。

    • max_uses: optional number

      Maximum number of times the tool can be used in the API request.

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

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

    • name: "web_search"

      Name of the tool.

      This is how the tool will be called by the model and in tool_use blocks.

      • "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

      If provided, only these domains will be included in results. Cannot be used alongside blocked_domains.

    • blocked_domains: optional array of string

      If provided, these domains will never appear in results. Cannot be used alongside allowed_domains.

    • cache_control: optional BetaCacheControlEphemeral

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

    • defer_loading: optional boolean

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    • max_uses: optional number

      Maximum number of times the tool can be used in the API request.

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

    • user_location: optional BetaUserLocation

      Parameters for the user's location. Used to provide more relevant search results.

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

    • name: "web_fetch"

      Name of the tool.

      This is how the tool will be called by the model and in tool_use blocks.

      • "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

      List of domains to allow fetching from

    • blocked_domains: optional array of string

      List of domains to block fetching from

    • cache_control: optional BetaCacheControlEphemeral

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

    • citations: optional BetaCitationsConfigParam

      Citations configuration for fetched documents. Citations are disabled by default.

    • defer_loading: optional boolean

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    • max_content_tokens: optional number

      通过在上下文中包含网页文本内容使用的最大 token 数。此限制是近似值，不适用于二进制内容（如 PDF）。

    • max_uses: optional number

      Maximum number of times the tool can be used in the API request.

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

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

    Web fetch tool with use_cache parameter for bypassing cached content.

    • name: "web_fetch"

      Name of the tool.

      This is how the tool will be called by the model and in tool_use blocks.

      • "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

      List of domains to allow fetching from

    • blocked_domains: optional array of string

      List of domains to block fetching from

    • cache_control: optional BetaCacheControlEphemeral

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

    • citations: optional BetaCitationsConfigParam

      Citations configuration for fetched documents. Citations are disabled by default.

    • defer_loading: optional boolean

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    • max_content_tokens: optional number

      通过在上下文中包含网页文本内容使用的最大 token 数。此限制是近似值，不适用于二进制内容（如 PDF）。

    • max_uses: optional number

      Maximum number of times the tool can be used in the API request.

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

    • use_cache: optional boolean

      Whether to use cached content. Set to false to bypass the cache and fetch fresh content. Only set to false when the user explicitly requests fresh content or when fetching rapidly-changing sources.

  • BetaAdvisorTool20260301 object { model, name, type, 6 more }

    • model: Model

      将完成您的提示的模型。

      See models for additional details and options.

    • name: "advisor"

      Name of the tool.

      This is how the tool will be called by the model and in tool_use blocks.

      • "advisor"

    • type: "advisor_20260301"

      • "advisor_20260301"

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

      • "direct"

      • "code_execution_20250825"

      • "code_execution_20260120"

    • cache_control: optional BetaCacheControlEphemeral

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

    • caching: optional BetaCacheControlEphemeral

      Caching for the advisor's own prompt. When set, each advisor call writes a cache entry at the given TTL so subsequent calls in the same conversation read the stable prefix. When omitted, the advisor prompt is not cached.

    • defer_loading: optional boolean

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    • max_uses: optional number

      Maximum number of times the tool can be used in the API request.

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

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

    • name: "tool_search_tool_bm25"

      Name of the tool.

      This is how the tool will be called by the model and in tool_use blocks.

      • "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 BetaCacheControlEphemeral

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

    • defer_loading: optional boolean

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

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

    • name: "tool_search_tool_regex"

      Name of the tool.

      This is how the tool will be called by the model and in tool_use blocks.

      • "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 BetaCacheControlEphemeral

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

    • defer_loading: optional boolean

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

  • BetaMCPToolset object { mcp_server_name, type, cache_control, 2 more }

    Configuration for a group of tools from an MCP server.

    Allows configuring enabled status and defer_loading for all tools from an MCP server, with optional per-tool overrides.

    • mcp_server_name: string

      Name of the MCP server to configure tools for

    • type: "mcp_toolset"

      • "mcp_toolset"

    • cache_control: optional BetaCacheControlEphemeral

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

    • configs: optional map[BetaMCPToolConfig]

      Configuration overrides for specific tools, keyed by tool name

      • defer_loading: optional boolean

      • enabled: optional boolean

    • default_config: optional BetaMCPToolDefaultConfig

      Default configuration applied to all tools from this server

      • defer_loading: optional boolean

      • enabled: optional boolean

• top_k: optional number

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

  Used to remove "long tail" low probability responses. Learn more technical details here.

  Recommended for advanced use cases only.

• top_p: optional number

  使用核采样。

  In nucleus sampling, we compute the cumulative distribution over all the options for each subsequent token in decreasing probability order and cut it off once it reaches a particular probability specified by top_p.

  Recommended for advanced use cases only.

• user_profile_id: optional string

  用于归因此请求的用户配置文件 ID。当代表非您组织的方行事时使用。

返回

• BetaMessage object { id, container, content, 9 more }

  • id: string

    唯一对象标识符。

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

  • container: BetaContainer

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

    • id: string

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

    • expires_at: string

      容器将过期的时间。

    • skills: array of BetaSkill

      容器中加载的技能

      • skill_id: string

        技能 ID

      • type: "anthropic" or "custom"

        技能类型 - 'anthropic'（内置）或 'custom'（用户自定义）

        • "anthropic"

        • "custom"

      • version: string

        技能版本或 'latest' 表示最新版本

  • content: array of BetaContentBlock

    模型生成的内容。

    这是一个内容块数组，每个块都有一个决定其形状的 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)"}]
    

    • BetaTextBlock object { citations, text, type }

      • citations: array of BetaTextCitation

        支持文本块的引用。

        返回的引用类型取决于被引用文档的类型。引用 PDF 会返回 page_location，纯文本返回 char_location，内容文档返回 content_block_location。

        • BetaCitationCharLocation 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"

        • BetaCitationPageLocation 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"

        • BetaCitationContentBlockLocation 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"

        • BetaCitationsWebSearchResultLocation 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

        • BetaCitationSearchResultLocation 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"

    • BetaThinkingBlock object { signature, thinking, type }

      • signature: string

      • thinking: string

      • type: "thinking"

        • "thinking"

    • BetaRedactedThinkingBlock object { data, type }

      • data: string

      • type: "redacted_thinking"

        • "redacted_thinking"

    • BetaToolUseBlock object { id, input, name, 2 more }

      • id: string

      • input: map[unknown]

      • name: string

      • type: "tool_use"

        • "tool_use"

      • caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

        模型直接发起的工具调用。

        • BetaDirectCaller object { type }

          模型直接发起的工具调用。

          • type: "direct"

            • "direct"

        • BetaServerToolCaller object { tool_id, type }

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

          • tool_id: string

          • type: "code_execution_20250825"

            • "code_execution_20250825"

        • BetaServerToolCaller20260120 object { tool_id, type }

          • tool_id: string

          • type: "code_execution_20260120"

            • "code_execution_20260120"

    • BetaServerToolUseBlock object { id, input, name, 2 more }

      • id: string

      • input: map[unknown]

      • name: "advisor" or "web_search" or "web_fetch" or 5 more

        • "advisor"

        • "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"

      • caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

        模型直接发起的工具调用。

        • BetaDirectCaller object { type }

          模型直接发起的工具调用。

        • BetaServerToolCaller object { tool_id, type }

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

        • BetaServerToolCaller20260120 object { tool_id, type }

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

      • content: BetaWebSearchToolResultBlockContent

        • BetaWebSearchToolResultError object { error_code, type }

          • error_code: BetaWebSearchToolResultErrorCode

            • "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 BetaWebSearchResultBlock

          • 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"

      • caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

        模型直接发起的工具调用。

        • BetaDirectCaller object { type }

          模型直接发起的工具调用。

        • BetaServerToolCaller object { tool_id, type }

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

        • BetaServerToolCaller20260120 object { tool_id, type }

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

      • content: BetaWebFetchToolResultErrorBlock or BetaWebFetchBlock

        • BetaWebFetchToolResultErrorBlock object { error_code, type }

          • error_code: BetaWebFetchToolResultErrorCode

            • "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"

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

          • content: BetaDocumentBlock

            • citations: BetaCitationConfig

              Citation configuration for the document

              • enabled: boolean

            • source: BetaBase64PDFSource or BetaPlainTextSource

              • BetaBase64PDFSource object { data, media_type, type }

                • data: string

                • media_type: "application/pdf"

                  • "application/pdf"

                • type: "base64"

                  • "base64"

              • BetaPlainTextSource 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 timestamp when the content was retrieved

          • type: "web_fetch_result"

            • "web_fetch_result"

          • url: string

            Fetched content URL

      • tool_use_id: string

      • type: "web_fetch_tool_result"

        • "web_fetch_tool_result"

      • caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

        模型直接发起的工具调用。

        • BetaDirectCaller object { type }

          模型直接发起的工具调用。

        • BetaServerToolCaller object { tool_id, type }

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

        • BetaServerToolCaller20260120 object { tool_id, type }

    • BetaAdvisorToolResultBlock object { content, tool_use_id, type }

      • content: BetaAdvisorToolResultError or BetaAdvisorResultBlock or BetaAdvisorRedactedResultBlock

        • BetaAdvisorToolResultError object { error_code, type }

          • error_code: "max_uses_exceeded" or "prompt_too_long" or "too_many_requests" or 3 more

            • "max_uses_exceeded"

            • "prompt_too_long"

            • "too_many_requests"

            • "overloaded"

            • "unavailable"

            • "execution_time_exceeded"

          • type: "advisor_tool_result_error"

            • "advisor_tool_result_error"

        • BetaAdvisorResultBlock object { text, type }

          • text: string

          • type: "advisor_result"

            • "advisor_result"

        • BetaAdvisorRedactedResultBlock object { encrypted_content, type }

          • encrypted_content: string

            Opaque blob containing the advisor's output. Round-trip verbatim; do not inspect or modify.

          • type: "advisor_redacted_result"

            • "advisor_redacted_result"

      • tool_use_id: string

      • type: "advisor_tool_result"

        • "advisor_tool_result"

    • BetaCodeExecutionToolResultBlock object { content, tool_use_id, type }

      • content: BetaCodeExecutionToolResultBlockContent

        代码执行结果，包含用于 PFC + web_search 结果的加密标准输出。

        • BetaCodeExecutionToolResultError object { error_code, type }

          • error_code: BetaCodeExecutionToolResultErrorCode

            • "invalid_tool_input"

            • "unavailable"

            • "too_many_requests"

            • "execution_time_exceeded"

          • type: "code_execution_tool_result_error"

            • "code_execution_tool_result_error"

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

          • content: array of BetaCodeExecutionOutputBlock

            • file_id: string

            • type: "code_execution_output"

              • "code_execution_output"

          • return_code: number

          • stderr: string

          • stdout: string

          • type: "code_execution_result"

            • "code_execution_result"

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

          代码执行结果，包含用于 PFC + web_search 结果的加密标准输出。

          • content: array of BetaCodeExecutionOutputBlock

            • 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"

    • BetaBashCodeExecutionToolResultBlock object { content, tool_use_id, type }

      • content: BetaBashCodeExecutionToolResultError or BetaBashCodeExecutionResultBlock

        • BetaBashCodeExecutionToolResultError object { error_code, type }

          • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more

            • "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"

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

          • content: array of BetaBashCodeExecutionOutputBlock

            • 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"

    • BetaTextEditorCodeExecutionToolResultBlock object { content, tool_use_id, type }

      • content: BetaTextEditorCodeExecutionToolResultError or BetaTextEditorCodeExecutionViewResultBlock or BetaTextEditorCodeExecutionCreateResultBlock or BetaTextEditorCodeExecutionStrReplaceResultBlock

        • BetaTextEditorCodeExecutionToolResultError object { error_code, error_message, type }

          • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more

            • "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"

        • BetaTextEditorCodeExecutionViewResultBlock 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"

        • BetaTextEditorCodeExecutionCreateResultBlock object { is_file_update, type }

          • is_file_update: boolean

          • type: "text_editor_code_execution_create_result"

            • "text_editor_code_execution_create_result"

        • BetaTextEditorCodeExecutionStrReplaceResultBlock 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"

    • BetaToolSearchToolResultBlock object { content, tool_use_id, type }

      • content: BetaToolSearchToolResultError or BetaToolSearchToolSearchResultBlock

        • BetaToolSearchToolResultError object { error_code, error_message, type }

          • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"

            • "invalid_tool_input"

            • "unavailable"

            • "too_many_requests"

            • "execution_time_exceeded"

          • error_message: string

          • type: "tool_search_tool_result_error"

            • "tool_search_tool_result_error"

        • BetaToolSearchToolSearchResultBlock object { tool_references, type }

          • tool_references: array of BetaToolReferenceBlock

            • 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"

    • BetaMCPToolUseBlock object { id, input, name, 2 more }

      • id: string

      • input: map[unknown]

      • name: string

        MCP 工具的名称

      • server_name: string

        MCP 服务器的名称

      • type: "mcp_tool_use"

        • "mcp_tool_use"

    • BetaMCPToolResultBlock object { content, is_error, tool_use_id, type }

      • content: string or array of BetaTextBlock

        • string

        • BetaMCPToolResultBlockContent = array of BetaTextBlock

          • citations: array of BetaTextCitation

            支持文本块的引用。

            返回的引用类型取决于被引用文档的类型。引用 PDF 会返回 page_location，纯文本返回 char_location，内容文档返回 content_block_location。

          • text: string

          • type: "text"

      • is_error: boolean

      • tool_use_id: string

      • type: "mcp_tool_result"

        • "mcp_tool_result"

    • BetaContainerUploadBlock object { file_id, type }

      Response model for a file uploaded to the container.

      • file_id: string

      • type: "container_upload"

        • "container_upload"

    • BetaCompactionBlock object { content, encrypted_content, type }

      A compaction block returned when autocompact is triggered.

      When content is None, it indicates the compaction failed to produce a valid summary (e.g., malformed output from the model). Clients may round-trip compaction blocks with null content; the server treats them as no-ops.

      • content: string

        Summary of compacted content, or null if compaction failed

      • encrypted_content: string

        Opaque metadata from prior compaction, to be round-tripped verbatim

      • type: "compaction"

        • "compaction"

  • context_management: BetaContextManagementResponse

    Context management response.

    Information about context management strategies applied during the request.

    • applied_edits: array of BetaClearToolUses20250919EditResponse or BetaClearThinking20251015EditResponse

      List of context management edits that were applied.

      • BetaClearToolUses20250919EditResponse object { cleared_input_tokens, cleared_tool_uses, type }

        • cleared_input_tokens: number

          Number of input tokens cleared by this edit.

        • cleared_tool_uses: number

          Number of tool uses that were cleared.

        • type: "clear_tool_uses_20250919"

          应用的上下文管理编辑类型。

          • "clear_tool_uses_20250919"

      • BetaClearThinking20251015EditResponse object { cleared_input_tokens, cleared_thinking_turns, type }

        • cleared_input_tokens: number

          Number of input tokens cleared by this edit.

        • cleared_thinking_turns: number

          Number of thinking turns that were cleared.

        • type: "clear_thinking_20251015"

          应用的上下文管理编辑类型。

          • "clear_thinking_20251015"

  • diagnostics: BetaDiagnostics

    Response envelope for request-level diagnostics. Present (possibly null) whenever the caller supplied diagnostics on the request.

    • cache_miss_reason: BetaCacheMissModelChanged or BetaCacheMissSystemChanged or BetaCacheMissToolsChanged or 3 more

      Explains why the prompt cache could not fully reuse the prefix from the request identified by diagnostics.previous_message_id. null means diagnosis is still pending — the response was serialized before the background comparison completed.

      • BetaCacheMissModelChanged object { cache_missed_input_tokens, type }

        • cache_missed_input_tokens: number

          Approximate number of input tokens that would have been read from cache had the prefix matched the previous request.

        • type: "model_changed"

          • "model_changed"

      • BetaCacheMissSystemChanged object { cache_missed_input_tokens, type }

        • cache_missed_input_tokens: number

          Approximate number of input tokens that would have been read from cache had the prefix matched the previous request.

        • type: "system_changed"

          • "system_changed"

      • BetaCacheMissToolsChanged object { cache_missed_input_tokens, type }

        • cache_missed_input_tokens: number

          Approximate number of input tokens that would have been read from cache had the prefix matched the previous request.

        • type: "tools_changed"

          • "tools_changed"

      • BetaCacheMissMessagesChanged object { cache_missed_input_tokens, type }

        • cache_missed_input_tokens: number

          Approximate number of input tokens that would have been read from cache had the prefix matched the previous request.

        • type: "messages_changed"

          • "messages_changed"

      • BetaCacheMissPreviousMessageNotFound object { type }

        • type: "previous_message_not_found"

          • "previous_message_not_found"

      • BetaCacheMissUnavailable object { type }

        • type: "unavailable"

          • "unavailable"

  • model: Model

    将完成您的提示的模型。

    See models for additional details and options.

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

      将完成您的提示的模型。

      See models for additional details and options.

      • "claude-opus-4-7"

        Frontier intelligence for long-running agents and coding

      • "claude-mythos-preview"

        New class of intelligence, strongest in coding and cybersecurity

      • "claude-opus-4-6"

        Frontier intelligence for long-running agents and coding

      • "claude-sonnet-4-6"

        Best combination of speed and intelligence

      • "claude-haiku-4-5"

        Fastest model with near-frontier intelligence

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

        Fastest model with near-frontier intelligence

      • "claude-opus-4-5"

        Premium model combining maximum intelligence with practical performance

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

        Premium model combining maximum intelligence with practical performance

      • "claude-sonnet-4-5"

        High-performance model for agents and coding

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

        High-performance model for agents and coding

      • "claude-opus-4-1"

        Exceptional model for specialized complex tasks

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

        Exceptional model for specialized complex tasks

      • "claude-opus-4-0"

        Powerful model for complex tasks

      • "claude-opus-4-20250514"

        Powerful model for complex tasks

      • "claude-sonnet-4-0"

        High-performance model with extended thinking

      • "claude-sonnet-4-20250514"

        High-performance model with extended thinking

      • "claude-3-haiku-20240307"

        Fast and cost-effective model

    • string

  • role: "assistant"

    Conversational role of the generated message.

    This will always be "assistant".

    • "assistant"

  • stop_details: BetaRefusalStopDetails

    Structured information about a refusal.

    • category: "cyber" or "bio"

      触发拒绝的策略类别。

      null when the refusal doesn't map to a named category.

      • "cyber"

      • "bio"

    • explanation: string

      Human-readable explanation of the refusal.

      This text is not guaranteed to be stable. null when no explanation is available for the category.

    • type: "refusal"

      • "refusal"

  • stop_reason: BetaStopReason

    我们停止的原因。

    可以是以下值之一：

    • "end_turn": the model reached a natural stopping point
    • "max_tokens": we exceeded the requested max_tokens or the model's maximum
    • "stop_sequence": one of your provided custom stop_sequences was generated
    • "tool_use": the model invoked one or more tools
    • "pause_turn": we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue.
    • "refusal": when streaming classifiers intervene to handle potential policy violations

    In non-streaming mode this value is always non-null. In streaming mode, it is null in the message_start event and non-null otherwise.

    • "end_turn"

    • "max_tokens"

    • "stop_sequence"

    • "tool_use"

    • "pause_turn"

    • "compaction"

    • "refusal"

    • "model_context_window_exceeded"

  • stop_sequence: string

    Which custom stop sequence was generated, if any.

    This value will be a non-null string if one of your custom stop sequences was generated.

  • type: "message"

    对象类型。

    For Messages, this is always "message".

    • "message"

  • usage: BetaUsage

    Billing and rate-limit usage.

    Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems.

    Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in usage will not match one-to-one with the exact visible content of an API request or response.

    For example, output_tokens will be non-zero, even for an empty string response from Claude.

    Total input tokens in a request is the summation of input_tokens, cache_creation_input_tokens, and cache_read_input_tokens.

    • cache_creation: BetaCacheCreation

      Breakdown of cached tokens by TTL

      • 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 数。

    • iterations: BetaIterationsUsage

      Per-iteration token usage breakdown.

      Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to:

      • Determine which iterations exceeded long context thresholds (>=200k tokens)

      • Calculate the true context window size from the last iteration

      • Understand token accumulation across server-side tool use loops

      • BetaMessageIterationUsage object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }

        Token usage for a sampling iteration.

        • cache_creation: BetaCacheCreation

          Breakdown of cached tokens by TTL

        • cache_creation_input_tokens: number

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

        • cache_read_input_tokens: number

          从缓存读取的输入 token 数。

        • input_tokens: number

          已使用的输入 token 数。

        • output_tokens: number

          已使用的输出 token 数。

        • type: "message"

          Usage for a sampling iteration

          • "message"

      • BetaCompactionIterationUsage object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }

        Token usage for a compaction iteration.

        • cache_creation: BetaCacheCreation

          Breakdown of cached tokens by TTL

        • cache_creation_input_tokens: number

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

        • cache_read_input_tokens: number

          从缓存读取的输入 token 数。

        • input_tokens: number

          已使用的输入 token 数。

        • output_tokens: number

          已使用的输出 token 数。

        • type: "compaction"

          Usage for a compaction iteration

          • "compaction"

      • BetaAdvisorMessageIterationUsage object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 4 more }

        Token usage for an advisor sub-inference iteration.

        • cache_creation: BetaCacheCreation

          Breakdown of cached tokens by TTL

        • cache_creation_input_tokens: number

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

        • cache_read_input_tokens: number

          从缓存读取的输入 token 数。

        • input_tokens: number

          已使用的输入 token 数。

        • model: Model

          将完成您的提示的模型。

          See models for additional details and options.

        • output_tokens: number

          已使用的输出 token 数。

        • type: "advisor_message"

          Usage for an advisor sub-inference iteration

          • "advisor_message"

    • output_tokens: number

      已使用的输出 token 数。

    • server_tool_use: BetaServerToolUsage

      服务器工具请求数。

      • web_fetch_requests: number

        网络获取工具请求数。

      • web_search_requests: number

        网络搜索工具请求数。

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

      If the request used the priority, standard, or batch tier.

      • "standard"

      • "priority"

      • "batch"

    • speed: "standard" or "fast"

      此请求使用的推理速度模式。

      • "standard"

      • "fast"

示例

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",
    "skills": [
      {
        "skill_id": "pdf",
        "type": "anthropic",
        "version": "latest"
      }
    ]
  },
  "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"
    }
  ],
  "context_management": {
    "applied_edits": [
      {
        "cleared_input_tokens": 0,
        "cleared_tool_uses": 0,
        "type": "clear_tool_uses_20250919"
      }
    ]
  },
  "diagnostics": {
    "cache_miss_reason": {
      "cache_missed_input_tokens": 0,
      "type": "model_changed"
    }
  },
  "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,
    "iterations": [
      {
        "cache_creation": {
          "ephemeral_1h_input_tokens": 0,
          "ephemeral_5m_input_tokens": 0
        },
        "cache_creation_input_tokens": 0,
        "cache_read_input_tokens": 0,
        "input_tokens": 0,
        "output_tokens": 0,
        "type": "message"
      }
    ],
    "output_tokens": 503,
    "server_tool_use": {
      "web_fetch_requests": 2,
      "web_search_requests": 0
    },
    "service_tier": "standard",
    "speed": "standard"
  }
}

统计消息中的 token 数

post /v1/messages/count_tokens

统计消息中的 token 数量。

Token 计数 API 可用于统计消息中的 token 数量（包括工具、图像和文档），而无需实际创建消息。

在我们的用户指南中了解更多关于 token 计数的信息

请求头参数

• "anthropic-beta": optional array of AnthropicBeta

  可选的请求头，用于指定您要使用的 beta 版本。

  • string

  • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 more

    • "message-batches-2024-09-24"

    • "prompt-caching-2024-07-31"

    • "computer-use-2024-10-22"

    • "computer-use-2025-01-24"

    • "pdfs-2024-09-25"

    • "token-counting-2024-11-01"

    • "token-efficient-tools-2025-02-19"

    • "output-128k-2025-02-19"

    • "files-api-2025-04-14"

    • "mcp-client-2025-04-04"

    • "mcp-client-2025-11-20"

    • "dev-full-thinking-2025-05-14"

    • "interleaved-thinking-2025-05-14"

    • "code-execution-2025-05-22"

    • "extended-cache-ttl-2025-04-11"

    • "context-1m-2025-08-07"

    • "context-management-2025-06-27"

    • "model-context-window-exceeded-2025-08-26"

    • "skills-2025-10-02"

    • "fast-mode-2026-02-01"

    • "output-300k-2026-03-24"

    • "user-profiles-2026-03-24"

    • "advisor-tool-2026-03-01"

    • "managed-agents-2026-04-01"

    • "cache-diagnosis-2026-04-07"

请求体参数

• messages: array of BetaMessageParam

  输入消息。

  我们的模型经过训练，可以处理交替的 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 BetaContentBlockParam

    • string

    • array of BetaContentBlockParam

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

        • text: string

        • type: "text"

          • "text"

        • cache_control: optional BetaCacheControlEphemeral

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

          • type: "ephemeral"

            • "ephemeral"

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

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

            可以是以下值之一：

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

            默认为 5m。

            • "5m"

            • "1h"

        • citations: optional array of BetaTextCitationParam

          • BetaCitationCharLocationParam 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"

          • BetaCitationPageLocationParam 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"

          • BetaCitationContentBlockLocationParam 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"

          • BetaCitationWebSearchResultLocationParam 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

          • BetaCitationSearchResultLocationParam 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"

      • BetaImageBlockParam object { source, type, cache_control }

        • source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource

          • BetaBase64ImageSource 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"

          • BetaURLImageSource object { type, url }

            • type: "url"

              • "url"

            • url: string

          • BetaFileImageSource object { file_id, type }

            • file_id: string

            • type: "file"

              • "file"

        • type: "image"

          • "image"

        • cache_control: optional BetaCacheControlEphemeral

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

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

        • source: BetaBase64PDFSource or BetaPlainTextSource or BetaContentBlockSource or 2 more

          • BetaBase64PDFSource object { data, media_type, type }

            • data: string

            • media_type: "application/pdf"

              • "application/pdf"

            • type: "base64"

              • "base64"

          • BetaPlainTextSource object { data, media_type, type }

            • data: string

            • media_type: "text/plain"

              • "text/plain"

            • type: "text"

              • "text"

          • BetaContentBlockSource object { content, type }

            • content: string or array of BetaContentBlockSourceContent

              • string

              • BetaContentBlockSourceContent = array of BetaContentBlockSourceContent

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

                • BetaImageBlockParam object { source, type, cache_control }

            • type: "content"

              • "content"

          • BetaURLPDFSource object { type, url }

            • type: "url"

              • "url"

            • url: string

          • BetaFileDocumentSource object { file_id, type }

            • file_id: string

            • type: "file"

              • "file"

        • type: "document"

          • "document"

        • cache_control: optional BetaCacheControlEphemeral

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

        • citations: optional BetaCitationsConfigParam

          • enabled: optional boolean

        • context: optional string

        • title: optional string

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

        • content: array of BetaTextBlockParam

          • text: string

          • type: "text"

          • cache_control: optional BetaCacheControlEphemeral

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

          • citations: optional array of BetaTextCitationParam

        • source: string

        • title: string

        • type: "search_result"

          • "search_result"

        • cache_control: optional BetaCacheControlEphemeral

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

        • citations: optional BetaCitationsConfigParam

      • BetaThinkingBlockParam object { signature, thinking, type }

        • signature: string

        • thinking: string

        • type: "thinking"

          • "thinking"

      • BetaRedactedThinkingBlockParam object { data, type }

        • data: string

        • type: "redacted_thinking"

          • "redacted_thinking"

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

        • id: string

        • input: map[unknown]

        • name: string

        • type: "tool_use"

          • "tool_use"

        • cache_control: optional BetaCacheControlEphemeral

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

        • caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

          模型直接发起的工具调用。

          • BetaDirectCaller object { type }

            模型直接发起的工具调用。

            • type: "direct"

              • "direct"

          • BetaServerToolCaller object { tool_id, type }

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

            • tool_id: string

            • type: "code_execution_20250825"

              • "code_execution_20250825"

          • BetaServerToolCaller20260120 object { tool_id, type }

            • tool_id: string

            • type: "code_execution_20260120"

              • "code_execution_20260120"

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

        • tool_use_id: string

        • type: "tool_result"

          • "tool_result"

        • cache_control: optional BetaCacheControlEphemeral

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

        • content: optional string or array of BetaTextBlockParam or BetaImageBlockParam or BetaSearchResultBlockParam or 2 more

          • string

          • array of BetaTextBlockParam or BetaImageBlockParam or BetaSearchResultBlockParam or 2 more

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

            • BetaImageBlockParam object { source, type, cache_control }

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

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

            • BetaToolReferenceBlockParam object { tool_name, type, cache_control }

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

              • tool_name: string

              • type: "tool_reference"

                • "tool_reference"

              • cache_control: optional BetaCacheControlEphemeral

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

        • is_error: optional boolean

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

        • id: string

        • input: map[unknown]

        • name: "advisor" or "web_search" or "web_fetch" or 5 more

          • "advisor"

          • "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 BetaCacheControlEphemeral

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

        • caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

          模型直接发起的工具调用。

          • BetaDirectCaller object { type }

            模型直接发起的工具调用。

          • BetaServerToolCaller object { tool_id, type }

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

          • BetaServerToolCaller20260120 object { tool_id, type }

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

        • content: BetaWebSearchToolResultBlockParamContent

          • ResultBlock = array of BetaWebSearchResultBlockParam

            • encrypted_content: string

            • title: string

            • type: "web_search_result"

              • "web_search_result"

            • url: string

            • page_age: optional string

          • BetaWebSearchToolRequestError object { error_code, type }

            • error_code: BetaWebSearchToolResultErrorCode

              • "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 BetaCacheControlEphemeral

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

        • caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

          模型直接发起的工具调用。

          • BetaDirectCaller object { type }

            模型直接发起的工具调用。

          • BetaServerToolCaller object { tool_id, type }

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

          • BetaServerToolCaller20260120 object { tool_id, type }

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

        • content: BetaWebFetchToolResultErrorBlockParam or BetaWebFetchBlockParam

          • BetaWebFetchToolResultErrorBlockParam object { error_code, type }

            • error_code: BetaWebFetchToolResultErrorCode

              • "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"

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

            • content: BetaRequestDocumentBlock

            • type: "web_fetch_result"

              • "web_fetch_result"

            • url: string

              Fetched content URL

            • retrieved_at: optional string

              ISO 8601 timestamp when the content was retrieved

        • tool_use_id: string

        • type: "web_fetch_tool_result"

          • "web_fetch_tool_result"

        • cache_control: optional BetaCacheControlEphemeral

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

        • caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

          模型直接发起的工具调用。

          • BetaDirectCaller object { type }

            模型直接发起的工具调用。

          • BetaServerToolCaller object { tool_id, type }

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

          • BetaServerToolCaller20260120 object { tool_id, type }

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

        • content: BetaAdvisorToolResultErrorParam or BetaAdvisorResultBlockParam or BetaAdvisorRedactedResultBlockParam

          • BetaAdvisorToolResultErrorParam object { error_code, type }

            • error_code: "max_uses_exceeded" or "prompt_too_long" or "too_many_requests" or 3 more

              • "max_uses_exceeded"

              • "prompt_too_long"

              • "too_many_requests"

              • "overloaded"

              • "unavailable"

              • "execution_time_exceeded"

            • type: "advisor_tool_result_error"

              • "advisor_tool_result_error"

          • BetaAdvisorResultBlockParam object { text, type }

            • text: string

            • type: "advisor_result"

              • "advisor_result"

          • BetaAdvisorRedactedResultBlockParam object { encrypted_content, type }

            • encrypted_content: string

              由先前响应生成的不透明数据块；必须原样来回传输。

            • type: "advisor_redacted_result"

              • "advisor_redacted_result"

        • tool_use_id: string

        • type: "advisor_tool_result"

          • "advisor_tool_result"

        • cache_control: optional BetaCacheControlEphemeral

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

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

        • content: BetaCodeExecutionToolResultBlockParamContent

          代码执行结果，包含用于 PFC + web_search 结果的加密标准输出。

          • BetaCodeExecutionToolResultErrorParam object { error_code, type }

            • error_code: BetaCodeExecutionToolResultErrorCode

              • "invalid_tool_input"

              • "unavailable"

              • "too_many_requests"

              • "execution_time_exceeded"

            • type: "code_execution_tool_result_error"

              • "code_execution_tool_result_error"

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

            • content: array of BetaCodeExecutionOutputBlockParam

              • file_id: string

              • type: "code_execution_output"

                • "code_execution_output"

            • return_code: number

            • stderr: string

            • stdout: string

            • type: "code_execution_result"

              • "code_execution_result"

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

            代码执行结果，包含用于 PFC + web_search 结果的加密标准输出。

            • content: array of BetaCodeExecutionOutputBlockParam

              • 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 BetaCacheControlEphemeral

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

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

        • content: BetaBashCodeExecutionToolResultErrorParam or BetaBashCodeExecutionResultBlockParam

          • BetaBashCodeExecutionToolResultErrorParam object { error_code, type }

            • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more

              • "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"

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

            • content: array of BetaBashCodeExecutionOutputBlockParam

              • 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 BetaCacheControlEphemeral

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

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

        • content: BetaTextEditorCodeExecutionToolResultErrorParam or BetaTextEditorCodeExecutionViewResultBlockParam or BetaTextEditorCodeExecutionCreateResultBlockParam or BetaTextEditorCodeExecutionStrReplaceResultBlockParam

          • BetaTextEditorCodeExecutionToolResultErrorParam object { error_code, type, error_message }

            • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more

              • "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

          • BetaTextEditorCodeExecutionViewResultBlockParam 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

          • BetaTextEditorCodeExecutionCreateResultBlockParam object { is_file_update, type }

            • is_file_update: boolean

            • type: "text_editor_code_execution_create_result"

              • "text_editor_code_execution_create_result"

          • BetaTextEditorCodeExecutionStrReplaceResultBlockParam 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 BetaCacheControlEphemeral

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

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

        • content: BetaToolSearchToolResultErrorParam or BetaToolSearchToolSearchResultBlockParam

          • BetaToolSearchToolResultErrorParam object { error_code, type }

            • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"

              • "invalid_tool_input"

              • "unavailable"

              • "too_many_requests"

              • "execution_time_exceeded"

            • type: "tool_search_tool_result_error"

              • "tool_search_tool_result_error"

          • BetaToolSearchToolSearchResultBlockParam object { tool_references, type }

            • tool_references: array of BetaToolReferenceBlockParam

              • tool_name: string

              • type: "tool_reference"

              • cache_control: optional BetaCacheControlEphemeral

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

            • 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 BetaCacheControlEphemeral

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

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

        • id: string

        • input: map[unknown]

        • name: string

        • server_name: string

          MCP 服务器的名称

        • type: "mcp_tool_use"

          • "mcp_tool_use"

        • cache_control: optional BetaCacheControlEphemeral

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

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

        • tool_use_id: string

        • type: "mcp_tool_result"

          • "mcp_tool_result"

        • cache_control: optional BetaCacheControlEphemeral

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

        • content: optional string or array of BetaTextBlockParam

          • string

          • BetaMCPToolResultBlockParamContent = array of BetaTextBlockParam

            • text: string

            • type: "text"

            • cache_control: optional BetaCacheControlEphemeral

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

            • citations: optional array of BetaTextCitationParam

        • is_error: optional boolean

      • BetaContainerUploadBlockParam object { file_id, type, cache_control }

        A content block that represents a file to be uploaded to the container Files uploaded via this block will be available in the container's input directory.

        • file_id: string

        • type: "container_upload"

          • "container_upload"

        • cache_control: optional BetaCacheControlEphemeral

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

      • BetaCompactionBlockParam object { content, type, cache_control, encrypted_content }

        A compaction block containing summary of previous context.

        Users should round-trip these blocks from responses to subsequent requests to maintain context across compaction boundaries.

        When content is None, the block represents a failed compaction. The server treats these as no-ops. Empty string content is not allowed.

        • content: string

          Summary of previously compacted content, or null if compaction failed

        • type: "compaction"

          • "compaction"

        • cache_control: optional BetaCacheControlEphemeral

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

        • encrypted_content: optional string

          Opaque metadata from prior compaction, to be round-tripped verbatim

  • role: "user" or "assistant"

    • "user"

    • "assistant"

• model: Model

  将完成您的提示的模型。

  See models for additional details and options.

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

    将完成您的提示的模型。

    See models for additional details and options.

    • "claude-opus-4-7"

      Frontier intelligence for long-running agents and coding

    • "claude-mythos-preview"

      New class of intelligence, strongest in coding and cybersecurity

    • "claude-opus-4-6"

      Frontier intelligence for long-running agents and coding

    • "claude-sonnet-4-6"

      Best combination of speed and intelligence

    • "claude-haiku-4-5"

      Fastest model with near-frontier intelligence

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

      Fastest model with near-frontier intelligence

    • "claude-opus-4-5"

      Premium model combining maximum intelligence with practical performance

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

      Premium model combining maximum intelligence with practical performance

    • "claude-sonnet-4-5"

      High-performance model for agents and coding

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

      High-performance model for agents and coding

    • "claude-opus-4-1"

      Exceptional model for specialized complex tasks

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

      Exceptional model for specialized complex tasks

    • "claude-opus-4-0"

      Powerful model for complex tasks

    • "claude-opus-4-20250514"

      Powerful model for complex tasks

    • "claude-sonnet-4-0"

      High-performance model with extended thinking

    • "claude-sonnet-4-20250514"

      High-performance model with extended thinking

    • "claude-3-haiku-20240307"

      Fast and cost-effective model

  • string

• cache_control: optional BetaCacheControlEphemeral

  Top-level cache control automatically applies a cache_control marker to the last cacheable block in the request.

• context_management: optional BetaContextManagementConfig

  Context management configuration.

  This allows you to control how Claude manages context across multiple requests, such as whether to clear function results or not.

  • edits: optional array of BetaClearToolUses20250919Edit or BetaClearThinking20251015Edit or BetaCompact20260112Edit

    List of context management edits to apply

    • BetaClearToolUses20250919Edit object { type, clear_at_least, clear_tool_inputs, 3 more }

      • type: "clear_tool_uses_20250919"

        • "clear_tool_uses_20250919"

      • clear_at_least: optional BetaInputTokensClearAtLeast

        Minimum number of tokens that must be cleared when triggered. Context will only be modified if at least this many tokens can be removed.

        • type: "input_tokens"

          • "input_tokens"

        • value: number

      • clear_tool_inputs: optional boolean or array of string

        Whether to clear all tool inputs (bool) or specific tool inputs to clear (list)

        • boolean

        • array of string

      • exclude_tools: optional array of string

        Tool names whose uses are preserved from clearing

      • keep: optional BetaToolUsesKeep

        Number of tool uses to retain in the conversation

        • type: "tool_uses"

          • "tool_uses"

        • value: number

      • trigger: optional BetaInputTokensTrigger or BetaToolUsesTrigger

        Condition that triggers the context management strategy

        • BetaInputTokensTrigger object { type, value }

          • type: "input_tokens"

            • "input_tokens"

          • value: number

        • BetaToolUsesTrigger object { type, value }

          • type: "tool_uses"

            • "tool_uses"

          • value: number

    • BetaClearThinking20251015Edit object { type, keep }

      • type: "clear_thinking_20251015"

        • "clear_thinking_20251015"

      • keep: optional BetaThinkingTurns or BetaAllThinkingTurns or "all"

        Number of most recent assistant turns to keep thinking blocks for. Older turns will have their thinking blocks removed.

        • BetaThinkingTurns object { type, value }

          • type: "thinking_turns"

            • "thinking_turns"

          • value: number

        • BetaAllThinkingTurns object { type }

          • type: "all"

            • "all"

        • "all"

          • "all"

    • BetaCompact20260112Edit object { type, instructions, pause_after_compaction, trigger }

      Automatically compact older context when reaching the configured trigger threshold.

      • type: "compact_20260112"

        • "compact_20260112"

      • instructions: optional string

        Additional instructions for summarization.

      • pause_after_compaction: optional boolean

        Whether to pause after compaction and return the compaction block to the user.

      • trigger: optional BetaInputTokensTrigger

        When to trigger compaction. Defaults to 150000 input tokens.

• mcp_servers: optional array of BetaRequestMCPServerURLDefinition

  MCP servers to be utilized in this request

  • name: string

  • type: "url"

    • "url"

  • url: string

  • authorization_token: optional string

  • tool_configuration: optional BetaRequestMCPServerToolConfiguration

    • allowed_tools: optional array of string

    • enabled: optional boolean

• output_config: optional BetaOutputConfig

  Configuration options for the model's output, such as the output format.

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

    All possible effort levels.

    • "low"

    • "medium"

    • "high"

    • "xhigh"

    • "max"

  • format: optional BetaJSONOutputFormat

    A schema to specify Claude's output format in responses. See structured outputs

    • schema: map[unknown]

      The JSON schema of the format

    • type: "json_schema"

      • "json_schema"

  • task_budget: optional BetaTokenTaskBudget

    User-configurable total token budget across contexts.

    • total: number

      Total token budget across all contexts in the session.

    • type: "tokens"

      预算类型。目前仅支持 'tokens'。

      • "tokens"

    • remaining: optional number

      Remaining tokens in the budget. Use this to track usage across contexts when implementing compaction client-side. Defaults to total if not provided.

• output_format: optional BetaJSONOutputFormat

  Deprecated: Use output_config.format instead. See structured outputs

  A schema to specify Claude's output format in responses. This parameter will be removed in a future release.

• speed: optional "standard" or "fast"

  此请求的推理速度模式。"fast" 启用高输出 token/秒推理。

  • "standard"

  • "fast"

• system: optional string or array of BetaTextBlockParam

  System prompt.

  系统提示是向 Claude 提供上下文和指令的一种方式，例如指定特定目标或角色。 See our guide to system prompts.

  • string

  • array of BetaTextBlockParam

    • text: string

    • type: "text"

    • cache_control: optional BetaCacheControlEphemeral

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

    • citations: optional array of BetaTextCitationParam

• thinking: optional BetaThinkingConfigParam

  Configuration for enabling Claude's extended thinking.

  When enabled, responses include thinking content blocks showing Claude's thinking process before the final answer. Requires a minimum budget of 1,024 tokens and counts towards your max_tokens limit.

  See extended thinking for details.

  • BetaThinkingConfigEnabled object { budget_tokens, type, display }

    • budget_tokens: number

      Determines how many tokens Claude can use for its internal reasoning process. Larger budgets can enable more thorough analysis for complex problems, improving response quality.

      Must be ≥1024 and less than max_tokens.

      See extended thinking for details.

    • type: "enabled"

      • "enabled"

    • display: optional "summarized" or "omitted"

      Controls how thinking content appears in the response. When set to summarized, thinking is returned normally. When set to omitted, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to summarized.

      • "summarized"

      • "omitted"

  • BetaThinkingConfigDisabled object { type }

    • type: "disabled"

      • "disabled"

  • BetaThinkingConfigAdaptive object { type, display }

    • type: "adaptive"

      • "adaptive"

    • display: optional "summarized" or "omitted"

      Controls how thinking content appears in the response. When set to summarized, thinking is returned normally. When set to omitted, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to summarized.

      • "summarized"

      • "omitted"

• tool_choice: optional BetaToolChoice

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

  • BetaToolChoiceAuto object { type, disable_parallel_tool_use }

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

    • type: "auto"

      • "auto"

    • disable_parallel_tool_use: optional boolean

      Whether to disable parallel tool use.

      Defaults to false. If set to true, the model will output at most one tool use.

  • BetaToolChoiceAny object { type, disable_parallel_tool_use }

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

    • type: "any"

      • "any"

    • disable_parallel_tool_use: optional boolean

      Whether to disable parallel tool use.

      Defaults to false. If set to true, the model will output exactly one tool use.

  • BetaToolChoiceTool object { name, type, disable_parallel_tool_use }

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

    • name: string

      要使用的工具的名称。

    • type: "tool"

      • "tool"

    • disable_parallel_tool_use: optional boolean

      Whether to disable parallel tool use.

      Defaults to false. If set to true, the model will output exactly one tool use.

  • BetaToolChoiceNone object { type }

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

    • type: "none"

      • "none"

• tools: optional array of BetaTool or BetaToolBash20241022 or BetaToolBash20250124 or 20 more

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

  If you include tools in your API request, the model may return tool_use content blocks that represent the model's use of those tools. You can then run those tools using the tool input generated by the model and then optionally return results back to the model using tool_result content blocks.

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

  Each tool definition includes:

  • name: Name of the tool.
  • description: Optional, but strongly-recommended description of the tool.
  • input_schema: JSON schema for the tool input shape that the model will produce in tool_use output content blocks.

  For example, if you defined tools as:

  [
    {
      "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"]
      }
    }
  ]
  

  And then asked the model "What's the S&P 500 at today?", the model might produce tool_use content blocks in the response like this:

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

  You might then run your get_stock_price tool with {"ticker": "^GSPC"} as an input, and return the following back to the model in a subsequent user message:

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

  Tools can be used for workflows that include running client-side tools and functions, or more generally whenever you want the model to produce a particular JSON structure of output.

  See our guide for more details.

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

    • input_schema: object { type, properties, required }

      JSON schema for this tool's input.

      This defines the shape of the input that your tool accepts and that the model will produce.

      • type: "object"

        • "object"

      • properties: optional map[unknown]

      • required: optional array of string

    • name: string

      Name of the tool.

      This is how the tool will be called by the model and in tool_use blocks.

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

      • "direct"

      • "code_execution_20250825"

      • "code_execution_20260120"

    • cache_control: optional BetaCacheControlEphemeral

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

    • defer_loading: optional boolean

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    • description: optional string

      Description of what this tool does.

      工具描述应尽可能详细。模型获得的关于工具是什么以及如何使用它的信息越多，其表现就越好。您可以使用自然语言描述来强化工具输入 JSON 模式的重要方面。

    • eager_input_streaming: optional boolean

      Enable eager input streaming for this tool. When true, tool input parameters will be streamed incrementally as they are generated, and types will be inferred on-the-fly rather than buffering the full JSON output. When false, streaming is disabled for this tool even if the fine-grained-tool-streaming beta is active. When null (default), uses the default behavior based on beta headers.

    • input_examples: optional array of map[unknown]

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

    • type: optional "custom"

      • "custom"

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

    • name: "bash"

      Name of the tool.

      This is how the tool will be called by the model and in tool_use blocks.

      • "bash"

    • type: "bash_20241022"

      • "bash_20241022"

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

      • "direct"

      • "code_execution_20250825"

      • "code_execution_20260120"

    • cache_control: optional BetaCacheControlEphemeral

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

    • defer_loading: optional boolean

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    • input_examples: optional array of map[unknown]

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

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

    • name: "bash"

      Name of the tool.

      This is how the tool will be called by the model and in tool_use blocks.

      • "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 BetaCacheControlEphemeral

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

    • defer_loading: optional boolean

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    • input_examples: optional array of map[unknown]

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

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

    • name: "code_execution"

      Name of the tool.

      This is how the tool will be called by the model and in tool_use blocks.

      • "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 BetaCacheControlEphemeral

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

    • defer_loading: optional boolean

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

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

    • name: "code_execution"

      Name of the tool.

      This is how the tool will be called by the model and in tool_use blocks.

      • "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 BetaCacheControlEphemeral

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

    • defer_loading: optional boolean

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

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

    Code execution tool with REPL state persistence (daemon mode + gVisor checkpoint).

    • name: "code_execution"

      Name of the tool.

      This is how the tool will be called by the model and in tool_use blocks.

      • "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 BetaCacheControlEphemeral

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

    • defer_loading: optional boolean

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

  • BetaToolComputerUse20241022 object { display_height_px, display_width_px, name, 7 more }

    • display_height_px: number

      显示器的高度（像素）。

    • display_width_px: number

      显示器的宽度（像素）。

    • name: "computer"

      Name of the tool.

      This is how the tool will be called by the model and in tool_use blocks.

      • "computer"

    • type: "computer_20241022"

      • "computer_20241022"

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

      • "direct"

      • "code_execution_20250825"

      • "code_execution_20260120"

    • cache_control: optional BetaCacheControlEphemeral

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

    • defer_loading: optional boolean

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    • display_number: optional number

      The X11 display number (e.g. 0, 1) for the display.

    • input_examples: optional array of map[unknown]

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

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

    • name: "memory"

      Name of the tool.

      This is how the tool will be called by the model and in tool_use blocks.

      • "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 BetaCacheControlEphemeral

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

    • defer_loading: optional boolean

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    • input_examples: optional array of map[unknown]

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

  • BetaToolComputerUse20250124 object { display_height_px, display_width_px, name, 7 more }

    • display_height_px: number

      显示器的高度（像素）。

    • display_width_px: number

      显示器的宽度（像素）。

    • name: "computer"

      Name of the tool.

      This is how the tool will be called by the model and in tool_use blocks.

      • "computer"

    • type: "computer_20250124"

      • "computer_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 BetaCacheControlEphemeral

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

    • defer_loading: optional boolean

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    • display_number: optional number

      The X11 display number (e.g. 0, 1) for the display.

    • input_examples: optional array of map[unknown]

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

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

    • name: "str_replace_editor"

      Name of the tool.

      This is how the tool will be called by the model and in tool_use blocks.

      • "str_replace_editor"

    • type: "text_editor_20241022"

      • "text_editor_20241022"

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

      • "direct"

      • "code_execution_20250825"

      • "code_execution_20260120"

    • cache_control: optional BetaCacheControlEphemeral

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

    • defer_loading: optional boolean

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    • input_examples: optional array of map[unknown]

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

  • BetaToolComputerUse20251124 object { display_height_px, display_width_px, name, 8 more }

    • display_height_px: number

      显示器的高度（像素）。

    • display_width_px: number

      显示器的宽度（像素）。

    • name: "computer"

      Name of the tool.

      This is how the tool will be called by the model and in tool_use blocks.

      • "computer"

    • type: "computer_20251124"

      • "computer_20251124"

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

      • "direct"

      • "code_execution_20250825"

      • "code_execution_20260120"

    • cache_control: optional BetaCacheControlEphemeral

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

    • defer_loading: optional boolean

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    • display_number: optional number

      The X11 display number (e.g. 0, 1) for the display.

    • enable_zoom: optional boolean

      Whether to enable an action to take a zoomed-in screenshot of the screen.

    • input_examples: optional array of map[unknown]

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

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

    • name: "str_replace_editor"

      Name of the tool.

      This is how the tool will be called by the model and in tool_use blocks.

      • "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 BetaCacheControlEphemeral

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

    • defer_loading: optional boolean

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    • input_examples: optional array of map[unknown]

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

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

    • name: "str_replace_based_edit_tool"

      Name of the tool.

      This is how the tool will be called by the model and in tool_use blocks.

      • "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 BetaCacheControlEphemeral

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

    • defer_loading: optional boolean

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    • input_examples: optional array of map[unknown]

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

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

    • name: "str_replace_based_edit_tool"

      Name of the tool.

      This is how the tool will be called by the model and in tool_use blocks.

      • "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 BetaCacheControlEphemeral

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

    • defer_loading: optional boolean

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    • input_examples: optional array of map[unknown]

    • max_characters: optional number

      Maximum number of characters to display when viewing a file. If not specified, defaults to displaying the full file.

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

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

    • name: "web_search"

      Name of the tool.

      This is how the tool will be called by the model and in tool_use blocks.

      • "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

      If provided, only these domains will be included in results. Cannot be used alongside blocked_domains.

    • blocked_domains: optional array of string

      If provided, these domains will never appear in results. Cannot be used alongside allowed_domains.

    • cache_control: optional BetaCacheControlEphemeral

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

    • defer_loading: optional boolean

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    • max_uses: optional number

      Maximum number of times the tool can be used in the API request.

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

    • user_location: optional BetaUserLocation

      Parameters for the user's location. Used to provide more relevant search results.

      • type: "approximate"

        • "approximate"

      • city: optional string

        用户的城市。

      • country: optional string

        用户的两位 ISO 国家代码。

      • region: optional string

        用户的地区。

      • timezone: optional string

        The IANA timezone of the user.

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

    • name: "web_fetch"

      Name of the tool.

      This is how the tool will be called by the model and in tool_use blocks.

      • "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

      List of domains to allow fetching from

    • blocked_domains: optional array of string

      List of domains to block fetching from

    • cache_control: optional BetaCacheControlEphemeral

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

    • citations: optional BetaCitationsConfigParam

      Citations configuration for fetched documents. Citations are disabled by default.

    • defer_loading: optional boolean

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    • max_content_tokens: optional number

      通过在上下文中包含网页文本内容使用的最大 token 数。此限制是近似值，不适用于二进制内容（如 PDF）。

    • max_uses: optional number

      Maximum number of times the tool can be used in the API request.

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

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

    • name: "web_search"

      Name of the tool.

      This is how the tool will be called by the model and in tool_use blocks.

      • "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

      If provided, only these domains will be included in results. Cannot be used alongside blocked_domains.

    • blocked_domains: optional array of string

      If provided, these domains will never appear in results. Cannot be used alongside allowed_domains.

    • cache_control: optional BetaCacheControlEphemeral

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

    • defer_loading: optional boolean

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    • max_uses: optional number

      Maximum number of times the tool can be used in the API request.

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

    • user_location: optional BetaUserLocation

      Parameters for the user's location. Used to provide more relevant search results.

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

    • name: "web_fetch"

      Name of the tool.

      This is how the tool will be called by the model and in tool_use blocks.

      • "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

      List of domains to allow fetching from

    • blocked_domains: optional array of string

      List of domains to block fetching from

    • cache_control: optional BetaCacheControlEphemeral

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

    • citations: optional BetaCitationsConfigParam

      Citations configuration for fetched documents. Citations are disabled by default.

    • defer_loading: optional boolean

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    • max_content_tokens: optional number

      通过在上下文中包含网页文本内容使用的最大 token 数。此限制是近似值，不适用于二进制内容（如 PDF）。

    • max_uses: optional number

      Maximum number of times the tool can be used in the API request.

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

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

    Web fetch tool with use_cache parameter for bypassing cached content.

    • name: "web_fetch"

      Name of the tool.

      This is how the tool will be called by the model and in tool_use blocks.

      • "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

      List of domains to allow fetching from

    • blocked_domains: optional array of string

      List of domains to block fetching from

    • cache_control: optional BetaCacheControlEphemeral

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

    • citations: optional BetaCitationsConfigParam

      Citations configuration for fetched documents. Citations are disabled by default.

    • defer_loading: optional boolean

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    • max_content_tokens: optional number

      通过在上下文中包含网页文本内容使用的最大 token 数。此限制是近似值，不适用于二进制内容（如 PDF）。

    • max_uses: optional number

      Maximum number of times the tool can be used in the API request.

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

    • use_cache: optional boolean

      Whether to use cached content. Set to false to bypass the cache and fetch fresh content. Only set to false when the user explicitly requests fresh content or when fetching rapidly-changing sources.

  • BetaAdvisorTool20260301 object { model, name, type, 6 more }

    • model: Model

      将完成您的提示的模型。

      See models for additional details and options.

    • name: "advisor"

      Name of the tool.

      This is how the tool will be called by the model and in tool_use blocks.

      • "advisor"

    • type: "advisor_20260301"

      • "advisor_20260301"

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

      • "direct"

      • "code_execution_20250825"

      • "code_execution_20260120"

    • cache_control: optional BetaCacheControlEphemeral

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

    • caching: optional BetaCacheControlEphemeral

      Caching for the advisor's own prompt. When set, each advisor call writes a cache entry at the given TTL so subsequent calls in the same conversation read the stable prefix. When omitted, the advisor prompt is not cached.

    • defer_loading: optional boolean

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    • max_uses: optional number

      Maximum number of times the tool can be used in the API request.

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

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

    • name: "tool_search_tool_bm25"

      Name of the tool.

      This is how the tool will be called by the model and in tool_use blocks.

      • "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 BetaCacheControlEphemeral

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

    • defer_loading: optional boolean

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

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

    • name: "tool_search_tool_regex"

      Name of the tool.

      This is how the tool will be called by the model and in tool_use blocks.

      • "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 BetaCacheControlEphemeral

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

    • defer_loading: optional boolean

      If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

  • BetaMCPToolset object { mcp_server_name, type, cache_control, 2 more }

    Configuration for a group of tools from an MCP server.

    Allows configuring enabled status and defer_loading for all tools from an MCP server, with optional per-tool overrides.

    • mcp_server_name: string

      Name of the MCP server to configure tools for

    • type: "mcp_toolset"

      • "mcp_toolset"

    • cache_control: optional BetaCacheControlEphemeral

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

    • configs: optional map[BetaMCPToolConfig]

      Configuration overrides for specific tools, keyed by tool name

      • defer_loading: optional boolean

      • enabled: optional boolean

    • default_config: optional BetaMCPToolDefaultConfig

      Default configuration applied to all tools from this server

      • defer_loading: optional boolean

      • enabled: optional boolean