클로드 배치 API로 대량 작업 비용 절반으로 줄이기

블로그 글 60개의 메타 설명을 다듬거나, 고객 리뷰 5,000건을 분류하거나, 상품 설명 1,000개를 번역해야 할 때. 이런 작업은 지금 당장 결과가 필요한 게 아닙니다. 오늘 밤에 돌려 두고 내일 아침에 받아도 충분하죠. 이런 대량 작업에 쓰는 것이 Message Batches API입니다.

배치 API의 핵심: 기다리는 대신 절반 가격

작동 방식

1. 요청 여러 건을 묶어 배치로 제출 (각 요청에 custom_id 부여)
2. Anthropic이 비동기로 처리
3. 상태를 조회해 처리 완료(ended) 확인
4. 결과를 받아 custom_id로 매칭

파이썬 예제: 리뷰 감정 분류

1. 배치 제출

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

client = anthropic.Anthropic()

reviews = {
    "r-0001": "배송 빠르고 포장도 꼼꼼했어요.",
    "r-0002": "사이즈가 안 맞아서 교환했는데 처리가 느렸어요.",
    # ... 수천 건
}

requests = [
    Request(
        custom_id=rid,
        params=MessageCreateParamsNonStreaming(
            model="claude-haiku-4-5",
            max_tokens=20,
            messages=[{
                "role": "user",
                "content": f"다음 리뷰의 감정을 긍정/부정/중립 중 하나로만 답해.\n\n{text}",
            }],
        ),
    )
    for rid, text in reviews.items()
]

batch = client.messages.batches.create(requests=requests)
print(batch.id, batch.processing_status)

2. 상태 조회

batch = client.messages.batches.retrieve(batch.id)
print(batch.processing_status)  # in_progress → ended

처리 중에는 몇 분~몇 시간 간격으로 조회하면 됩니다. 반복문으로 계속 조회하는 대신 일정 시간 뒤에 다시 확인하는 방식을 권합니다.

3. 결과 수집

results = {}
for item in client.messages.batches.results(batch.id):
    if item.result.type == "succeeded":
        text = "".join(b.text for b in item.result.message.content if b.type == "text")
        results[item.custom_id] = text.strip()
    else:
        results[item.custom_id] = f"ERROR: {item.result.type}"

결과는 요청 순서대로 오지 않습니다. 반드시 custom_id로 매칭하세요. 실패(errored)나 만료(expired)된 건은 따로 모아 다시 제출합니다.

비용 계산 예시

리뷰 10,000건, 건당 입력 150토큰·출력 5토큰, Haiku 4.5(입력 $1, 출력 $5 / 1M) 기준:

일반 API: 입력 1.5M × $1 + 출력 0.05M × $5 = $1.50 + $0.25 = $1.75
배치 API: 위 금액의 50% ≈ $0.88

건수가 늘거나 큰 모델을 쓸수록 절감액이 커집니다. 같은 지시문이 반복된다면 프롬프트 캐싱과 함께 쓸 수 있습니다.

배치에 맞는 작업, 맞지 않는 작업

실무 팁

1. 먼저 소량으로 테스트: 20~50건을 일반 API로 돌려 프롬프트와 출력 형식을 확정한 뒤 배치로 보냅니다. 배치로 1만 건을 보냈는데 형식이 틀리면 전부 다시 해야 합니다.
2. custom_id를 의미 있게: 원본 데이터의 ID를 그대로 쓰면 결과를 합치기 쉽습니다.
3. 출력 형식 고정: 결과를 코드로 처리하므로 "한 단어로만", "JSON으로만"처럼 형식을 엄격히 지정합니다.
4. 실패 건 재처리 로직: 일부 실패는 정상입니다. 실패 건만 모아 다시 제출하는 코드를 미리 만들어 둡니다.

💬 당장 필요한 결과인가요?

배치 API를 처음 썼을 때는 "하루까지 걸릴 수 있다"는 안내 때문에 망설였는데, 실제로 제가 보낸 수백 건 규모의 작업은 대부분 훨씬 빨리 끝났습니다. 그래도 일정에 여유를 두고 쓰는 것이 원칙입니다. 대량 작업을 일반 API로 돌리고 있다면, 결과가 당장 필요한지 한 번 생각해 보세요. 기다릴 수 있다면 비용은 절반이 됩니다.

이 글의 요점

1. 배치 API는 비동기 처리 대신 표준 요금의 50%로 대량 작업을 처리합니다.
2. 제출 → 상태 조회 → 결과 수집 순서로 쓰고, 결과는 custom_id로 매칭합니다.
3. 소량 테스트로 형식을 확정하고, 실패 건 재처리 로직을 준비하세요.

출처·참고 링크

• Message Batches API (Anthropic 공식 문서)
• 함께 읽기: 클로드 API 요금 계산법