프롬프트 캐싱·배치·effort로 API 비용 줄이기

한눈에 요약

비용은 **호출 한 번의 단가가 아니라 “작업 하나를 끝내는 데 든 총액”**으로 봐야 해요. 같은 일을 여러 번 시키거나 실패해서 재시도하면 싼 모델도 비싸져요.
공식 순서는 캐싱과 입력 줄이기 -> 프롬프트 점검 -> effort 조절 -> 모델 비교 -> 출력·예산 상한 순이에요. 품질을 건드리지 않는 것부터 하세요.
프롬프트 캐싱: 똑같이 반복되는 앞부분을 캐시하면 읽기 단가가 기본 입력가의 10%예요. Opus 5.5와 Sonnet 5.5는 5%, Fable 5.1은 2.5%예요.
Message Batches API: 급하지 않은 일은 입력·출력 모두 50% 할인이에요. 대신 결과가 최대 24시간 걸릴 수 있어요.
아래 예시 계산(요청 1,000건)에서 Opus 5.5는 기본 $88.00, 캐시 $12.10, 배치 $44.00, 캐시+배치 이론상 $6.05예요.
호출마다 usage를 로그로 남기고, 실제 호출 전에는 count_tokens로 입력 크기를 재세요.

이 튜토리얼로 할 수 있게 되는 것

cache_control로 반복되는 프롬프트를 캐시하고, usage로 캐시가 실제로 동작하는지 확인할 수 있어요.
급하지 않은 대량 작업을 Message Batches API로 돌려 비용을 절반으로 줄일 수 있어요.
effort와 모델을 바꿔 보며 “작업당 비용”을 비교하는 방법을 알 수 있어요.
내 워크로드의 비용을 계산기와 사용량 로그로 미리 추정하고 추적할 수 있어요.

먼저 알아둘 개념

모델별 가격 (100만 토큰당 USD, 2026-10-11 기준)

가격은 미국 달러 기준이고 바뀔 수 있어요. 항상 공식 pricing 페이지로 확인하세요. 모델 ID와 입력/출력 가격은 C16과 같아요.

모델	입력	5분 캐시 쓰기	1시간 캐시 쓰기	캐시 읽기	출력
Fable 5.1 (`claude-fable-5-1`)	$10	$12.50	$20	$0.25	$50
Opus 5.5 (`claude-opus-5-5`)	$4	$5	$8	$0.20	$20
Sonnet 5.5 (`claude-sonnet-5-5`)	$2	$2.50	$4	$0.10	$10
Haiku 5.5 (`claude-haiku-5-5`), 프롬프트 10만 토큰 이하	$0.10	$0.125	$0.20	$0.01	$0.50
Haiku 5.5, 프롬프트 10만 토큰 초과	$0.50	$0.625	$1	$0.05	$2.50

Haiku 5.5는 요청 하나의 프롬프트가 10만 토큰을 넘으면 그 요청에 더 비싼 가격이 적용돼요. 캐시 읽기·쓰기 토큰도 프롬프트 길이에 포함돼요.
배치는 위 가격의 50%예요. 다른 수정자와 곱해져요(공식 문서: 배치 할인은 다른 가격 수정자와 stack).
미국에만 추론을 고정(inference_geo)하면 모든 가격에 1.1배가 붙어요(공식 pricing 페이지).

비용을 줄이는 순서

공식 비용 가이드는 품질을 건드리지 않는 “공짜 수단”을 먼저, 품질과 맞바꾸는 “트레이드오프”를 나중에 하라고 해요.

순서	수단	성격
1	프롬프트 캐싱, 입력 토큰 줄이기	품질 그대로
2	오래된 프롬프트 점검	품질 그대로
3	급하지 않은 일은 배치	품질 그대로, 대신 느려요
4	effort 조절	품질과 맞바꿔요
5	모델 비교(작업당 비용)	품질과 맞바꿔요
6	`max_tokens`와 예산 상한	안전장치
7	여러 모델 조합	마지막에, 측정 후에만

공식 가이드는 내부 측정으로 캐싱이 에이전트 루프 비용을 2.7~5.3배 줄인 사례를 소개해요. 이 수치는 방향을 보여 주는 참고값이고 내 워크로드에서 같다는 보장은 아니에요.

