배치 처리
Message Batches API로 대량의 Messages 요청을 비동기적으로 처리하여 비용을 50퍼센트 절감하고 처리량을 높이세요.
“Batch processing”(배치 처리)은 대량의 요청을 효율적으로 처리하기 위한 강력한 접근 방식입니다. 요청을 하나씩 처리하고 즉시 응답을 받는 대신, 배치 처리를 사용하면 여러 요청을 함께 제출하여 비동기적으로 처리할 수 있습니다. 이 패턴은 특히 다음과 같은 경우에 유용합니다:
- 대량의 데이터를 처리해야 하는 경우
- 즉각적인 응답이 필요하지 않은 경우
- 비용 효율성을 최적화하려는 경우
- 대규모 평가 또는 분석을 실행하는 경우
Message Batches API는 이 패턴에 대한 Anthropic의 첫 번째 구현입니다.
Message Batches API
Message Batches API는 대량의 MessagesAPI 참조 링크가 포함된 미리보기 사용 가능 — 카드에 포커스가 들어올 때까지 Tab을 누르고, 돌아가려면 Escape를 누르세요. 요청을 비동기적으로 처리하는 강력하고 비용 효율적인 방법입니다. 이 접근 방식은 즉각적인 응답이 필요하지 않은 작업에 적합하며, 대부분의 배치는 1시간 이내에 완료되면서 비용을 50퍼센트 절감하고 처리량을 높여 줍니다.
이 가이드 외에도 API 레퍼런스를 직접 살펴볼API 참조 링크가 포함된 미리보기 사용 가능 — 카드에 포커스가 들어올 때까지 Tab을 누르고, 돌아가려면 Escape를 누르세요. 수 있습니다.
Message Batches API 작동 방식
Message Batches API에 요청을 보내면:
- 시스템은 제공된 Messages 요청으로 새로운 메시지 배치를 생성합니다.
- 그런 다음 배치는 비동기적으로 처리되며, 각 요청은 독립적으로 처리됩니다.
- 배치의 상태를 폴링할 수 있으며, 모든 요청의 처리가 끝나면 결과를 가져올 수 있습니다.
이는 즉각적인 결과가 필요하지 않은 대량 작업에 특히 유용합니다. 예를 들면 다음과 같습니다:
- 대규모 평가: 수천 개의 테스트 케이스를 효율적으로 처리합니다.
- 콘텐츠 모더레이션: 대량의 사용자 생성 콘텐츠를 비동기적으로 분석합니다.
- 데이터 분석: 대규모 데이터셋에 대한 인사이트나 요약을 생성합니다.
- 대량 콘텐츠 생성: 다양한 목적(예: 제품 설명, 기사 요약)을 위해 대량의 텍스트를 생성합니다.
배치 제한 사항
- 메시지 배치는 100,000개의 Message 요청 또는 256 MB 크기 중 먼저 도달하는 쪽으로 제한됩니다.
- 시스템은 각 배치를 최대한 빠르게 처리하며, 대부분의 배치는 1시간 이내에 완료됩니다. 배치 결과는 모든 메시지가 완료되었을 때 또는 24시간이 지난 후 중 먼저 도래하는 시점에 접근할 수 있습니다. 24시간 이내에 처리가 완료되지 않으면 배치는 만료됩니다.
- 배치 결과는 생성 후 29일 동안 사용할 수 있습니다. 그 이후에도 배치를 볼 수는 있지만, 결과는 더 이상 다운로드할 수 없습니다.
- 배치는 Claude Console의 워크스페이스에 범위가 지정됩니다. 요청이 실행되는 워크스페이스 내에서 생성된 모든 배치(및 그 결과)를 볼 수 있습니다.
- “Rate limit”(속도 제한)은 Batches API HTTP 요청과 처리 대기 중인 배치 내 요청 수 모두에 적용됩니다. Message Batches API 속도 제한을 참조하세요. 또한 현재 수요와 요청량에 따라 처리 속도가 느려질 수 있습니다. 이 경우 24시간 후 만료되는 요청이 더 많아질 수 있습니다.
- 높은 처리량과 동시 처리로 인해, 배치는 Claude Console에서 워크스페이스에 설정된 지출 한도를 약간 초과할 수 있습니다.
- 배치에 포함된 각 요청의
max_tokensAPI 참조 링크가 포함된 미리보기 사용 가능 — 카드에 포커스가 들어올 때까지 Tab을 누르고, 돌아가려면 Escape를 누르세요.는 최소1이상이어야 합니다.max_tokens: 0(캐시 사전 준비)은 배치 내에서 지원되지 않습니다. 배치 처리 중에 기록된 임시 캐시 항목은 후속 요청이 실행되기 전에 만료될 가능성이 높기 때문입니다.
지원 모델
모든 활성 모델이 Message Batches API를 지원합니다.
배치로 처리할 수 있는 항목
Messages API에 보낼 수 있는 거의 모든 요청을 배치에 포함할 수 있습니다. 여기에는 다음이 포함됩니다:
- 비전
- 도구 사용(모든 서버 도구 포함: 웹 검색, 웹 가져오기, 코드 실행, MCP 커넥터, 어드바이저, 도구 검색)
- 시스템 메시지
- 멀티턴 대화
- 확장 사고
- 대부분의 베타 기능
배치의 각 요청은 독립적으로 처리되므로, 단일 배치 내에서 다양한 유형의 요청을 혼합할 수 있습니다.
소수의 Messages API 매개변수는 배치 요청에서 지원되지 않습니다. 이 중 하나라도 포함하면 유효성 검사 오류가 반환됩니다:
| 매개변수 | 이유 |
|---|---|
stream: true | 배치 결과는 스트림이 아닌 단일 파일로 반환됩니다. |
speed (Fast mode) | Fast mode는 동기식 지연 시간을 조정하는 기능으로, 비동기 배치 처리에는 적용되지 않습니다. |
fallbacks (서버 측 폴백) | 서버 측 폴백은 배치에 적용되지 않습니다. 거부된 요청을 재시도하려면 Message Batches에서의 거부를 참조하세요. |
max_tokens: 0 | 배치 제한 사항을 참조하세요. |
가격
Batches API는 상당한 비용 절감 효과를 제공합니다. 모든 사용량은 표준 API 가격의 50퍼센트로 청구됩니다.
| 모델 | 배치 토큰 | |
|---|---|---|
| 이름 | 입력 | 출력 |
Claude Fable 5.2For demanding reasoning and long-horizon agentic work | US$4 / | US$20 / MTok |
Claude Opus 5.5For long-running agentic coding and knowledge work | US$2 / MTok | US$10 / MTok |
Claude Sonnet 5.5The best combination of speed and intelligence | US$1 / MTok | US$5 / MTok |
Claude Haiku 5.5For high-volume, latency-sensitive tasks such as classification, extraction, and routing | US$0.05 / MTok100,000토큰 이하 프롬프트 기준 | US$0.25 / MTok |
US$0.25 / MTok100,000토큰을 초과하는 프롬프트의 경우 | US$1.25 / MTok | |
US$4 / MTok | US$20 / MTok | |
US$5 / MTok | US$25 / MTok | |
US$5 / MTok | US$25 / MTok | |
US$5 / MTok | US$25 / MTok | |
US$5 / MTok | US$25 / MTok | |
US$2.50 / MTok | US$12.50 / MTok | |
US$2.50 / MTok | US$12.50 / MTok | |
US$2.50 / MTok | US$12.50 / MTok | |
US$2.50 / MTok | US$12.50 / MTok | |
US$2.50 / MTok | US$12.50 / MTok | |
Claude Opus 4.1 | US$7.50 / MTok | US$37.50 / MTok |
Claude Opus 4 | US$7.50 / MTok | US$37.50 / MTok |
US$1 / MTok | US$5 / MTok | |
US$1.50 / MTok | US$7.50 / MTok | |
US$1.50 / MTok | US$7.50 / MTok | |
Claude Sonnet 4 | US$1.50 / MTok | US$7.50 / MTok |
US$0.50 / MTok | US$2.50 / MTok | |
Message Batches API 사용 방법
배치 준비 및 생성
메시지 배치는 Message를 생성하기 위한 요청 목록으로 구성됩니다. 개별 요청의 형태는 다음으로 구성됩니다:
- Messages 요청을 식별하기 위한 고유한
custom_idAPI 참조 링크가 포함된 미리보기 사용 가능 — 카드에 포커스가 들어올 때까지 Tab을 누르고, 돌아가려면 Escape를 누르세요.. 1~64자여야 하며 영숫자, 하이픈, 밑줄만 포함해야 합니다(^[a-zA-Z0-9_-]{1,64}$와 일치). - 표준 Messages APIAPI 참조 링크가 포함된 미리보기 사용 가능 — 카드에 포커스가 들어올 때까지 Tab을 누르고, 돌아가려면 Escape를 누르세요. 매개변수가 포함된
paramsAPI 참조 링크가 포함된 미리보기 사용 가능 — 카드에 포커스가 들어올 때까지 Tab을 누르고, 돌아가려면 Escape를 누르세요. 객체
이 목록을 requests 매개변수에 전달하여 배치를 생성API 참조 링크가 포함된 미리보기 사용 가능 — 카드에 포커스가 들어올 때까지 Tab을 누르고, 돌아가려면 Escape를 누르세요.할 수 있습니다:
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-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": "Hello, world",
}
],
),
),
Request(
custom_id="my-second-request",
params=MessageCreateParamsNonStreaming(
model="claude-opus-5-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
}배치 추적
메시지 배치의 processing_statusAPI 참조 링크가 포함된 미리보기 사용 가능 — 카드에 포커스가 들어올 때까지 Tab을 누르고, 돌아가려면 Escape를 누르세요. 필드는 배치가 현재 어떤 처리 단계에 있는지를 나타냅니다. 처음에는 in_progress로 시작하며, 배치의 모든 요청 처리가 완료되고 결과가 준비되면 ended로 업데이트됩니다. Console을 방문하거나 조회 엔드포인트를 사용하여 배치 상태를 모니터링할 수 있습니다.
Retrieve a Message Batch
This endpoint is idempotent and can be used to poll for Message Batch completion. To access the results of a Message Batch, make a request to the results_url field in the response.
ID of the 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)모든 메시지 배치 나열
목록 엔드포인트API 참조 링크가 포함된 미리보기 사용 가능 — 카드에 포커스가 들어올 때까지 Tab을 누르고, 돌아가려면 Escape를 누르세요.를 사용하여 워크스페이스의 모든 메시지 배치를 나열할 수 있습니다. API는 페이지네이션을 지원하며, 필요에 따라 추가 페이지를 자동으로 가져옵니다:
client = anthropic.Anthropic()
# 필요에 따라 다음 페이지를 자동으로 가져옵니다.
for message_batch in client.messages.batches.list(limit=20):
print(message_batch)배치 결과 가져오기
배치 처리가 끝나면 배치의 각 Messages 요청에는 결과가 있습니다. 결과 유형은 네 가지입니다:
| 결과 유형 | 설명 |
|---|---|
succeeded | 요청이 성공했습니다. 메시지 결과가 포함됩니다. |
errored | 요청에서 오류가 발생하여 메시지가 생성되지 않았습니다. 가능한 오류로는 잘못된 요청과 내부 서버 오류가 있습니다. 이러한 요청에 대해서는 요금이 청구되지 않습니다. |
canceled | 이 요청이 모델로 전송되기 전에 사용자가 배치를 취소했습니다. 이러한 요청에 대해서는 요금이 청구되지 않습니다. |
expired | 이 요청이 모델로 전송되기 전에 배치가 24시간 만료 시간에 도달했습니다. 이러한 요청에 대해서는 요금이 청구되지 않습니다. |
배치의 request_counts 객체는 아직 처리 중인 요청 수와 각 결과 유형별 요청 수를 집계합니다.
배치 결과는 메시지 배치의 results_urlAPI 참조 링크가 포함된 미리보기 사용 가능 — 카드에 포커스가 들어올 때까지 Tab을 누르고, 돌아가려면 Escape를 누르세요. 속성에서 다운로드할 수 있으며, 조직 권한이 허용하는 경우 Console에서도 다운로드할 수 있습니다. 결과의 크기가 클 수 있으므로, 한 번에 모두 다운로드하기보다는 결과를 스트리밍API 참조 링크가 포함된 미리보기 사용 가능 — 카드에 포커스가 들어올 때까지 Tab을 누르고, 돌아가려면 Escape를 누르세요.하는 것이 좋습니다.
client = anthropic.Anthropic()
# 결과 파일을 메모리 효율적인 청크 단위로 스트리밍하여 한 번에 하나씩 처리합니다
for result in client.messages.batches.results(
"msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d",
):
outcome = result.result
match outcome.type:
case "succeeded":
print(f"Success! {result.custom_id}")
case "errored":
if outcome.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 형식이며, 각 줄은 메시지 배치 내 단일 요청의 결과를 나타내는 유효한 JSON 객체입니다. 스트리밍된 각 결과에 대해 custom_id와 결과 유형에 따라 다른 작업을 수행할 수 있습니다. 다음은 결과 예시입니다:
{"custom_id":"my-second-request","result":{"type":"succeeded","message":{"id":"msg_014VwiXbi91y3JMjcpyGBHX5","type":"message","role":"assistant","model":"claude-opus-5-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-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는 표준 오류 형태로 설정됩니다.
배치 결과는 배치를 생성한 요청의 API 버전을 사용합니다.
메시지 배치 취소
취소 엔드포인트API 참조 링크가 포함된 미리보기 사용 가능 — 카드에 포커스가 들어올 때까지 Tab을 누르고, 돌아가려면 Escape를 누르세요.를 사용하여 현재 처리 중인 메시지 배치를 취소할 수 있습니다. 취소 직후 배치의 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 Batches에서 프롬프트 캐싱 사용
Message Batches API는 “prompt caching”(프롬프트 캐싱)을 지원하므로, 배치 요청의 비용과 처리 시간을 줄일 수 있습니다. 프롬프트 캐싱과 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-5-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-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 커넥터, 어드바이저, 도구 검색)는 배치 요청에서 작동합니다. 배치 워커는 동기식 Messages API와 동일한 서버 측 에이전트 루프를 실행합니다.
유지해야 할 열린 연결이 없으므로, 배치 루프는 stop_reason: "pause_turn"을 반환하기 전에 동기식 요청보다 한 턴에서 더 많은 반복을 실행할 수 있습니다. 배치 결과가 pause_turn으로 반환되면 해당 턴은 완료되지 않은 것입니다. pause_turn 연속 패턴에 나온 대로 일시 중지된 어시스턴트 콘텐츠를 후속 요청(배치 또는 동기식)으로 제출하여 계속할 수 있습니다.
배치 워커는 또한 각 조직에 대해 web_search를 조절하여, 동시성이 높은 배치 처리가 조직의 웹 검색 속도 제한을 소진하지 않도록 합니다. 배치는 조절된 요청을 자동으로 재시도하므로 직접 처리할 필요는 없지만, 매우 큰 웹 검색 배치는 완료하는 데 더 오래 걸릴 수 있습니다.
확장 출력 (베타)
output-300k-2026-03-24 베타 헤더는 Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5.5, Claude Sonnet 5, Claude Sonnet 4.6 또는 Claude Haiku 5.5를 사용하는 배치 요청의 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-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일이 지나면 결과를 더 이상 볼 수 없습니다. - 배치가 취소되지 않았는지 확인하세요.
배치 내 한 요청의 실패는 다른 요청의 처리에 영향을 주지 않습니다.
배치 저장 및 개인정보 보호
-
워크스페이스 격리: 배치는 생성된 워크스페이스 내에서 격리됩니다. 동일한 워크스페이스의 API 요청 또는 Console에서 워크스페이스 배치를 볼 수 있는 권한이 있는 사용자만 접근할 수 있습니다.
-
결과 이용 가능 기간: 배치 결과는 배치 생성 후 29일 동안 사용할 수 있어, 조회 및 처리에 충분한 시간을 제공합니다.
FAQ
배치 처리에는 최대 24시간이 걸릴 수 있지만, 많은 경우 더 빨리 완료됩니다. 실제 처리 시간은 배치 크기, 현재 수요 및 요청량에 따라 달라집니다. 배치가 만료되어 24시간 이내에 완료되지 않을 수도 있습니다.
지원 모델 목록은 지원 모델을 참조하세요.
예, Message Batches API는 대부분의 베타 기능을 포함하여 Messages API에서 사용 가능한 거의 모든 기능을 지원합니다. 소수의 매개변수(stream, speed, fallbacks, max_tokens: 0)는 지원되지 않습니다. 전체 목록은 배치로 처리할 수 있는 항목을 참조하세요.
Message Batches API는 표준 API 가격 대비 모든 사용량에 대해 50퍼센트 할인을 제공합니다. 이는 입력 토큰, 출력 토큰 및 모든 특수 토큰에 적용됩니다. 가격에 대한 자세한 내용은 가격을 참조하세요.
아니요, 배치가 제출되면 수정할 수 없습니다. 변경이 필요한 경우 현재 배치를 취소하고 새 배치를 제출하세요. 취소가 즉시 적용되지 않을 수 있다는 점에 유의하세요.
Message Batches API에는 처리가 필요한 요청 수에 대한 제한 외에도 HTTP 요청 기반 속도 제한이 있습니다. Message Batches API 속도 제한을 참조하세요. Batches API 사용은 Messages API의 속도 제한에 영향을 주지 않습니다.
결과를 가져오면 각 요청에는 succeeded, errored, canceled, expired 중 어느 것인지를 나타내는 result 필드가 있습니다. errored 결과의 경우 추가 오류 정보가 제공됩니다. 오류 응답 객체는 API 레퍼런스API 참조 링크가 포함된 미리보기 사용 가능 — 카드에 포커스가 들어올 때까지 Tab을 누르고, 돌아가려면 Escape를 누르세요.에서 확인하세요.
Message Batches API는 강력한 개인정보 보호 및 데이터 분리 조치를 갖추도록 설계되었습니다:
- 배치와 그 결과는 생성된 워크스페이스 내에서 격리됩니다. 즉, 동일한 워크스페이스의 API 요청으로만 접근할 수 있습니다.
- 배치 내의 각 요청은 독립적으로 처리되며, 요청 간 데이터 유출이 없습니다.
- 결과는 제한된 기간(29일) 동안만 사용할 수 있으며, Anthropic의 데이터 보존 정책을 따릅니다.
- Console에서 배치 결과 다운로드는 조직 수준 또는 워크스페이스별로 비활성화할 수 있습니다.
예, Message Batches API에서 프롬프트 캐싱을 사용할 수 있습니다. 다만 비동기 배치 요청은 동시에 임의의 순서로 처리될 수 있으므로, 캐시 적중은 최선의 노력 기준으로 제공됩니다.
제공 여부
Claude API
- API
- Messages API
- Managed Agents 지원되지 않음
- 모델
- 모든 모델
Claude Platform on AWS
- API
- Messages API
- Managed Agents 지원되지 않음
- 모델
- 모든 모델
Claude Models on Google Cloud (Anthropic managed)
- API
- Messages API
- Managed Agents 지원되지 않음
- 모델
- 모든 모델
데이터 처리
데이터 처리 개요적용 엔드포인트
/v1/messages/batches
29일 보존. 비동기 저장소 필요. 자세히 알아보기
배치 처리는 배치 생성 후 최대 29일 동안 요청 및 응답 데이터를 저장합니다. 처리 후 언제든지 DELETE /v1/messages/batches/{batch_id}API 참조 링크가 포함된 미리보기 사용 가능 — 카드에 포커스가 들어올 때까지 Tab을 누르고, 돌아가려면 Escape를 누르세요. 엔드포인트를 사용하여 메시지 배치를 삭제할 수 있습니다. 진행 중인 배치를 삭제하려면 먼저 취소하세요. 비동기 처리를 위해서는 배치 완료 및 결과 조회 시까지 입력과 출력 모두를 서버 측에 저장해야 합니다.
다음 단계
이 페이지가 도움이 되었나요?