Messages 요청의 해부학

필수 다섯 개와 구조 결정 하나

Messages API 요청마다 API가 진짜 필요로 하는 필드 다섯 개와 그 위에 너가 내리는 구조 결정 하나가 있어. 필수: model, max_tokens, messages. 선택이지만 거의 항상 쓰이는: system, temperature. 구조 결정: 단일 응답(non-streaming)이냐 이벤트 스트림이냐.

왜 max_tokens가 모델 게 아니라 너 거냐

일부 API와 달리 Anthropic은 호출마다 출력 예산을 declare하라고 요구해. 이건 과금 안전장치이자 지연 손잡이. 합법적인 완성이 잘리지 않을 만큼 넉넉하게, 그리고 폭주한 모델이 예산 초과하지 못할 만큼 빡빡하게 잡아. 출력 토큰 예산은 진짜 과금 라인이지 권장사항 아니야.

Messages, chat 아님

messages 배열은 {role, content} 객체 리스트, role은 ['user', 'assistant']. 배열 안에 system role은 없어 — 시스템 프롬프트는 별도 top-level 필드. 역할이 번갈아야 함(user 메시지 두 번 연속 X); 추가 컨텍스트 주입하고 싶으면 user 턴 안에 넣거나 시스템 프롬프트로.

원칙: 요청 바디를 API 계약으로 다뤄. 헬퍼 SDK 메서드는 편의지, 바디가 진실이야.

Code

최소 Messages 요청 (Python)·python

from anthropic import Anthropic

client = Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system="You answer in exactly one sentence, no more.",
    messages=[
        {"role": "user", "content": "Why is max_tokens required by Anthropic but optional by some other providers?"},
    ],
    temperature=0.2,
)
print(response.content[0].text)
print("in:", response.usage.input_tokens, "out:", response.usage.output_tokens)

같은 호출의 raw HTTP (wire format)·bash

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-4-6",
    "max_tokens": 1024,
    "system": "You answer in exactly one sentence, no more.",
    "messages": [
      {"role": "user", "content": "Why is max_tokens required?"}
    ],
    "temperature": 0.2
  }'

Exercise

프로젝트에서 Claude 부르는 기능 하나 골라. 가장 작은 valid 요청 바디(model, max_tokens, messages) + 진짜 필요한 선택 필드(system 또는 temperature) 한 개를 써. 각 선택을 한 구절로 정당화.

Hint

Temperature 값을 정당화 못 하면 빼 — 디폴트가 대부분의 프로덕션 호출에 OK.

필수 다섯 개와 구조 결정 하나

왜 max_tokens가 모델 게 아니라 너 거냐

Messages, chat 아님

Code

External links

Exercise

Progress

댓글 0