본문으로 건너뛰기

Messages

Anthropic Messages 형식의 응답과 도구 호출 처리

Anthropic Messages의 인증 헤더, 요청 필드와 응답 블록, 종료 이유 및 스트리밍 이벤트를 설명합니다.

페이지 목차
POST
https://gw.letsur.ai/v1/messages
인증x-api-key: <API_KEY>

지원 범위와 인증

이 엔드포인트는 Anthropic Messages 형식으로 요청을 받고 응답과 도구 호출 요청을 반환합니다. Messages 형식을 지원하는 모델에서만 쓸 수 있으며, 에셋의 Anthropic 모델이 여기에 해당합니다. 요청 필드는 이 페이지에 정리한 지원 범위 안에서 사용합니다. Chat Completions, Responses와의 차이는 API 형식 선택에 있습니다.

/v1/messages를 호출할 때는 x-api-key: <API_KEY> 헤더를 권장합니다. 대안으로 Authorization: Bearer <API_KEY>도 사용할 수 있습니다. base URL과 anthropic-version 헤더는 인증에서 확인합니다.

답변 생성 전에 입력 토큰 수 확인하기

POST /v1/messages/count_tokens는 답변 생성 전에 Anthropic Messages 입력의 토큰 수를 확인하는 경로입니다. 직접 호출할 때는 AI 게이트웨이 API 키를 x-api-key로 보내고 Content-Type: application/json과 anthropic-version을 지정합니다. JSON 본문의 model에는 사용할 모델 코드를, messages에는 토큰 수를 확인할 메시지를 넣으세요.

요청 본문 예시

{"model":"<MODEL_CODE>","messages":[{"role":"user","content":"안녕하세요."}]}

응답 본문 예시

{"input_tokens":42}

input_tokens는 입력 토큰 수입니다. 답변이 필요하면 POST /v1/messages로 생성 요청을 별도로 보내세요. 해당 모델로 답변을 생성할 수 있는지는 사용 중인 스페이스에서 확인하세요. 요청이 실패하면 HTTP 상태와 오류 메시지를 확인하세요. 401이면 API 키를 확인하고, 400이면 요청 본문의 모델 코드와 Messages 입력 형식을 확인하세요.

요청 필드

기본값 칸의 -는 기본값이 명시되지 않았다는 뜻입니다.

필드타입요구 여부기본값설명
modelstring필수-에셋에 표시된 모델 코드. Messages를 지원하는 모델이어야 함
messagesarray필수-{role, content} 객체의 배열 (role은 user 또는 assistant)
max_tokensinteger필수-응답 최대 토큰 (Anthropic Messages 형식에서 필수)
systemstring선택-시스템 지시를 지정하는 별도 필드 (messages 배열 밖에 지정)
temperaturenumber선택10 ~ 1
top_pnumber선택-누적 확률을 기준으로 다음 토큰 후보를 선택하는 설정
top_kinteger선택-확률이 높은 k개 후보에서 다음 토큰을 선택하는 설정
stop_sequencesarray선택-응답 중단 시퀀스
streamboolean선택falseSSE 스트리밍 (스트리밍)
toolsarray선택-도구 호출 정의 (Anthropic 형식)
tool_choiceobject선택{"type": "auto"}도구 선택 방식

위 표에는 자주 사용하는 파라미터를 정리했습니다. 파라미터의 지원 여부와 세부 제한은 요청의 model이 가리키는 모델마다 다릅니다. 지원 여부는 에셋 화면의 표시값에서 확인합니다.

Chat Completions와는 세 가지가 다릅니다. system이 별도 필드이고, max_tokens가 필수이며, role에 system 값이 없습니다.

응답 (200)

{ "id": "msg_...", "type": "message", "role": "assistant", "model": "<MODEL_CODE>", "content": [ {"type": "text", "text": "..."} ], "stop_reason": "end_turn", "stop_sequence": null, "usage": { "input_tokens": 12, "output_tokens": 48 }, "estimated_cost": { "amount": "0.00032400", "currency": "unit", "disclaimer": "Estimated based on published pricing. Actual charges may differ." } }
필드설명
content[]응답 블록 배열 (text / tool_use 등)
stop_reason응답이 끝난 이유. 아래 표에 따라 완료 여부와 후속 행동을 판단할 값
usage.input_tokens / output_tokens입력과 출력 토큰 수
estimated_cost비스트리밍 응답 최상위의 호출별 비용 객체. 의미와 null 처리 기준은 요청별 비용을 따름

