Messages API (Claude Code 호환)

Claude Code(Anthropic Messages API 호환)

Anthropic Messages API 와이어 포맷과 호환되는 엔드포인트입니다. Claude Code가 보내는 system·messages(콘텐츠 블록)·max_tokens·tools(input_schema) 형태를 그대로 받아, 카탈로그의 어떤 텍스트 모델로도 호출할 수 있습니다.

엔드포인트

POST/api/v1/messages

x-api-key: YOUR_API_KEY 헤더로 인증합니다(Claude Code 관례). Authorization: Bearer YOUR_API_KEY 헤더도 허용됩니다.

요청 파라미터

이름	타입	필수	설명	기본값
`model`*	string	* 필수	사용할 모델 ID. 카탈로그의 모든 텍스트 모델을 사용할 수 있습니다.	-
`max_tokens`*	number	* 필수	최대 출력 토큰 수(1~200000). Anthropic 규격상 필수입니다.	-
`messages`*	array	* 필수	대화 메시지 배열. 각 메시지는 role("user" \| "assistant")과 content(문자열 또는 콘텐츠 블록 배열: text · image · tool_use · tool_result)를 포함합니다.	-
`system`	string \| array	선택	시스템 프롬프트. 문자열 또는 {type:"text", text} 블록 배열로 전달합니다.	-
`stream`	boolean	선택	SSE 스트리밍 여부. true로 설정하면 이벤트 단위로 실시간 전송합니다.	`false`
`temperature`	number	선택	생성 온도(0~1).	-
`top_p`	number	선택	누적 확률 샘플링.	-
`stop_sequences`	array	선택	생성을 중단할 문자열 목록(최대 4개).	-
`tools`	array	선택	도구 목록. {name, description, input_schema} 형태로 전달합니다.	-
`tool_choice`	object	선택	{type: "auto" \| "any" \| "none" \| "tool", name?}. disable_parallel_tool_use로 병렬 호출을 끌 수 있습니다.	-
`metadata`	object	선택	부가 메타데이터. metadata.user_id는 최종 사용자 식별자로 매핑됩니다.	-

응답 필드

이름	타입	필수	설명	기본값
`id`*	string	* 필수	응답 ID(msg_...).	-
`type`*	string	* 필수	"message" 고정값.	-
`role`*	string	* 필수	"assistant" 고정값.	-
`model`*	string	* 필수	요청한 모델 ID를 그대로 반환합니다.	-
`content`*	array	* 필수	콘텐츠 블록 배열. {type:"text", text} 또는 {type:"tool_use", id, name, input} 블록을 포함합니다.	-
`stop_reason`*	string	* 필수	생성 종료 사유. end_turn · max_tokens · tool_use.	-
`stop_sequence`*	string \| null	* 필수	일치한 중단 문자열(없으면 null).	-
`usage`*	object	* 필수	토큰 사용량. input_tokens, output_tokens, cache_read_input_tokens, cache_creation_input_tokens.	-

코드 예제

curl -X POST https://billing-ai.doublezero.kr/api/v1/messages \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-8",
    "max_tokens": 1024,
    "system": "당신은 도움이 되는 코딩 어시스턴트입니다.",
    "messages": [
      {"role": "user", "content": "피보나치 수열을 구하는 함수를 작성해 주세요."}
    ]
  }'

응답 예시

{
  "id": "msg_abc123",
  "type": "message",
  "role": "assistant",
  "model": "claude-opus-4-8",
  "content": [
    {
      "type": "text",
      "text": "다음은 피보나치 수열을 구하는 함수입니다..."
    }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 24,
    "output_tokens": 88,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0
  }
}

스트리밍

stream: true로 설정하면 Anthropic 네이티브 SSE로 응답합니다. 이벤트 순서는 message_start → content_block_start/content_block_delta/content_block_stop → message_delta → message_stop 이며, 약 15초 간격으로 ping keepalive 이벤트를 전송합니다.

참고사항

•max_tokens는 Anthropic 규격상 필수입니다(1~200000).
•에러는 Anthropic 형태 {type:"error", error:{type, message}}로 반환됩니다.
•top_k는 지원하지 않으며 무시됩니다. document 블록 입력도 지원하지 않습니다.