Claude Platform Docs
MessagesClaude로 구축하기

Messages API 사용하기

Messages API를 효과적으로 사용하기 위한 실용적인 패턴과 예제

Anthropic은 Claude로 빌드하는 두 가지 방법을 제공하며, 각각 서로 다른 사용 사례에 적합합니다:

Messages APIClaude Managed Agents
무엇인가모델에 직접 프롬프트를 보낼 수 있는 액세스관리형 인프라에서 실행되는, 사전 구축되고 구성 가능한 에이전트 하네스
적합한 용도커스텀 에이전트 루프 및 세밀한 제어장기 실행 작업 및 비동기 작업

이 가이드는 기본 요청, 멀티턴 대화, 프리필 기법, 비전 기능을 포함하여 Messages API를 사용할 때의 일반적인 패턴을 다룹니다. 전체 API 사양은 Messages API 레퍼런스API 참조 링크가 포함된 미리보기 사용 가능 — 카드에 포커스가 들어올 때까지 Tab을 누르고, 돌아가려면 Escape를 누르세요.를 참조하세요. 대신 관리형 에이전트 하네스에 대해서는 Claude Managed Agents 개요를 참조하세요.

기본 요청 및 응답

message = anthropic.Anthropic().messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message)
Output
{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello!"
    }
  ],
  "model": "claude-opus-5-5",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 6
  }
}

거부 응답(stop_reason: "refusal")에는 모든 모델에서 거부를 유발한 정책 카테고리를 식별하는 stop_details 객체도 포함됩니다. 필드 레퍼런스와 예제 처리 코드는 중지 사유 처리를 참조하세요.

여러 대화 턴

Messages API는 상태 비저장(stateless) 방식이므로, 항상 전체 대화 기록을 API로 전송해야 합니다. 이 패턴을 사용하여 시간에 걸쳐 대화를 구축할 수 있습니다. 이전 대화 턴이 반드시 실제로 Claude에서 생성된 것일 필요는 없습니다. 합성된 assistant 메시지를 사용할 수 있습니다.

베타로 제공되는 메시지 스레드를 사용하면 API가 대화를 유지할 수 있으므로, 이후의 각 요청에서는 새 메시지만 전송하면 됩니다. 스레드는 마지막 요청 후 5분이 지나면 만료되며, 마지막 사용 후 1시간 이내에 삭제됩니다.

message = anthropic.Anthropic().messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, Claude"},
        {"role": "assistant", "content": "Hello!"},
        {"role": "user", "content": "Can you describe LLMs to me?"},
    ],
)
print(message)
Output
{
  "id": "msg_018gCsTGsXkYJVqYPxTgDHBU",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Sure, I'd be happy to provide..."
    }
  ],
  "model": "claude-opus-5-5",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 30,
    "output_tokens": 309
  }
}

메시지 내 시스템 역할

사용자 턴 이후에 "role": "system"이 포함된 메시지를 추가하여(배치 규칙에 따름) 대화 도중에 새로운 시스템 지시를 추가할 수 있습니다. 이 기능은 Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Opus 5.5, Claude Opus 4.8, Claude Opus 5, Claude Sonnet 5.5, Claude Haiku 5.5에서 작동합니다. 내용을 담고 있는 system 메시지는 messages의 첫 번째 항목이 될 수 없습니다. 처음부터 적용되는 지시에는 최상위 system 필드를 사용하세요.

대화 중간의 시스템 메시지는 최상위 system 필드와 동일한 권한을 가지지만, 메시지 기록의 끝에 추가되므로 그 앞에 있는 캐시된 접두사를 무효화하지 않습니다. 맨 첫 턴부터 적용되어야 하는 지시에는 최상위 system 필드를 사용하고, 나중에야 관련성이 생기는 지시에는 대화 중간의 시스템 메시지를 사용하세요.

프롬프트 캐싱과 결합하는 방법을 포함한 전체 가이드는 대화 중간 시스템 메시지를 참조하세요.

Claude의 응답 프리필하기

입력 메시지 목록의 마지막 위치에서 Claude 응답의 일부를 “prefill”(미리 채우기)할 수 있습니다. 이 기법을 사용하여 Claude의 응답 형태를 조정할 수 있습니다. 다음 예제는 "max_tokens": 1을 사용하여 Claude로부터 단일 객관식 답변을 얻습니다.