단계별 따라하기

0/7 완료

내 요청에서 반복되는 앞부분(시스템 프롬프트, 도구, 문서)을 찾았어요
cache_control을 달고 usage에서 cache_read_input_tokens가 찍히는 것을 확인했어요
급하지 않은 작업을 배치로 보내 결과를 custom_id로 받았어요
effort를 바꿔 가며 작업당 비용을 비교했어요
count_tokens로 입력 크기를 미리 쟀어요
usage를 CSV로 남기는 로거를 붙였어요
가격 계산기로 우리 워크로드를 추정했어요

프롬프트 캐싱 적용하기

캐시는 앞부분이 한 바이트도 다르지 않을 때만 적용돼요. 요청은 tools -> system -> messages 순서로 이어 붙여서 비교하니, 안 바뀌는 것(규정집, 도구 정의)을 앞에 두고 바뀌는 것(질문, 날짜)을 뒤에 두세요.

company_manual.txt에 사내 규정집 같은 긴 텍스트를 저장하고 cache_demo.py를 만들어요. 캐시되려면 접두사가 최소 512토큰(Opus 5.5, Sonnet 5.5, Haiku 5.5 기준)이어야 해요. 그보다 짧으면 오류 없이 조용히 캐시가 안 돼요.

import anthropic

client = anthropic.Anthropic()

# 매 요청 똑같은 긴 매뉴얼(512토큰 이상이어야 캐시돼요). 날짜·요청 ID 같은 값은 넣지 마세요.
MANUAL = open("company_manual.txt", encoding="utf-8").read()


def ask(question: str):
    response = client.messages.create(
        model="claude-sonnet-5-5",
        max_tokens=1024,
        system=[
            {"type": "text", "text": "사내 규정 도우미야. 매뉴얼 근거로만 한국어로 답해."},
            {
                "type": "text",
                "text": MANUAL,
                # 여기까지(도구 -> system -> 이 블록)를 캐시해요. 기본 수명은 5분이에요.
                "cache_control": {"type": "ephemeral"},
            },
        ],
        messages=[{"role": "user", "content": question}],  # 바뀌는 부분은 항상 뒤쪽에
        output_config={"effort": "low"},
    )
    u = response.usage
    print(
        f"새 입력 {u.input_tokens} | 캐시 쓰기 {u.cache_creation_input_tokens}"
        f" | 캐시 읽기 {u.cache_read_input_tokens} | 출력 {u.output_tokens}"
    )
    return response


ask("연차는 며칠이에요?")  # 첫 호출: 캐시 쓰기가 찍혀야 해요
ask("경조사 휴가는요?")  # 두 번째: 캐시 읽기가 찍혀야 해요 (0이면 캐시 무효화 원인을 찾으세요)

첫 호출은 캐시 쓰기가, 두 번째 호출은 캐시 읽기가 찍혀야 해요. 쓰기는 기본 입력가의 1.25배, 읽기는 Opus 5.5·Sonnet 5.5에서 0.05배예요. 5분 캐시는 재사용이 한 번만 있어도 쓰기 프리미엄을 회수해요.

항목	값
기본 수명(TTL)	5분. 히트할 때마다 갱신돼요(추가 비용 없음)
1시간 수명	`"cache_control": {"type": "ephemeral", "ttl": "1h"}`. 쓰기가 2배
명시 브레이크포인트	요청당 최대 4개
한 브레이크포인트의 룩백	최대 20블록
총 입력 토큰	`cache_read_input_tokens + cache_creation_input_tokens + input_tokens`

요청 간격이 5분보다 길면 매번 캐시를 새로 써서 오히려 손해일 수 있어요. 그럴 때만 1시간 수명을 검토하세요. 1시간 캐시는 쓰기가 2배라 재사용이 여러 번 있어야 이득이에요.

배치로 반값에 처리하기

사용자가 기다리지 않는 일(분류, 요약, 평가, 야간 리포트)은 Message Batches API로 보내요. 입력과 출력 모두 50% 할인이에요. batch_demo.py를 만들어요.

import time

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

client = anthropic.Anthropic()

