Anthropic Messages

Anthropic Messages 호환 구조로 메시지와 Content Blocks를 전송합니다.

Messages API는 user, assistant 메시지와 Content Blocks로 모델 응답을 생성하며 텍스트, 이미지, 도구 호출, 스트리밍 출력 및 확장된 사고를 지원합니다. 사용할 수 있는 콘텐츠 블록, 도구 및 고급 매개변수는 모델마다 다를 수 있으므로 현재 API 키에 표시되는 모델과 실제 API 기능을 기준으로 하세요.

POST/v1/messages

user와 assistant 메시지를 바탕으로 다음 assistant 응답을 생성합니다. 메시지 콘텐츠에는 문자열 또는 텍스트, 이미지, 도구, 문서 Content Blocks를 사용할 수 있습니다.

일반 JSON 응답과 SSE 스트리밍 이벤트를 지원합니다. 이미지, 도구 호출 및 확장된 사고 기능은 선택한 모델에 따라 다릅니다.

인증

anthropicApiKey

x-api-key<token>

x-api-key Header로 API 키를 전달합니다.

전달 위치: header

Header 매개변수

anthropic-version*string

사용할 API 버전을 지정합니다.

기본값"2023-06-01"

anthropic-beta?string

사용할 beta 버전을 지정합니다. 여러 값을 쉼표로 구분하거나 이 Header를 여러 번 전송할 수 있습니다.

요청 본문

Messages는 Content Blocks로 텍스트, 이미지, 도구 및 확장된 사고를 표현합니다. 작업에 맞는 보기를 선택하세요.

application/json

텍스트 대화

user와 assistant 메시지로 단일 턴 또는 여러 턴 텍스트 대화를 구성합니다. system은 최상위 필드를 사용합니다.

model: 현재 API 키에 표시되며 Messages를 지원하는 모델 ID입니다.
max_tokens: 이번 응답에서 생성할 수 있는 최대 토큰 수입니다.
messages[]: user와 assistant 메시지를 순서대로 정렬합니다.

application/json

{
  "model": "MODEL_ID",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "안녕하세요! 자신을 소개해 주세요."
    }
  ]
}

기본 텍스트 대화입니다. messages에는 문자열 콘텐츠 또는 text 콘텐츠 블록을 사용할 수 있습니다.

model*string

사용할 모델 ID입니다. 현재 API 키에 표시되며 Messages를 지원하는 모델을 선택하세요.

길이1 <= length <= 256

max_tokens*integer

생성할 수 있는 최대 토큰 수입니다. 한도는 모델마다 다릅니다. 0으로 설정하면 응답을 생성하지 않고 프롬프트 캐시만 채울 수 있습니다.

범위0 <= value

messages*array<>

전송 순서대로 정렬한 텍스트 대화 메시지입니다. content는 문자열 또는 text 콘텐츠 블록 배열일 수 있습니다.

항목1 <= items

metadata?

요청과 연결된 메타데이터입니다.

cache_control?|null

최상위 캐시 제어이며 요청에서 마지막으로 캐시 가능한 콘텐츠 블록에 자동 적용됩니다. 사용 가능 여부는 모델과 채널에 따라 다릅니다.

container?||null

요청 간에 컨테이너를 재사용하거나 컨테이너에 로드할 Skills를 지정합니다. 사용 가능 여부는 모델, 채널 및 계정에 따라 다릅니다.

inference_geo?string|null

추론을 실행할 지리적 지역을 지정합니다. 설정하지 않으면 계정의 기본 지역을 사용합니다. 사용 가능 여부는 계정과 채널에 따라 다릅니다.

output_config?

모델 출력 설정입니다. 필드 사용 가능 여부는 선택한 모델과 채널에 따라 다릅니다.

service_tier?string

요청에 사용할 서비스 등급입니다. auto는 사용 가능한 경우 우선 용량을 사용하고 standard_only는 표준 용량만 사용합니다. 실제 지원 범위는 계정과 채널에 따라 다릅니다.

허용 값

"auto"
"standard_only"

stop_sequences?array<string>

생성을 중지하는 사용자 정의 텍스트 시퀀스입니다.

stream?boolean

Server-Sent Events를 통해 응답을 점진적으로 반환할지 지정합니다.

기본값false

system?|array<>

최상위 시스템 프롬프트입니다. Messages 목록에는 system 역할이 없습니다.

temperature?number

사용 중단 예정

더 이상 권장되지 않습니다. Claude Opus 4.6 이후 출시된 모델은 사용자 정의 temperature를 지원하지 않습니다. 이전 요청과의 호환성을 위해 1.0을 허용할 수 있으나 다른 값은 400을 반환할 수 있습니다. 새 모델에서는 이 필드를 생략하는 것이 좋습니다.

범위0 <= value <= 1

thinking?||

확장된 사고 설정입니다. 새 모델에서는 adaptive를 우선 사용하고 이전 모델에서는 enabled와 budget_tokens를 계속 사용할 수 있습니다.

tool_choice?||

tools?array<|||||||>

모델에서 사용할 사용자 정의 도구 또는 내장 도구입니다.

top_k?integer

사용 중단 예정

더 이상 권장되지 않습니다. Claude Opus 4.6 이후 출시된 모델은 모든 top_k 값을 거부하고 400을 반환할 수 있습니다. 새 모델에서는 이 필드를 생략하는 것이 좋습니다.

범위1 <= value

top_p?number

사용 중단 예정

더 이상 권장되지 않습니다. Claude Opus 4.6 이후 출시된 모델은 기본값에 가까운 설정에 대해서만 제한적 호환 동작을 유지하며 다른 값은 400을 반환할 수 있습니다. 새 모델에서는 이 필드를 생략하는 것이 좋습니다.

범위0 < value < 1

이미지, 도구 및 확장된 사고 기능은 모델과 상위 채널에 따라 다를 수 있습니다. 최소 텍스트 요청을 먼저 완료한 후 고급 필드를 하나씩 활성화하는 것이 좋습니다.

응답 본문

`application/json`

curl -X POST "https://example.com/v1/messages" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": "안녕하세요! 자신을 소개해 주세요."
      }
    ]
  }'

{
  "content": [
    {
      "type": "text",
      "text": "안녕하세요! 저는 AI 도우미입니다."
    }
  ],
  "id": "msg_example",
  "model": "MODEL_ID",
  "role": "assistant",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "type": "message",
  "usage": {
    "input_tokens": 12,
    "output_tokens": 16,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0
  }
}

Anthropic Messages 공식 문서상위 프로토콜 정의 및 최신 필드 변경 사항을 확인합니다.

인증

Header 매개변수

요청 본문

응답 본문

200application/json

400application/json

401application/json

429application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`