일괄 처리

빌드모델 기능

배치 처리

대량의 요청을 효율적으로 처리하기 위한 배치 처리 방식에 대해 알아봅니다.

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

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

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

This feature is not eligible for Zero Data Retention (ZDR). Data is retained according to the feature's standard retention policy.

Message Batches API

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

API 참조를 직접 탐색할 수 있으며, 이 가이드 외에도 참고할 수 있습니다.

Message Batches API의 작동 방식

Message Batches API에 요청을 보낼 때:

시스템은 제공된 Messages 요청으로 새로운 Message Batch를 생성합니다.
배치는 비동기적으로 처리되며, 각 요청은 독립적으로 처리됩니다.
배치의 상태를 폴링하고 모든 요청의 처리가 끝나면 결과를 검색할 수 있습니다.

이는 즉시 결과가 필요하지 않은 대량 작업에 특히 유용합니다:

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

배치 제한사항

Message Batch는 100,000개의 Message 요청 또는 256MB 크기 중 먼저 도달하는 것으로 제한됩니다.
시스템은 각 배치를 최대한 빠르게 처리하며, 대부분의 배치는 1시간 이내에 완료됩니다. 모든 메시지가 완료되거나 24시간 후 중 먼저 오는 시점에 배치 결과에 액세스할 수 있습니다. 처리가 24시간 내에 완료되지 않으면 배치가 만료됩니다.
배치 결과는 생성 후 29일 동안 사용 가능합니다. 그 후에는 여전히 배치를 볼 수 있지만 결과는 더 이상 다운로드할 수 없습니다.
배치는 Workspace로 범위가 지정됩니다. API 키가 속한 Workspace 내에서 생성된 모든 배치(및 해당 결과)를 볼 수 있습니다.
속도 제한은 Batches API HTTP 요청과 처리 대기 중인 배치 내의 요청 수에 모두 적용됩니다. Message Batches API 속도 제한을 참조하세요. 또한 현재 수요와 요청 볼륨에 따라 처리가 느려질 수 있습니다. 이 경우 24시간 후 만료되는 더 많은 요청이 표시될 수 있습니다.
높은 처리량과 동시 처리로 인해 배치는 Workspace의 구성된 지출 제한을 약간 초과할 수 있습니다.

지원되는 모델

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

배치 처리 가능한 항목

Messages API에 대해 수행할 수 있는 모든 요청을 배치에 포함할 수 있습니다. 여기에는 다음이 포함됩니다:

Vision
Tool use
System messages
Multi-turn conversations
모든 베타 기능

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

배치는 처리하는 데 5분 이상 걸릴 수 있으므로, 배치를 처리할 때 공유 컨텍스트로 더 나은 캐시 히트율을 위해 프롬프트 캐싱과 함께 1시간 캐시 기간을 사용하는 것을 고려하세요.

가격 책정

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

Model	Batch input	Batch output
Claude Opus 4.7	$2.50 / MTok	$12.50 / MTok
Claude Opus 4.6	$2.50 / MTok	$12.50 / MTok
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.6	$1.50 / MTok	$7.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 (deprecated)	$7.50 / MTok	$37.50 / MTok
Claude Haiku 3	$0.125 / MTok	$0.625 / MTok

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-4-7",
                max_tokens=1024,
                messages=[
                    {
                        "role": "user",
                        "content": "Hello, world",
                    }
                ],
            ),
        ),
        Request(
            custom_id="my-second-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-4-7",
                max_tokens=1024,
                messages=[
                    {
                        "role": "user",
                        "content": "Hi again, friend",
                    }
                ],
            ),
        ),
    ]
)

print(message_batch)

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

Messages API로 배치 요청 테스트

각 메시지 요청에 대한 params 객체의 유효성 검사는 비동기적으로 수행되며, 유효성 검사 오류는 전체 배치의 처리가 끝났을 때 반환됩니다. Messages API로 먼저 요청 형태를 확인하여 입력을 올바르게 구축하고 있는지 확인할 수 있습니다.

배치가 처음 생성될 때 응답은 in_progress의 처리 상태를 가집니다.

Output

