创建消息 Batch

post /v1/messages/batches

发送一批消息创建请求。

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

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

请求体参数

• requests: array of object { custom_id, params }

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

  • custom_id: string

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

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

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

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

    详见 Messages API 参考了解可用参数的完整文档。

    • max_tokens: number

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

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

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

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

    • messages: array of MessageParam

      输入消息。

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

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

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

      单条 user 消息示例：

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

      多轮对话示例：

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

      Claude 部分填充响应示例：

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

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

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

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

      详见输入示例。

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

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

      • content: string or array of ContentBlockParam

        • string

        • array of ContentBlockParam

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

            • text: string

            • type: "text"

              • "text"

            • cache_control: optional CacheControlEphemeral

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

              • type: "ephemeral"

                • "ephemeral"

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

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

                这可能是以下值之一：

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

                默认为 5m。

                • "5m"

                • "1h"

            • citations: optional array of TextCitationParam

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

                • cited_text: string

                • document_index: number

                • document_title: string

                • end_char_index: number

                • start_char_index: number

                • type: "char_location"

                  • "char_location"

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

                • cited_text: string

                • document_index: number

                • document_title: string

                • end_page_number: number

                • start_page_number: number

                • type: "page_location"

                  • "page_location"

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

                • cited_text: string

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

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

                • document_index: number

                • document_title: string

                • end_block_index: number

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

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

                • start_block_index: number

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

                • type: "content_block_location"

                  • "content_block_location"

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

                • cited_text: string

                • encrypted_index: string

                • title: string

                • type: "web_search_result_location"

                  • "web_search_result_location"

                • url: string

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

                • cited_text: string

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

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

                • end_block_index: number

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

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

                • search_result_index: number

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

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

                • source: string

                • start_block_index: number

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

                • title: string

                • type: "search_result_location"

                  • "search_result_location"

          • ImageBlockParam object { source, type, cache_control }

            • source: Base64ImageSource or URLImageSource

              • Base64ImageSource object { data, media_type, type }

                • data: string

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

                  • "image/jpeg"

                  • "image/png"

                  • "image/gif"

                  • "image/webp"

                • type: "base64"

                  • "base64"

              • URLImageSource object { type, url }

                • type: "url"

                  • "url"

                • url: string

            • type: "image"

              • "image"

            • cache_control: optional CacheControlEphemeral

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

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

            • source: Base64PDFSource or PlainTextSource or ContentBlockSource or URLPDFSource

              • Base64PDFSource object { data, media_type, type }

                • data: string

                • media_type: "application/pdf"

                  • "application/pdf"

                • type: "base64"

                  • "base64"

              • PlainTextSource object { data, media_type, type }

                • data: string

                • media_type: "text/plain"

                  • "text/plain"

                • type: "text"

                  • "text"

              • ContentBlockSource object { content, type }

                • content: string or array of ContentBlockSourceContent

                  • string

                  • ContentBlockSourceContent = array of ContentBlockSourceContent

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

                    • ImageBlockParam object { source, type, cache_control }

                • type: "content"

                  • "content"

              • URLPDFSource object { type, url }

                • type: "url"

                  • "url"

                • url: string

            • type: "document"

              • "document"

            • cache_control: optional CacheControlEphemeral

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

            • citations: optional CitationsConfigParam

              • enabled: optional boolean

            • context: optional string

            • title: optional string

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

            • content: array of TextBlockParam

              • text: string

              • type: "text"

              • cache_control: optional CacheControlEphemeral

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

              • citations: optional array of TextCitationParam

            • source: string

            • title: string

            • type: "search_result"

              • "search_result"

            • cache_control: optional CacheControlEphemeral

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

            • citations: optional CitationsConfigParam

          • ThinkingBlockParam object { signature, thinking, type }

            • signature: string

            • thinking: string

            • type: "thinking"

              • "thinking"

          • RedactedThinkingBlockParam object { data, type }

            • data: string

            • type: "redacted_thinking"

              • "redacted_thinking"

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

            • id: string

            • input: map[unknown]

            • name: string

            • type: "tool_use"

              • "tool_use"

            • cache_control: optional CacheControlEphemeral

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

            • caller: optional DirectCaller or ServerToolCaller or ServerToolCaller20260120

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

              • DirectCaller object { type }

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

                • type: "direct"

                  • "direct"

              • ServerToolCaller object { tool_id, type }

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

                • tool_id: string

                • type: "code_execution_20250825"

                  • "code_execution_20250825"

              • ServerToolCaller20260120 object { tool_id, type }

                • tool_id: string

                • type: "code_execution_20260120"

                  • "code_execution_20260120"

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

            • tool_use_id: string

            • type: "tool_result"

              • "tool_result"

            • cache_control: optional CacheControlEphemeral

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

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

              • string

              • array of TextBlockParam or ImageBlockParam or SearchResultBlockParam or 2 more

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

                • ImageBlockParam object { source, type, cache_control }

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

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

                • ToolReferenceBlockParam object { tool_name, type, cache_control }

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

                  • tool_name: string

                  • type: "tool_reference"

                    • "tool_reference"

                  • cache_control: optional CacheControlEphemeral

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

            • is_error: optional boolean

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

            • id: string

            • input: map[unknown]

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

              • "web_search"

              • "web_fetch"

              • "code_execution"

              • "bash_code_execution"

              • "text_editor_code_execution"

              • "tool_search_tool_regex"

              • "tool_search_tool_bm25"

            • type: "server_tool_use"

              • "server_tool_use"

            • cache_control: optional CacheControlEphemeral

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

            • caller: optional DirectCaller or ServerToolCaller or ServerToolCaller20260120

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

              • DirectCaller object { type }

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

              • ServerToolCaller object { tool_id, type }

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

              • ServerToolCaller20260120 object { tool_id, type }

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

            • content: WebSearchToolResultBlockParamContent

              • WebSearchToolResultBlockItem = array of WebSearchResultBlockParam

                • encrypted_content: string

                • title: string

                • type: "web_search_result"

                  • "web_search_result"

                • url: string

                • page_age: optional string

              • WebSearchToolRequestError object { error_code, type }

                • error_code: WebSearchToolResultErrorCode

                  • "invalid_tool_input"

                  • "unavailable"

                  • "max_uses_exceeded"

                  • "too_many_requests"

                  • "query_too_long"

                  • "request_too_large"

                • type: "web_search_tool_result_error"

                  • "web_search_tool_result_error"

            • tool_use_id: string

            • type: "web_search_tool_result"

              • "web_search_tool_result"

            • cache_control: optional CacheControlEphemeral

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

            • caller: optional DirectCaller or ServerToolCaller or ServerToolCaller20260120

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

              • DirectCaller object { type }

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

              • ServerToolCaller object { tool_id, type }

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

              • ServerToolCaller20260120 object { tool_id, type }

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

            • content: WebFetchToolResultErrorBlockParam or WebFetchBlockParam

              • WebFetchToolResultErrorBlockParam object { error_code, type }

                • error_code: WebFetchToolResultErrorCode

                  • "invalid_tool_input"

                  • "url_too_long"

                  • "url_not_allowed"

                  • "url_not_accessible"

                  • "unsupported_content_type"

                  • "too_many_requests"

                  • "max_uses_exceeded"

                  • "unavailable"

                • type: "web_fetch_tool_result_error"

                  • "web_fetch_tool_result_error"

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

                • content: DocumentBlockParam

                • type: "web_fetch_result"

                  • "web_fetch_result"

                • url: string

                  获取的内容 URL

                • retrieved_at: optional string

                  获取内容时的 ISO 8601 时间戳

            • tool_use_id: string

            • type: "web_fetch_tool_result"

              • "web_fetch_tool_result"

            • cache_control: optional CacheControlEphemeral

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

            • caller: optional DirectCaller or ServerToolCaller or ServerToolCaller20260120

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

              • DirectCaller object { type }

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

              • ServerToolCaller object { tool_id, type }

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

              • ServerToolCaller20260120 object { tool_id, type }

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

            • content: CodeExecutionToolResultBlockParamContent

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

              • CodeExecutionToolResultErrorParam object { error_code, type }

                • error_code: CodeExecutionToolResultErrorCode

                  • "invalid_tool_input"

                  • "unavailable"

                  • "too_many_requests"

                  • "execution_time_exceeded"

                • type: "code_execution_tool_result_error"

                  • "code_execution_tool_result_error"

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

                • content: array of CodeExecutionOutputBlockParam

                  • file_id: string

                  • type: "code_execution_output"

                    • "code_execution_output"

                • return_code: number

                • stderr: string

                • stdout: string

                • type: "code_execution_result"

                  • "code_execution_result"

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

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

                • content: array of CodeExecutionOutputBlockParam

                  • file_id: string

                  • type: "code_execution_output"

                • encrypted_stdout: string

                • return_code: number

                • stderr: string

                • type: "encrypted_code_execution_result"

                  • "encrypted_code_execution_result"

            • tool_use_id: string

            • type: "code_execution_tool_result"

              • "code_execution_tool_result"

            • cache_control: optional CacheControlEphemeral

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

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

            • content: BashCodeExecutionToolResultErrorParam or BashCodeExecutionResultBlockParam

              • BashCodeExecutionToolResultErrorParam object { error_code, type }

                • error_code: BashCodeExecutionToolResultErrorCode

                  • "invalid_tool_input"

                  • "unavailable"

                  • "too_many_requests"

                  • "execution_time_exceeded"

                  • "output_file_too_large"

                • type: "bash_code_execution_tool_result_error"

                  • "bash_code_execution_tool_result_error"

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

                • content: array of BashCodeExecutionOutputBlockParam

                  • file_id: string

                  • type: "bash_code_execution_output"

                    • "bash_code_execution_output"

                • return_code: number

                • stderr: string

                • stdout: string

                • type: "bash_code_execution_result"

                  • "bash_code_execution_result"

            • tool_use_id: string

            • type: "bash_code_execution_tool_result"

              • "bash_code_execution_tool_result"

            • cache_control: optional CacheControlEphemeral

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

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

            • content: TextEditorCodeExecutionToolResultErrorParam or TextEditorCodeExecutionViewResultBlockParam or TextEditorCodeExecutionCreateResultBlockParam or TextEditorCodeExecutionStrReplaceResultBlockParam

              • TextEditorCodeExecutionToolResultErrorParam object { error_code, type, error_message }

                • error_code: TextEditorCodeExecutionToolResultErrorCode

                  • "invalid_tool_input"

                  • "unavailable"

                  • "too_many_requests"

                  • "execution_time_exceeded"

                  • "file_not_found"

                • type: "text_editor_code_execution_tool_result_error"

                  • "text_editor_code_execution_tool_result_error"

                • error_message: optional string

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

                • content: string

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

                  • "text"

                  • "image"

                  • "pdf"

                • type: "text_editor_code_execution_view_result"

                  • "text_editor_code_execution_view_result"

                • num_lines: optional number

                • start_line: optional number

                • total_lines: optional number

              • TextEditorCodeExecutionCreateResultBlockParam object { is_file_update, type }

                • is_file_update: boolean

                • type: "text_editor_code_execution_create_result"

                  • "text_editor_code_execution_create_result"

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

                • type: "text_editor_code_execution_str_replace_result"

                  • "text_editor_code_execution_str_replace_result"

                • lines: optional array of string

                • new_lines: optional number

                • new_start: optional number

                • old_lines: optional number

                • old_start: optional number

            • tool_use_id: string

            • type: "text_editor_code_execution_tool_result"

              • "text_editor_code_execution_tool_result"

            • cache_control: optional CacheControlEphemeral

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

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

            • content: ToolSearchToolResultErrorParam or ToolSearchToolSearchResultBlockParam

              • ToolSearchToolResultErrorParam object { error_code, type }

                • error_code: ToolSearchToolResultErrorCode

                  • "invalid_tool_input"

                  • "unavailable"

                  • "too_many_requests"

                  • "execution_time_exceeded"

                • type: "tool_search_tool_result_error"

                  • "tool_search_tool_result_error"

              • ToolSearchToolSearchResultBlockParam object { tool_references, type }

                • tool_references: array of ToolReferenceBlockParam

                  • tool_name: string

                  • type: "tool_reference"

                  • cache_control: optional CacheControlEphemeral

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

                • type: "tool_search_tool_search_result"

                  • "tool_search_tool_search_result"

            • tool_use_id: string

            • type: "tool_search_tool_result"

              • "tool_search_tool_result"

            • cache_control: optional CacheControlEphemeral

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

          • ContainerUploadBlockParam object { file_id, type, cache_control }

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

            • file_id: string

            • type: "container_upload"

              • "container_upload"

            • cache_control: optional CacheControlEphemeral

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

      • role: "user" or "assistant"

        • "user"

        • "assistant"

    • model: Model

      将完成您的提示的模型。

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

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

        将完成您的提示的模型。

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

        • "claude-opus-4-7"

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

        • "claude-mythos-preview"

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

        • "claude-opus-4-6"

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

        • "claude-sonnet-4-6"

          速度与智能的最佳组合

        • "claude-haiku-4-5"

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

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

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

        • "claude-opus-4-5"

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

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

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

        • "claude-sonnet-4-5"

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

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

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

        • "claude-opus-4-1"

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

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

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

        • "claude-opus-4-0"

          用于复杂任务的强大模型

        • "claude-opus-4-20250514"

          用于复杂任务的强大模型

        • "claude-sonnet-4-0"

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

        • "claude-sonnet-4-20250514"

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

        • "claude-3-haiku-20240307"

          快速且经济高效的模型

      • string

    • cache_control: optional CacheControlEphemeral

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

    • container: optional string

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

    • inference_geo: optional string

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

    • metadata: optional Metadata

      描述请求元数据的对象。

      • user_id: optional string

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

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

    • output_config: optional OutputConfig

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

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

        所有可用的努力级别。

        • "low"

        • "medium"

        • "high"

        • "xhigh"

        • "max"

      • format: optional JSONOutputFormat

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

        • schema: map[unknown]

          格式的 JSON 模式

        • type: "json_schema"

          • "json_schema"

    • service_tier: optional "auto" or "standard_only"

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

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

      • "auto"

      • "standard_only"

    • stop_sequences: optional array of string

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

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

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

    • stream: optional boolean

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

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

    • system: optional string or array of TextBlockParam

      系统提示。

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

      • string

      • array of TextBlockParam

        • text: string

        • type: "text"

        • cache_control: optional CacheControlEphemeral

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

        • citations: optional array of TextCitationParam

    • temperature: optional number

      注入响应的随机性程度。

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

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

    • thinking: optional ThinkingConfigParam

      启用 Claude 扩展思考的配置。

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

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

      • ThinkingConfigEnabled object { budget_tokens, type, display }

        • budget_tokens: number

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

          必须 ≥1024 且小于 max_tokens。

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

        • type: "enabled"

          • "enabled"

        • display: optional "summarized" or "omitted"

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

          • "summarized"

          • "omitted"

      • ThinkingConfigDisabled object { type }

        • type: "disabled"

          • "disabled"

      • ThinkingConfigAdaptive object { type, display }

        • type: "adaptive"

          • "adaptive"

        • display: optional "summarized" or "omitted"

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

          • "summarized"

          • "omitted"

    • tool_choice: optional ToolChoice

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

      • ToolChoiceAuto object { type, disable_parallel_tool_use }

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

        • type: "auto"

          • "auto"

        • disable_parallel_tool_use: optional boolean

          是否禁用并行工具使用。

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

      • ToolChoiceAny object { type, disable_parallel_tool_use }

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

        • type: "any"

          • "any"

        • disable_parallel_tool_use: optional boolean

          是否禁用并行工具使用。

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

      • ToolChoiceTool object { name, type, disable_parallel_tool_use }

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

        • name: string

          要使用的工具的名称。

        • type: "tool"

          • "tool"

        • disable_parallel_tool_use: optional boolean

          是否禁用并行工具使用。

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

      • ToolChoiceNone object { type }

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

        • type: "none"

          • "none"

    • tools: optional array of ToolUnion

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

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

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

      每个工具定义包括：

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

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

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

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

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

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

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

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

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

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

        • input_schema: object { type, properties, required }

          此工具输入的 JSON schema。

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

          • type: "object"

            • "object"

          • properties: optional map[unknown]

          • required: optional array of string

        • name: string

          工具名称。

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

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

          • "direct"

          • "code_execution_20250825"

          • "code_execution_20260120"

        • cache_control: optional CacheControlEphemeral

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

        • defer_loading: optional boolean

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

        • description: optional string

          此工具的功能描述。

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

        • eager_input_streaming: optional boolean

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

        • input_examples: optional array of map[unknown]

        • strict: optional boolean

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

        • type: optional "custom"

          • "custom"

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

        • name: "bash"

          工具名称。

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

          • "bash"

        • type: "bash_20250124"

          • "bash_20250124"

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

          • "direct"

          • "code_execution_20250825"

          • "code_execution_20260120"

        • cache_control: optional CacheControlEphemeral

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

        • defer_loading: optional boolean

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

        • input_examples: optional array of map[unknown]

        • strict: optional boolean

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

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

        • name: "code_execution"

          工具名称。

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

          • "code_execution"

        • type: "code_execution_20250522"

          • "code_execution_20250522"

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

          • "direct"

          • "code_execution_20250825"

          • "code_execution_20260120"

        • cache_control: optional CacheControlEphemeral

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

        • defer_loading: optional boolean

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

        • strict: optional boolean

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

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

        • name: "code_execution"

          工具名称。

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

          • "code_execution"

        • type: "code_execution_20250825"

          • "code_execution_20250825"

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

          • "direct"

          • "code_execution_20250825"

          • "code_execution_20260120"

        • cache_control: optional CacheControlEphemeral

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

        • defer_loading: optional boolean

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

        • strict: optional boolean

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

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

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

        • name: "code_execution"

          工具名称。

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

          • "code_execution"

        • type: "code_execution_20260120"

          • "code_execution_20260120"

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

          • "direct"

          • "code_execution_20250825"

          • "code_execution_20260120"

        • cache_control: optional CacheControlEphemeral

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

        • defer_loading: optional boolean

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

        • strict: optional boolean

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

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

        • name: "memory"

          工具名称。

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

          • "memory"

        • type: "memory_20250818"

          • "memory_20250818"

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

          • "direct"

          • "code_execution_20250825"

          • "code_execution_20260120"

        • cache_control: optional CacheControlEphemeral

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

        • defer_loading: optional boolean

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

        • input_examples: optional array of map[unknown]

        • strict: optional boolean

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

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

        • name: "str_replace_editor"

          工具名称。

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

          • "str_replace_editor"

        • type: "text_editor_20250124"

          • "text_editor_20250124"

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

          • "direct"

          • "code_execution_20250825"

          • "code_execution_20260120"

        • cache_control: optional CacheControlEphemeral

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

        • defer_loading: optional boolean

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

        • input_examples: optional array of map[unknown]

        • strict: optional boolean

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

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

        • name: "str_replace_based_edit_tool"

          工具名称。

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

          • "str_replace_based_edit_tool"

        • type: "text_editor_20250429"

          • "text_editor_20250429"

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

          • "direct"

          • "code_execution_20250825"

          • "code_execution_20260120"

        • cache_control: optional CacheControlEphemeral

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

        • defer_loading: optional boolean

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

        • input_examples: optional array of map[unknown]

        • strict: optional boolean

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

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

        • name: "str_replace_based_edit_tool"

          工具名称。

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

          • "str_replace_based_edit_tool"

        • type: "text_editor_20250728"

          • "text_editor_20250728"

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

          • "direct"

          • "code_execution_20250825"

          • "code_execution_20260120"

        • cache_control: optional CacheControlEphemeral

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

        • defer_loading: optional boolean

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

        • input_examples: optional array of map[unknown]

        • max_characters: optional number

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

        • strict: optional boolean

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

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

        • name: "web_search"

          工具名称。

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

          • "web_search"

        • type: "web_search_20250305"

          • "web_search_20250305"

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

          • "direct"

          • "code_execution_20250825"

          • "code_execution_20260120"

        • allowed_domains: optional array of string

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

        • blocked_domains: optional array of string

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

        • cache_control: optional CacheControlEphemeral

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

        • defer_loading: optional boolean

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

        • max_uses: optional number

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

        • strict: optional boolean

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

        • user_location: optional UserLocation

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

          • type: "approximate"

            • "approximate"

          • city: optional string

            用户的城市。

          • country: optional string

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

          • region: optional string

            用户的区域。

          • timezone: optional string

            用户的 IANA 时区。

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

        • name: "web_fetch"

          工具名称。

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

          • "web_fetch"

        • type: "web_fetch_20250910"

          • "web_fetch_20250910"

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

          • "direct"

          • "code_execution_20250825"

          • "code_execution_20260120"

        • allowed_domains: optional array of string

          允许获取的域名列表

        • blocked_domains: optional array of string

          阻止获取的域名列表

        • cache_control: optional CacheControlEphemeral

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

        • citations: optional CitationsConfigParam

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

        • defer_loading: optional boolean

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

        • max_content_tokens: optional number

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

        • max_uses: optional number

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

        • strict: optional boolean

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

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

        • name: "web_search"

          工具名称。

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

          • "web_search"

        • type: "web_search_20260209"

          • "web_search_20260209"

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

          • "direct"

          • "code_execution_20250825"

          • "code_execution_20260120"

        • allowed_domains: optional array of string

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

        • blocked_domains: optional array of string

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

        • cache_control: optional CacheControlEphemeral

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

        • defer_loading: optional boolean

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

        • max_uses: optional number

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

        • strict: optional boolean

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

        • user_location: optional UserLocation

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

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

        • name: "web_fetch"

          工具名称。

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

          • "web_fetch"

        • type: "web_fetch_20260209"

          • "web_fetch_20260209"

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

          • "direct"

          • "code_execution_20250825"

          • "code_execution_20260120"

        • allowed_domains: optional array of string

          允许获取的域名列表

        • blocked_domains: optional array of string

          阻止获取的域名列表

        • cache_control: optional CacheControlEphemeral

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

        • citations: optional CitationsConfigParam

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

        • defer_loading: optional boolean

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

        • max_content_tokens: optional number

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

        • max_uses: optional number

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

        • strict: optional boolean

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

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

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

        • name: "web_fetch"

          工具名称。

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

          • "web_fetch"

        • type: "web_fetch_20260309"

          • "web_fetch_20260309"

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

          • "direct"

          • "code_execution_20250825"

          • "code_execution_20260120"

        • allowed_domains: optional array of string

          允许获取的域名列表

        • blocked_domains: optional array of string

          阻止获取的域名列表

        • cache_control: optional CacheControlEphemeral

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

        • citations: optional CitationsConfigParam

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

        • defer_loading: optional boolean

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

        • max_content_tokens: optional number

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

        • max_uses: optional number

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

        • strict: optional boolean

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

        • use_cache: optional boolean

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

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

        • name: "tool_search_tool_bm25"

          工具名称。

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

          • "tool_search_tool_bm25"

        • type: "tool_search_tool_bm25_20251119" or "tool_search_tool_bm25"

          • "tool_search_tool_bm25_20251119"

          • "tool_search_tool_bm25"

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

          • "direct"

          • "code_execution_20250825"

          • "code_execution_20260120"

        • cache_control: optional CacheControlEphemeral

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

        • defer_loading: optional boolean

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

        • strict: optional boolean

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

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

        • name: "tool_search_tool_regex"

          工具名称。

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

          • "tool_search_tool_regex"

        • type: "tool_search_tool_regex_20251119" or "tool_search_tool_regex"

          • "tool_search_tool_regex_20251119"

          • "tool_search_tool_regex"

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

          • "direct"

          • "code_execution_20250825"

          • "code_execution_20260120"

        • cache_control: optional CacheControlEphemeral

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

        • defer_loading: optional boolean

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

        • strict: optional boolean

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

    • top_k: optional number

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

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

      仅建议高级用例使用。

    • top_p: optional number

      使用核采样。

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

      仅建议高级用例使用。

返回值

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

  • id: string

    唯一对象标识符。

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

  • archived_at: string

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

  • cancel_initiated_at: string

    RFC 3339 日期时间字符串，表示为消息批处理启动取消的时间。仅在启动取消时指定。

  • created_at: string

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

  • ended_at: string

    RFC 3339 日期时间字符串，表示消息批处理处理结束的时间。仅在处理结束后指定。

    当消息批处理中的每个请求已成功、出错、取消或过期时，处理结束。

  • expires_at: string

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

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

    消息批处理的处理状态。

    • "in_progress"

    • "canceling"

    • "ended"

  • request_counts: MessageBatchRequestCounts

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

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

    • canceled: number

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

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

    • errored: number

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

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

    • expired: number

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

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

    • processing: number

      消息批处理中正在处理的请求数。

    • succeeded: number

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

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

  • results_url: string

    包含消息批处理请求结果的 .jsonl 文件的 URL。仅在处理结束后指定。

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

  • type: "message_batch"

    对象类型。

    对于消息批处理，始终为 "message_batch"。

    • "message_batch"

Example

curl https://api.anthropic.com/v1/messages/batches \
    -H 'Content-Type: application/json' \
    -H 'anthropic-version: 2023-06-01' \
    -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"
}