Claude API를 Base URL 하나로 호출하기
Claude API 호출에 필요한 변경은 두 가지입니다. Base URL을 https://api.relayswitch.io/v1로, 키를 RelaySwitch 키로 바꾸면 Anthropic SDK와 OpenAI SDK를 코드 구조 그대로 쓸 수 있습니다. Claude 모델 13개가 같은 키에 있고 요금은 토큰당 선불로 차감됩니다.
01curl로 먼저 확인
SDK에 넣기 전에 curl 한 번으로 키와 주소를 확인하는 편이 빠릅니다. 코드 블록은 Anthropic Messages 형식의 최소 요청입니다. 응답 헤더에는 이 요청의 id가 들어 있고, 그 id로 서명된 영수증을 조회할 수 있습니다.
키는 x-api-key 헤더와 Authorization: Bearer 헤더 어느 쪽으로 보내도 됩니다. 다만 한 요청에 서로 다른 키 두 개를 실으면 400으로 거부됩니다.
curl -i https://api.relayswitch.io/v1/messages \ -H "Authorization: Bearer sk-relay-..." \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{"model": "claude-fable-5.1", "max_tokens": 16, "messages": [{"role": "user", "content": "Reply with ok"}]}'02Python: Anthropic SDK
Anthropic SDK에서는 base_url과 api_key 두 인자만 바꿉니다. SDK는 Base URL 뒤에 /v1/messages를 직접 붙이는데, 게이트웨이가 중복된 /v1을 처리하므로 예시는 모두 https://api.relayswitch.io/v1로 통일했습니다.
응답의 usage에 들어 있는 입력, 출력 토큰 수는 영수증의 숫자와 같습니다. 스트리밍은 stream을 true로 두면 server-sent events로 내려옵니다.
import anthropic client = anthropic.Anthropic(base_url="https://api.relayswitch.io/v1", api_key="sk-relay-...")reply = client.messages.create( model="claude-fable-5.1", max_tokens=300, messages=[{"role": "user", "content": "Reply with ok"}],)print(reply.content[0].text)print(reply.usage)03Python: OpenAI SDK
이미 OpenAI 형식으로 작성한 코드라면 구조를 바꿀 필요가 없습니다. base_url을 https://api.relayswitch.io/v1로 바꾸고 model에 Claude id를 넣으면 /chat/completions 경로로 같은 모델이 응답합니다. 두 형식은 같은 키, 같은 잔액을 쓰고 가격도 같습니다.
from openai import OpenAI client = OpenAI(base_url="https://api.relayswitch.io/v1", api_key="sk-relay-...")reply = client.chat.completions.create( model="claude-fable-5.1", messages=[{"role": "user", "content": "Reply with ok"}],)print(reply.choices[0].message.content)04Anthropic 형식과 OpenAI 형식 중 무엇을 쓸까
| 새로 작성하는 코드 | Anthropic SDK로 /messages를 씁니다. system 필드, tool use의 네이티브 구조, 프롬프트 캐시 표시 같은 Claude 고유 기능을 그대로 쓸 수 있습니다. |
| OpenAI 형식으로 작성된 기존 코드 | /chat/completions를 유지하고 model만 Claude id로 바꿉니다. |
| 같은 코드로 여러 개발사의 모델을 호출 | OpenAI 형식이 편합니다. model 값만 바꾸면 GPT, Gemini, DeepSeek도 같은 키로 응답합니다. |
| Claude Code, Cline 같은 코딩 도구 | 도구마다 쓰는 형식이 정해져 있습니다. Claude Code 설정과 영어 가이드 모음을 참고하십시오. |
05Claude 모델 가격
백만 토큰당 달러 가격이며 페이지를 렌더링할 때 카탈로그에서 읽습니다. 과금 단가는 입력, 캐시 입력, 출력 세 가지입니다. 긴 시스템 프롬프트나 반복해서 보내는 문서, 여러 턴의 대화 이력이 프롬프트 캐시에 적중하면 그 토큰은 입력 단가보다 낮은 캐시 입력 단가로 계산됩니다. 영수증에는 세 종류의 토큰 수가 따로 적혀 있어 요청 단위로 대조할 수 있습니다.
| 모델 | 개발사 | 입력 | 출력 | 컨텍스트 |
|---|---|---|---|---|
| Claude Fable 5.1claude-fable-5.1 | Anthropic | $6.00 | $30.00 | 1,000,000 |
| Claude Fable 5.2claude-fable-5.2 | Anthropic | $4.00 | $20.00 | 1,000,000 |
| Claude Fable 5claude-fable-5 | Anthropic | $3.00 | $15.00 | 1,000,000 |
| Claude Opus 5.5claude-opus-5-5 | Anthropic | $2.716 | $9.70 | 1,000,000 |
| Claude Sonnet 4.6claude-sonnet-4-6 | Anthropic | $1.80 | $9.00 | 1,000,000 |
| Claude Opus 4.6claude-opus-4-6 | Anthropic | $1.80 | $7.50 | 1,000,000 |
| Claude Opus 4.7claude-opus-4-7 | Anthropic | $1.80 | $7.50 | 1,000,000 |
| Claude Opus 4.8claude-opus-4-8 | Anthropic | $1.80 | $7.50 | 1,000,000 |
| Claude Opus 5claude-opus-5 | Anthropic | $1.80 | $7.50 | 1,000,000 |
| Claude Haiku 4.5claude-haiku-4-5 | Anthropic | $0.60 | $3.00 | 200,000 |
| Claude Sonnet 5claude-sonnet-5 | Anthropic | $1.20 | $3.00 | 1,000,000 |
| Claude Sonnet 5.5claude-sonnet-5-5 | Anthropic | $1.20 | $3.00 | 1,000,000 |
| Claude Haiku 5.5claude-haiku-5-5 | Anthropic | $0.0582 | $0.1455 | 1,000,000 |
백만 토큰당 가격(USD)
06오류 코드
오류 본문은 호출한 쪽의 형식(Anthropic 또는 OpenAI)에 맞는 오류 구조로 내려옵니다. 401부터 404까지는 요청이 모델에 도달하기 전에 반환되고, 429, 502, 503은 응답 내용이 없으므로 모두 과금되지 않습니다.
401 invalid_api_key | 키가 없거나 틀렸거나 폐기되었습니다. |
402 insufficient_balance | 잔액이 부족합니다. 키의 예산이나 사용 한도를 다 쓴 경우는 별도의 오류 코드로 구분됩니다. |
403 scope_denied | 키의 모델 허용 목록에 없는 id를 호출했습니다. |
404 model_not_found | 카탈로그에 없는 모델 id입니다. 대부분 오타입니다. |
429 rate_limited | 키의 속도 제한에 닿았습니다. retry-after 헤더가 기다릴 초 수를 알려 줍니다. |
502 upstream_error, 503 upstream_unavailable | 경로에서 오류가 났거나, 응답한 경로가 일시적으로 없습니다. |
07운영 환경에 올리기 전에
운영용 키는 따로 만들고 필요한 만큼 예산, 일일 사용 한도, 모델 허용 목록, IP 허용 목록을 설정하십시오. 분당 요청 수 한도는 키마다 조정할 수 있습니다. 실패한 요청은 retry-after 헤더를 보고 재시도 간격을 정하고, 오류에 포함된 요청 id는 로그에 남겨 두면 원인을 찾을 때 쓸 수 있습니다.
하나의 모델 id에는 여러 경로가 연결되어 있어, 한 경로가 5xx나 429를 반환하면 요청이 그 모델의 다음 경로로 자동으로 넘어가고 가격은 같습니다. 경로가 하나뿐인 모델은 503을 반환하므로 백오프 후 재시도하거나 다른 id로 바꾸십시오. 전체 API 레퍼런스는 영어 문서에 있습니다.
자주 묻는 질문
- Claude API를 쓰려면 Anthropic 콘솔 계정이 따로 필요한가요?
- 필요하지 않습니다. 계정과 잔액은 RelaySwitch에 있고, 키는 sk-relay- 로 시작합니다. 요청 본문, 모델 id, 스트리밍, tool use는 그대로 쓰며 코드에서 달라지는 것은 Base URL과 키뿐입니다.
- Base URL에 /v1을 넣어야 하나요?
- 넣습니다. https://api.relayswitch.io/v1 를 지정하면 SDK가 /messages 또는 /chat/completions 경로를 붙입니다.
- 스트리밍을 지원하나요?
- 지원합니다. 요청에 stream: true를 넣으면 server-sent events로 응답합니다. 카탈로그의 모든 모델이 스트리밍을 지원합니다.
- 요청 한 건의 비용은 어디서 확인하나요?
- 요청마다 서명된 영수증이 있습니다. GET https://api.relayswitch.io/v1/requests/:id/receipt 로 조회하면 모델 id, 과금 토큰, 비용이 나오고 공개 키로 오프라인 검증할 수 있습니다. 응답의 usage 값과 숫자가 같습니다.
- 경로 하나에 장애가 나면 어떻게 되나요?
- 한 경로가 5xx나 429를 반환하면 요청이 같은 모델의 다음 경로로 넘어가며 가격은 변하지 않습니다. 경로가 하나뿐인 모델은 503을 반환합니다.
- 프롬프트 내용이 저장되나요?
- 요청 내용은 모델로 전달만 하고 저장하지 않으며 학습에도 쓰지 않습니다.