다루는 내용과 다루지 않는 내용
이 가이드는 Claude Console에서 Anthropic API 키를 만들고, 첫 Messages API 요청을 보내고, 사용량을 확인하고, 흔한 오류를 처리하는 방법을 다룹니다.
이 가이드는 소비자용 Claude 요금제는 다루지 않습니다. 소비자용 요금제로 로그인해도 API 키를 받을 수 없습니다. API 사용량은 Console에서 별도로 청구됩니다. 요금제 세부 정보는 Claude 가격 페이지에서 확인하세요.
사전 준비
- 메일을 받을 수 있는 이메일 주소와 API 사용료를 결제할 수단(2단계 참조)
curl이 설치된 터미널- 키를 안전하게 보관할 곳(비밀번호 관리자나 시크릿 관리 서비스 등)
- 조직을 사용하는 경우 키를 만들 권한. "Create key" 버튼이 비활성화되어 있다면 역할에 권한이 없을 수 있으니 조직 관리자에게 문의하세요.
1단계: Console 계정 만들기
platform.claude.com에 접속해 가입하거나 로그인하세요. API 개요는 Claude Console 계정을 API 사용의 첫 번째 요건으로 안내합니다.
2단계: 결제 설정 및 사용량 기반 요금 이해하기
API 요청은 토큰 수에 따라 모델별 요율로 청구됩니다. 가격 페이지에는 모델별 요율이 백만 토큰(MTok)당 USD로 나와 있습니다. 요율은 바뀌므로 이 가이드에서는 숫자를 반복하지 않습니다. 프로젝트를 계획하기 전에 해당 페이지를 확인하세요.
Console의 Billing 페이지에서 크레딧을 구매하거나 결제 수단을 관리할 수 있습니다. 표준 계정에서는 주요 신용카드를 사용할 수 있습니다.
각 사용량 등급에는 월간 지출 한도(spend cap)가 있습니다. Spend limits 페이지에서 그보다 낮은 개인 한도를 설정할 수 있습니다. 지출 한도와 요청 속도 제한의 차이는 속도 제한 문서에 설명되어 있습니다.
3단계: API 키 만들기 및 한 번만 복사하기
- Console의 API keys 페이지를 엽니다.
- Create key를 클릭하고 이름을 입력한 뒤 만료 기간을 선택하고, Linked account를 본인 또는 서비스 계정으로 설정합니다. 워크스페이스를 선택할 수도 있습니다.
- 키를 바로 복사하세요. Console은 전체 키를 생성 시 한 번만 보여주며, 키는
sk-ant-로 시작합니다. 잃어버리면 다시 볼 수 없으니 새 키를 만드세요.
개인 키는 본인의 개발에, 서비스 계정 키는 CI 파이프라인이나 운영 서비스처럼 공유하는 용도에 사용하세요. 키는 시크릿 관리 서비스에 보관하고, 프로젝트 파일에 저장하지 마세요.
4단계: 첫 Messages API 호출
키는 셸 세션에서만 설정하고, 스크립트나 파일에 넣지 마세요. 그다음 아래 요청을 실행합니다.
# Set ANTHROPIC_API_KEY in this shell first, for example from your secrets manager.
# Never paste the key itself into a file, script or chat.
curl https://api.anthropic.com/v1/messages \
-H "content-type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1000,
"messages": [
{
"role": "user",
"content": "Say hello in one sentence."
}
]
}'
예시의 모델 ID는 공식 시작 가이드의 예시에서 가져왔습니다. 모델 ID는 바뀔 수 있으므로, 의존하기 전에 Console 또는 공식 모델 문서에 나온 ID로 바꾸세요. 성공하면 msg_로 시작하는 id와 텍스트가 담긴 content 배열이 포함된 JSON이 반환됩니다.
5단계: Console에서 사용량 확인하기
Claude Console에서 사용량을 추적할 수 있습니다. 테스트 요청 후 사용량 화면을 열어, 요청이 예상한 워크스페이스에 기록되었는지 확인하세요. 또한 Spend limits와 Billing 페이지도 확인하세요. 사용량 화면의 정확한 메뉴 위치는 확인한 자료에서 UNKNOWN이므로, Console 내비게이션에서 사용량 항목을 찾으세요.
키 보안
- 키를 커밋하지 마세요. Git, 티켓, 채팅, 스크린샷, 소스 코드에 넣지 마세요. 환경 변수나 시크릿 관리 서비스에서 불러오세요.
- 노출된 키는 교체하세요. 새 키를 만들고 애플리케이션을 업데이트한 뒤, API keys 페이지에서 이전 키를 삭제하세요.
- 프로젝트나 서비스마다 키 하나를 사용하세요. 키를 나누어 두면 하나를 교체해도 다른 키에 영향이 없습니다. 공유 워크로드에는 서비스 계정 키를 사용하세요.
- 브라우저에서 키를 사용하지 마세요. 직접적인 브라우저 호출을 제한하는 조직에서는 브라우저 요청이 401을 반환할 수 있습니다. API 요청은 자체 백엔드에서 보내세요.
문제 해결
오류 유형의 기준 자료는 공식 Claude API 오류 참조입니다. 먼저 응답의 상태 코드와 오류 유형을 확인하세요.
| 상태 | 오류 유형 | 확인할 내용 |
|---|---|---|
| 401 | authentication_error | 키 형식이 잘못되었거나, 폐기되었거나, 만료되었을 수 있습니다. echo "${#ANTHROPIC_API_KEY}"를 실행하면 길이만 표시됩니다. 0이면 이 셸에서 변수가 비어 있는 것입니다. 필요하면 새 키를 만드세요. |
| 402 | billing_error | Billing 페이지에서 결제 정보를 확인하세요. |
| 403 | permission_error | 키에 해당 리소스에 대한 권한이 없습니다. 조직 접근 권한과 워크스페이스 설정을 확인하세요. 키가 워크스페이스에 범위가 지정되지 않았다면 인증 문서에 anthropic-workspace-id 헤더가 설명되어 있습니다. 원인으로서의 지역 제한은 확인한 자료에서 UNKNOWN입니다. 인증 문서 |
| 404 | not_found_error | 엔드포인트 경로와 리소스 ID를 확인하세요. |
| 429 | rate_limit_error | 속도 제한이거나 월간 지출 한도입니다. 지수 백오프로 기다렸다가 재시도하고, retry-after 헤더가 있으면 따르세요. 지출 한도로 인한 429에는 retry-after가 없으며 액세스가 회복될 때까지 계속 실패합니다. Spend limits 페이지를 확인하세요. |
| 500 | api_error | 지수 백오프로 재시도하세요. 계속되면 요청 ID와 함께 지원팀에 문의하세요. |
| 504 | timeout_error | 긴 Messages API 요청에는 스트리밍을 사용하세요. |
| 529 | overloaded_error | 전체 트래픽으로 API가 일시적으로 과부하 상태입니다. 나중에 백오프를 두고 재시도하세요. |
공식 SDK는 일부 일시적 실패를 기본적으로 두 번까지 자동 재시도합니다. 속도 제한 문서는 제한이 시간에 따라 적용되는 방식을 설명합니다.
소비자용 Claude 계정 정지는 별도 사안
정지되었거나 제한된 소비자용 Claude 계정은 API 키와 별도로 처리됩니다. API 키를 만든다고 소비자용 계정의 상태가 바뀌지는 않습니다. 공식 Claude 도움말 센터의 안전 보호 경고 및 이의 제기 문서와 통지문의 안내를 따르세요. Cue는 제3자 계정을 복구하거나 우회할 수 없으며, 검토 결과를 약속할 수도 없습니다. 이 경우의 Cue 가이드는 Cue의 Claude 계정 정지 가이드를 참고하세요.
일상 업무를 위한 데스크톱 AI 어시스턴트. Cue로 메모, 문서, 작업을 정리하세요. Claude와 GPT 모델 옵션이 있습니다. 사용 가능한 모델과 한도는 Cue 계정에서 확인하고, Cue 이용약관도 읽어보세요. Cue는 Anthropic API 키를 발급할 수 없으며, Anthropic의 계정, 결제, 키 관련 결정을 바꿀 수 없습니다.
Claude 계정이 정지되어 어려움을 겪고 계신가요? Cue의 Claude 계정 정지 가이드를 참고하세요.