Claude API 시작하기: 키 발급부터 첫 호출, 가격까지

한눈에 요약

Claude API는 Claude Console(platform.claude.com) 계정과 API 키로 써요. Claude Pro/Max 구독에는 API 사용이 포함되지 않고 별도로 청구돼요.
키는 Console의 Settings > API keys에서 만들어요. sk-ant-로 시작하고, 만들 때 한 번만 전체가 보여요.
키를 환경변수 ANTHROPIC_API_KEY에 넣으면 SDK가 자동으로 읽어요. 키를 코드에 직접 적지 마세요.
모델 ID는 claude-opus-5-5, claude-sonnet-5-5, claude-haiku-5-5, claude-fable-5-1이에요.
가격은 100만 토큰당 입력/출력 기준으로 Opus 5.5 $4/$20, Sonnet 5.5 $2/$10이에요 (2026-10-10 기준).
예제의 모델 ID만 바꿔 돌릴 때 모델마다 막히는 파라미터가 달라요. Opus 5.5는 thinking을 끌 수 없고, Haiku 5.5는 budget_tokens와 샘플링 파라미터가 400 오류예요. 자세한 표는 빠른 참조표에 있어요.

이 튜토리얼로 할 수 있게 되는 것

Console에서 API 키를 만들고 안전하게 보관할 수 있어요.
curl로 Messages API를 직접 호출해 응답 구조를 읽을 수 있어요.
Python SDK로 같은 호출을 하고, 시스템 프롬프트와 모델을 바꿔 볼 수 있어요.
모델별 가격과 절약 수단(Batch API, 프롬프트 캐시)을 이해하고 모델을 고를 수 있어요.

먼저 알아둘 개념

용어	뜻
Claude Console	API 키와 결제를 관리하는 개발자용 콘솔이에요 (platform.claude.com). claude.ai 구독과는 별개예요.
API 키	호출을 인증하는 비밀 문자열이에요. `sk-ant-`로 시작해요.
Messages API	`POST https://api.anthropic.com/v1/messages`로 대화를 보내고 답을 받는 기본 API예요.
토큰	가격 계산의 단위예요. 응답의 `usage`에 입력·출력 토큰 수가 나와요.
SDK	공식 클라이언트 라이브러리예요. 환경변수에서 키를 자동으로 읽어요.

Console의 Playground

예전에 Workbench라고 부르던 화면이 2026-08-18부터 Playground로 이름이 바뀌었어요(platform.claude.com/playground). Messages API의 모든 파라미터를 지원하고, 실행마다 SDK 요청 전체와 API 응답을 보여 줘서 코드를 쓰기 전에 요청을 시험해 보기 좋아요. 옛 글에서 “Workbench”라는 말을 보면 같은 화면이라고 생각하면 돼요.

API 키의 종류

종류	설명
개인(personal) 키	내 계정 기준이에요. 조직을 떠나면 무효가 돼요.
서비스 계정 키	CI·프로덕션·에이전트용이에요. 공유 용도로 권장돼요.
워크스페이스 키	레거시예요.

속도 제한은 사용 티어(Start, Build, Scale, Custom)로 정해지고 조직이 사용 이력에 따라 자동 배치돼요(공식 Rate limits 문서, 2026-10-10). 월 지출 상한은 Start $500, Build $1,000, Scale $200,000이고, 모델별 분당 요청·토큰 한도는 티어마다 달라요. 예를 들어 Start 티어의 Sonnet 5.5는 분당 요청 1,000, 입력 토큰 2,000,000, 출력 토큰 400,000이에요. 새 조직은 이보다 낮은 Evaluation 티어에서 시작할 수 있어요. 크레딧 충전은 공식 결제 도움말에 따라 Admin 또는 Billing 역할로 Console에 로그인해 Settings > Billing에서 “Buy credits”를 누르고 금액을 입력해 확정해요. 구매한 크레딧은 바로 적용돼요(2026-10-13 확인). 청구서(인보이스) 계약 조직은 월 단위로 청구돼요. 결제 수단 등록 화면은 Console 안내를 따르세요.

단계별 따라하기

0/6 완료

Console에 가입하고 로그인했어요
API 키를 만들어 안전한 곳에 저장했어요
ANTHROPIC_API_KEY 환경변수를 설정했어요
curl로 첫 호출을 성공했어요
Python SDK로 첫 호출을 성공했어요
시스템 프롬프트를 넣어 보고 모델을 바꿔 봤어요

Console에서 API 키 만들기

