批处理

创建消息批处理

post /v1/messages/batches

发送一批消息创建请求。

消息批处理 API 可用于同时处理多个 Messages API 请求。消息批处理创建后会立即开始处理。批处理最多可能需要 24 小时才能完成。

在我们的用户指南中了解更多关于消息批处理 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"

请求体参数

• requests: array of object { custom_id, params }

  提示补全请求列表。每个请求都是创建消息的独立请求。

  • custom_id: string

    开发人员为消息批处理中每个请求创建的 ID。用于将结果与请求进行匹配，因为结果可能不按请求顺序返回。

    在消息批处理中，每个请求的此值必须唯一。

  • params: object { max_tokens, messages, model, 21 more }

    单个请求的 Messages API 创建参数。

    有关可用参数的完整文档，请参阅 Messages API 参考。

    • 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。当代表非您组织的方行事时使用。

返回

• BetaMessageBatch object { id, archived_at, cancel_initiated_at, 7 more }

  • id: string

    唯一对象标识符。

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

  • archived_at: string

    RFC 3339 日期时间字符串，表示消息批处理被归档且其结果变为不可用的时间。

  • cancel_initiated_at: string

    RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated.

  • created_at: string

    RFC 3339 日期时间字符串，表示消息批处理创建的时间。

  • ended_at: string

    RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends.

    Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired.

  • expires_at: string

    RFC 3339 日期时间字符串，表示消息批处理将过期并结束处理的时间，即创建后 24 小时。

  • processing_status: "in_progress" or "canceling" or "ended"

    消息批处理的处理状态。

    • "in_progress"

    • "canceling"

    • "ended"

  • request_counts: BetaMessageBatchRequestCounts

    按状态分类统计消息批处理中的请求。

    请求从 processing 开始，只有在整个批处理处理结束后才会转移到其他状态。所有值的总和始终与批处理中的请求总数匹配。

    • canceled: number

      消息批处理中已取消的请求数。

      在整个消息批处理处理结束之前，此值为零。

    • errored: number

      消息批处理中遇到错误的请求数。

      在整个消息批处理处理结束之前，此值为零。

    • expired: number

      消息批处理中已过期的请求数。

      在整个消息批处理处理结束之前，此值为零。

    • processing: number

      Number of requests in the Message Batch that are processing.

    • succeeded: number

      消息批处理中已成功完成的请求数。

      在整个消息批处理处理结束之前，此值为零。

  • results_url: string

    URL to a .jsonl file containing the results of the Message Batch requests. Specified only once processing ends.

    文件中的结果不保证与请求顺序相同。使用 custom_id 字段将结果与请求进行匹配。

  • type: "message_batch"

    对象类型。

    For Message Batches, this is always "message_batch".

    • "message_batch"

示例

curl https://api.anthropic.com/v1/messages/batches \
    -H 'Content-Type: application/json' \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: message-batches-2024-09-24' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY" \
    -d '{
          "requests": [
            {
              "custom_id": "my-custom-id-1",
              "params": {
                "max_tokens": 1024,
                "messages": [
                  {
                    "content": "Hello, world",
                    "role": "user"
                  }
                ],
                "model": "claude-opus-4-6"
              }
            }
          ]
        }'

响应

{
  "id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF",
  "archived_at": "2024-08-20T18:37:24.100435Z",
  "cancel_initiated_at": "2024-08-20T18:37:24.100435Z",
  "created_at": "2024-08-20T18:37:24.100435Z",
  "ended_at": "2024-08-20T18:37:24.100435Z",
  "expires_at": "2024-08-20T18:37:24.100435Z",
  "processing_status": "in_progress",
  "request_counts": {
    "canceled": 10,
    "errored": 30,
    "expired": 10,
    "processing": 100,
    "succeeded": 50
  },
  "results_url": "https://api.anthropic.com/v1/messages/batches/msgbatch_013Zva2CMHLNnXjNJJKqJ2EF/results",
  "type": "message_batch"
}

