배치 처리는 대량의 요청을 효율적으로 처리하기 위한 강력한 접근 방식입니다. 즉각적인 응답과 함께 요청을 하나씩 처리하는 대신, 배치 처리를 사용하면 여러 요청을 함께 제출하여 비동기적으로 처리할 수 있습니다. 이 패턴은 특히 다음과 같은 경우에 유용합니다:

• 대량의 데이터를 처리해야 하는 경우
• 즉각적인 응답이 필요하지 않은 경우
• 비용 효율성을 최적화하고자 하는 경우
• 대규모 평가 또는 분석을 실행하는 경우

Message Batches API는 이 패턴에 대한 Anthropic의 첫 번째 구현입니다.



Message Batches API

Message Batches API는 대량의 Messages 요청을 비동기적으로 처리하는 강력하고 비용 효율적인 방법입니다. 이 접근 방식은 즉각적인 응답이 필요하지 않은 작업에 적합하며, 대부분의 배치는 1시간 이내에 완료되면서 비용을 50% 절감하고 처리량을 높입니다.

이 가이드 외에도 API 레퍼런스를 직접 살펴볼 수 있습니다.



Message Batches API 작동 방식

Message Batches API에 요청을 보내면:

1. 시스템은 제공된 Messages 요청으로 새로운 Message Batch를 생성합니다.
2. 그런 다음 배치는 비동기적으로 처리되며, 각 요청은 독립적으로 처리됩니다.
3. 배치의 상태를 폴링하고 모든 요청의 처리가 종료되면 결과를 가져올 수 있습니다.

이는 즉각적인 결과가 필요하지 않은 대량 작업에 특히 유용합니다. 예를 들면:

• 대규모 평가: 수천 개의 테스트 케이스를 효율적으로 처리합니다.
• 콘텐츠 조정: 대량의 사용자 생성 콘텐츠를 비동기적으로 분석합니다.
• 데이터 분석: 대규모 데이터셋에 대한 인사이트 또는 요약을 생성합니다.
• 대량 콘텐츠 생성: 다양한 목적(예: 제품 설명, 기사 요약)을 위해 대량의 텍스트를 생성합니다.



배치 제한 사항

• Message Batch는 100,000개의 Message 요청 또는 256 MB 크기 중 먼저 도달하는 것으로 제한됩니다.
• 시스템은 각 배치를 가능한 한 빠르게 처리하며, 대부분의 배치는 1시간 이내에 완료됩니다. 모든 메시지가 완료되었거나 24시간이 지난 후 중 먼저 도래하는 시점에 배치 결과에 접근할 수 있습니다. 24시간 이내에 처리가 완료되지 않으면 배치는 만료됩니다.
• 배치 결과는 생성 후 29일 동안 사용할 수 있습니다. 그 이후에도 Batch를 볼 수는 있지만, 결과는 더 이상 다운로드할 수 없습니다.
• 배치는 Workspace 범위로 제한됩니다. API 키가 속한 Workspace 내에서 생성된 모든 배치(및 그 결과)를 볼 수 있습니다.
• 속도 제한은 Batches API HTTP 요청과 처리 대기 중인 배치 내 요청 수 모두에 적용됩니다. Message Batches API 속도 제한을 참조하세요. 또한 현재 수요와 요청량에 따라 처리 속도가 느려질 수 있습니다. 이 경우 24시간 후에 만료되는 요청이 더 많아질 수 있습니다.
• 높은 처리량과 동시 처리로 인해 배치가 Workspace에 구성된 지출 한도를 약간 초과할 수 있습니다.
• 각 배치 요청은 max_tokens가 최소 1 이상이어야 합니다. max_tokens: 0(캐시 사전 워밍)은 배치 내에서 지원되지 않습니다. 배치 처리 중에 작성된 임시 캐시 항목은 후속 요청이 실행되기 전에 만료될 가능성이 높기 때문입니다.



지원되는 모델

모든 활성 모델이 Message Batches API를 지원합니다.



배치 처리할 수 있는 항목

Messages API에 보낼 수 있는 거의 모든 요청을 배치에 포함할 수 있습니다. 여기에는 다음이 포함됩니다:

• 비전
• 도구 사용, 모든 서버 도구 포함(웹 검색, 웹 가져오기, 코드 실행, MCP 커넥터, advisor, 도구 검색)
• 시스템 메시지
• 멀티턴 대화
• 확장 사고
• 대부분의 베타 기능