platform.claude.com에 가입하거나 로그인해요. 설정(Settings) > API keys(https://platform.claude.com/settings/keys)에서 Create key를 눌러요. 이름, 만료, 연결할 계정(Linked account: 본인 또는 서비스 계정), 필요하면 워크스페이스를 정해요.

이 단계에서 보게 될 화면
Console의 Settings > API keys에서 Create key를 누른 화면
공식 도움말에서 이 화면 보기 ↗
실제 화면은 서비스 업데이트에 따라 다를 수 있어요
API 키 만드는 길
1. platform.claude.com (Console)가입 또는 로그인
2. 설정(Settings) > API keysCreate key 누르기
3. 키 만들기 입력이름·만료·Linked account 정하기→ sk-ant- 키가 한 번만 표시돼요. 바로 저장하세요
단순화한 흐름도예요. 실제 화면은 공식 도움말에서 확인하세요.
sk-ant-로 시작하는 키는 생성할 때 한 번만 전체가 표시돼요. 잃어버리면 새로 만들어야 해요. 비밀번호 관리자 같은 안전한 곳에 바로 저장하세요.
환경변수에 키 넣기

키를 코드나 저장소에 직접 적지 말고 환경변수로 넣어요. SDK는 ANTHROPIC_API_KEY를 자동으로 읽어요.
터미널 창
```
export ANTHROPIC_API_KEY="your-api-key-here"
```
키가 들어 있는 코드를 GitHub 같은 곳에 올리면 누구나 내 계정으로 호출해 요금을 발생시킬 수 있어요. 코드에는 os.environ이나 SDK의 자동 읽기만 쓰고, 키가 든 파일(예: .env)은 .gitignore에 넣으세요. 키가 노출됐다면 Console에서 그 키를 삭제하고 새로 만드세요. 채팅이나 스크린샷에도 붙여넣지 마세요.
curl로 첫 호출하기

공식 quickstart의 예시예요. 직접 HTTP로 호출할 때는 x-api-key 헤더와 anthropic-version: 2023-06-01 헤더가 필요해요.
터미널 창
```
curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 1000,
    "messages": [
      {
        "role": "user",
        "content": "What should I search for to find the latest developments in renewable energy?"
      }
    ]
  }'
```
응답은 JSON이에요. 답변은 content 배열의 type이 text인 블록에 있고, 끝난 이유는 stop_reason, 토큰 수는 usage(input_tokens, output_tokens)에 있어요.

이 단계에서 보게 될 화면
curl 응답 JSON (content, stop_reason, usage)
공식 도움말에서 이 화면 보기 ↗
실제 화면은 서비스 업데이트에 따라 다를 수 있어요

Python으로 첫 호출하기

가상환경을 만들고 SDK를 설치해요.

mkdir claude-quickstart && cd claude-quickstart
python3 -m venv .venv && source .venv/bin/activate
pip install anthropic

quickstart.py 파일을 만들어요. 키는 코드에 없고, SDK가 환경변수에서 읽어요.

import anthropic

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1000,
    messages=[
        {
            "role": "user",
            "content": "What should I search for to find the latest developments in renewable energy?",
        }
    ],
)

for block in message.content:
    if block.type == "text":
        print(block.text)

python quickstart.py

시스템 프롬프트와 모델 바꿔 보기

시스템 프롬프트는 최상위 system 필드로 전달해요. 비용을 줄이고 싶으면 model을 claude-sonnet-5-5나 claude-haiku-5-5로 바꿔 보세요. 아래는 위 예제를 바꾼 예시예요.
```
message = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=1000,
    system="You are a helpful assistant. Answer in Korean.",
    messages=[
        {"role": "user", "content": "재생 에너지 최신 동향을 알려면 무엇을 검색해야 하나요?"}
    ],
)
```
이 프롬프트를 복사해서 붙여넣으세요
위 quickstart.py에 시스템 프롬프트를 넣어서, 답변을 항상 세 줄 이내 한국어로 하게 바꿔 주세요. 키는 코드에 넣지 말고 환경변수에서 읽게 해 주세요.

빠른 참조표

모델 ID와 가격 (100만 토큰당 입력/출력, 2026-10-10 기준)

가격은 미국 달러 기준이에요. 자세한 내용은 공식 pricing 페이지를 확인하세요.

모델	모델 ID	입력 / 출력
Fable 5.1	`claude-fable-5-1`	$10 / $50
Opus 5.5	`claude-opus-5-5`	$4 / $20
Sonnet 5.5	`claude-sonnet-5-5`	$2 / $10
Haiku 5.5	`claude-haiku-5-5`	$0.10부터 / $0.50부터