tickets = {
    "t-001": "배송이 너무 늦어요. 환불해 주세요.",
    "t-002": "사용법이 궁금해요. 감사합니다!",
    "t-003": "결제가 두 번 됐어요.",
}

batch = client.messages.batches.create(
    requests=[
        Request(
            custom_id=ticket_id,  # 결과는 순서가 섞여 오니 반드시 custom_id로 짝지어요
            params=MessageCreateParamsNonStreaming(
                model="claude-haiku-5-5",
                max_tokens=1024,  # Haiku 5.5는 기본으로 생각하고, 생각도 max_tokens에 포함돼요
                output_config={"effort": "low"},
                messages=[
                    {
                        "role": "user",
                        "content": f"문의를 '환불', '사용법', '결제오류', '기타' 중 하나로만 분류해: {text}",
                    }
                ],
            ),
        )
        for ticket_id, text in tickets.items()
    ]
)
print("배치 ID:", batch.id)

# 보통 1시간 안에 끝나지만 최대 24시간이 걸릴 수 있어요. 실제로는 스케줄러로 나눠 확인하세요.
while True:
    batch = client.messages.batches.retrieve(batch.id)
    if batch.processing_status == "ended":
        break
    time.sleep(60)

for entry in client.messages.batches.results(batch.id):
    if entry.result.type == "succeeded":
        text = next((b.text for b in entry.result.message.content if b.type == "text"), "")
        print(entry.custom_id, "->", text)
    else:
        print(entry.custom_id, "실패:", entry.result.type)

항목	값
배치 한도	요청 100,000개 또는 256MB 중 먼저 닿는 쪽
처리 시간	대부분 1시간 안, 24시간 안에 끝나지 않으면 만료
결과 보관	생성 후 29일
결과 순서	무작위. 반드시 `custom_id`로 매칭
결과 종류	`succeeded`, `errored`, `canceled`, `expired`

배치 안에서도 캐싱을 쓸 수 있지만 요청이 동시에 처리돼서 캐시 히트는 best-effort예요(공식 문서는 30~98% 범위를 언급).
배치는 요청마다 한 번 응답하는 방식이라 도구 루프는 돌릴 수 없어요. 필요한 데이터를 미리 가져와 프롬프트에 넣는 식으로 바꿔야 해요.
배치는 서버가 입력과 출력을 보관해요. 개인정보나 보존 정책(ZDR) 조건은 공식 “API and data retention” 문서를 확인하세요. 처리가 끝난 배치는 삭제할 수 있어요.
Claude Managed Agents 세션에는 배치 모드가 없어요.

effort로 깊이와 비용 조절하기

output_config={"effort": "low"}처럼 effort를 정하면 생각 깊이와 전체 토큰 사용량이 달라져요. 단계는 low, medium, high, xhigh, max예요. 기본값은 모델마다 달라요. Opus 5.5와 Haiku 5.5는 medium, Sonnet 5.5는 high예요. 그래서 명시적으로 정하는 것을 권해요.

공식 비용 가이드의 측정(내부·방향성 수치)은 이래요.
- 연구형 벤치마크에서 low는 정확도 1~~3점을 내주고 비용을 3분의 1~~2분의 1로 줄였고, medium은 기본 정확도에 비용 70~87%였어요.
- 코딩 벤치마크(SWE-bench Pro)에서 high 대비 medium은 약 2.5점 낮고 비용은 약 70%, low는 약 8점 낮고 비용은 약 3분의 1, xhigh는 1.4점 높고 비용은 2.5배였어요.
- 일부 측정에서는 Opus 5.5를 medium으로 쓴 쪽이 Fable 5.1 기본 설정과 비슷한 정확도를 훨씬 낮은 “정답당 비용”으로 냈어요.
내 작업에서도 같다는 보장은 없어요. 채팅·분류·대량 처리는 low로도 충분한 경우가 많고, 코딩·긴 에이전트 작업은 effort에 민감해요. 대표 샘플로 직접 재 보세요.

공식 비용 가이드는 effort를 바꾸면 메시지 캐시가 무효화되니 effort마다 별도 세션에서 시험하라고 해요. 한 대화 안에서 최상위 effort 값을 오르내리는 설계는 피하세요. 다만 공식 effort 문서(2026-10-12 기준)에 따르면 Fable 5.1, Opus 5.5, Sonnet 5.5, Haiku 5.5 등은 메시지별 effort 변경(베타, 베타 헤더 mid-conversation-output-config-2026-07-01)을 지원하고, 이 방식은 프롬프트 캐시를 유지해요.

