Loading...
    • 开发者指南
    • API 参考
    • MCP
    • 资源
    • 发布说明
    Search...
    ⌘K
    快速开始
    Claude 简介快速入门
    模型与定价
    模型概览选择模型Claude 4.5 新功能迁移到 Claude 4.5模型弃用定价
    使用 Claude 构建
    功能概览使用 Messages API上下文窗口提示词最佳实践
    能力
    提示词缓存上下文编辑扩展思考工作量流式消息批量处理引用多语言支持Token 计数嵌入视觉PDF 支持Files API搜索结果结构化输出Google Sheets 插件
    工具
    概览如何实现工具使用Token 高效的工具使用细粒度工具流式处理Bash 工具代码执行工具程序化工具调用计算机使用工具文本编辑器工具Web 获取工具Web 搜索工具内存工具工具搜索工具
    Agent 技能
    概览快速入门最佳实践在 API 中使用技能
    Agent SDK
    概览TypeScript SDKPython SDK迁移指南
    指南
    流式输入处理权限会话管理SDK 中的结构化输出托管 Agent SDK修改系统提示词SDK 中的 MCP自定义工具SDK 中的子 AgentSDK 中的斜杠命令SDK 中的 Agent 技能跟踪成本和使用情况待办事项列表SDK 中的插件
    API 中的 MCP
    MCP 连接器远程 MCP 服务器
    第三方平台上的 Claude
    Amazon BedrockMicrosoft FoundryVertex AI
    提示词工程
    概览提示词生成器使用提示词模板提示词改进器清晰直接使用示例(多轮提示)让 Claude 思考(CoT)使用 XML 标签给 Claude 一个角色(系统提示词)预填充 Claude 的响应链接复杂提示词长上下文提示扩展思考提示
    测试与评估
    定义成功标准开发测试用例使用评估工具降低延迟
    加强防护栏
    减少幻觉提高输出一致性缓解越狱流式拒绝减少提示词泄露保持 Claude 的角色
    管理和监控
    Admin API 概览使用和成本 APIClaude Code 分析 API
    Console
    Log in
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...

    Solutions

    • AI agents
    • Code modernization
    • Coding
    • Customer support
    • Education
    • Financial services
    • Government
    • Life sciences

    Partners

    • Amazon Bedrock
    • Google Cloud's Vertex AI

    Learn

    • Blog
    • Catalog
    • Courses
    • Use cases
    • Connectors
    • Customer stories
    • Engineering at Anthropic
    • Events
    • Powered by Claude
    • Service partners
    • Startups program

    Company

    • Anthropic
    • Careers
    • Economic Futures
    • Research
    • News
    • Responsible Scaling Policy
    • Security and compliance
    • Transparency

    Learn

    • Blog
    • Catalog
    • Courses
    • Use cases
    • Connectors
    • Customer stories
    • Engineering at Anthropic
    • Events
    • Powered by Claude
    • Service partners
    • Startups program

    Help and security

    • Availability
    • Status
    • Support
    • Discord

    Terms and policies

    • Privacy policy
    • Responsible disclosure policy
    • Terms of service: Commercial
    • Terms of service: Consumer
    • Usage policy
    能力

    批处理

    批处理是高效处理大量请求的强大方法。了解如何使用消息批处理API异步处理大量消息请求,同时降低成本并提高吞吐量。

    批处理是高效处理大量请求的强大方法。与逐个处理请求并立即响应不同,批处理允许您将多个请求一起提交进行异步处理。这种模式在以下情况下特别有用:

    • 您需要处理大量数据
    • 不需要立即响应
    • 您希望优化成本效率
    • 您正在运行大规模评估或分析

    消息批处理API是我们对这种模式的首次实现。


    消息批处理API

    消息批处理API是一种强大且经济高效的方式,可以异步处理大量消息请求。这种方法非常适合不需要立即响应的任务,大多数批处理在1小时内完成,同时降低50%的成本并提高吞吐量。

    除了本指南外,您还可以直接探索API参考。

    消息批处理API的工作原理

    当您向消息批处理API发送请求时:

    1. 系统使用提供的消息请求创建一个新的消息批处理。
    2. 然后异步处理批处理,每个请求独立处理。
    3. 您可以轮询批处理的状态,并在所有请求处理结束时检索结果。

    这对于不需要立即结果的批量操作特别有用,例如:

    • 大规模评估:高效处理数千个测试用例。
    • 内容审核:异步分析大量用户生成的内容。
    • 数据分析:为大型数据集生成洞察或摘要。
    • 批量内容生成:为各种目的创建大量文本(例如,产品描述、文章摘要)。

    批处理限制

    • 消息批处理限制为100,000个消息请求或256 MB大小,以先达到的为准。
    • 我们尽可能快地处理每个批处理,大多数批处理在1小时内完成。当所有消息完成或24小时后(以先到者为准),您将能够访问批处理结果。如果处理在24小时内未完成,批处理将过期。
    • 批处理结果在创建后29天内可用。之后,您仍可以查看批处理,但其结果将不再可供下载。
    • 批处理的作用域限定在工作区内。您可以查看在您的API密钥所属工作区内创建的所有批处理及其结果。
    • 速率限制适用于批处理API HTTP请求和批处理内等待处理的请求数量。请参阅消息批处理API速率限制。此外,我们可能会根据当前需求和您的请求量放慢处理速度。在这种情况下,您可能会看到更多请求在24小时后过期。
    • 由于高吞吐量和并发处理,批处理可能会略微超过您工作区配置的支出限制。

    支持的模型

    所有活跃模型都支持消息批处理API。

    可以批处理的内容

    任何您可以向消息API发出的请求都可以包含在批处理中。这包括:

    • 视觉
    • 工具使用
    • 系统消息
    • 多轮对话
    • 任何测试版功能

    由于批处理中的每个请求都是独立处理的,您可以在单个批处理中混合不同类型的请求。

    由于批处理可能需要超过5分钟的处理时间,在处理具有共享上下文的批处理时,考虑使用1小时缓存持续时间与提示缓存以获得更好的缓存命中率。


    定价

    批处理API提供显著的成本节省。所有使用按标准API价格的50%收费。

    ModelBatch inputBatch output
    Claude Opus 4.5$2.50 / MTok$12.50 / MTok
    Claude Opus 4.1$7.50 / MTok$37.50 / MTok
    Claude Opus 4$7.50 / MTok$37.50 / MTok
    Claude Sonnet 4.5$1.50 / MTok$7.50 / MTok
    Claude Sonnet 4$1.50 / MTok$7.50 / MTok
    Claude Sonnet 3.7 (deprecated)$1.50 / MTok$7.50 / MTok
    Claude Haiku 4.5$0.50 / MTok$2.50 / MTok
    Claude Haiku 3.5$0.40 / MTok$2 / MTok
    Claude Opus 3 ()

    如何使用消息批处理API

    准备并创建您的批处理

    消息批处理由创建消息的请求列表组成。单个请求的结构包括:

    • 用于识别消息请求的唯一custom_id
    • 包含标准消息API参数的params对象

    您可以通过将此列表传递到requests参数中来创建批处理:

    在此示例中,两个单独的请求被批处理在一起进行异步处理。每个请求都有一个唯一的custom_id,并包含您用于消息API调用的标准参数。

    使用消息API测试您的批处理请求

    每个消息请求的params对象的验证是异步执行的,验证错误在整个批处理处理结束时返回。您可以通过首先使用消息API验证您的请求结构来确保正确构建输入。

    首次创建批处理时,响应的处理状态为in_progress。

    JSON
    {
      "id": "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d",
      "type": "message_batch",
      "processing_status": "in_progress",
      "request_counts": {
        "processing": 2,
        "succeeded": 0,
        "errored": 0,
        "canceled": 0,
        "expired": 0
      },
      "ended_at": null,
      "created_at": "2024-09-24T18:37:24.100435Z",
      "expires_at": "2024-09-25T18:37:24.100435Z",
      "cancel_initiated_at": null,
      "results_url": null
    }

    跟踪您的批处理

    消息批处理的processing_status字段指示批处理所处的处理阶段。它开始为in_progress,然后在批处理中的所有请求完成处理且结果准备就绪后更新为ended。您可以通过访问控制台或使用检索端点来监控批处理的状态:

    您可以轮询此端点以了解处理何时结束。

    检索批处理结果

    批处理处理结束后,批处理中的每个消息请求都将有一个结果。有4种结果类型:

    结果类型描述
    succeeded请求成功。包含消息结果。
    errored请求遇到错误,未创建消息。可能的错误包括无效请求和内部服务器错误。您不会为这些请求付费。
    canceled用户在此请求发送到模型之前取消了批处理。您不会为这些请求付费。
    expired批处理在此请求发送到模型之前达到了24小时过期时间。您不会为这些请求付费。

    您将通过批处理的request_counts看到结果概览,显示有多少请求达到了这四种状态中的每一种。

    批处理的结果可在消息批处理的results_url属性处下载,如果组织权限允许,也可在控制台中下载。由于结果的潜在大小,建议流式传输结果而不是一次性下载所有结果。

    结果将采用.jsonl格式,其中每行是一个有效的JSON对象,表示消息批处理中单个请求的结果。对于每个流式传输的结果,您可以根据其custom_id和结果类型执行不同的操作。以下是一组示例结果:

    .jsonl file
    {"custom_id":"my-second-request","result":{"type":"succeeded","message":{"id":"msg_014VwiXbi91y3JMjcpyGBHX5","type":"message","role":"assistant","model":"claude-sonnet-4-5-20250929","content":[{"type":"text","text":"Hello again! It's nice to see you. How can I assist you today? Is there anything specific you'd like to chat about or any questions you have?"}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":11,"output_tokens":36}}}}
    {"custom_id":"my-first-request","result":{"type":"succeeded","message":{"id":"msg_01FqfsLoHwgeFbguDgpz48m7","type":"message","role":"assistant","model":"claude-sonnet-4-5-20250929","content":[{"type":"text","text":"Hello! How can I assist you today? Feel free to ask me any questions or let me know if there's anything you'd like to chat about."}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":10,"output_tokens":34}}}}

    如果您的结果有错误,其result.error将设置为我们的标准错误形状。

    批处理结果可能与输入顺序不匹配

    批处理结果可以以任何顺序返回,可能与创建批处理时请求的顺序不匹配。在上面的示例中,第二个批处理请求的结果在第一个之前返回。要正确匹配结果与其对应的请求,请始终使用custom_id字段。

    在消息批处理中使用提示缓存

    消息批处理API支持提示缓存,允许您可能降低批处理请求的成本和处理时间。提示缓存和消息批处理的定价折扣可以叠加,当两个功能一起使用时提供更大的成本节省。但是,由于批处理请求是异步和并发处理的,缓存命中是基于尽力而为的基础提供的。用户通常体验到30%到98%的缓存命中率,具体取决于他们的流量模式。

    要最大化批处理请求中缓存命中的可能性:

    1. 在批处理内的每个消息请求中包含相同的cache_control块
    2. 保持稳定的请求流以防止缓存条目在5分钟生命周期后过期
    3. 构建您的请求以共享尽可能多的缓存内容

    在批处理中实现提示缓存的示例:

    在此示例中,批处理中的两个请求都包含相同的系统消息和标有cache_control的《傲慢与偏见》全文,以增加缓存命中的可能性。

    有效批处理的最佳实践

    要充分利用批处理API:

    • 定期监控批处理处理状态,并为失败的请求实施适当的重试逻辑。
    • 使用有意义的custom_id值来轻松匹配结果与请求,因为不保证顺序。
    • 考虑将非常大的数据集分解为多个批处理以获得更好的可管理性。
    • 使用消息API对单个请求形状进行试运行以避免验证错误。

    常见问题故障排除

    如果遇到意外行为:

    • 验证批处理请求的总大小不超过256 MB。如果请求大小太大,您可能会收到413 request_too_large错误。
    • 检查您是否为批处理中的所有请求使用了支持的模型。
    • 确保批处理中的每个请求都有唯一的custom_id。
    • 确保自批处理created_at(不是处理ended_at)时间起不到29天。如果超过29天,结果将不再可查看。
    • 确认批处理未被取消。

    请注意,批处理中一个请求的失败不会影响其他请求的处理。


    批处理存储和隐私

    • 工作区隔离:批处理在创建它们的工作区内隔离。它们只能由与该工作区关联的API密钥或在控制台中有权查看工作区批处理的用户访问。

    • 结果可用性:批处理结果在批处理创建后29天内可用,为检索和处理提供充足的时间。


    常见问题

    • 消息批处理API的工作原理
    • 如何使用消息批处理API
    deprecated
    $7.50 / MTok
    $37.50 / MTok
    Claude Haiku 3$0.125 / MTok$0.625 / MTok
    curl https://api.anthropic.com/v1/messages/batches \
         --header "x-api-key: $ANTHROPIC_API_KEY" \
         --header "anthropic-version: 2023-06-01" \
         --header "content-type: application/json" \
         --data \
    '{
        "requests": [
            {
                "custom_id": "my-first-request",
                "params": {
                    "model": "claude-sonnet-4-5",
                    "max_tokens": 1024,
                    "messages": [
                        {"role": "user", "content": "Hello, world"}
                    ]
                }
            },
            {
                "custom_id": "my-second-request",
                "params": {
                    "model": "claude-sonnet-4-5",
                    "max_tokens": 1024,
                    "messages": [
                        {"role": "user", "content": "Hi again, friend"}
                    ]
                }
            }
        ]
    }'
    curl https://api.anthropic.com/v1/messages/batches/msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     | sed -E 's/.*"id":"([^"]+)".*"processing_status":"([^"]+)".*/Batch \1 processing status is \2/'
    #!/bin/sh
    curl "https://api.anthropic.com/v1/messages/batches/msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d" \
      --header "anthropic-version: 2023-06-01" \
      --header "x-api-key: $ANTHROPIC_API_KEY" \
      | grep -o '"results_url":[[:space:]]*"[^"]*"' \
      | cut -d'"' -f4 \
      | while read -r url; do
        curl -s "$url" \
          --header "anthropic-version: 2023-06-01" \
          --header "x-api-key: $ANTHROPIC_API_KEY" \
          | sed 's/}{/}\n{/g' \
          | while IFS= read -r line
        do
          result_type=$(echo "$line" | sed -n 's/.*"result":[[:space:]]*{[[:space:]]*"type":[[:space:]]*"\([^"]*\)".*/\1/p')
          custom_id=$(echo "$line" | sed -n 's/.*"custom_id":[[:space:]]*"\([^"]*\)".*/\1/p')
          error_type=$(echo "$line" | sed -n 's/.*"error":[[:space:]]*{[[:space:]]*"type":[[:space:]]*"\([^"]*\)".*/\1/p')
    
          case "$result_type" in
            "succeeded")
              echo "Success! $custom_id"
              ;;
            "errored")
              if [ "$error_type" = "invalid_request" ]; then
                # Request body must be fixed before re-sending request
                echo "Validation error: $custom_id"
              else
                # Request can be retried directly
                echo "Server error: $custom_id"
              fi
              ;;
            "expired")
              echo "Expired: $line"
              ;;
          esac
        done
      done
    
    curl https://api.anthropic.com/v1/messages/batches \
         --header "x-api-key: $ANTHROPIC_API_KEY" \
         --header "anthropic-version: 2023-06-01" \
         --header "content-type: application/json" \
         --data \
    '{
        "requests": [
            {
                "custom_id": "my-first-request",
                "params": {
                    "model": "claude-sonnet-4-5",
                    "max_tokens": 1024,
                    "system": [
                        {
                            "type": "text",
                            "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
                        },
                        {
                            "type": "text",
                            "text": "<the entire contents of Pride and Prejudice>",
                            "cache_control": {"type": "ephemeral"}
                        }
                    ],
                    "messages": [
                        {"role": "user", "content": "Analyze the major themes in Pride and Prejudice."}
                    ]
                }
            },
            {
                "custom_id": "my-second-request",
                "params": {
                    "model": "claude-sonnet-4-5",
                    "max_tokens": 1024,
                    "system": [
                        {
                            "type": "text",
                            "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
                        },
                        {
                            "type": "text",
                            "text": "<the entire contents of Pride and Prejudice>",
                            "cache_control": {"type": "ephemeral"}
                        }
                    ],
                    "messages": [
                        {"role": "user", "content": "Write a summary of Pride and Prejudice."}
                    ]
                }
            }
        ]
    }'