배치의 각 요청은 독립적으로 처리되므로 단일 배치 내에서 서로 다른 유형의 요청을 혼합할 수 있습니다.

소수의 Messages API 매개변수는 배치 요청에서 지원되지 않습니다. 이러한 매개변수를 포함하면 유효성 검사 오류가 반환됩니다:



가격

Batches API는 상당한 비용 절감을 제공합니다. 모든 사용량은 표준 API 가격의 50%로 청구됩니다.



Message Batches API 사용 방법



배치 준비 및 생성

Message Batch는 Message를 생성하기 위한 요청 목록으로 구성됩니다. 개별 요청의 형태는 다음으로 구성됩니다:

• Messages 요청을 식별하기 위한 고유한 custom_id. 1~64자여야 하며 영숫자, 하이픈, 밑줄만 포함할 수 있습니다(^[a-zA-Z0-9_-]{1,64}$와 일치).
• 표준 Messages API 매개변수가 포함된 params 객체

이 목록을 requests 매개변수에 전달하여 배치를 생성할 수 있습니다:

from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.messages.batch_create_params import Request

client = anthropic.Anthropic()

message_batch = client.messages.batches.create(
    requests=[
        Request(
            custom_id="my-first-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-5",
                max_tokens=1024,
                messages=[
                    {
                        "role": "user",
                        "content": "Hello, world",
                    }
                ],
            ),
        ),
        Request(
            custom_id="my-second-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-5",
                max_tokens=1024,
                messages=[
                    {
                        "role": "user",
                        "content": "Hi again, friend",
                    }
                ],
            ),
        ),
    ]
)

print(message_batch)

이 예제에서는 두 개의 개별 요청이 비동기 처리를 위해 함께 배치됩니다. 각 요청에는 고유한 custom_id가 있으며 Messages API 호출에 사용하는 표준 매개변수가 포함되어 있습니다.

배치가 처음 생성되면 응답의 처리 상태는 in_progress입니다.

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



배치 추적

Message Batch의 processing_status 필드는 배치가 어느 처리 단계에 있는지 나타냅니다. in_progress로 시작한 다음, 배치의 모든 요청 처리가 완료되고 결과가 준비되면 ended로 업데이트됩니다. Console을 방문하거나 조회 엔드포인트를 사용하여 배치 상태를 모니터링할 수 있습니다.



Message Batch 완료 폴링

Message Batch를 폴링하려면 배치 생성 시 응답에서 제공되거나 배치 목록 조회를 통해 얻을 수 있는 id가 필요합니다. 처리가 종료될 때까지 주기적으로 배치 상태를 확인하는 폴링 루프를 구현할 수 있습니다:

import time

client = anthropic.Anthropic()

MESSAGE_BATCH_ID = "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d"

message_batch = None
while True:
    message_batch = client.messages.batches.retrieve(MESSAGE_BATCH_ID)
    if message_batch.processing_status == "ended":
        break

    print(f"Batch {MESSAGE_BATCH_ID} is still processing...")
    time.sleep(60)
print(message_batch)



모든 Message Batch 목록 조회

목록 엔드포인트를 사용하여 Workspace의 모든 Message Batch를 나열할 수 있습니다. API는 페이지네이션을 지원하며, 필요에 따라 추가 페이지를 자동으로 가져옵니다:

client = anthropic.Anthropic()

# 필요에 따라 자동으로 더 많은 페이지를 가져옵니다.
for message_batch in client.messages.batches.list(limit=20):
    print(message_batch)



배치 결과 가져오기

배치 처리가 종료되면 배치의 각 Messages 요청에 결과가 생깁니다. 결과 유형은 네 가지입니다:

배치의 request_counts는 결과의 개요를 보여주며, 이 네 가지 상태 각각에 도달한 요청 수를 나타냅니다.

배치 결과는 Message Batch의 results_url 속성에서 다운로드할 수 있으며, 조직 권한이 허용하는 경우 Console에서도 다운로드할 수 있습니다. 결과의 크기가 클 수 있으므로 한 번에 모두 다운로드하기보다는 결과를 스트리밍하는 것이 좋습니다.

client = anthropic.Anthropic()

