Messages API 사용하기

Messages API 사용

Anthropic offers two ways to build with Claude, each suited to different use cases:

	Messages API	Claude Managed Agents
What it is	Direct model prompting access	Pre-built, configurable agent harness that runs in managed infrastructure
Best for	Custom agent loops and fine-grained control	Long-running tasks and asynchronous work
Learn more	Messages API docs	Claude Managed Agents docs

이 가이드는 기본 요청, 다중 턴 대화, 프리필 기법, 비전 기능을 포함하여 Messages API로 작업하기 위한 일반적인 패턴을 다룹니다. 완전한 API 사양은 Messages API 참조를 참조하세요.

This feature is eligible for Zero Data Retention (ZDR). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned.

기본 요청 및 응답

message = anthropic.Anthropic().messages.create(
    model="claude-opus-4-7",
    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-4-7",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 6
  }
}

여러 대화 턴

Messages API는 상태를 유지하지 않으므로 항상 전체 대화 기록을 API에 보냅니다. 이 패턴을 사용하여 시간에 따라 대화를 구축할 수 있습니다. 이전 대화 턴이 반드시 Claude에서 실제로 시작될 필요는 없습니다. 합성된 assistant 메시지를 사용할 수 있습니다.

Output

{
  "id": "msg_018gCsTGsXkYJVqYPxTgDHBU",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Sure, I'd be happy to provide..."
    }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 30,
    "output_tokens": 309
  }
}

Claude의 입에 말을 넣기

입력 메시지 목록의 마지막 위치에서 Claude의 응답 일부를 미리 채울 수 있습니다. 이를 사용하여 Claude의 응답을 형성할 수 있습니다. 아래 예제는 "max_tokens": 1을 사용하여 Claude에서 단일 객관식 답변을 얻습니다.

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 Mythos Preview, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 4.6에서 지원되지 않습니다. 이러한 모델과 함께 프리필을 사용하는 요청은 400 오류를 반환합니다. 대신 구조화된 출력 또는 시스템 프롬프트 지침을 사용하세요. 마이그레이션 패턴은 마이그레이션 가이드를 참조하세요.

비전

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

출력

{
  "id": "msg_01EcyWo6m4hyW8KHs2y2pei5",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "This image shows an ant, specifically a close-up view of an ant. The ant is shown in detail, with its distinct head, antennae, and legs clearly visible. The image is focused on capturing the intricate details and features of the ant, likely taken with a macro lens to get an extreme close-up perspective."
    }
  ],
  "model": "claude-opus-4-7",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 1551,
    "output_tokens": 71
  }
}

도구 사용 및 컴퓨터 사용

Messages API에서 도구를 사용하는 방법의 예는 도구 사용 가이드를 참조하세요. Messages API로 데스크톱 컴퓨터 환경을 제어하는 방법의 예는 컴퓨터 사용 가이드를 참조하세요. 보장된 JSON 출력의 경우 구조화된 출력을 참조하세요.

message = anthropic.Anthropic().messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, Claude"},
        {"role": "assistant", "content": "Hello!"},
        {"role": "user", "content": "Can you describe LLMs to me?"},
    ],
)
print(message)

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)

import base64
import httpx

# Option 1: Base64-encoded image
image_url = "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"
image_media_type = "image/jpeg"
image_data = base64.standard_b64encode(httpx.get(image_url).content).decode("utf-8")

message = anthropic.Anthropic().messages.create(
    model="claude-opus-4-7",
    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)

# Option 2: URL-referenced image
message_from_url = anthropic.Anthropic().messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg",
                    },
                },
                {"type": "text", "text": "What is in the above image?"},
            ],
        }
    ],
)
print(message_from_url)