max_tokens도 함께 보세요. 너무 낮으면 응답이 잘려 재시도 비용이 들고, 에이전트 작업에는 64,000 정도가 권장돼요(공식 비용 가이드). 반대로 짧은 분류에는 256 같은 작은 값이 안전장치가 돼요. Opus 5.5는 thinking을 끌 수 없어서 effort가 유일한 조절 수단이에요.
모델 분담으로 작업당 비용 낮추기

가장 큰 모델이 늘 가장 비싼 결과를 내는 것은 아니에요. 공식 비용 가이드의 측정 사례에서는 Haiku 5.5가 한 과학 추론 벤치마크(GPQA Diamond)에서 Opus 5.5 비용의 약 20분의 1로 85%(Opus 5.5는 91%)를 냈어요. 쉬운 일은 작은 모델이 하고 어려운 일만 큰 모델로 올리면 평균 비용이 크게 내려가요.
- 분류, 추출, 요약 같은 대량 작업은 Haiku 5.5나 Sonnet 5.5로 시작하세요.
- 어려운 판단만 Opus 5.5로 올리고, 필요하면 Fable 5.1은 가장 어려운 일에만 쓰세요.
- 가격이 아니라 작업당 비용으로 비교하세요. 싼 모델이 더 자주 실패해 재시도하면 오히려 비싸요. 공식 가이드는 “가장 어려운 10%의 작업 비용”도 따로 보라고 해요.
- 모델을 바꿀 때는 C16의 모델별 요청 제한을 먼저 확인하세요(예: Haiku 5.5는 budget_tokens와 샘플링 파라미터가 400 오류).
- 모델이 달라지면 캐시도 따로예요. 캐시는 모델별로 분리돼요.
Claude Code에서 모델을 나누는 방법은 C15. 모델 분담 전략에서 다뤘어요.
토큰 미리 세기

보내기 전에 count_tokens로 입력이 몇 토큰인지 재요. 이 엔드포인트는 무료이고, 메시지 생성과 별개로 분당 요청 제한(Start 5,000, Build 10,000, Scale 20,000)이 있어요. 결과는 추정치라서 실제와 조금 다를 수 있어요. count_demo.py를 만들어요.
```
import anthropic

client = anthropic.Anthropic()

system_prompt = open("company_manual.txt", encoding="utf-8").read()
question = [{"role": "user", "content": "연차는 며칠이에요?"}]

# 토큰 세기는 무료지만 분당 요청 제한이 있어요. 모델마다 토큰 수가 다르니 쓸 모델로 세세요.
for model in ["claude-opus-5-5", "claude-sonnet-5-5", "claude-haiku-5-5"]:
    count = client.messages.count_tokens(model=model, system=system_prompt, messages=question)
    print(model, count.input_tokens)
```
- 모델마다 토큰 수가 달라요. Opus 4.7 이후 모델의 토크나이저는 이전 모델보다 같은 글에 약 30% 더 많은 토큰을 써요. 예전 모델에서 잰 숫자로 비용을 추정하지 말고, 쓸 모델 ID로 다시 세세요.
- 웹 검색 같은 서버 도구, MCP 커넥터, URL이나 파일 ID로 넘기는 이미지·문서는 세기에서 오류가 나요. 그런 요청은 응답의 usage로 확인하세요.
- count_tokens에 cache_control을 넣어도 캐시는 쓰이지 않아요. 캐시 효과는 실제 호출의 usage로만 보여요.
- 입력이 너무 커서 모델 컨텍스트 창을 넘을지 확인할 때도 써요.
사용량 로그와 모니터링