{
  "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 Batches 나열

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

client = anthropic.Anthropic()

# Automatically fetches more pages as needed.
for message_batch in client.messages.batches.list(limit=20):
    print(message_batch)

배치 결과 검색

배치 처리가 완료되면 배치의 각 Messages 요청에 결과가 있습니다. 4가지 결과 유형이 있습니다:

결과 유형	설명
`succeeded`	요청이 성공했습니다. 메시지 결과를 포함합니다.
`errored`	요청에서 오류가 발생했으며 메시지가 생성되지 않았습니다. 가능한 오류에는 잘못된 요청 및 내부 서버 오류가 포함됩니다. 이러한 요청에 대해서는 청구되지 않습니다.
`canceled`	사용자가 이 요청을 모델로 보내기 전에 배치를 취소했습니다. 이러한 요청에 대해서는 청구되지 않습니다.
`expired`	배치가 이 요청을 모델로 보내기 전에 24시간 만료 기한에 도달했습니다. 이러한 요청에 대해서는 청구되지 않습니다.

배치의 request_counts를 통해 결과의 개요를 볼 수 있으며, 이는 각 4가지 상태에 도달한 요청의 수를 보여줍니다.

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

client = anthropic.Anthropic()

# Stream results file in memory-efficient chunks, processing one at a time
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":
                # Request body must be fixed before re-sending request
                print(f"Validation error {result.custom_id}")
            else:
                # Request can be retried directly
                print(f"Server error {result.custom_id}")
        case "expired":
            print(f"Request expired {result.custom_id}")

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

.jsonl file

{"custom_id":"my-second-request","result":{"type":"succeeded","message":{"id":"msg_014VwiXbi91y3JMjcpyGBHX5","type":"message","role":"assistant","model":"claude-opus-4-7","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-4-7","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 필드를 사용하세요.

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 상태임을 보여줍니다:

Output

{
  "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 Batches에서 프롬프트 캐싱 사용

Message Batches API는 프롬프트 캐싱을 지원하므로 배치 요청의 비용과 처리 시간을 잠재적으로 줄일 수 있습니다. 프롬프트 캐싱과 Message Batches의 가격 할인이 누적되어 두 기능을 함께 사용할 때 훨씬 더 큰 비용 절감을 제공합니다. 그러나 배치 요청은 비동기적으로 동시에 처리되므로 캐시 히트는 최선의 노력 기준으로 제공됩니다. 사용자는 일반적으로 트래픽 패턴에 따라 30%에서 98% 범위의 캐시 히트율을 경험합니다.

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

배치 내의 모든 Message 요청에 동일한 cache_control 블록을 포함합니다
캐시 항목이 5분의 수명 후 만료되는 것을 방지하기 위해 안정적인 요청 스트림을 유지합니다
가능한 한 많은 캐시된 콘텐츠를 공유하도록 요청을 구조화합니다

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

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-4-7",
                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-4-7",
                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로 표시된 Pride and Prejudice의 전체 텍스트를 포함하여 캐시 히트 가능성을 높입니다.

확장 출력(베타)

output-300k-2026-03-24 베타 헤더는 Claude Opus 4.7, Claude Opus 4.6 또는 Claude Sonnet 4.6을 사용하는 배치 요청의 max_tokens 상한을 300,000으로 올립니다. 헤더를 포함하여 한 번에 표준 제한(모델에 따라 64k에서 128k)보다 훨씬 긴 출력을 생성합니다.

확장 출력은 Message Batches API에서만 사용 가능하며 동기식 Messages API에서는 사용할 수 없습니다. Claude API에서 지원되며 Amazon Bedrock, Vertex AI 또는 Microsoft Foundry에서는 사용할 수 없습니다.

확장 출력을 책 길이의 초안 및 기술 문서와 같은 장문 생성, 철저한 구조화된 데이터 추출, 대규모 코드 생성 스캐폴드 및 긴 추론 체인에 사용합니다.

단일 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-4-7",
                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일 이상 경과한 경우 결과를 더 이상 볼 수 없습니다.
배치가 취소되지 않았는지 확인합니다.

배치의 한 요청이 실패해도 다른 요청의 처리에는 영향을 주지 않습니다.

배치 저장소 및 개인정보 보호

워크스페이스 격리: 배치는 생성된 워크스페이스 내에서 격리됩니다. 해당 워크스페이스의 API 키 또는 Console에서 워크스페이스 배치를 볼 수 있는 권한이 있는 사용자만 액세스할 수 있습니다.
결과 가용성: 배치 결과는 배치 생성 후 29일 동안 사용 가능하므로 검색 및 처리를 위한 충분한 시간을 제공합니다.

데이터 보존

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

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

FAQ

Was this page helpful?

빌드모델 기능

배치 처리

대량의 요청을 효율적으로 처리하기 위한 배치 처리 방식에 대해 알아봅니다.

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

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

This feature is not eligible for Zero Data Retention (ZDR). Data is retained according to the feature's standard retention policy.

Message Batches API

API 참조를 직접 탐색할 수 있으며, 이 가이드 외에도 참고할 수 있습니다.

Message Batches API의 작동 방식

Message Batches API에 요청을 보낼 때:

시스템은 제공된 Messages 요청으로 새로운 Message Batch를 생성합니다.
배치는 비동기적으로 처리되며, 각 요청은 독립적으로 처리됩니다.
배치의 상태를 폴링하고 모든 요청의 처리가 끝나면 결과를 검색할 수 있습니다.

이는 즉시 결과가 필요하지 않은 대량 작업에 특히 유용합니다:

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

배치 제한사항

Message Batch는 100,000개의 Message 요청 또는 256MB 크기 중 먼저 도달하는 것으로 제한됩니다.
시스템은 각 배치를 최대한 빠르게 처리하며, 대부분의 배치는 1시간 이내에 완료됩니다. 모든 메시지가 완료되거나 24시간 후 중 먼저 오는 시점에 배치 결과에 액세스할 수 있습니다. 처리가 24시간 내에 완료되지 않으면 배치가 만료됩니다.
배치 결과는 생성 후 29일 동안 사용 가능합니다. 그 후에는 여전히 배치를 볼 수 있지만 결과는 더 이상 다운로드할 수 없습니다.
배치는 Workspace로 범위가 지정됩니다. API 키가 속한 Workspace 내에서 생성된 모든 배치(및 해당 결과)를 볼 수 있습니다.
속도 제한은 Batches API HTTP 요청과 처리 대기 중인 배치 내의 요청 수에 모두 적용됩니다. Message Batches API 속도 제한을 참조하세요. 또한 현재 수요와 요청 볼륨에 따라 처리가 느려질 수 있습니다. 이 경우 24시간 후 만료되는 더 많은 요청이 표시될 수 있습니다.
높은 처리량과 동시 처리로 인해 배치는 Workspace의 구성된 지출 제한을 약간 초과할 수 있습니다.

지원되는 모델

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

배치 처리 가능한 항목

Messages API에 대해 수행할 수 있는 모든 요청을 배치에 포함할 수 있습니다. 여기에는 다음이 포함됩니다:

Vision
Tool use
System messages
Multi-turn conversations
모든 베타 기능

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

가격 책정

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

Model	Batch input	Batch output
Claude Opus 4.7	$2.50 / MTok	$12.50 / MTok
Claude Opus 4.6	$2.50 / MTok	$12.50 / MTok
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.6	$1.50 / MTok	$7.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 (deprecated)	$7.50 / MTok	$37.50 / MTok
Claude Haiku 3	$0.125 / MTok	$0.625 / MTok

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-4-7",
                max_tokens=1024,
                messages=[
                    {
                        "role": "user",
                        "content": "Hello, world",
                    }
                ],
            ),
        ),
        Request(
            custom_id="my-second-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-4-7",
                max_tokens=1024,
                messages=[
                    {
                        "role": "user",
                        "content": "Hi again, friend",
                    }
                ],
            ),
        ),
    ]
)