message = anthropic.Anthropic().messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1,
    messages=[
        {
            "role": "user",
            "content": "What is latin for Ant? (A) Apoidea, (B) Rhopalocera, (C) Formicidae",
        },
        {"role": "assistant", "content": "The answer is ("},
    ],
)
print(message)
Output
{
  "id": "msg_01Q8Faay6S7QPTvEUUQARt7h",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "C"
    }
  ],
  "model": "claude-sonnet-4-5",
  "stop_reason": "max_tokens",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 42,
    "output_tokens": 1
  }
}

비전

Claude는 요청에 포함된 텍스트와 이미지를 모두 읽을 수 있습니다. base64, url, file 소스 유형을 사용하여 이미지를 제공할 수 있습니다. file 소스 유형은 Files API를 통해 업로드된 이미지를 참조합니다. 지원되는 미디어 유형은 image/jpeg, image/png, image/gif, image/webp입니다. 자세한 내용은 비전 가이드를 참조하세요.

import base64
import httpx2

# 옵션 1: base64로 인코딩된 이미지
image_url = "https://platform.claude.com/docs/images/vision-example.jpg"
image_media_type = "image/jpeg"
image_data = base64.standard_b64encode(httpx2.get(image_url).content).decode("utf-8")

message = anthropic.Anthropic().messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": image_media_type,
                        "data": image_data,
                    },
                },
                {"type": "text", "text": "What is in the above image?"},
            ],
        }
    ],
)
print(message)

# 옵션 2: URL로 참조하는 이미지
message_from_url = anthropic.Anthropic().messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://platform.claude.com/docs/images/vision-example.jpg",
                    },
                },
                {"type": "text", "text": "What is in the above image?"},
            ],
        }
    ],
)
print(message_from_url)
Output
{
  "id": "msg_011CdKmWtV3oFx1C5yUbf5CY",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "This image is a beautiful minimalist/flat-design illustration of a sunset landscape. Here's what it contains:\n\n**Sky & Sun:**\n- A warm gradient sky transitioning from golden-yellow at the top to deep orange toward the horizon\n- A large pale yellow sun positioned in the upper-right area\n\n**Birds:**\n- Three small silhouetted birds flying in the upper-left portion of the sky, depicted as simple \"M\" or \"v\" shapes\n\n**Mountains:**\n- Multiple layered mountain peaks in purple and maroon tones\n- The mountains overlap to create depth, with varying shades of dusty purple and deep burgundy\n\n**Water:**\n- A dark purple body of water at the bottom of the image\n- A reflection of the sun shown as horizontal cream/peach colored lines in the center-bottom area\n\nThe overall style is clean, geometric, and uses a warm sunset color palette (oranges, yellows, purples, and maroons), giving it a peaceful, serene aesthetic typical of modern vector/flat design artwork."
    }
  ],
  "model": "claude-opus-5-5",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 1030,
    "output_tokens": 350
  }
}

다음 단계

중지 사유 및 폴백

각 stop_reason 값을 처리하고 응답이 종료될 때 수행할 작업을 결정하세요.

Claude와 함께하는 도구 사용

Messages API 내에서 외부 서비스와 API를 호출할 수 있도록 Claude에게 도구를 제공하세요.

컴퓨터 사용 도구

Messages API로 데스크톱 컴퓨터 환경을 제어하세요.

브라우저 사용 도구

직접 실행하는 브라우저에서 Claude가 웹페이지를 탐색하고, 읽고, 상호작용하도록 하세요.

구조화된 출력

Claude로부터 스키마 검증이 보장된 JSON 출력을 받으세요.

작업 예산

output_config.task_budget을 사용하여 전체 에이전트 루프에 걸친 권고 토큰 예산을 설정하세요.

제공 여부

Messages API
Availability requirements for Messages API are the same across all supported platforms.
모델
  • 모든 모델

데이터 처리

데이터 처리 개요

적용 엔드포인트

  • /v1/messages
제로 데이터 보존적격

적용 모델 제외

Claude 응답 생성을 위한 표준 API 호출입니다.

HIPAA적격

이 페이지가 도움이 되었나요?