호출마다 usage를 남기면 어떤 기능이 돈을 쓰는지 보여요. usage_log.py를 만들어요. 5분 캐시 쓰기 기준으로 계산하니 1시간 캐시를 쓴다면 usage.cache_creation의 ephemeral_1h_input_tokens를 따로 계산에 넣으세요.
```
import csv
import time

PRICES = {  # input, cache_write_5m, cache_read, output  (USD / MTok)
    "claude-opus-5-5": (4.00, 5.00, 0.20, 20.00),
    "claude-sonnet-5-5": (2.00, 2.50, 0.10, 10.00),
}


def log_usage(response, model: str, task: str, path: str = "usage.csv") -> float:
    """호출 한 번의 비용을 계산해 CSV에 한 줄 남겨요. 반환값은 USD."""
    u = response.usage
    p_in, p_write, p_read, p_out = PRICES[model]
    usd = (
        u.input_tokens * p_in
        + (u.cache_creation_input_tokens or 0) * p_write
        + (u.cache_read_input_tokens or 0) * p_read
        + u.output_tokens * p_out
    ) / 1_000_000
    with open(path, "a", newline="", encoding="utf-8") as f:
        csv.writer(f).writerow(
            [time.strftime("%Y-%m-%d %H:%M:%S"), model, task, u.input_tokens,
             u.cache_creation_input_tokens or 0, u.cache_read_input_tokens or 0,
             u.output_tokens, f"{usd:.6f}"]
        )
    return usd
```
사용하는 곳에서는 응답을 받은 직후에 log_usage(response, model, task)를 호출하면 돼요. 작업 이름(task)을 함께 남기면 “작업당 비용”으로 모아 볼 수 있어요.

조직 전체의 사용량은 Console의 Usage와 Cost 화면이나 Usage and Cost Admin API에서 볼 수 있어요. 이 API는 usage_report/messages와 cost_report 엔드포인트가 있고 Admin API 키(sk-ant-admin...)가 필요해요. Admin API 키는 개인 계정으로는 만들 수 없는 조직용 키라서 조건을 공식 문서에서 확인하세요. Amazon Bedrock, Vertex AI, Foundry로 호출한 트래픽은 이 보고서에 나오지 않을 수 있어요.

이 단계에서 보게 될 화면
Console의 Usage와 Cost 화면
Anthropic 문서에서 보기 ↗
실제 화면은 서비스 업데이트에 따라 다를 수 있어요

조직 지출 상한은 사용 티어에 따라 정해져요(Start $500, Build $1,000, Scale $200,000, 월 기준, 2026-10-12 기준). 공식 rate limits 문서에 따르면 Console의 설정(Settings) > 결제(Billing)에서 Spend limits 섹션의 Adjust limit(없으면 Set limit)을 눌러 티어 상한 이하로 내 지출 한도를 정할 수 있어요. 내가 정한 한도에 닿으면 요청이 HTTP 400(invalid_request_error)으로 거절돼요. 지출 알림 설정 절차는 공식 rate limits 문서에 없어요(2026-10-13 확인). 티어 설명은 C16에서도 소개했어요.
가격 비교 계산하기

바꾸기 전에 숫자로 비교해 보세요. cost_calc.py는 요청 수, 고정 접두사, 새 입력, 출력 토큰으로 모델별·방식별 비용을 계산해요. 캐시는 첫 요청이 쓰기고 이후는 모두 읽기(계속 살아 있음)라고 가정해요.
```
"""가격 비교 계산기. 가격은 100만 토큰(MTok)당 USD, 2026-10-11 공식 pricing 페이지 기준."""

PRICES = {  # input, cache_write_5m, cache_read, output
    "claude-opus-5-5": (4.00, 5.00, 0.20, 20.00),
    "claude-sonnet-5-5": (2.00, 2.50, 0.10, 10.00),
    "claude-haiku-5-5": (0.10, 0.125, 0.01, 0.50),  # 프롬프트 100,000토큰 이하 기준
}


def cost(model, requests, prefix_tokens, new_input_tokens, output_tokens,
         cached=False, batch=False):
    p_in, p_write, p_read, p_out = PRICES[model]
    if cached:
        # 첫 요청은 캐시 쓰기, 나머지는 캐시 읽기 (캐시가 계속 살아 있다고 가정)
        prefix = prefix_tokens * p_write + prefix_tokens * p_read * (requests - 1)
        total_in = prefix + new_input_tokens * requests * p_in
    else:
        total_in = (prefix_tokens + new_input_tokens) * requests * p_in
    total_out = output_tokens * requests * p_out
    total = (total_in + total_out) / 1_000_000
    return total * 0.5 if batch else total


if __name__ == "__main__":
    args = dict(requests=1000, prefix_tokens=20_000, new_input_tokens=500, output_tokens=300)
    for model in PRICES:
        base = cost(model, **args)
        cached = cost(model, cached=True, **args)
        batch = cost(model, batch=True, **args)
        both = cost(model, cached=True, batch=True, **args)
        print(f"{model:20s} 기본 ${base:7.2f} | 캐시 ${cached:6.2f} | 배치 ${batch:6.2f} | 둘 다 ${both:6.2f}")
```
가정: 하루 요청 1,000건, 고정 접두사(규정집) 20,000토큰, 새 입력 500토큰, 출력 300토큰이에요. 실행 결과는 이래요.