응답의 usage에 단계별 사용량(iterations)이 있으면 비용은 단계마다 그 단계에 쓰인 모델의 단가로 계산해 합산합니다. 그래서 요청한 모델의 단가만으로 계산한 값보다 클 수 있습니다.

종료 이유에 따른 다음 행동

값뜻과 다음 행동
end_turn모델의 이번 응답이 끝났습니다. 응답 내용이 애플리케이션의 조건을 만족하는지 확인합니다.
max_tokens응답이 출력 상한에 도달했습니다. 부분 응답을 완성된 답으로 처리하지 말고 입력과 출력 한도 안에서 후속 요청을 구성합니다.
stop_sequence응답이 지정한 중단 문자열에 도달했습니다. stop_sequence와 실제 응답 범위를 확인합니다.
tool_usecontent[]에 도구 호출 요청이 있습니다. 애플리케이션이 그 요청을 처리하고 결과를 후속 요청으로 보냅니다. 후속 요청 형식은 아래 도구 실행 결과 반환 절에 있습니다.
그 밖의 값 또는 누락이 표에 없는 값이거나 stop_reason이 없습니다. 완료로 처리하지 말고, 받은 내용과 종료 이유를 확인해 후속 처리를 결정합니다.

요청과 응답 예시

예제를 실행하려면 AI 게이트웨이 API 키와 Messages를 지원하는 모델 코드가 필요합니다. cURL 예제는 LETSUR_API_KEY 환경 변수를 사용합니다. <MODEL_CODE>는 실제 모델 코드로 바꿉니다. Python 예제는 환경 변수가 없으면 키와 모델 코드를 입력받습니다.

SDK 예제에서는 자동 재시도를 끕니다. timeout이나 응답 유실 뒤의 재전송 여부는 제약과 공통 오류의 기준에 따라 판단합니다.

cURL로 요청을 직접 보냅니다.

cURL
curl https://gw.letsur.ai/v1/messages \ -H "x-api-key: $LETSUR_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "Content-Type: application/json" \ --data '{"model":"<MODEL_CODE>","max_tokens":1024,"messages":[{"role":"user","content":"안녕"}]}'

Python 예제는 응답 내용과 종료 이유를 함께 출력합니다. cURL로 실행했다면 응답 JSON의 content[]와 stop_reason을 보고 종료 이유에 따른 다음 행동을 따르세요. stop_reason이 max_tokens이면 받은 부분 응답을 보존하고, tool_use이면 도구 실행 결과 반환을 따릅니다. 이 예제는 후속 요청을 자동으로 보내거나 도구를 실행하지 않습니다.

Claude Code에서 사용하는 별도 환경 변수와 모델 설정은 Claude Code 연동에 있습니다.

함수 도구 정의하기

tools[]의 각 객체에 함수 이름 name, 설명 description과 JSON Schema인 input_schema를 지정합니다. 다음은 첫 도구 요청의 본문 예시입니다. 선택한 모델이 도구 호출을 지원하는지 먼저 확인하고 <MODEL_CODE>를 실제 모델 코드로 바꿉니다.

{ "model": "<MODEL_CODE>", "max_tokens": 1024, "system": "날씨 질문에는 get_weather 도구를 사용하세요.", "messages": [{"role": "user", "content": "서울 날씨 알려 줘"}], "tools": [{ "name": "get_weather", "description": "지정한 도시의 현재 날씨를 조회합니다.", "input_schema": { "type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"] } }], "tool_choice": {"type": "auto"} }

tool_choice는 객체로 보냅니다. 위 예시의 auto를 지정하면 모델이 도구 사용 여부를 선택합니다. 도구 입력 형식은 input_schema로 정의합니다. Chat Completions의 function.parameters나 Responses의 parameters와 다른 필드입니다. 다른 선택 방식과 도구 정의는 Messages 도구 사용 형식 을 참고합니다.