Retrieve a Message Batch

get /v1/messages/batches/{message_batch_id}

This endpoint is idempotent and can be used to poll for Message Batch completion. To access the results of a Message Batch, make a request to the results_url field in the response.

在我们的用户指南中了解更多关于消息批处理 API 的信息

路径参数

• message_batch_id: string

  消息批处理的 ID。

请求头参数

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

返回

• BetaMessageBatch object { id, archived_at, cancel_initiated_at, 7 more }

  • id: string

    唯一对象标识符。

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

  • archived_at: string

    RFC 3339 日期时间字符串，表示消息批处理被归档且其结果变为不可用的时间。

  • cancel_initiated_at: string

    RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated.

  • created_at: string

    RFC 3339 日期时间字符串，表示消息批处理创建的时间。

  • ended_at: string

    RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends.

    Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired.

  • expires_at: string

    RFC 3339 日期时间字符串，表示消息批处理将过期并结束处理的时间，即创建后 24 小时。

  • processing_status: "in_progress" or "canceling" or "ended"

    消息批处理的处理状态。

    • "in_progress"

    • "canceling"

    • "ended"

  • request_counts: BetaMessageBatchRequestCounts

    按状态分类统计消息批处理中的请求。

    请求从 processing 开始，只有在整个批处理处理结束后才会转移到其他状态。所有值的总和始终与批处理中的请求总数匹配。

    • canceled: number

      消息批处理中已取消的请求数。

      在整个消息批处理处理结束之前，此值为零。

    • errored: number

      消息批处理中遇到错误的请求数。

      在整个消息批处理处理结束之前，此值为零。

    • expired: number

      消息批处理中已过期的请求数。

      在整个消息批处理处理结束之前，此值为零。

    • processing: number

      Number of requests in the Message Batch that are processing.

    • succeeded: number

      消息批处理中已成功完成的请求数。

      在整个消息批处理处理结束之前，此值为零。

  • results_url: string

    URL to a .jsonl file containing the results of the Message Batch requests. Specified only once processing ends.

    文件中的结果不保证与请求顺序相同。使用 custom_id 字段将结果与请求进行匹配。

  • type: "message_batch"

    对象类型。

    For Message Batches, this is always "message_batch".

    • "message_batch"

示例

curl https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: message-batches-2024-09-24' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

响应

{
  "id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF",
  "archived_at": "2024-08-20T18:37:24.100435Z",
  "cancel_initiated_at": "2024-08-20T18:37:24.100435Z",
  "created_at": "2024-08-20T18:37:24.100435Z",
  "ended_at": "2024-08-20T18:37:24.100435Z",
  "expires_at": "2024-08-20T18:37:24.100435Z",
  "processing_status": "in_progress",
  "request_counts": {
    "canceled": 10,
    "errored": 30,
    "expired": 10,
    "processing": 100,
    "succeeded": 50
  },
  "results_url": "https://api.anthropic.com/v1/messages/batches/msgbatch_013Zva2CMHLNnXjNJJKqJ2EF/results",
  "type": "message_batch"
}

List Message Batches

get /v1/messages/batches

List all Message Batches within a Workspace. Most recently created batches are returned first.

在我们的用户指南中了解更多关于消息批处理 API 的信息

查询参数

• after_id: optional string

  用作分页游标的对象 ID。提供时，返回此对象之后的结果页。

• before_id: optional string

  用作分页游标的对象 ID。提供时，返回此对象之前的结果页。

• limit: optional number

  每页返回的项目数。

  默认为 20。范围从 1 到 1000。

请求头参数

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

返回