모델 기본 캐시 배치 캐시+배치

Opus 5.5 $88.00 $12.10 $44.00 $6.05

Sonnet 5.5 $44.00 $6.05 $22.00 $3.02

Haiku 5.5 $2.20 $0.40 $1.10 $0.20

읽는 법은 이래요.
- 같은 Opus 5.5에서 캐시만으로 약 86% 절감이에요(88.00 -> 12.10). 접두사가 클수록 효과가 커요.
- 모델을 Opus 5.5에서 Sonnet 5.5로 바꾸면 기본 요금이 절반이고, Haiku 5.5는 40분의 1 수준이에요. 단 품질이 그 작업에 충분한지는 따로 재야 해요.
- 캐시+배치는 이론상 최저치예요. 배치에서는 캐시 히트가 best-effort이고, 실제는 중간쯤일 가능성이 커요.
- 이 계산은 생각(thinking) 토큰을 넣지 않았어요. 생각은 출력으로 과금되므로 실제 출력 비용은 더 클 수 있어요. 실제 usage로 보정하세요.
- 요청 간격이 5분을 넘어 캐시가 자주 만료되면 쓰기 비용이 반복돼서 캐시 효과가 줄어요.
이 프롬프트를 복사해서 붙여넣으세요
내 서비스의 하루 요청 수는 ( ), 고정 프롬프트는 약 ( )토큰, 질문은 평균 ( )토큰, 답변은 평균 ( )토큰이야. cost_calc.py를 이 값으로 바꿔 돌려서, Sonnet 5.5 기준으로 캐시와 배치를 각각 적용했을 때 하루 비용을 표로 정리해 줘. 사용자가 기다리는 요청과 아닌 요청을 구분해서 어디에 배치를 쓸지도 제안해 줘.

모델	기본	캐시	배치	캐시+배치
Opus 5.5	$88.00	$12.10	$44.00	$6.05
Sonnet 5.5	$44.00	$6.05	$22.00	$3.02
Haiku 5.5	$2.20	$0.40	$1.10	$0.20

빠른 참조표

수단별 비교

수단	절감	대가	쓰기 좋은 때
프롬프트 캐싱	반복 접두사 입력의 90~95%	쓰기 프리미엄 1.25배, 접두사 고정 필요	긴 시스템 프롬프트, 도구, 문서를 여러 번 쓸 때
Message Batches	입력·출력 50%	최대 24시간 지연, 도구 루프 불가	분류, 평가, 야간 처리
effort 낮추기	작업에 따라 다름	어려운 작업은 품질 하락	채팅, 분류, 단순 조회
작은 모델	가격 차이만큼	품질 위험	대량·정형 작업, 서브에이전트
`max_tokens` 제한	의도치 않은 긴 출력 방지	너무 낮으면 잘림	짧은 답이 정해진 작업
입력 줄이기	입력 토큰만큼	정보 누락 위험	도구 결과·긴 문서 정리

캐시 규칙 요약

항목	값
최소 길이	Opus 5.5, Sonnet 5.5, Haiku 5.5는 512토큰 (공식 caching 페이지)
쓰기 비용	5분 1.25배, 1시간 2배
읽기 비용	기본 입력의 0.1배. Opus 5.5·Sonnet 5.5 0.05배, Fable 5.1 0.025배
수명	5분(기본) 또는 1시간. 히트 시 갱신
순서	tools -> system -> messages
같은 요청에서 TTL을 섞으면	1시간 항목이 5분 항목보다 앞에 와야 해요

