메시지 API (Messages API)

메시지 API (Messages API)

Anthropic에서 Claude로 서비스를 만들 때 크게 두 가지 길이 있어요. 하나는 모델에 직접 프롬프트를 던지는 Messages API, 다른 하나는 관리형 인프라에서 돌아가는 사전 구성된 에이전트 하네스인 Claude Managed Agents입니다. 어떤 상황에 어떤 걸 쓰면 좋을지 먼저 표로 정리해 볼게요.

이 가이드는 Messages API를 다룰 때 자주 쓰는 패턴을 다뤄요. 기본 요청부터 여러 턴에 걸친 대화, 프리필(prefill) 기법, 비전 기능까지요. 완전한 API 사양이 필요하면 Messages API 레퍼런스를 보면 됩니다. 관리형 에이전트 하네스 쪽이 궁금하다면 Claude Managed Agents 개요를 확인해 보세요.

한 가지 참고로, 이 기능은 Zero Data Retention(ZDR) 대상이에요. 조직에서 ZDR 계약을 맺고 있으면 API 응답이 반환된 뒤 이 기능으로 주고받은 데이터는 저장되지 않습니다.

기본 요청과 응답

첫 요청은 정말 단순합니다. model과 max_tokens, 그리고 messages 배열만 넣어서 보내면 돼요. 여기서 max_tokens는 필수 값이니 꼭 넣어 줘야 합니다.

다만 주의할 게 하나 있어요. temperature, top_p, top_k 같은 샘플링 파라미터는 Claude 4.7 이후 모델과 Claude Mythos Preview에서는 지원되지 않습니다. 이 값들을 기본값이 아닌 값으로 설정하면 400 에러가 나요. 요청 본문에서 빼고, 대신 프롬프트를 잘 설계해서 모델의 동작을 이끄는 방식으로 바꿔야 합니다. 마이그레이션 패턴은 마이그레이션 가이드를 참고하세요.

# cURL
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-opus-5",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Hello, Claude"}
    ]
  }'

# CLI
ant messages create \
  --model claude-opus-5 \
  --max-tokens 1024 \
  --message '{role: user, content: "Hello, Claude"}'

# Python
message = anthropic.Anthropic().messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message)

// TypeScript
const anthropic = new Anthropic();

const message = await anthropic.messages.create({
  model: "claude-opus-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello, Claude" }]
});
console.log(message);

// C#
AnthropicClient client = new();

var parameters = new MessageCreateParams
{
    Model = Model.ClaudeOpus5,
    MaxTokens = 1024,
    Messages = [new() { Role = Role.User, Content = "Hello, Claude" }]
};
var message = await client.Messages.CreateAsync(parameters);

여러 턴의 대화

Messages API는 무상태(stateless) 방식입니다. 즉 항상 대화 전체 히스토리를 통째로 API에 보내야 해요. 이 패턴을 이용하면 시간이 지나면서 대화를 쌓아 올릴 수 있습니다.

재미있는 점은, 앞선 턴이 반드시 실제로 Claude가 생성한 것일 필요 없다는 거예요. assistant 역할의 **합성 메시지(synthetic messages)**를 직접 만들어 넣어도 됩니다.

Claude의 입에 말을 넣기 (프리필)

입력 messages 목록의 마지막 위치에 Claude의 응답 일부를 미리 채워 넣을 수 있습니다. 이렇게 하면 Claude의 응답 형태를 원하는 쪽으로 유도할 수 있어요. 아래 예시는 "max_tokens": 1로 설정해서 Claude에게 객관식 답변 하나만 받아내는 방식입니다.

주의할 점이 있어요. 프리필은 Claude Mythos Preview, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 4.6에서는 지원되지 않습니다. 이 모델들에 프리필을 쓰는 요청은 400 에러가 나요. 대신 구조화 출력(structured outputs)이나 시스템 프롬프트 지시로 바꾸면 됩니다. 마이그레이션 패턴은 마이그레이션 가이드에서 확인할 수 있어요.

비전 (Vision)

Claude는 요청에서 텍스트와 이미지를 모두 읽을 수 있어요. 이미지는 base64, url, file 세 가지 소스 타입으로 제공할 수 있습니다. 여기서 file 소스 타입은 Files API로 업로드한 이미지를 참조하는 방식이에요. 지원되는 미디어 타입은 image/jpeg, image/png, image/gif, image/webp입니다. 더 자세한 내용은 비전 가이드를 참고하세요.

도구 사용과 컴퓨터 사용

Messages API로 도구를 쓰는 예시는 도구 사용 가이드에서 볼 수 있어요. 데스크톱 컴퓨터 환경을 제어하는 예시는 컴퓨터 사용 가이드를 확인하면 됩니다. JSON 출력을 보장받고 싶다면 구조화 출력(Structured Outputs)를 보세요.