Messages API 개요

메시지 생성 (Create a Message)

POST /v1/messages

텍스트와(또는) 이미지 콘텐츠로 구성된 입력 메시지 목록을 구조화된 형태로 보내면, 모델이 대화의 다음 메시지를 생성합니다.

Messages API는 단일 질의에도, 상태를 저장하지 않는(stateless) 멀티턴 대화에도 사용할 수 있습니다.

Messages API에 대한 자세한 내용은 사용자 가이드를 참고하세요.

요청 본문 파라미터 (Body Parameters)

`max_tokens` (number)

생성을 멈추기 전까지 생성할 토큰의 최대 개수입니다. 모델은 이 최댓값에 도달하기 전에 멈출 수도 있다는 점을 유의하세요. 이 파라미터는 생성할 토큰의 절대 상한만 지정합니다. 0으로 설정하면 응답을 생성하지 않고 프롬프트 캐시만 채울 수 있습니다. 모델마다 이 파라미터에 허용되는 최댓값이 다르므로, 자세한 내용은 모델 문서를 참고하세요.

`messages` (array of MessageParam)

입력 메시지입니다. Claude 모델은 user(사용자)와 assistant(어시스턴트) 대화 턴이 번갈아 이어지도록 학습되어 있습니다. 새 Message를 생성할 때는 이전 대화 턴을 messages 파라미터로 지정하며, 그러면 모델이 대화의 다음 Message를 생성합니다.

요청에서 연속된 user 턴이나 연속된 assistant 턴은 하나의 턴으로 합쳐집니다. 각 입력 메시지는 role과 content를 가진 객체여야 합니다. 단일 user 역할 메시지만 지정할 수도 있고, 여러 개의 user/assistant 메시지를 함께 넣을 수도 있습니다.

마지막 메시지가 assistant 역할을 사용하는 경우, 응답 콘텐츠는 해당 메시지의 내용에 이어서 곧바로 이어집니다. 이를 활용해 모델 응답의 일부를 제약할 수 있습니다.

단일 user 메시지 예시:

[{"role": "user", "content": "Hello, Claude"}]

여러 대화 턴 예시:

[
  {"role": "user", "content": "Hello there."},
  {"role": "assistant", "content": "Hi, I'm Claude. How can I help you?"},
  {"role": "user", "content": "Can you explain LLMs in plain English?"}
]

Claude의 응답을 일부 미리 채워 둔 예시:

