Claude API 연동 가이드: Anthropic 네이티브 인터페이스 및 키 설정

1. 개요

极智API(AzzTimes)는 개발자분들께 Anthropic Messages API(/v1/messages)와 호환되는 중계 접속 서비스를 제공합니다. 요청을 본 사이트 게이트웨이로 보내고, 인증 키를 「사용자 센터 - API 키」에서 생성한 sk- 키로 교체하기만 하면 기존 코드를 수정할 필요 없이 Claude 시리즈 모델을 바로 사용할 수 있습니다.

현재 제공되는 모델은 모델 광장을 기준으로 합니다(예: claude-sonnet-5, claude-opus-5, claude-sonnet-4-6, claude-opus-4-8 등). 전체 목록과 단가는 언제든지 GET /v1/models를 통해 조회할 수 있습니다.

2. 인터페이스 주소

메서드	경로	설명
POST	/v1/messages	중계 전달 진입점, 요청 본문은 Anthropic /v1/messages 페이로드와 동일
GET	/v1/models	모델 및 단가 목록 (인증 불필요)

게이트웨이 주소: https://www.relay-api.com. 요청 경로는 위 표에 따라 작성하십시오.

3. 인증 방식

「사용자 센터 → API 키」에서 sk-xxxxxxxx 형식의 키를 생성하십시오. 호출 시 다음 방식 중 하나를 사용하여 전달합니다:

• Authorization 헤더: Authorization: Bearer sk-내키 (권장, 대부분의 SDK와 호환)
• x-api-key 헤더: x-api-key: sk-내키

키가 유효하지 않거나, 정지되었거나, 잔액이 부족하면 401 / 403 오류가 반환됩니다. 먼저 키 상태와 계정 잔액을 확인해 주십시오.

4. 빠른 시작 (curl)

4.1 비스트리밍 대화

curl -X POST https://www.relay-api.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-내키" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "너 자신을 한 문장으로 소개해줘"}
    ]
  }'

4.2 시스템 프롬프트 및 멀티턴 대화

curl -X POST https://www.relay-api.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk-내키" \
  -d '{
    "model": "claude-opus-5",
    "max_tokens": 2048,
    "system": "당신은 엄격한 기술 문서 엔지니어입니다.",
    "messages": [
      {"role": "user", "content": "Claude Messages API의 인증 헤더는 무엇인가요?"},
      {"role": "assistant", "content": "x-api-key 또는 Authorization: Bearer를 사용하여 키를 전달합니다."},
      {"role": "user", "content": "스트리밍 요청 예시를 하나 더 들어줘."}
    ],
    "metadata": {"request_id": "demo-001"}
  }'

metadata.request_id는 사용량 로그에 기록되어 「사용자 센터 → 사용량 명세」에서 정산 내역을 확인할 때 유용합니다.

5. 요청 매개변수

필드	타입	필수	설명
model	string	예	모델 slug, 예: claude-sonnet-5
max_tokens	int	예	최대 출력 토큰 수, 1~64000 권장
messages	array	예	대화 메시지, 요소는 {role, content}, role은 user / assistant 사용
system	string	아니오	시스템 프롬프트
temperature	number	아니오	샘플링 온도, 기본값 1.0, 범위 0~1
top_p	number	아니오	핵 샘플링(Nucleus sampling), 기본값 0.999
stream	bool	아니오	스트리밍 반환 여부, 기본값 false
stop_sequences	array	아니오	중단 시퀀스
metadata.request_id	string	아니오	정산을 위한 사용자 정의 요청 ID

6. 응답 구조

비스트리밍 요청은 표준 Anthropic Messages 구조를 반환합니다:

{
  "id": "msg_01ABCDEFG",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-5",
  "content": [
    {"type": "text", "text": "안녕하세요! 저는 Claude입니다."}
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 12,
    "output_tokens": 18,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0
  }
}

필드	설명
id	메시지 고유 ID
content[].type	콘텐츠 블록 타입, text / thinking 등
content[].text	텍스트 내용
stop_reason	중단 사유: end_turn / max_tokens / stop_sequence
usage.input_tokens	입력 토큰 수 (과금 기준)
usage.output_tokens	출력 토큰 수 (과금 기준)
usage.cache_read_input_tokens	캐시 적중 입력 토큰 수 (캐시 읽기 요금 적용)
usage.cache_creation_input_tokens	캐시 생성 토큰 수 (캐시 쓰기 요금 적용)

7. 스트리밍 출력

요청 본문에 "stream": true를 추가하면, 서버가 SSE(Server-Sent Events)를 통해 데이터를 조각별로 반환하며 이벤트 타입은 Anthropic과 동일합니다:

event: message_start
data: {"type": "message_start", "message": {"id": "msg_...", "model": "claude-sonnet-5"}}

event: content_block_delta
data: {"type": "content_block_delta", "delta": {"type": "text_delta", "text": "안녕하세요"}}

event: message_delta
data: {"type": "message_delta", "delta": {"stop_reason": "end_turn"}, "usage": {"output_tokens": 18}}

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

클라이언트는 data: 행에 따라 JSON을 파싱해야 하며 event: 행과 빈 줄은 무시하십시오. message_stop을 수신하면 스트림이 종료된 것입니다. 요금은 서버 측에서 전체 요청의 usage를 기준으로 정산되며 스트리밍 여부와는 무관합니다.

8. 일반적인 오류 코드

HTTP 상태 코드	의미	처리 제안
400	요청 매개변수 오류 (model/max_tokens 누락, 모델 미활성화 등)	응답 message를 확인하여 요청 본문 수정
401	API 키 누락 또는 유효하지 않음	Authorization / x-api-key 헤더 확인
403	키 정지, 잔액 부족 또는 모델/경로 권한 없음	충전, 키 상태 확인 또는 키 권한 조정
404	요청한 모델이 존재하지 않음	GET /v1/models로 사용 가능한 모델 확인
429	요청이 너무 빈번함 (레이트 리밋)	지수 백오프(Exponential Backoff)를 통한 재시도
500	서비스 내부 오류	잠시 후 재시도; 지속 시 고객센터 문의

오류 응답 본문은 일관되게 {"code": 상태코드, "message": "오류설명", "data": null} 구조를 가집니다.

9. 사용량 및 잔액

• 모든 호출은 토큰 사용량 × 모델 단가 × 경로 배율에 따라 실시간 차감되며, 단가와 경로는 GET /v1/models에서 확인할 수 있습니다.
• 로그인 후 「사용자 센터 → API 사용량」에서 호출 기록(모델, 토큰, 비용, 상태)을 확인할 수 있습니다.
• 잔액 부족 시 호출 시 403 오류가 반환되며, 충전 후 즉시 정상화됩니다.