Messages API 기초

Claude API 코스의 첫 글입니다. 2주차 교재에서 "API는 AI 회사의 모델을 내 프로그램에 연결하는 창구"라고 정의했습니다. 이 글은 그 창구의 실제 모양을 공식 문서 값만으로 적었습니다. 읽고 나면 BizPlan CRM의 사업계획서 생성기처럼 Claude를 서버 코드에서 직접 부르는 첫 요청을 쓸 수 있습니다. 다음 글은 프롬프트 캐싱입니다.

핵심 요약

• 엔드포인트는 POST https://api.anthropic.com/v1/messages, 헤더는 x-api-key, anthropic-version, content-type 세 개입니다.
• 필수 필드는 model, max_tokens, messages 세 개이고, 시스템 프롬프트는 별도 system 파라미터입니다.
• 현재 모델 ID는 claude-fable-5-1, claude-opus-5, claude-sonnet-5, claude-haiku-4-5-20251001이며, 이전 세대 claude-fable-5는 레거시로 여전히 호출할 수 있습니다.
• 도구 호출은 stop_reason: "tool_use"를 받으면 내가 실행하고 tool_result로 돌려주는 왕복 구조입니다.

가장 단순한 요청

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "정책자금 컨설팅 보고서 목차를 5개 항목으로 제안해 줘"}]
  }'

응답은 id, type("message"), role("assistant"), content(블록 배열), model, stop_reason, usage를 담습니다. usage의 input_tokens, output_tokens, cache_creation_input_tokens, cache_read_input_tokens 네 값이 비용 계산의 출발점입니다.

모델은 공식 모델 페이지 기준 네 가지입니다. Fable 5.1(claude-fable-5-1, 입력 100만 토큰당 10달러, 출력 50달러. 이전 세대 Fable 5 claude-fable-5는 레거시로 유지), Opus 5(claude-opus-5, 5달러와 25달러), Sonnet 5(claude-sonnet-5, 2달러와 10달러), Haiku 4.5(claude-haiku-4-5-20251001, 1달러와 5달러). 컨텍스트 창은 Haiku 4.5가 20만 토큰, 나머지는 100만 토큰입니다.

대화 유지

API는 이전 대화를 기억하지 않습니다. 대화를 이어 가려면 지금까지의 user와 assistant 메시지를 messages 배열에 순서대로 다시 보냅니다.

{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "messages": [
    {"role": "user", "content": "보고서 목차를 제안해 줘"},
    {"role": "assistant", "content": "1. 기업 개요 2. 자금 목적 ..."},
    {"role": "user", "content": "2번 항목을 제조업 기준으로 더 구체화해 줘"}
  ]
}

매 턴마다 전체 이력이 입력 토큰으로 다시 과금됩니다. 대화가 길어질수록 다음 글의 캐싱이 중요해지는 이유입니다.

시스템 프롬프트

역할, 말투, 금지 사항은 messages 안이 아니라 최상위 system 파라미터에 넣습니다. 문자열 하나 또는 텍스트 블록 배열이 가능합니다.

{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "system": "너는 정책자금 컨설턴트의 보조다. 모든 문서는 존댓말로 쓴다. 고객 실명은 홍OO 형태로만 쓴다. 확실하지 않은 수치는 지어내지 않는다.",
  "messages": [{"role": "user", "content": "상담 메모를 보고서로 정리해 줘: ..."}]
}

2주차 CLAUDE.md 세 줄과 같은 내용입니다. Claude Code에서 지침 파일이 하던 역할을 API에서는 system이 맡습니다.

스트리밍

"stream": true를 넣으면 응답이 서버 전송 이벤트(SSE)로 조금씩 옵니다. 순서는 message_start, 블록마다 content_block_start, 하나 이상의 content_block_delta, content_block_stop, 그리고 message_delta, 마지막 message_stop이며 중간에 ping이 섞일 수 있습니다. 텍스트는 content_block_delta의 text_delta에 담겨 오고, message_delta의 usage는 누적값입니다. 10분 이상 걸리는 긴 요청은 공식 문서가 스트리밍 또는 배치 API를 권합니다.

도구 호출

도구는 tools 배열에 name, description, input_schema(JSON Schema)로 정의합니다. Claude가 도구를 쓰기로 하면 stop_reason이 "tool_use"가 되고 content에 tool_use 블록(id, name, input)이 옵니다. 내 코드가 실행한 결과를 다음 user 메시지에 tool_result 블록으로 담아 보내면 Claude가 최종 답을 씁니다.

{
  "role": "user",
  "content": [
    {"type": "tool_result", "tool_use_id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", "content": "매출 8.4억, 업종 제조업"}
  ]
}

tool_choice는 auto(기본), any(반드시 하나 호출), tool(지정 도구 강제), none 중 하나이며, disable_parallel_tool_use: true로 한 턴에 한 도구만 부르게 할 수 있습니다. 도구 정의와 tool_use, tool_result 블록은 입력 토큰으로 과금되고, 도구가 하나라도 있으면 모델별 도구용 시스템 프롬프트 토큰(Sonnet 5는 auto일 때 354토큰)이 붙습니다.

비용을 줄이는 세 가지

1. 모델 선택. 분류나 추출처럼 단순한 작업은 Haiku 4.5(입력 1달러), 보고서 생성 같은 본작업은 Sonnet 5(2달러), 복잡한 판단만 Opus 5(5달러)로 보냅니다.
2. 프롬프트 캐싱. 반복되는 앞부분을 캐시에 올리면 읽기 비용이 기본 입력 가격의 0.1배입니다. 다음 글에서 다룹니다.
3. 배치 API. 실시간 응답이 필요 없는 대량 작업은 입력과 출력 모두 50% 할인이며 캐싱 할인과 겹쳐 적용됩니다.

오류 처리

공식 오류 표의 주요 항목입니다.

공식 SDK는 연결 오류, 429, 5xx를 기본 2회까지 지수 백오프로 자동 재시도하며 retry-after 헤더를 존중합니다. 모든 응답에 request-id 헤더가 있고 오류 본문에도 request_id가 있으니 로그에 남겨 둡니다. 스트리밍 중에는 200을 받은 뒤에도 오류 이벤트가 올 수 있어 별도 처리가 필요합니다.

정리

• 요청은 model, max_tokens, messages가 뼈대이고, 지침은 system에 둡니다.
• 대화 이력은 매번 다시 보내며, 도구 호출은 tool_use와 tool_result의 왕복입니다.
• 비용은 모델 선택, 캐싱, 배치로 줄이고, 오류는 코드별로 처리합니다.

자주 묻는 질문