1. 개요
극지(极智) API는 개발자에게 Anthropic Messages API(/v1/messages) 호환 중계 액세스를 제공합니다. 요청을 본 사이트 게이트웨이로 보내고, 인증 키를 '사용자 센터 - API 키'에서 생성한 sk- 키로 교체하기만 하면 기존 코드를 수정할 필요 없이 Claude 시리즈 모델을 바로 사용할 수 있습니다.
현재 오픈된 모델은 모델 광장(Model Square) 기준을 따르며(예: 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 system 프롬프트 포함 및 다중 턴 대화
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 | 아니오 | 핵 샘플링, 기본값 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 | 요청이 너무 빈번하거나 속도 제한 초과 | 재시도(지수 백오프) |
| 500 | 서버 내부 오류 | 잠시 후 재시도; 실패가 지속되면 고객센터 문의 |
오류 응답 본문은 {"code": 상태코드, "message": "오류 설명", "data": null} 구조로 통일됩니다.
9. 사용량 및 잔액
- 모든 호출은 토큰 사용량 × 모델 단가 × 경로 배율에 따라 실시간으로 차감되며, 단가와 경로는
GET /v1/models에서 확인할 수 있습니다. - 로그인 후 '사용자 센터 → API 사용량'에서 호출 기록(모델, 토큰, 비용, 상태)을 확인할 수 있습니다.
- 잔액 부족 시 403 오류가 반환되며, 충전 후 즉시 정상화됩니다.
Base URL 설명: 본 사이트는 /v1beta/models/...와 /v1beta/v1beta/models/...(및 /v1/...와 /v1/v1/...)를 동시에 허용하므로, 클라이언트가 직접 /v1이나 /v1beta를 추가하더라도 호출에 영향을 주지 않습니다. Base URL은 도메인 루트를 입력하거나 /v1beta가 포함된 주소를 입력해도 모두 작동합니다. 모델 ID는 콘솔 '토큰' 페이지 오른쪽 상단 '모델 ID'에서 조회하여 복사하십시오.