Batch API는 50% 할인이에요.
프롬프트 캐시 읽기는 기본 입력가의 10%예요. 단 Fable 5.1은 2.5%, Opus 5.5와 Sonnet 5.5는 5%예요.
모델 선택 기준은 C1, 모델을 나눠 써서 비용을 줄이는 방법은 C15를 보세요.

요청 필수 요소 (직접 HTTP 호출)

항목	값
주소	`POST https://api.anthropic.com/v1/messages`
헤더	`content-type: application/json`, `x-api-key: $ANTHROPIC_API_KEY`, `anthropic-version: 2023-06-01`
본문	`model`, `max_tokens`, `messages` (시스템 프롬프트는 `system`)

모델별 요청 제한 (400 오류 주의, 2026-10-11 기준)

예제의 model만 바꿔 쓰면 아래 이유로 400 오류가 날 수 있어요. 공식 릴리스 노트 기준이에요.

모델	제한
Opus 5.5	thinking을 끌 수 없어요. `thinking: {"type": "disabled"}`와 `{"type": "enabled", ...}`는 400 오류예요. `thinking` 필드를 빼고 `effort`로 깊이를 조절하세요. `tool_choice`의 `any`, `tool`도 400 오류라서 `auto`와 strict tool use를 쓰세요.
Sonnet 5.5	`tool_choice`의 `any`, `tool`은 400 오류예요. `auto`와 strict tool use를 쓰세요. (샘플링 파라미터 400 제약은 Sonnet 5.5가 아니라 이전 세대 Sonnet 5와 Haiku 5.5에 해당해요.)
Fable 5.1, Mythos 5.1	`tool_choice`의 `any`, `tool`은 지원되지 않고 400 오류예요(`auto`, `none`은 그대로). 스키마에 맞는 도구 입력이 필요하면 strict tool use를 쓰세요.
Haiku 5.5	Haiku 4.5 방식 코드가 깨질 수 있어요. `budget_tokens`(수동 확장 사고), `temperature`·`top_p`·`top_k`, assistant 메시지 prefill이 각각 400 오류를 낼 수 있어요. 적응형 사고가 기본이라 응답이 `thinking` 블록으로 시작할 수 있고, 그 텍스트는 `thinking.display`를 `"summarized"`로 정하지 않으면 생략돼요.

데이터 보관: Fable 5.1과 Mythos 5.1은 Fable 5처럼 30일 데이터 보관이 필요하고, Anthropic이 명시적으로 허용하지 않는 한 ZDR(zero data retention) 조직에서는 쓸 수 없어요. ZDR 계약이 있다면 Fable로 바꾸기 전에 확인하세요.
어떤 모델이 thinking 끄기나 서버 도구를 받는지는 Models API의 capabilities(thinking.types.disabled, server_tools)로 조회할 수 있어요.

공식 SDK 설치

언어	설치
Python	`pip install anthropic` (v1.0부터 Python 3.10 이상)
TypeScript	`npm install @anthropic-ai/sdk`
C#	`dotnet add package Anthropic`
Go	`go get github.com/anthropics/anthropic-sdk-go`
PHP	`composer require anthropic-ai/sdk`
Ruby	`bundle add anthropic`
Java	공식 quickstart의 Gradle/Maven 안내 참고
CLI	`brew install anthropics/tap/ant` 후 `ant auth login`

자주 막히는 지점

키를 잃어버렸어요

원인: 키는 생성 시 한 번만 전체가 보여요.
해결: Console에서 새 키를 만들고, 옛 키는 삭제하세요.

Claude Pro/Max를 구독 중인데 API가 안 돼요

원인: 구독에는 Console API 사용이 포함되지 않고 별도로 청구돼요.
해결: Console에서 API용 결제 설정을 따로 하세요. 절차는 화면 안내를 따르세요.

직접 HTTP로 호출했더니 오류가 나요

원인: 필수 헤더가 빠졌을 수 있어요.
해결: x-api-key와 anthropic-version: 2023-06-01 헤더, max_tokens 값을 확인하세요.

Opus 5.5나 Haiku 5.5로 바꿨더니 400 오류가 나요

원인: Opus 5.5는 thinking 끄기·고정과 tool_choice의 any/tool이, Haiku 5.5는 budget_tokens·샘플링 파라미터·prefill이 허용되지 않아요.
해결: 빠른 참조표의 “모델별 요청 제한”을 보고 해당 파라미터를 빼세요. 오류 메시지의 파라미터 이름이 단서예요.

Python SDK를 올렸더니 `temperature`가 오류예요 (SDK 1.0)