도구 실행 결과 반환

함수는 애플리케이션이 실행합니다. 응답으로 받은 assistant 메시지의 content를 대화에 보존한 뒤, 다음 user 메시지에 tool_result 블록으로 결과를 넣습니다. tool_use_id는 응답에서 대응하는 tool_use.id와 같아야 합니다.

[ {"role": "user", "content": "서울 날씨 알려 줘"}, {"role": "assistant", "content": [ {"type": "tool_use", "id": "toolu_example", "name": "get_weather", "input": {"city": "서울"}} ]}, {"role": "user", "content": [ {"type": "tool_result", "tool_use_id": "toolu_example", "content": "날씨 조회 함수의 실제 실행 결과"} ]} ]

위 예시의 ID, 함수와 결과는 구조를 설명하기 위한 값입니다.

  1. 실제 응답의 블록을 보존하고, 여러 도구 호출이 있으면 각 결과를 호출마다 대응시킵니다.
  2. 위 배열을 후속 요청의 messages에 지정하고 같은 모델과 도구 정의, 필수 max_tokens 및 필요한 system으로 다시 요청합니다.
  3. 응답의 stop_reason을 확인합니다.

도구 실행 결과에 Chat Completions의 role: "tool" 형식을 섞지 않습니다.

스트리밍

stream: true로 요청하면 응답을 Server-Sent Events(SSE) 이벤트 단위로 받습니다.

event: message_start data: {"type":"message_start","message":{"id":"msg_...","type":"message","role":"assistant","content":[],"model":"<MODEL_CODE>","usage":{"input_tokens":12,"output_tokens":0}}} event: content_block_start data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}} event: content_block_delta data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"안"}} ... event: content_block_stop data: {"type":"content_block_stop","index":0} event: message_delta data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":48},"estimated_cost":{"amount":"0.00032400","currency":"unit","disclaimer":"Estimated based on published pricing. Actual charges may differ."}} event: message_stop data: {"type":"message_stop"}
이벤트의미
message_start응답 시작과 초기 usage(input_tokens)를 전달합니다
content_block_start출력 블록을 시작합니다
content_block_delta텍스트나 tool_use 일부를 전달합니다
content_block_stop출력 블록 하나를 끝냅니다
message_deltastop_reason, 누적 output_tokens와 계산 가능한 경우 estimated_cost를 전달합니다 (마지막 응답 조각에서 최종값 확인)
message_stop이 메시지의 이벤트 전송을 끝냅니다. 답변의 완성 여부는 stop_reason으로 판단합니다

스트림을 받는 중에는 다음 상황을 구분해 처리합니다.

상황처리
비용이 null이거나 사용량 이벤트를 받지 못함요청별 비용의 기준에 따라 비용을 0으로 기록하지 않습니다.
content_block_stop을 받음한 블록의 끝입니다. 전체 응답을 마치는 message_stop과 구분합니다.
응답 종료를 확인하기 전에 연결이 끊김받은 내용은 부분 응답으로 남깁니다.
message_stop을 받음message_delta의 delta.stop_reason을 종료 이유에 따른 다음 행동에 따라 확인합니다. 종료 이유가 max_tokens이면 받은 내용은 부분 응답이고, tool_use이면 도구 처리와 후속 요청이 필요합니다.
종료 이유가 없거나 알 수 없는 값임완료로 처리하지 않습니다.

제약과 공통 오류

응답을 받지 못한 요청을 다시 보내면 추가 비용이 생길 수 있습니다

timeout이나 응답 유실 뒤 같은 요청을 다시 보내면 별도 호출로 처리됩니다. 다시 보내기 전에 동기 호출의 재시도와 비용 확인에 따라 원래 호출과 새 호출을 구분하세요.

  • 도구 호출 지원 여부와 입력 한도는 모델마다 다르며 에셋에서 확인합니다.
  • AI 게이트웨이 API 키에는 월 사용 한도 검사가 적용됩니다.
  • 공통 오류 형식과 복구 기준은 오류 코드에 있습니다.