본문으로 건너뛰기

Anthropic Messages

Anthropic Messages 형식으로 지원 Claude 모델을 호출하세요.

Anthropic Messages 요청은 별도 system 필드와 필수 max_tokens를 사용하며, 모델별 기능은 게이트웨이 지원 범위를 따릅니다.

POSThttps://gw.letsur.ai/v1/messages

인증

/v1/messages 호출에는 아래 인증 헤더 중 하나를 사용합니다. base URL과 anthropic-version 헤더는 인증에서 확인합니다.

방식헤더
권장x-api-key: <API_KEY>
대안Authorization: Bearer <API_KEY>

요청 필드

이 엔드포인트는 지원 범위 안에서 Anthropic Messages 형식을 받습니다.

필드타입요구 여부기본값설명
modelstring필수—에셋의 Anthropic 모델 코드
messagesarray필수—{role, content} 객체의 배열 (role은 user 또는 assistant)
max_tokensinteger필수—응답 최대 토큰 (Anthropic은 필수)
systemstring선택—시스템 프롬프트 (별도 필드, OpenAI와 다름)
temperaturenumber선택10 ~ 1
top_pnumber선택—nucleus sampling
top_kinteger선택—top-k sampling
stop_sequencesarray선택—응답 중단 시퀀스
streamboolean선택falseSSE 스트리밍 (스트리밍)
toolsarray선택—Tool calling 정의 (Anthropic 형식)
tool_choiceobject선택{"type": "auto"}Tool 선택 정책

위 표는 자주 쓰는 파라미터입니다. 모델별 지원 범위는 에셋에서 확인합니다. 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_reasonend_turn / max_tokens / stop_sequence / tool_use 중 하나
usage.input_tokens / output_tokens입력과 출력 토큰 수
estimated_cost비스트리밍 응답 최상위의 호출별 비용 객체입니다. 의미와 null 처리 기준은 요청별 비용을 따릅니다

요청과 응답 예시

아래 예제는 Bash 또는 서버 runtime의 LETSUR_API_KEY 환경 변수를 읽습니다. 키 설정과 첫 실행은 AI 게이트웨이 시작하기에서 확인합니다. Claude Code의 별도 환경 변수와 모델 설정은 Claude Code 연동을 따릅니다.

(
  test -n "${LETSUR_API_KEY:-}" || { echo "LETSUR_API_KEY가 필요합니다." >&2; exit 1; }
  env -u LETSUR_API_KEY curl https://gw.letsur.ai/v1/messages \
    --header @- \
    -H "anthropic-version: 2023-06-01" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "<MODEL_CODE>",
      "max_tokens": 1024,
      "messages": [{"role": "user", "content": "안녕"}]
    }' <<EOF
x-api-key: ${LETSUR_API_KEY}
EOF
)

스트리밍

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를 전달합니다 (마지막 chunk에서 최종값 확인)
message_stop응답을 종료합니다

제약과 공통 오류

  • max_tokens는 Anthropic Messages 형식에서 필수입니다.
  • system은 message role이 아니라 별도 request field로 전달합니다.
  • 모델별 tool use와 입력 한계는 에셋의 지원 범위를 확인합니다.
  • AI 게이트웨이 API 키에는 월 사용 한도 검사를 적용합니다.
  • 공통 에러 형식과 복구 기준은 에러 코드에서 확인합니다.
마지막 업데이트