print(message_batch)

Messages API로 배치 요청 테스트

배치가 처음 생성될 때 응답은 in_progress의 처리 상태를 가집니다.

Output

{
  "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 완료 폴링

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 Batches 나열

client = anthropic.Anthropic()

# Automatically fetches more pages as needed.
for message_batch in client.messages.batches.list(limit=20):
    print(message_batch)

배치 결과 검색

배치 처리가 완료되면 배치의 각 Messages 요청에 결과가 있습니다. 4가지 결과 유형이 있습니다:

결과 유형	설명
`succeeded`	요청이 성공했습니다. 메시지 결과를 포함합니다.
`errored`	요청에서 오류가 발생했으며 메시지가 생성되지 않았습니다. 가능한 오류에는 잘못된 요청 및 내부 서버 오류가 포함됩니다. 이러한 요청에 대해서는 청구되지 않습니다.
`canceled`	사용자가 이 요청을 모델로 보내기 전에 배치를 취소했습니다. 이러한 요청에 대해서는 청구되지 않습니다.
`expired`	배치가 이 요청을 모델로 보내기 전에 24시간 만료 기한에 도달했습니다. 이러한 요청에 대해서는 청구되지 않습니다.

배치의 request_counts를 통해 결과의 개요를 볼 수 있으며, 이는 각 4가지 상태에 도달한 요청의 수를 보여줍니다.

client = anthropic.Anthropic()

# Stream results file in memory-efficient chunks, processing one at a time
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":
                # Request body must be fixed before re-sending request
                print(f"Validation error {result.custom_id}")
            else:
                # Request can be retried directly
                print(f"Server error {result.custom_id}")
        case "expired":
            print(f"Request expired {result.custom_id}")

.jsonl file

{"custom_id":"my-second-request","result":{"type":"succeeded","message":{"id":"msg_014VwiXbi91y3JMjcpyGBHX5","type":"message","role":"assistant","model":"claude-opus-4-7","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-4-7","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 취소

client = anthropic.Anthropic()

MESSAGE_BATCH_ID = "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d"

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

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

Output

{
  "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 Batches에서 프롬프트 캐싱 사용

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

배치 내의 모든 Message 요청에 동일한 cache_control 블록을 포함합니다
캐시 항목이 5분의 수명 후 만료되는 것을 방지하기 위해 안정적인 요청 스트림을 유지합니다
가능한 한 많은 캐시된 콘텐츠를 공유하도록 요청을 구조화합니다

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

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-4-7",
                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-4-7",
                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.",
                    }
                ],
            ),
        ),
    ]
)