원인: Python SDK v1.0(2026-08-20)은 Python 3.10 이상이 필요하고, 오래 전에 지원 중단된 것들을 없앴어요. Text Completions API, Messages 메서드의 temperature·top_p·top_k 파라미터가 그 예예요. HTTP 계층도 httpx에서 httpx2로 바뀌었어요.
해결: 해당 파라미터를 빼거나 공식 마이그레이션 안내의 전후 코드를 따르세요. 예제의 pip install anthropic은 그대로 쓰면 돼요.

개인 키가 갑자기 작동하지 않아요

원인: 개인 키는 조직을 떠나면 무효가 돼요.
해결: CI나 프로덕션에는 서비스 계정 키를 쓰세요.

응답이 중간에 끊겨요

원인: max_tokens가 작을 수 있어요. 응답의 stop_reason을 확인하세요.
해결: max_tokens를 늘리세요.

실전 팁

비용이 걱정되면 작은 모델부터. 예제는 공식 quickstart대로 claude-opus-5-5를 쓰지만, claude-sonnet-5-5나 claude-haiku-5-5로 바꿔도 돼요. 공식 가이드는 effort 조정도 좋은 수단이라고 해요.
max_tokens를 작게. 짧게 답해도 되는 호출에서는 출력 상한을 낮춰 의도치 않은 긴 출력을 막을 수 있어요.
usage를 로그로. 호출마다 입력·출력 토큰 수를 남기면 비용을 추정하기 쉬워요.
실시간이 필요 없으면 Batch API. 50% 할인이에요.
공유 용도는 서비스 계정 키. 개인 키는 팀 서비스에 쓰지 마세요.
키는 정기적으로 점검. 만료일을 설정하고 쓰지 않는 키는 삭제하세요.
베타 헤더는 이제 필요 없어요. Files API(/v1/files)와 Agent Skills(/v1/skills)는 2026-08-19에 Claude API에서 정식(GA)이 되어 files-api-2025-04-14, skills-2025-10-02 베타 헤더가 필요 없어요. 헤더를 계속 보내도 동작하지만 Files API는 이전 응답 형식으로 돌아와요.
Max·Team이라면 API 크레딧을 확인하세요. 플랜에 월 API 크레딧이 포함돼요. 수령 방법은 C2를 보세요.

다음 단계: 더 깊이 가려면

입문 범위를 넘어서는 기능이에요. 이름만 알아 두고 필요할 때 공식 문서를 보세요.

Claude Managed Agents: 클라우드에서 에이전트를 돌리는 서비스예요. 동적 워크플로(베타, 2026-10-09)로 에이전트가 여러 에이전트를 단계별로 돌리는 워크플로를 직접 쓰게 할 수 있어요.
컴퓨터·브라우저 툴셋: computer_toolset_20260801은 2026-08-19에 베타를 벗어났고, 같은 날 브라우저 툴셋(browser_toolset_20260801)이 나왔어요. Python·TypeScript SDK에는 이를 상속해 쓰는 클래스가 베타로 있어요.
Compaction: 대화가 길어질 때 요약 블록으로 압축하는 Messages API 기능이에요(2026-09-14, 베타, compact-2026-09-04 헤더).
Models API capabilities: 모델이 무엇을 받는지 조회해 위 400 오류를 코드에서 미리 피할 수 있어요.

다음에 볼 튜토리얼

C1. Claude 한눈에 보기 — 모델 4종 비교와 선택 가이드
C15. 모델 분담 전략 — 비용을 줄이는 모델 분담
C14. Claude Code 핵심 기능 — Claude Code로 API 코드를 짜는 법
C2. 요금제와 사용량 한도 — 구독 요금제와 API는 어떻게 다른지
도구 사용(Tool use)으로 업무 봇 만들기 — API로 도구를 호출하는 봇 만들기
프롬프트 캐싱·배치·effort로 API 비용 줄이기 — 캐시와 Batch API 자세히
Managed Agents로 서버에서 에이전트 돌리기 — 클라우드에서 에이전트 돌리기

출처

마지막 확인일: 2026년 10월 13일

How do I pay for my Claude API usage? support.claude.com
Rate limits platform.claude.com
Get started with Claude (API) platform.claude.com
Get your Claude API key platform.claude.com
Models overview platform.claude.com
What is the Pro plan? support.claude.com
Prompting best practices platform.claude.com
Claude Platform release notes platform.claude.com
Model deprecations platform.claude.com

가격·한도·메뉴 이름은 자주 바뀌어요. 중요한 결정 전에는 위 공식 페이지에서 최신 내용을 다시 확인하세요.