[
  {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"},
  {"role": "assistant", "content": "The best answer is ("}
]

각 입력 메시지의 content는 하나의 string이거나, 콘텐츠 블록(content block)의 배열일 수 있습니다. 각 블록은 고유한 type을 가집니다. content에 string을 쓰는 것은 "text" 타입 콘텐츠 블록 하나로 이루어진 배열의 축약 표현입니다. 따라서 다음 두 입력 메시지는 동일합니다.

{"role": "user", "content": "Hello, Claude"}

{"role": "user", "content": [{"type": "text", "text": "Hello, Claude"}]}

시스템 프롬프트를 포함하려면 최상위 system 파라미터를 사용하면 됩니다. Messages API의 입력 메시지에는 "system" 역할이 별도로 존재하지 않습니다. 하나의 요청에는 최대 100,000개의 메시지를 담을 수 있습니다.

콘텐츠 블록 타입 (Content block types)

content 배열의 각 블록은 type 값에 따라 형태가 결정됩니다. 주요 콘텐츠 블록 타입은 다음과 같습니다.

text — 텍스트 블록. text(문자열) 필드를 가집니다. 선택적으로 cache_control과 citations(인용)를 포함할 수 있습니다.
image — 이미지 블록. source로 이미지를 지정합니다. source는 base64 인코딩(base64) 또는 URL(url) 방식일 수 있으며, 지원 미디어 타입은 image/jpeg, image/png, image/gif, image/webp입니다.
document — 문서 블록. source로 PDF(application/pdf), 일반 텍스트(text/plain), 콘텐츠 블록, 또는 URL을 지정할 수 있습니다. citations 설정과 title, context를 함께 줄 수 있습니다.
search_result — 검색 결과 블록. content, source, title로 구성되며 인용을 지원합니다.
thinking / redacted_thinking — 확장 사고(extended thinking) 블록. thinking 텍스트와 signature를 포함하거나, 가려진(redacted) 형태의 데이터를 담습니다.
tool_use — 모델이 도구를 호출한 블록. id, name, input을 가집니다.
tool_result — 도구 실행 결과 블록. tool_use_id로 어떤 도구 호출에 대한 결과인지 연결하며, content와 is_error(오류 여부)를 가집니다.
server_tool_use — 서버 측 도구 호출 블록. name은 web_search, web_fetch, code_execution 등이 될 수 있습니다.
web_search_tool_result / web_fetch_tool_result / code_execution_tool_result — 각각 웹 검색, 웹 페치, 코드 실행 등 서버 측 도구의 결과 블록입니다.

여러 블록 타입은 선택적으로 cache_control을 가질 수 있습니다. cache_control을 {"type": "ephemeral"}로 지정하면 해당 콘텐츠 블록 위치에 캐시 분기점(breakpoint)을 만듭니다. ttl(time-to-live)로 캐시 유효 기간을 5m(5분) 또는 1h(1시간)로 지정할 수 있으며, 기본값은 5m입니다.

`model` (string)

응답을 생성할 모델입니다. 사용 가능한 모델 목록과 각 모델의 상세 정보는 모델 문서를 참고하세요.

`system` (string 또는 array of TextBlockParam)

시스템 프롬프트입니다. 시스템 프롬프트는 Claude에게 맥락과 지침을 제공하는 방법으로, 특정 목표나 역할을 지정하는 데 사용할 수 있습니다.

`stream` (boolean)

서버-전송 이벤트(server-sent events)를 사용해 응답을 증분적으로 스트리밍할지 여부입니다.

`temperature` (number)

응답에 주입할 무작위성의 정도입니다. 0.0에서 1.0 사이의 값을 사용합니다. 분석적이거나 객관식과 같은 작업에는 0.0에 가깝게, 창의적이거나 생성적인 작업에는 1.0에 가깝게 설정합니다. temperature를 설정하더라도 완전한 결정성은 보장되지 않습니다.

참고: temperature, top_p, top_k 샘플링 파라미터는 일부 최신 모델에서 지원되지 않을 수 있습니다. 기본값이 아닌 값으로 설정하면 400 오류가 반환될 수 있으므로, 해당 모델에서는 요청에서 생략하고 프롬프트로 동작을 유도하세요. 자세한 내용은 마이그레이션 가이드를 참고하세요.

`tools` (array)

모델이 사용할 수 있는 도구의 정의 목록입니다. 각 도구는 이름(name), 설명(description), 입력 스키마(input_schema)를 가집니다. 모델은 적절한 시점에 도구 사용(tool use)을 통해 도구를 호출할 수 있습니다.

`tool_choice` (object)

모델이 제공된 도구를 어떻게 사용할지 제어합니다. 모델이 스스로 결정하게 하거나(auto), 반드시 도구를 사용하게 하거나(any), 특정 도구를 강제하거나(tool), 도구 사용을 끄는(none) 방식을 지정할 수 있습니다.

`output_config` (object)

모델 출력에 대한 설정 옵션으로, 출력 형식 등을 지정합니다.

effort: 추론 노력 수준을 지정합니다. 값은 low, medium, high, xhigh, max 중 하나입니다.
format: 응답의 출력 형식을 지정하는 스키마입니다. type: "json_schema"와 함께 schema(JSON 스키마)를 제공하면, 스키마로 검증된 JSON 출력을 받을 수 있습니다(구조화된 출력, structured outputs).

`metadata` (object)

요청에 대한 메타데이터를 담는 객체입니다. 예를 들어 user_id로 요청과 연결된 사용자에 대한 외부 식별자를 전달할 수 있습니다.

`stop_sequences` (array of string)

모델 생성을 멈추게 할 사용자 지정 텍스트 시퀀스입니다. 이 시퀀스 중 하나를 만나면 모델이 생성을 중단합니다.

응답 (Response)

응답으로 반환되는 Message 객체의 주요 필드는 다음과 같습니다.

`id` (string)

객체의 고유 식별자입니다. ID의 형식과 길이는 시간이 지나면서 바뀔 수 있습니다.

`type` (string)

객체의 타입으로, Messages API의 응답에서는 항상 "message"입니다.

`role` (string)

생성된 메시지의 대화 역할입니다. 응답에서는 항상 "assistant"입니다.

`content` (array of ContentBlock)

모델이 생성한 콘텐츠입니다. 각각 type을 가진 콘텐츠 블록의 배열입니다.

예시:

[{"type": "text", "text": "Hi, I'm Claude."}]

`model` (string)

요청을 처리한 모델입니다.

`stop_reason` (string)

모델이 생성을 멈춘 이유입니다. 주요 값은 다음과 같습니다.

end_turn: 모델이 자연스럽게 턴의 끝(stopping point)에 도달했습니다.
max_tokens: 요청한 max_tokens 또는 모델의 최대 토큰 한도에 도달했습니다.
stop_sequence: 지정한 사용자 정의 정지 시퀀스(stop sequence) 중 하나를 생성했습니다.
tool_use: 모델이 하나 이상의 도구를 호출했습니다.
refusal: 모델이 안전상의 이유로 응답을 거부했습니다.

`stop_sequence` (string 또는 null)

stop_reason이 stop_sequence인 경우, 생성된 정지 시퀀스를 담습니다. 그 외에는 null입니다.

`container` (object)

요청에 사용된 컨테이너에 대한 정보입니다(코드 실행 도구 등에 해당). id(이 요청에 사용된 컨테이너 식별자)와 expires_at(컨테이너 만료 시각)을 가집니다.

`usage` (object)

청구와 사용량 산정에 쓰이는 토큰 사용량 정보입니다. 주요 필드는 다음과 같습니다.

input_tokens: 입력에 사용된 토큰 수.
output_tokens: 생성된 출력 토큰 수.
cache_creation_input_tokens: 캐시를 생성하는 데 사용된 입력 토큰 수.
cache_read_input_tokens: 캐시에서 읽어 온 입력 토큰 수.

응답 예시:

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello!"
    }
  ],
  "model": "claude-opus-4-8",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 6
  }
}

Messages API 개요

메시지 생성 (Create a Message)

요청 본문 파라미터 (Body Parameters)

max_tokens (number)

messages (array of MessageParam)

콘텐츠 블록 타입 (Content block types)

model (string)

system (string 또는 array of TextBlockParam)

stream (boolean)

temperature (number)

tools (array)

tool_choice (object)

output_config (object)

metadata (object)

stop_sequences (array of string)

응답 (Response)

id (string)

type (string)

role (string)

content (array of ContentBlock)

model (string)

stop_reason (string)

stop_sequence (string 또는 null)

container (object)

usage (object)

관련 API

`max_tokens` (number)

`messages` (array of MessageParam)

`model` (string)

`system` (string 또는 array of TextBlockParam)

`stream` (boolean)

`temperature` (number)

`tools` (array)

`tool_choice` (object)

`output_config` (object)

`metadata` (object)

`stop_sequences` (array of string)

`id` (string)

`type` (string)

`role` (string)

`content` (array of ContentBlock)

`model` (string)

`stop_reason` (string)

`stop_sequence` (string 또는 null)

`container` (object)

`usage` (object)