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

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

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

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

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

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

경로 2 — 게이트웨이 키

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

# 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-4-6",
    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-4-6","max_tokens":32,
       "messages":[{"role":"user","content":"안녕하세요"}]}'

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

키를 나눠 쓰기

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

FAQ