• data: array of BetaMessageBatch

  • id: string

    唯一对象标识符。

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

  • archived_at: string

    RFC 3339 日期时间字符串，表示消息批处理被归档且其结果变为不可用的时间。

  • cancel_initiated_at: string

    RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated.

  • created_at: string

    RFC 3339 日期时间字符串，表示消息批处理创建的时间。

  • ended_at: string

    RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends.

    Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired.

  • expires_at: string

    RFC 3339 日期时间字符串，表示消息批处理将过期并结束处理的时间，即创建后 24 小时。

  • processing_status: "in_progress" or "canceling" or "ended"

    消息批处理的处理状态。

    • "in_progress"

    • "canceling"

    • "ended"

  • request_counts: BetaMessageBatchRequestCounts

    按状态分类统计消息批处理中的请求。

    请求从 processing 开始，只有在整个批处理处理结束后才会转移到其他状态。所有值的总和始终与批处理中的请求总数匹配。

    • canceled: number

      消息批处理中已取消的请求数。

      在整个消息批处理处理结束之前，此值为零。

    • errored: number

      消息批处理中遇到错误的请求数。

      在整个消息批处理处理结束之前，此值为零。

    • expired: number

      消息批处理中已过期的请求数。

      在整个消息批处理处理结束之前，此值为零。

    • processing: number

      Number of requests in the Message Batch that are processing.

    • succeeded: number

      消息批处理中已成功完成的请求数。

      在整个消息批处理处理结束之前，此值为零。

  • results_url: string

    URL to a .jsonl file containing the results of the Message Batch requests. Specified only once processing ends.

    文件中的结果不保证与请求顺序相同。使用 custom_id 字段将结果与请求进行匹配。

  • type: "message_batch"

    对象类型。

    For Message Batches, this is always "message_batch".

    • "message_batch"

• first_id: string

  First ID in the data 列表。 Can be used as the before_id for the previous page.

• has_more: boolean

  Indicates if there are more results in the requested page direction.

• last_id: string

  Last ID in the data 列表。 Can be used as the after_id for the next page.

示例

curl https://api.anthropic.com/v1/messages/batches \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: message-batches-2024-09-24' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

响应

{
  "data": [
    {
      "id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF",
      "archived_at": "2024-08-20T18:37:24.100435Z",
      "cancel_initiated_at": "2024-08-20T18:37:24.100435Z",
      "created_at": "2024-08-20T18:37:24.100435Z",
      "ended_at": "2024-08-20T18:37:24.100435Z",
      "expires_at": "2024-08-20T18:37:24.100435Z",
      "processing_status": "in_progress",
      "request_counts": {
        "canceled": 10,
        "errored": 30,
        "expired": 10,
        "processing": 100,
        "succeeded": 50
      },
      "results_url": "https://api.anthropic.com/v1/messages/batches/msgbatch_013Zva2CMHLNnXjNJJKqJ2EF/results",
      "type": "message_batch"
    }
  ],
  "first_id": "first_id",
  "has_more": true,
  "last_id": "last_id"
}

Cancel a Message Batch

post /v1/messages/batches/{message_batch_id}/cancel

Batches may be canceled any time before processing ends. Once cancellation is initiated, the batch enters a canceling state, at which time the system may complete any in-progress, non-interruptible requests before finalizing cancellation.

已取消的请求数在 request_counts 中指定。要确定哪些请求被取消，请检查批处理中的各个结果。请注意，如果请求不可中断，取消可能不会导致任何请求被取消。

在我们的用户指南中了解更多关于消息批处理 API 的信息

路径参数

• message_batch_id: string

  消息批处理的 ID。

请求头参数

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

返回