확장 출력(베타)

확장 출력을 책 길이의 초안 및 기술 문서와 같은 장문 생성, 철저한 구조화된 데이터 추출, 대규모 코드 생성 스캐폴드 및 긴 추론 체인에 사용합니다.

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-4-7",
                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일 이상 경과한 경우 결과를 더 이상 볼 수 없습니다.
배치가 취소되지 않았는지 확인합니다.

배치의 한 요청이 실패해도 다른 요청의 처리에는 영향을 주지 않습니다.

배치 저장소 및 개인정보 보호

워크스페이스 격리: 배치는 생성된 워크스페이스 내에서 격리됩니다. 해당 워크스페이스의 API 키 또는 Console에서 워크스페이스 배치를 볼 수 있는 권한이 있는 사용자만 액세스할 수 있습니다.
결과 가용성: 배치 결과는 배치 생성 후 29일 동안 사용 가능하므로 검색 및 처리를 위한 충분한 시간을 제공합니다.

데이터 보존

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

FAQ

Was this page helpful?

Message Batches API

Message Batches API의 작동 방식

배치 제한사항

지원되는 모델

배치 처리 가능한 항목

가격 책정

Message Batches API 사용 방법

배치 준비 및 생성

배치 추적

Message Batch 완료 폴링

모든 Message Batches 나열

배치 결과 검색

Message Batch 취소

Message Batches에서 프롬프트 캐싱 사용

확장 출력(베타)

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

일반적인 문제 해결

배치 저장소 및 개인정보 보호

데이터 보존

FAQ

배치 처리에 얼마나 걸리나요?

Batches API는 모든 모델에서 사용 가능한가요?

Message Batches API를 다른 API 기능과 함께 사용할 수 있나요?

Message Batches API는 가격에 어떤 영향을 미치나요?

배치를 제출한 후 업데이트할 수 있나요?

Message Batches API 속도 제한이 있으며 Messages API 속도 제한과 상호 작용하나요?

배치 요청에서 오류를 어떻게 처리하나요?

Message Batches API는 개인정보 보호 및 데이터 분리를 어떻게 처리하나요?

Message Batches API에서 프롬프트 캐싱을 사용할 수 있나요?

Message Batches API

Message Batches API의 작동 방식

배치 제한사항

지원되는 모델

배치 처리 가능한 항목

가격 책정

Message Batches API 사용 방법

배치 준비 및 생성

배치 추적

Message Batch 완료 폴링

모든 Message Batches 나열

배치 결과 검색

Message Batch 취소

Message Batches에서 프롬프트 캐싱 사용

확장 출력(베타)

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

일반적인 문제 해결

배치 저장소 및 개인정보 보호

데이터 보존

FAQ

배치 처리에 얼마나 걸리나요?

Batches API는 모든 모델에서 사용 가능한가요?

Message Batches API를 다른 API 기능과 함께 사용할 수 있나요?

Message Batches API는 가격에 어떤 영향을 미치나요?

배치를 제출한 후 업데이트할 수 있나요?

Message Batches API 속도 제한이 있으며 Messages API 속도 제한과 상호 작용하나요?

배치 요청에서 오류를 어떻게 처리하나요?

Message Batches API는 개인정보 보호 및 데이터 분리를 어떻게 처리하나요?

Message Batches API에서 프롬프트 캐싱을 사용할 수 있나요?