Claude Message Batches API로 50% 할인을 받기 전 24시간 처리 조건과 제한을 확인해보세요

Message Batches API의 할인 요율과 적용 조건은 어떻게 되나요?

모델 가격 정책 문서에 따르면 Message Batches API는 Claude 3.5 Sonnet, Claude 3.5 Haiku, Claude 3 Opus를 포함한 주요 모델에 동일하게 50% 단가 할인을 제공해요. 표준 동기식 API인 /v1/messages 엔드포인트와 비교하면 기본 입력과 출력 요율이 모두 절반으로 낮아져요.

출처는 Anthropic 공식 가격 정책 문서이고 확인일은 2026-10-26이에요.

배치 안에서도 프롬프트 캐싱을 함께 지정할 수 있어요. 1,024 토큰 이상의 고정 시스템 지침이 여러 배치 요청에 공통으로 들어간다면, 캐시 쓰기는 기본의 62.5%, 캐시 읽기는 기본의 5% 수준으로 떨어져요. 대규모 데이터셋을 분석할 때 고정 지침을 재사용하면 비용 절감 폭이 더 커져요.

24시간 처리 창과 비동기 수신 구조는 어떻게 동작하나요?

배치 처리 공식 문서에서 규정하는 기본 처리 기한(Turnaround Time)은 최대 24시간이에요. 서버 부하에 따라 몇 분 만에 끝나기도 하지만, 공식 서비스 수준 계약은 24시간 이내 처리를 기준으로 삼아요.

배치를 요청할 때는 POST /v1/messages/batches 엔드포인트로 JSON 요청을 전달해요. 배치 하나에는 최대 10,000개의 개별 메시지 요청을 담을 수 있고, 전체 페이로드 크기는 32MB로 제한돼요. 요청이 성공적으로 접수되면 즉시 고유한 배치 식별자(id)와 함께 in_progress 상태가 반환돼요.

배치 작업이 끝나면 상태가 ended로 바뀌고, 결과 파일 주소인 results_url이 제공돼요. 이 주소에서 JSON Lines(JSONL) 형식의 결과 파일을 내려받아 파싱하면 돼요. 결과 파일은 배치 완료 시점부터 29일 동안 보관되니 만료 전에 내려받아 자체 스토리지에 보관해야 해요.

개별 요청의 오류와 취소는 어떻게 처리하나요?

배치 안에 포함된 각 요청은 custom_id라는 고유 문자열로 식별해요. 개발자가 부여하는 이 식별자는 최대 64자까지 지원하며, 결과 파일에서 어떤 요청의 응답인지 추적할 때 사용해요.

배치 내부의 개별 요청은 서로 독립적으로 실행돼요. 만약 1,000건 중 3건의 요청에서 토큰 한도 초과나 잘못된 매개변수로 오류가 생기더라도 나머지 997건의 처리는 중단되지 않아요. 결과 파일의 각 줄에는 custom_id와 함께 succeeded, errored, canceled, expired 중 하나의 실행 결과 상태가 기록돼요.

진행 중인 배치를 취소해야 할 때는 POST /v1/messages/batches/{batch_id}/cancel 엔드포인트를 호출해요. 취소 요청을 보내면 상태가 canceling으로 바뀌고, 아직 처리되지 않은 요청들은 canceled 처리되어 과금되지 않아요. 이미 처리가 끝난 요청에 대해서만 정상 요금이 청구돼요.

프로덕션 환경에서 어떤 워크로드가 적합한가요?

배치 API는 응답 지연 시간(Latency)보다 처리 비용(Cost) 절감이 우선인 백엔드 파이프라인에 가장 알맞아요. 기존 실시간 호출 코드를 배치로 옮기기 전에 아래 조건을 점검해 보세요.

1. 고객 응답이 즉시 필요 없는 비동기 데이터 가공: 일일 단위로 누적된 고객 상담 기록 분류, 지원 티켓 태깅, 야간 영수증 광학 인식 결과 검증에 유리해요.
2. 대규모 모델 평가와 벤치마크 테스트: 새로운 프롬프트나 프롬프트 체인을 수만 건의 테스트 케이스에 돌려 성능을 측정할 때 비용을 절반으로 줄일 수 있어요.
3. 정기 오프라인 임베딩 및 지식 기반 요약: 매일 새벽 최신 사내 위키나 기술 문서를 읽고 요약본을 만들어 두는 작업에 적합해요.
4. 사용자 대면 인터페이스 제외: 사용자가 웹 화면에서 질문을 입력하고 즉시 답변을 기다리는 챗봇이나 실시간 코드 자동완성에는 결코 쓰면 안 돼요.

이 기준은 서비스 아키텍처 결정을 돕기 위한 기술적 제안이에요. 사용자 대기 시간이 걸리는 경로와 비동기 백그라운드 큐를 명확히 분리해 설계하세요.

적용 전에 코드와 인프라에서 무엇부터 점검하나요?

Python SDK 저장소의 배치 클라이언트를 보면 기존 동기식 호출과 코드 패턴이 크게 달라요. 단순한 함수 호출 대신 배치 상태를 주기적으로 확인하는 폴링(Polling) 루프나 비동기 작업 큐가 필요해요.

먼저 데이터베이스에 배치 상태를 저장할 테이블을 마련하세요. 배치 id, 생성 시각, 처리 상태, 전송한 custom_id 목록과 원본 데이터 매핑 정보를 보관해야 결과 수신 후 원래 레코드에 안전하게 연결할 수 있어요.

둘째로 배치 전용 속도 제한(Rate Limits)을 확인하세요. Anthropic은 계정 등급(Tier)마다 동기식 요청과 별도로 대기열에 담을 수 있는 최대 배치 토큰 수(Enqueued Tokens)를 정해 두고 있어요. 일괄 전송량이 허용 한도를 넘으면 rate_limit_error가 발생하므로 한 번에 보낼 배치 크기를 적절히 분할해야 해요.

오늘은 비동기로 처리 가능한 백엔드 작업 목록을 정리하고, 소규모 데이터로 결과 파싱 로직을 먼저 시험해 보세요. 공식 자료 확인일은 2026-10-26이에요.