# 결과 파일을 메모리 효율적인 청크로 스트리밍하여 한 번에 하나씩 처리합니다
for result in client.messages.batches.results(
    "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d",
):
    match result.result.type:
        case "succeeded":
            print(f"Success! {result.custom_id}")
        case "errored":
            if result.result.error.error.type == "invalid_request_error":
                # 요청을 다시 보내기 전에 요청 본문을 수정해야 합니다
                print(f"Validation error {result.custom_id}")
            else:
                # 요청을 바로 재시도할 수 있습니다
                print(f"Server error {result.custom_id}")
        case "expired":
            print(f"Request expired {result.custom_id}")

결과는 .jsonl 형식이며, 각 줄은 Message Batch의 단일 요청 결과를 나타내는 유효한 JSON 객체입니다. 스트리밍된 각 결과에 대해 custom_id와 결과 유형에 따라 다른 작업을 수행할 수 있습니다. 다음은 결과 세트의 예입니다:

{"custom_id":"my-second-request","result":{"type":"succeeded","message":{"id":"msg_014VwiXbi91y3JMjcpyGBHX5","type":"message","role":"assistant","model":"claude-opus-5","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-opus-5","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는 표준 오류 형태로 설정됩니다.



Message Batch 취소

취소 엔드포인트를 사용하여 현재 처리 중인 Message Batch를 취소할 수 있습니다. 취소 직후 배치의 processing_status는 canceling이 됩니다. 앞서 설명한 것과 동일한 폴링 기법을 사용하여 취소가 완료될 때까지 기다릴 수 있습니다. 취소된 배치는 ended 상태로 종료되며, 취소 전에 처리된 요청에 대한 부분 결과를 포함할 수 있습니다.

client = anthropic.Anthropic()

MESSAGE_BATCH_ID = "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d"

message_batch = client.messages.batches.cancel(
    MESSAGE_BATCH_ID,
)
print(message_batch)

응답은 배치가 canceling 상태임을 보여줍니다:

{
  "id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message_batch",
  "processing_status": "canceling",
  "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": "2024-09-24T18:39:03.114875Z",
  "results_url": null
}



Message Batch에서 프롬프트 캐싱 사용하기

Message Batches API는 프롬프트 캐싱을 지원하므로 배치 요청의 비용과 처리 시간을 잠재적으로 줄일 수 있습니다. 프롬프트 캐싱과 Message Batches의 가격 할인은 중첩될 수 있어, 두 기능을 함께 사용하면 더 큰 비용 절감 효과를 얻을 수 있습니다. 그러나 배치 요청은 비동기적이고 동시에 처리되므로 캐시 적중은 최선 노력(best-effort) 방식으로 제공됩니다. 사용자는 일반적으로 트래픽 패턴에 따라 30%에서 98% 범위의 캐시 적중률을 경험합니다.

배치 요청에서 캐시 적중 가능성을 최대화하려면:

1. 배치 내 모든 Message 요청에 동일한 cache_control 블록을 포함하세요.
2. 캐시 항목이 5분 수명 후 만료되지 않도록 꾸준한 요청 스트림을 유지하세요.
3. 가능한 한 많은 캐시된 콘텐츠를 공유하도록 요청을 구성하세요.

배치에서 프롬프트 캐싱을 구현하는 예:

from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.messages.batch_create_params import Request

client = anthropic.Anthropic()

message_batch = client.messages.batches.create(
    requests=[
        Request(
            custom_id="my-first-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-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.",
                    }
                ],
            ),
        ),
        Request(
            custom_id="my-second-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-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.",
                    }
                ],
            ),
        ),
    ]
)

이 예제에서는 배치의 두 요청 모두 캐시 적중 가능성을 높이기 위해 동일한 시스템 메시지와 cache_control로 표시된 오만과 편견의 전체 텍스트를 포함합니다.



서버 도구와 에이전트 루프

모든 서버 도구(웹 검색, 웹 가져오기, 코드 실행, MCP 커넥터, advisor, 도구 검색)는 배치 요청에서 작동합니다. 배치 워커는 동기 Messages API와 동일한 서버 측 에이전트 루프를 실행합니다.

유지해야 할 열린 연결이 없기 때문에, 배치 루프는 stop_reason: "pause_turn"을 반환하기 전에 동기 요청보다 턴당 더 많은 반복을 실행합니다. 배치 결과가 pause_turn과 함께 반환되면 해당 턴이 완료되지 않은 것입니다. pause_turn 계속 패턴에 표시된 것과 정확히 동일하게 일시 중지된 어시스턴트 콘텐츠를 후속 요청(배치 또는 동기)에 제출하여 계속할 수 있습니다.

