클로드 API 키 발급 방법 — 공식 경로와 게이트웨이 경로

클로드 API 키를 받는 경로는 두 가지입니다. Anthropic 콘솔에서 직접 발급받는 공식 경로와, Anthropic 호환 엔드포인트를 제공하는 게이트웨이에서 받는 경로입니다. 둘 다 같은 Claude 모델을 호출하고, 코드에서 달라지는 것은 base URL과 키 문자열뿐입니다.

아래에서는 두 경로를 모두 정리하고, 한국에서 특히 자주 막히는 결제 문제도 같이 다룹니다.

경로 1 — Anthropic 콘솔에서 직접 발급

Anthropic 계정을 만들고, 결제 수단을 등록한 뒤 콘솔에서 API 키를 생성합니다. 이 경로의 키는 Anthropic 정가로 청구되며, 공식 문서와 지원을 그대로 받을 수 있다는 것이 장점입니다.

한국에서 막히는 지점은 대부분 결제 단계입니다. 해외 결제가 차단된 카드는 등록이 되지 않으므로, 카드사 앱에서 해외 결제를 허용한 뒤 다시 시도하면 대부분 해결됩니다.

경로 2 — 게이트웨이 키

Anthropic 계정 없이 Claude 모델을 호출하는 방법입니다. Kunavo는 Anthropic Messages API와 OpenAI 호환 API를 모두 제공하므로, 기존 코드에서 base URL과 키만 바꾸면 됩니다.

이 경로는 결제 단계에서도 덜 막힙니다. Kunavo 선불 충전은 결제 화면이 원화로 표시되면 카카오페이, 네이버페이, PAYCO, 삼성페이, 해외 결제가 열리지 않은 국내 카드를 결제 수단으로 제공합니다(토스페이는 제공되지 않습니다). 충전한 잔액은 Claude API 호출에 쓰이며, Anthropic 구독 요금을 내는 수단은 아닙니다.

# OpenAI SDK를 그대로 쓰면서 base_url만 바꾸는 방식.
# 코드에서 바뀌는 줄은 base_url 한 줄뿐입니다.
from openai import OpenAI

client = OpenAI(
    base_url="https://api.kunavo.com/v1",
    api_key="sk-kn-...",
)

resp = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "안녕하세요"}],
)
print(resp.choices[0].message.content)

Anthropic 네이티브 형식을 쓰던 코드라면 base URL을 https://api.kunavo.com으로 두면 됩니다 — 이 경우 /v1을 붙이지 않습니다. 두 형식의 차이는 ANTHROPIC_BASE_URL 문서에 정리돼 있습니다.

요율

요율은 페이지가 렌더링될 때 카탈로그에서 읽어오므로 이 문서가 실제 청구액과 어긋날 수 없습니다. 결제 수단과 국내 카드 관련 내용은 Claude API 가격·결제에 더 자세히 정리돼 있습니다.

발급 후 30초 점검

키를 받았으면 바로 한 번 호출해 보세요. 이 확인을 먼저 해두면, 이후에 나는 오류가 키 문제인지 아닌지를 곧바로 가를 수 있습니다.

# 발급받은 키가 실제로 동작하는지 확인하는 최소 요청.
# 200이 오면 키는 정상입니다.
curl -sS https://api.kunavo.com/v1/messages \
  -H "Authorization: Bearer sk-kn-..." \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":32,
       "messages":[{"role":"user","content":"안녕하세요"}]}'

200이 오면 키는 정상입니다. 401이면 인증 헤더 종류가 어긋난 경우가 대부분이고, 429는 속도 제한, 529는 업스트림 과부하로 키와 무관합니다. 각 오류의 대응은 클로드 코드 오류 정리에 있습니다.

키를 나눠 쓰기

용도별로 키를 나누는 편이 안전합니다. 하나를 폐기해도 나머지는 영향을 받지 않고, 키마다 월 사용 한도를 걸어둘 수도 있습니다. 한도는 요청이 실행되기 전에 확인되고 매월 초에 초기화되므로, 사람이 지켜보지 않는 에이전트에 키를 넘길 때 특히 유용합니다.

자주 묻는 질문