Anthropic API 키는 Claude API로 보내는 모든 요청과 함께 전송하는 자격 증명입니다. 이 키는 sk-ant-로 시작하며, Claude Console에서 생성하고, 조직의 선불 크레딧에서 사용량을 청구합니다. API 키를 다뤄본 적이 없다면, API 키란 무엇인가에 대한 저희의 입문서가 일반적인 개념을 다룹니다. 이 가이드는 구체적인 내용을 다룹니다: Console 계정 생성, 크레딧 충전, 올바른 범위로 키 생성, curl 및 Python SDK로 첫 번째 Messages 요청 전송, 그리고 이후 키를 안전하게 유지하는 방법입니다.
Anthropic의 공식 API 키 받기 페이지는 버튼이 어디 있는지 알려줍니다. 하지만 첫 번째 요청이 왜 401을 반환하는지, 현재 어떤 모델 ID가 사용되는지, 또는 셸 기록에 붙여넣지 않고 키를 테스트하는 방법을 알려주지는 않습니다. 나머지는 이 가이드에서 다룹니다.
시작하기 전에 필요한 것
- platform.claude.com (현재 console.anthropic.com으로 리디렉션됨)의 Claude Console에 사용할 이메일.
- 결제 카드. API는 선불이며, Admin 또는 Billing 역할만 크레딧을 구매할 수 있습니다.
- curl, 또는 SDK 예제를 위한 Python 3.10+ 버전.
- Apidog는 키를 로컬 변수로 저장하고 요청을 반복 가능한 테스트로 저장하는 데 사용됩니다. 무료 플랜은 최대 4명으로 구성된 팀을 지원합니다.
1단계: Claude Console 계정 생성
platform.claude.com에서 가입하세요. 이렇게 하면 기본 워크스페이스가 있는 조직이 생성되며, 키, 크레딧, 속도 제한이 모두 이 조직에 연결됩니다. 팀원이 이미 계정을 만들었다면, 두 번째 조직을 만드는 대신 초대를 요청하세요. 크레딧과 사용량 등급은 이전되지 않습니다.
2단계: 첫 호출 전에 크레딧 추가
네, 크레딧이 먼저입니다. Anthropic의 결제 문서는 명확합니다: API를 사용하기 전에 크레딧을 구매해야 하며, 잔액이 0이면 API도 플레이그라운드도 작동하지 않습니다. 신규 사용자는 테스트를 위한 소량의 무료 크레딧을 받으므로, 구매 전에 잔액을 확인하세요. 하지만 이는 계획이라기보다는 보너스로 생각하세요.
Settings > Billing을 열고 Buy credits를 클릭하세요. 자동 충전을 켜면 무인으로 실행되는 모든 것이 계속 작동합니다. 현재 단계는 크레딧 구매 방법을 참조하세요. 조직은 또한 월별 지출 한도가 있는 사용량 등급에 속하게 되며, 이는 속도 제한 섹션에서 다룹니다.
3단계: API 키 생성
Settings > API keys로 이동하여 Create key를 클릭하세요. 네 가지 선택 사항이 중요합니다:
- Name: 사람 이름이 아닌 앱 이름을 지정하세요.
my key보다orders-service-staging이 좋습니다. - Expiration: 3시간에서 30일, 사용자 지정 또는 Never. 테스트를 위해 짧은 기간을 선택하세요. 나중에 변경할 수 없습니다.
- Linked account: 개인 키의 경우 본인, 공유되는 모든 항목의 경우 서비스 계정. 개인 키는 조직을 떠나면 만료됩니다.
- Workspace: 하나의 워크스페이스로 범위를 지정하면
anthropic-workspace-id헤더를 건너뛸 수 있습니다. 다중 워크스페이스 키는 모든 요청에 해당 헤더를 보내야 하며, 그렇지 않으면 400 오류가 발생합니다.
Console은 전체 키를 정확히 한 번만 보여주므로, 즉시 비밀 관리자에 복사하세요. 공개 버튼은 없습니다. Create key가 회색으로 표시되어 있다면, 귀하의 역할로는 키를 생성할 수 없다는 의미이므로 관리자에게 문의하세요.
4단계: 모든 요청에 필요한 세 가지 헤더
POST https://api.anthropic.com/v1/messages에 대한 모든 호출은 세 가지 헤더를 포함합니다.
| 헤더 | 값 | 참고 |
|---|---|---|
x-api-key |
sk-ant-... 키 |
Authorization: Bearer <key>도 작동하며 현재 문서화된 기본 형식입니다. x-api-key는 레거시 대체 방식이지만 여전히 지원됩니다. |
anthropic-version |
2023-06-01 |
필수. 응답 형식을 고정합니다. 날짜는 안정적이며 모델 릴리스와 연결되지 않습니다. |
content-type |
application/json |
JSON 본문에 필수입니다. |
공식 SDK는 이 세 가지를 모두 자동으로 전송합니다. 순수 HTTP 및 API 클라이언트는 이를 명시해야 하며, 대부분의 첫 요청 실패는 여기서 발생합니다. 전체 참조: Claude API 개요.
5단계: 첫 Messages 요청 보내기
본문에는 model, max_tokens, messages가 필요합니다. 현재 모델 ID를 사용하세요. 2026년 9월 기준으로 이는 claude-opus-5 (권장 기본값), claude-fable-5-1 (가장 성능 좋은), claude-sonnet-5, claude-haiku-4-5입니다. 이전 3.x 및 4.x ID는 404를 반환하거나 사용 중지된 모델을 가리키며, 현재 ID에는 날짜 접미사가 없습니다. Claude Opus 5 API 워크스루는 사고, 노력, 스트리밍에 대해 더 깊이 다룹니다.
curl
export ANTHROPIC_API_KEY="sk-ant-api03-..."
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "Write a one-sentence OpenAPI description for POST /orders, which creates an order and returns 201."}
]
}'
성공적인 응답 (일부 생략):
{
"id": "msg_01...",
"role": "assistant",
"model": "claude-opus-5",
"content": [{"type": "text", "text": "Creates a new order and returns it with a 201 status."}],
"stop_reason": "end_turn",
"usage": {"input_tokens": 31, "output_tokens": 24}
}
content[].text에서 텍스트를 읽고, stop_reason이 end_turn인지 확인하며, usage는 비용 추적을 위해 보관합니다. request-id 응답 헤더는 문제가 발생했을 때 지원팀에서 요청하는 정보입니다.
Python SDK
pip install anthropic
import anthropic
client = anthropic.Anthropic() # reads ANTHROPIC_API_KEY from the environment
message = client.messages.create(
model="claude-opus-5",
max_tokens=1024,
messages=[{
"role": "user",
"content": "Write a one-sentence OpenAPI description for POST /orders, which creates an order and returns 201.",
}],
)
for block in message.content:
if block.type == "text":
print(block.text)
SDK는 ANTHROPIC_API_KEY를 읽고, 버전 및 콘텐츠 유형 헤더를 추가하며, 429 및 5xx 오류 발생 시 백오프와 함께 두 번 재시도합니다. 키를 문자열 리터럴로 전달하지 마세요. 환경 변수를 사용하는 것이 핵심입니다.
6단계: Apidog에 키 저장 및 테스트
셸에 붙여넣은 키는 기록 파일에 남습니다. 공유 요청에 저장된 키는 팀원들과 동기화됩니다. Apidog는 이 두 가지를 분리합니다: 요청 구조는 공유되지만, 비밀은 사용자 컴퓨터에 유지됩니다.
키를 로컬 변수로 저장하세요. Environment Management를 열고, Anthropic이라는 환경을 생성한 후, ANTHROPIC_API_KEY 변수를 추가하세요. 공유 값은 SET_LOCALLY로 두고 실제 키를 로컬 값에 붙여넣으세요. 이 값은 클라이언트 캐시에 남아 절대 동기화되지 않습니다. Apidog 환경 및 비밀 변수 가이드에서 범위 규칙을 다룹니다.
헤더를 한 번만 설정하세요. 동일한 패널에서 Headers 아래에 두 개의 전역 매개변수를 추가하세요: x-api-key를 {{ANTHROPIC_API_KEY}}로 설정하고, anthropic-version을 2023-06-01로 설정하세요. 이들은 프로젝트의 모든 요청에 적용되며, Apidog는 JSON 본문에 대해 자동으로 content-type을 추가합니다.
첫 요청을 보내세요. 새 요청을 만들고, https://api.anthropic.com/v1/messages로 POST하며, curl 예제에서 JSON 본문을 붙여넣고 전송하세요. Actual Request 탭을 열어 두 헤더가 변수가 해결된 상태로 전송되었는지 확인하세요. 이 탭은 401 오류가 키 문제가 아니라 헤더 문제임을 가장 빠르게 증명하는 방법입니다.
테스트로 저장하세요. 요청을 엔드포인트 케이스로 저장한 다음, 세 가지 어설션을 추가하세요: 상태가 200과 같고, stop_reason이 end_turn과 같으며, usage.output_tokens가 0보다 큰지 확인합니다. Apidog CLI에서 실행하고 런타임에 CI 비밀 저장소에서 키를 주입하세요. 이는 키, 헤더, 모델 ID에 대한 원클릭 스모크 테스트입니다. 따라 하려면 Apidog를 다운로드하세요. 무료 플랜에는 4개의 좌석이 포함됩니다.
속도 제한 및 요청 비용
제한은 조직별, 모델별로 적용됩니다: 분당 요청 수(RPM), 분당 입력 토큰 수(ITPM), 분당 출력 토큰 수(OTPM). 캐시되지 않은 입력만 ITPM에 포함되므로, 프롬프트 캐싱은 등급 변경 없이 처리량을 증가시킵니다. 속도 제한 문서에서:
| 등급 | 월별 지출 한도 | Claude Opus 5 (RPM / ITPM / OTPM) | Claude Fable 5.x (RPM / ITPM / OTPM) |
|---|---|---|---|
| Start | $500 | 1,000 / 2M / 400K | 1,000 / 500K / 100K |
| Build | $1,000 | 5,000 / 5M / 1M | 2,000 / 1.5M / 300K |
| Scale | $200,000 | 10,000 / 10M / 2M | 4,000 / 4M / 800K |
| Custom | 없음 | 협상 | 협상 |
Sonnet 5와 Haiku 4.5는 각 등급에서 Opus 5와 동일한 숫자를 공유합니다. 모든 응답에는 anthropic-ratelimit-*-remaining 및 -reset 헤더가 포함되어 있어, Console을 폴링하지 않고도 여유 공간을 확인할 수 있습니다.
가격 페이지에 따르면, 백만 토큰당: Opus 5는 입력 $5 / 출력 $25, Sonnet 5는 $2 / $10, Fable 5.1은 $10 / $50, Haiku 4.5는 $1 / $5입니다. 캐시 읽기는 입력 비용의 10% (Fable 5.1에서는 2.5%)이며, Batch API는 양쪽을 절반으로 줄입니다. 첫 curl 요청 비용은 1센트 미만입니다.
일반적인 오류 및 해결 방법
오류는 error.type 및 request_id를 포함하는 JSON 형태로 반환됩니다. 오류 참조에는 모든 코드가 나열되어 있으며, 다음은 가장 먼저 접하게 될 오류입니다.
| 상태 및 유형 | 일반적인 원인 | 해결 방법 |
|---|---|---|
401 authentication_error |
키가 잘못되었거나, 취소되었거나, 만료되었거나, 환경 변수가 비어 있음 | echo $ANTHROPIC_API_KEY를 실행하고 후행 공백을 확인합니다. 만료되었다면 새 키를 생성합니다. |
400 invalid_request_error |
max_tokens 누락, 잘못된 JSON, anthropic-workspace-id가 없는 다중 워크스페이스 키, 4.7+ 모델에서 thinking.type: enabled 사용, 또는 설정한 지출 한도 도달 |
error.message를 읽으세요. 필드 또는 한도를 명시합니다. |
404 not_found_error |
모델 ID 오타, 날짜 접미사가 붙은 추측, 사용 중지된 모델, 잘못된 경로 | 현재 모델 테이블에서 ID를 사용하고 경로가 /v1/messages인지 확인합니다. |
402 billing_error |
결제 또는 크레딧 문제 | Settings > Billing을 확인합니다. |
429 rate_limit_error |
RPM, ITPM 또는 OTPM을 초과했습니다. | retry-after에 지정된 시간만큼 기다린 후 다시 시도합니다. retry-after 헤더가 없으면 해당 등급의 월별 지출 한도에 도달한 것입니다 (error_code: enforced_spend_limit_reached). |
500 api_error / 529 overloaded_error |
Anthropic 측 오류 또는 높은 트래픽 | 백오프와 함께 재시도합니다. request_id를 보관합니다. |
키 관리: 순환, 범위 지정, 클라이언트 코드에 절대 포함하지 않기
브라우저나 모바일 앱에 키를 절대 포함하지 마세요. JavaScript 번들이나 APK에 있는 모든 것은 몇 분 안에 공개됩니다. 호출을 자체 백엔드 뒤에 두세요. Claude를 직접 호출해야 하는 Apple 앱의 경우, 정적 키 대신 App Attest가 검증된 빌드에 단기 토큰을 발급합니다.
앱 및 환경별로 하나의 키를 사용하세요. 별도의 워크스페이스에 스테이징 및 프로덕션 키를 분리하면 스테이징 지출을 제한하고, 다른 키에 영향을 주지 않고 하나를 취소할 수 있습니다.
정기적으로 순환하세요. 새 키를 생성하고 배포한 다음, 작동하는지 확인한 후 이전 키를 삭제하세요. Disable은 되돌릴 수 있지만, Delete는 영구적입니다. 유출이 의심되면 먼저 비활성화하고 나중에 조사하세요. 리포지토리의 비밀 스캐너는 누군가 알아채기 전에 커밋된 키를 잡아냅니다.
프로덕션에서는 단기 자격 증명을 선호하세요. 워크로드 아이덴티티 연동(Workload Identity Federation)은 클라우드 제공업체의 아이덴티티 토큰을 단기 Claude 토큰으로 교환하므로, 유출될 sk-ant- 문자열 자체가 없습니다.
FAQ
Anthropic API 키와 Claude API 키는 동일한가요?
네, 동일합니다. Console, SDK, 문서 모두 이제 "Claude API"라고 지칭하며, 키 형식과 헤더는 동일합니다. "Anthropic API 키"라고 말하는 이전 튜토리얼도 동일한 자격 증명을 의미합니다.
Anthropic API 키를 무료로 받을 수 있나요?
키 생성은 무료입니다. 사용은 선불 크레딧에서 차감되며, Anthropic의 가격 페이지에 따르면 신규 사용자는 테스트를 위한 소량의 무료 크레딧을 받습니다. 비용 지불 없이 실제 워크로드를 실행하려는 경우, 무료 Claude API 액세스에 대한 솔직한 분석을 먼저 읽어본 후 결정하는 것이 좋습니다.
Claude Pro 또는 Max 구독에 API 액세스가 포함되나요?
아니요. Claude.ai 구독과 Console API 크레딧은 별도로 청구됩니다. Claude.ai에 이미 비용을 지불하고 있더라도 크레딧이 있는 Console 조직이 필요합니다.
키가 만료되면 어떻게 되나요?
요청은 401 authentication_error를 반환합니다. 만료된 키는 재활성화할 수 없으므로, 새 키를 생성하고 환경 변수를 업데이트하세요. Anthropic은 충분히 긴 유효 기간을 가진 키에 대해 만료 7일 전과 1일 전에 키 생성자에게 이메일을 보냅니다.
다음 단계
7일 만료 키를 생성하여 Apidog 로컬 변수에 넣고, 스모크 테스트를 실행한 다음 코드를 연결하세요. 이 단계가 통과하면 자격 증명, 헤더 및 모델 ID가 모두 올바른 것이므로, 그 이후의 모든 401 오류는 오타가 아닌 실제 문제입니다.