배치 워커는 또한 고도로 동시적인 배치 처리가 조직의 웹 검색 속도 제한을 소진하지 않도록 조직별로 web_search를 제한합니다. 배치는 제한된 요청을 자동으로 재시도하므로 직접 처리할 필요는 없지만, 매우 큰 웹 검색 배치는 완료하는 데 더 오래 걸릴 수 있습니다.



확장 출력(베타)

output-300k-2026-03-24 베타 헤더는 Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5 또는 Claude Sonnet 4.6을 사용하는 배치 요청에 대해 max_tokens 상한을 300,000으로 높입니다. 이 헤더를 포함하면 단일 턴에서 표준 128k max_tokens 제한보다 훨씬 긴 출력을 생성할 수 있습니다.

책 분량의 초안 및 기술 문서, 포괄적인 구조화된 데이터 추출, 대규모 코드 생성 스캐폴드, 긴 추론 체인과 같은 장문 생성에 확장 출력을 사용하세요.

단일 300k 토큰 생성은 완료하는 데 1시간 이상 걸릴 수 있으므로 24시간 처리 기간을 염두에 두고 배치 제출을 계획하세요. 표준 배치 가격(표준 API 가격의 50%)이 적용됩니다.

from anthropic.types.beta.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.beta.messages.batch_create_params import Request

client = anthropic.Anthropic()

message_batch = client.beta.messages.batches.create(
    betas=["output-300k-2026-03-24"],
    requests=[
        Request(
            custom_id="long-form-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-5",
                max_tokens=300_000,
                messages=[
                    {
                        "role": "user",
                        "content": "Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices.",
                    }
                ],
            ),
        ),
    ],
)

print(message_batch)



효과적인 배치 처리를 위한 모범 사례

Batches API를 최대한 활용하려면:

• 배치 처리 상태를 정기적으로 모니터링하고 실패한 요청에 대한 적절한 재시도 로직을 구현하세요.
• 순서가 보장되지 않으므로 결과를 요청과 쉽게 일치시킬 수 있도록 의미 있는 custom_id 값을 사용하세요.
• 더 나은 관리를 위해 매우 큰 데이터셋을 여러 배치로 나누는 것을 고려하세요.
• 유효성 검사 오류를 방지하기 위해 Messages API로 단일 요청 형태를 사전 테스트하세요.



일반적인 문제 해결

예기치 않은 동작이 발생하는 경우:

• 전체 배치 요청 크기가 256 MB를 초과하지 않는지 확인하세요. 요청 크기가 너무 크면 413 request_too_large 오류가 발생할 수 있습니다.
• 배치의 모든 요청에 대해 지원되는 모델을 사용하고 있는지 확인하세요.
• 배치의 각 요청에 고유한 custom_id가 있는지 확인하세요.
• 배치 created_at(처리 ended_at이 아님) 시간으로부터 29일이 지나지 않았는지 확인하세요. 29일이 지나면 결과를 더 이상 볼 수 없습니다.
• 배치가 취소되지 않았는지 확인하세요.

배치에서 한 요청의 실패는 다른 요청의 처리에 영향을 미치지 않습니다.



배치 저장 및 개인정보 보호

• Workspace 격리: 배치는 생성된 Workspace 내에서 격리됩니다. 해당 Workspace와 연결된 API 키 또는 Console에서 Workspace 배치를 볼 수 있는 권한이 있는 사용자만 접근할 수 있습니다.

• 결과 가용성: 배치 결과는 배치 생성 후 29일 동안 사용할 수 있어 가져오기 및 처리에 충분한 시간을 제공합니다.



데이터 보존

배치 처리는 배치 생성 후 최대 29일 동안 요청 및 응답 데이터를 저장합니다. 처리 후 언제든지 DELETE /v1/messages/batches/{batch_id} 엔드포인트를 사용하여 메시지 배치를 삭제할 수 있습니다. 진행 중인 배치를 삭제하려면 먼저 취소하세요. 비동기 처리는 배치 완료 및 결과 가져오기까지 입력과 출력 모두의 서버 측 저장이 필요합니다.

모든 기능에 대한 ZDR 적격성은 API 및 데이터 보존을 참조하세요.



FAQ



다음 단계