• BetaMessageBatch object { id, archived_at, cancel_initiated_at, 7 more }

  • id: string

    唯一对象标识符。

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

  • archived_at: string

    RFC 3339 日期时间字符串，表示消息批处理被归档且其结果变为不可用的时间。

  • cancel_initiated_at: string

    RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated.

  • created_at: string

    RFC 3339 日期时间字符串，表示消息批处理创建的时间。

  • ended_at: string

    RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends.

    Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired.

  • expires_at: string

    RFC 3339 日期时间字符串，表示消息批处理将过期并结束处理的时间，即创建后 24 小时。

  • processing_status: "in_progress" or "canceling" or "ended"

    消息批处理的处理状态。

    • "in_progress"

    • "canceling"

    • "ended"

  • request_counts: BetaMessageBatchRequestCounts

    按状态分类统计消息批处理中的请求。

    请求从 processing 开始，只有在整个批处理处理结束后才会转移到其他状态。所有值的总和始终与批处理中的请求总数匹配。

    • canceled: number

      消息批处理中已取消的请求数。

      在整个消息批处理处理结束之前，此值为零。

    • errored: number

      消息批处理中遇到错误的请求数。

      在整个消息批处理处理结束之前，此值为零。

    • expired: number

      消息批处理中已过期的请求数。

      在整个消息批处理处理结束之前，此值为零。

    • processing: number

      Number of requests in the Message Batch that are processing.

    • succeeded: number

      消息批处理中已成功完成的请求数。

      在整个消息批处理处理结束之前，此值为零。

  • results_url: string

    URL to a .jsonl file containing the results of the Message Batch requests. Specified only once processing ends.

    文件中的结果不保证与请求顺序相同。使用 custom_id 字段将结果与请求进行匹配。

  • type: "message_batch"

    对象类型。

    For Message Batches, this is always "message_batch".

    • "message_batch"

示例

curl https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID/cancel \
    -X POST \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: message-batches-2024-09-24' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

响应

{
  "id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF",
  "archived_at": "2024-08-20T18:37:24.100435Z",
  "cancel_initiated_at": "2024-08-20T18:37:24.100435Z",
  "created_at": "2024-08-20T18:37:24.100435Z",
  "ended_at": "2024-08-20T18:37:24.100435Z",
  "expires_at": "2024-08-20T18:37:24.100435Z",
  "processing_status": "in_progress",
  "request_counts": {
    "canceled": 10,
    "errored": 30,
    "expired": 10,
    "processing": 100,
    "succeeded": 50
  },
  "results_url": "https://api.anthropic.com/v1/messages/batches/msgbatch_013Zva2CMHLNnXjNJJKqJ2EF/results",
  "type": "message_batch"
}

Delete a Message Batch

delete /v1/messages/batches/{message_batch_id}

Delete a Message Batch.

Message Batches can only be deleted once they've finished processing. If you'd like to delete an in-progress batch, you must first cancel it.

在我们的用户指南中了解更多关于消息批处理 API 的信息

路径参数

• message_batch_id: string

  消息批处理的 ID。

请求头参数

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

返回

• BetaDeletedMessageBatch object { id, type }

  • id: string

    消息批处理的 ID。

  • type: "message_batch_deleted"

    Deleted object type.

    For Message Batches, this is always "message_batch_deleted".

    • "message_batch_deleted"

示例

curl https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID \
    -X DELETE \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: message-batches-2024-09-24' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

响应

{
  "id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message_batch_deleted"
}

获取消息批处理结果

get /v1/messages/batches/{message_batch_id}/results

以 .jsonl 文件形式流式传输消息批处理的结果。

文件中的每一行都是一个 JSON 对象，包含消息批处理中单个请求的结果。结果不保证与请求顺序相同。使用 custom_id 字段将结果与请求进行匹配。

在我们的用户指南中了解更多关于消息批处理 API 的信息

路径参数

• message_batch_id: string

  消息批处理的 ID。

请求头参数

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

返回