자주 막히는 지점

`cache_read_input_tokens`가 계속 0이에요

원인: 접두사가 512토큰보다 짧거나, 요청마다 앞부분이 달라져요(시각, ID, 도구 순서 변경). 요청 간격이 TTL보다 길거나 워크스페이스가 달라도 그래요.
해결: 접두사 길이를 count_tokens로 확인하고, 바뀌는 값을 cache_control 뒤쪽으로 옮기세요. 두 번째 요청이 첫 요청 직후 5분 안에 가는지 확인하세요.

배치 결과가 보낸 순서와 달라요

원인: 배치는 요청을 비동기로, 순서 없이 처리해요.
해결: 항상 custom_id로 짝지으세요.

배치 요청 일부가 `expired`예요

원인: 24시간 안에 처리되지 않았어요. 수요가 많거나 요청이 많으면 늘어날 수 있다고 공식 문서가 설명해요.
해결: 만료된 요청만 모아 다시 제출하세요. 공식 문서(2026-10-12 기준)는 expired 요청에는 비용이 청구되지 않는다고 설명해요.

Haiku 5.5로 바꿨더니 400 오류나 응답이 비어요

원인: Haiku 5.5는 budget_tokens, 샘플링 파라미터, prefill이 400 오류예요. 기본으로 생각해서 max_tokens가 작으면 생각만 하다 끝날 수 있어요.
해결: C16의 모델별 요청 제한을 보고 파라미터를 빼고, max_tokens를 넉넉히 두거나 effort를 low로 낮추세요.

추정한 비용과 청구서가 달라요

원인: 생각 토큰, 도구 사용 시스템 프롬프트(약 286토큰), 도구 정의와 결과, 캐시 쓰기 프리미엄이 계산에서 빠졌을 수 있어요. count_tokens도 추정치예요.
해결: usage 로그로 실제 토큰 4종(입력, 캐시 쓰기, 캐시 읽기, 출력)을 모아 단가를 곱해 보정하세요.

실전 팁

“작업 하나”를 단위로 비용을 재세요. 한 번의 호출이 아니라 사용자 요청 하나를 끝내는 모든 호출의 합을 로그로 남기세요.
측정이 먼저예요. 어디서 돈이 나가는지 로그로 보기 전에는 최적화하지 마세요. 공식 가이드도 입력 비용 대부분이 반복 접두사라면 캐싱이 가장 큰 수단이라고 해요.
사용자가 기다리는 요청과 아닌 요청을 나누세요. 같은 서비스라도 실시간 응답은 일반 호출, 야간 리포트는 배치로 보내요.
큰 변경은 한 번에 하나씩. 캐싱, effort, 모델을 한꺼번에 바꾸면 무엇이 효과였는지 알 수 없어요. 대표 샘플로 품질을 같이 재세요(품질 측정은 08편 평가를 보세요).
상한을 두세요. 에이전트 루프나 반복 호출은 반복 횟수, max_tokens, 일일 호출 수 상한을 코드에 넣으세요. 배치와 에이전트는 한 번 실행에 큰 비용이 나갈 수 있어요.
이 사이트 자체도 기획은 큰 모델, 구현은 작은 모델로 나눠서 만들었어요. 그 사례는 C15에 있어요.

다음에 볼 튜토리얼

1. 도구 사용으로 업무 봇 만들기 — 도구 정의가 긴 봇에 캐싱을 적용해 보세요
C15. 모델 분담 전략 — Claude Code에서의 모델 분담
C16. Claude API 시작하기 — 가격표와 모델별 요청 제한
9. 사내 문서 Q&A 만들기: Files API와 인용(citations) — 긴 문서에 프롬프트 캐싱을 적용하는 실례

출처

마지막 확인일: 2026년 10월 13일

Pricing platform.claude.com
Prompt caching platform.claude.com
Batch processing platform.claude.com
Token counting platform.claude.com
Optimizing for cost and intelligence platform.claude.com
Effort platform.claude.com
Usage and Cost Admin API platform.claude.com

가격·한도·메뉴 이름은 자주 바뀌어요. 중요한 결정 전에는 위 공식 페이지에서 최신 내용을 다시 확인하세요.