Messages

POST /v1/messages 는 Anthropic 네이티브 메시지 API와 호환되는 엔드포인트입니다. Claude Code 같은 Anthropic SDK 클라이언트에서 base URL만 바꾸면 그대로 호출할 수 있습니다.


POST https://gw.letsur.ai/v1/messages

인증

이 엔드포인트는 두 가지 인증 방식을 지원합니다.

시나리오	헤더 / env
Letsur Gateway 키	`x-api-key` 헤더에 Letsur Gateway 키 (`Authorization` 헤더도 가능)
Anthropic 원본 키	`x-api-key` 헤더 또는 `ANTHROPIC_API_KEY` 환경변수에 Anthropic 원본 키

Anthropic 원본 키로 호출하면 Letsur 한도와 비용 추적이 적용되지 않습니다. 한도와 비용 추적이 필요하면 Letsur Gateway 키로 호출합니다.

요청 파라미터

이 엔드포인트는 Anthropic 원본 스펙을 그대로 받습니다.

파라미터	타입	필수	기본값	설명
`model`	string	○	—	Anthropic 모델 코드 (예: `claude-sonnet-4-6`)
`messages`	array	○	—	`{role, content}` — `role`은 `user` 또는 `assistant`
`max_tokens`	integer	○	—	응답 최대 토큰 (Anthropic은 필수)
`system`	string	×	—	시스템 프롬프트 (별도 필드, OpenAI와 다름)
`temperature`	number	×	`1`	0 ~ 1
`top_p`	number	×	—	nucleus sampling
`top_k`	integer	×	—	top-k sampling
`stop_sequences`	array	×	—	응답 중단 시퀀스
`stream`	boolean	×	`false`	SSE 스트리밍 (스트리밍)
`tools`	array	×	—	Tool calling 정의 (Anthropic 형식)
`tool_choice`	object	×	`{"type": "auto"}`	Tool 선택 정책

위 표는 자주 쓰는 파라미터입니다. 나머지 파라미터는 Anthropic Messages API 문서 의 표준을 따릅니다. Chat Completions와는 세 가지가 다릅니다. system을 별도 필드로 받고, max_tokens가 필수이며, role에 system이 없습니다.

응답 (200)


{
  "id": "msg_...",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-4-6",
  "content": [
    {"type": "text", "text": "..."}
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 48
  }
}

필드	의미
`content[]`	응답 블록 배열 (text / tool_use 등)
`stop_reason`	`end_turn` / `max_tokens` / `stop_sequence` / `tool_use` 중 하나
`usage.input_tokens` / `output_tokens`	입력·출력 토큰 수

Letsur Gateway 키로 호출하면 응답의 usage에 estimated_cost 필드가 함께 들어갑니다. 이 값으로 호출 비용을 바로 확인할 수 있습니다. Anthropic 원본 키로 호출하면 Anthropic 원본 응답이 그대로 돌아오며 estimated_cost가 포함되지 않습니다.

예시

Claude Code 연동


export ANTHROPIC_BASE_URL=https://gw.letsur.ai
export ANTHROPIC_API_KEY=<key>
 
claude

도구별 설정은 외부 도구 연동의 Claude Code 항목에서 확인합니다.

API 호출

cURL


curl https://gw.letsur.ai/v1/messages \
  -H "x-api-key: <API_KEY>" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "안녕"}]
  }'

스트리밍

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


event: message_start
data: {"type":"message_start","message":{"id":"msg_...","type":"message","role":"assistant","content":[],"model":"claude-sonnet-4-6","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}}

event: message_stop
data: {"type":"message_stop"}

이벤트	의미
`message_start`	응답 시작과 초기 `usage`(input_tokens)를 전달합니다
`content_block_start`	출력 블록을 시작합니다
`content_block_delta`	텍스트나 tool_use 일부를 전달합니다
`content_block_stop`	출력 블록 하나를 끝냅니다
`message_delta`	`stop_reason`과 누적 `output_tokens`를 전달합니다 (마지막 chunk에서 최종값 확인)
`message_stop`	응답을 종료합니다

에러

에러 형식은 인증 방식에 따라 다릅니다.

시나리오	응답 형식
Letsur Gateway 키	RFC 7807 형식으로 매핑한 응답
Anthropic 원본 키	Anthropic 원본 형식 그대로 — `error` 객체 (RFC 7807 아님)

Anthropic 원본 키로 호출할 때의 에러 응답 예시입니다.


{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "..."
  }
}

Letsur Gateway 키로 호출하면 에러 코드의 분류기를 거쳐 RFC 7807 형식으로 통일되고, 인증·한도 같은 공통 에러도 함께 적용됩니다. Anthropic 원본 키로 호출하면 Anthropic 측 에러가 그대로 노출됩니다.

다음에 볼 것

OpenAI 호환 경로 (Chat Completions)외부 도구 연동 에러 코드 지원 엔드포인트