• BetaMessageBatchIndividualResponse object { custom_id, result }

  这是响应 .jsonl 文件中的单行，并不代表整个响应。

  • custom_id: string

    开发人员为消息批处理中每个请求创建的 ID。用于将结果与请求进行匹配，因为结果可能不按请求顺序返回。

    在消息批处理中，每个请求的此值必须唯一。

  • result: BetaMessageBatchResult

    此请求的处理结果。

    如果处理成功则包含消息输出，如果处理失败则包含错误响应，或者包含未尝试处理的原因（如取消或过期）。

    • BetaMessageBatchSucceededResult object { message, type }

      • message: BetaMessage

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

      • type: "succeeded"

        • "succeeded"

    • BetaMessageBatchErroredResult object { error, type }

      • error: BetaErrorResponse

        • error: BetaError

          • BetaInvalidRequestError object { message, type }

            • message: string

            • type: "invalid_request_error"

              • "invalid_request_error"

          • BetaAuthenticationError object { message, type }

            • message: string

            • type: "authentication_error"

              • "authentication_error"

          • BetaBillingError object { message, type }

            • message: string

            • type: "billing_error"

              • "billing_error"

          • BetaPermissionError object { message, type }

            • message: string

            • type: "permission_error"

              • "permission_error"

          • BetaNotFoundError object { message, type }

            • message: string

            • type: "not_found_error"

              • "not_found_error"

          • BetaRateLimitError object { message, type }

            • message: string

            • type: "rate_limit_error"

              • "rate_limit_error"

          • BetaGatewayTimeoutError object { message, type }

            • message: string

            • type: "timeout_error"

              • "timeout_error"

          • BetaAPIError object { message, type }

            • message: string

            • type: "api_error"

              • "api_error"

          • BetaOverloadedError object { message, type }

            • message: string

            • type: "overloaded_error"

              • "overloaded_error"

        • request_id: string

        • type: "error"

          • "error"

      • type: "errored"

        • "errored"

    • BetaMessageBatchCanceledResult object { type }

      • type: "canceled"

        • "canceled"

    • BetaMessageBatchExpiredResult object { type }

      • type: "expired"

        • "expired"

示例

curl https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID/results \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: message-batches-2024-09-24' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

域类型

Beta Deleted Message Batch

• BetaDeletedMessageBatch object { id, type }

  • id: string

    消息批处理的 ID。

  • type: "message_batch_deleted"

    Deleted object type.

    For Message Batches, this is always "message_batch_deleted".

    • "message_batch_deleted"

Beta Message Batch

• BetaMessageBatch object { id, archived_at, cancel_initiated_at, 7 more }

  • id: string

    唯一对象标识符。

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

  • archived_at: string

    RFC 3339 日期时间字符串，表示消息批处理被归档且其结果变为不可用的时间。

  • cancel_initiated_at: string

    RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated.

  • created_at: string

    RFC 3339 日期时间字符串，表示消息批处理创建的时间。

  • ended_at: string

    RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends.

    Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired.

  • expires_at: string

    RFC 3339 日期时间字符串，表示消息批处理将过期并结束处理的时间，即创建后 24 小时。

  • processing_status: "in_progress" or "canceling" or "ended"

    消息批处理的处理状态。

    • "in_progress"

    • "canceling"

    • "ended"

  • request_counts: BetaMessageBatchRequestCounts

    按状态分类统计消息批处理中的请求。

    请求从 processing 开始，只有在整个批处理处理结束后才会转移到其他状态。所有值的总和始终与批处理中的请求总数匹配。

    • canceled: number

      消息批处理中已取消的请求数。

      在整个消息批处理处理结束之前，此值为零。

    • errored: number

      消息批处理中遇到错误的请求数。

      在整个消息批处理处理结束之前，此值为零。

    • expired: number

      消息批处理中已过期的请求数。

      在整个消息批处理处理结束之前，此值为零。

    • processing: number

      Number of requests in the Message Batch that are processing.

    • succeeded: number

      消息批处理中已成功完成的请求数。

      在整个消息批处理处理结束之前，此值为零。

  • results_url: string

    URL to a .jsonl file containing the results of the Message Batch requests. Specified only once processing ends.

    文件中的结果不保证与请求顺序相同。使用 custom_id 字段将结果与请求进行匹配。

  • type: "message_batch"

    对象类型。

    For Message Batches, this is always "message_batch".

    • "message_batch"

