统计消息中的 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

返回

• BetaMessageTokensCount object { context_management, input_tokens }

  • context_management: BetaCountTokensContextManagementResponse

    Information about context management applied to the message.

    • original_input_tokens: number

      应用上下文管理之前的原始 token 计数

  • input_tokens: number

    提供的消息列表、系统提示和工具的 token 总数。

示例

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

响应

{
  "context_management": {
    "original_input_tokens": 0
  },
  "input_tokens": 2095
}