Beta Message Batch Canceled Result

• BetaMessageBatchCanceledResult object { type }

  • type: "canceled"

    • "canceled"

Beta Message Batch Errored Result

• BetaMessageBatchErroredResult object { error, type }

  • error: BetaErrorResponse

    • error: BetaError

      • BetaInvalidRequestError object { message, type }

        • message: string

        • type: "invalid_request_error"

          • "invalid_request_error"

      • BetaAuthenticationError object { message, type }

        • message: string

        • type: "authentication_error"

          • "authentication_error"

      • BetaBillingError object { message, type }

        • message: string

        • type: "billing_error"

          • "billing_error"

      • BetaPermissionError object { message, type }

        • message: string

        • type: "permission_error"

          • "permission_error"

      • BetaNotFoundError object { message, type }

        • message: string

        • type: "not_found_error"

          • "not_found_error"

      • BetaRateLimitError object { message, type }

        • message: string

        • type: "rate_limit_error"

          • "rate_limit_error"

      • BetaGatewayTimeoutError object { message, type }

        • message: string

        • type: "timeout_error"

          • "timeout_error"

      • BetaAPIError object { message, type }

        • message: string

        • type: "api_error"

          • "api_error"

      • BetaOverloadedError object { message, type }

        • message: string

        • type: "overloaded_error"

          • "overloaded_error"

    • request_id: string

    • type: "error"

      • "error"

  • type: "errored"

    • "errored"

Beta Message Batch Expired Result

• BetaMessageBatchExpiredResult object { type }

  • type: "expired"

    • "expired"

Beta Message Batch Individual Response

• BetaMessageBatchIndividualResponse object { custom_id, result }

  这是响应 .jsonl 文件中的单行，并不代表整个响应。

  • custom_id: string

    开发人员为消息批处理中每个请求创建的 ID。用于将结果与请求进行匹配，因为结果可能不按请求顺序返回。

    在消息批处理中，每个请求的此值必须唯一。

  • result: BetaMessageBatchResult

    此请求的处理结果。

    如果处理成功则包含消息输出，如果处理失败则包含错误响应，或者包含未尝试处理的原因（如取消或过期）。

    • BetaMessageBatchSucceededResult object { message, type }

      • message: BetaMessage

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

      • type: "succeeded"

        • "succeeded"

    • BetaMessageBatchErroredResult object { error, type }

      • error: BetaErrorResponse

        • error: BetaError

          • BetaInvalidRequestError object { message, type }

            • message: string

            • type: "invalid_request_error"

              • "invalid_request_error"

          • BetaAuthenticationError object { message, type }

            • message: string

            • type: "authentication_error"

              • "authentication_error"

          • BetaBillingError object { message, type }

            • message: string

            • type: "billing_error"

              • "billing_error"

          • BetaPermissionError object { message, type }

            • message: string

            • type: "permission_error"

              • "permission_error"

          • BetaNotFoundError object { message, type }

            • message: string

            • type: "not_found_error"

              • "not_found_error"

          • BetaRateLimitError object { message, type }

            • message: string

            • type: "rate_limit_error"

              • "rate_limit_error"

          • BetaGatewayTimeoutError object { message, type }

            • message: string

            • type: "timeout_error"

              • "timeout_error"

          • BetaAPIError object { message, type }

            • message: string

            • type: "api_error"

              • "api_error"

          • BetaOverloadedError object { message, type }

            • message: string

            • type: "overloaded_error"

              • "overloaded_error"

        • request_id: string

        • type: "error"

          • "error"

      • type: "errored"

        • "errored"

    • BetaMessageBatchCanceledResult object { type }

      • type: "canceled"

        • "canceled"

    • BetaMessageBatchExpiredResult object { type }

      • type: "expired"

        • "expired"