첫 API 호출

초급

API는 여러분의 프로그램이 Claude와 대화하게 해줍니다. 이 레슨이 끝나면 실제 요청을 실행해봤을 것이고, 각 구성 요소가 정확히 무엇을 하는지 이해하게 될 것입니다.

What you'll learn

API 키를 만들고 환경 변수로 안전하게 저장하기
Python 또는 TypeScript용 공식 SDK를 설치하기(또는 순수 cURL 사용)
첫 messages 요청을 보내고 Claude의 응답 읽기
네 가지 핵심 필드 이해하기: model, max_tokens, messages, system

전체 여정을 세 단계로

아래 모든 것은 하나의 단순한 순서에 들어맞습니다. 진행하면서 이 지도를 염두에 두세요.

Guided walkthrough1 of 3

Anthropic Console에서 키를 만들고 환경 변수로 export하여 코드 안에 절대 남지 않게 하세요.

1. API 키 발급

Anthropic Console에서 하나 만드세요. 그런 다음 코드 안에 절대 남지 않도록 환경 변수로 설정하세요:

API 키 export하기

export ANTHROPIC_API_KEY="sk-ant-..."

Watch out

키를 절대 커밋하지 마세요. 키는 환경 변수나 시크릿 매니저에 보관하고, 소스 관리에는 절대 넣지 마세요. 보안 페이지(/docs/security)를 참고하세요.

2. SDK 설치

언어를 고르세요. SDK는 방금 설정한 환경 변수에서 키를 자동으로 읽습니다.

Python
TypeScript
cURL

설치 (Python)

pip install anthropic

설치 (TypeScript)

npm install @anthropic-ai/sdk

설치할 것이 없습니다 — curl만 있으면 됩니다.

3. 호출하기

모든 요청은 messages의 목록입니다. 모델은 content로 응답합니다. 여러분의 언어에 맞는 스니펫을 실행하면 Claude가 질문에 답하는 것을 볼 수 있습니다.

Python
TypeScript
cURL

import anthropic

client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY from the environment

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "In one sentence, what is an API?"}
    ],
)

print(message.content[0].text)

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic(); // reads ANTHROPIC_API_KEY from the environment

const message = await client.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 1024,
  messages: [
    { role: "user", content: "In one sentence, what is an API?" },
  ],
});

console.log(message.content[0].text);

curl https://api.anthropic.com/v1/messages \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "content-type: application/json" \
  --data '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "In one sentence, what is an API?"}
    ]
  }'

방금 무슨 일이 일어났나

여러분은 네 가지 정보를 보냈습니다. 각각이 무엇을 제어하는지 살펴봅시다:

model — 어떤 Claude를 사용할지. 무작정 하드코딩하지 마세요; 모델 선택을 참고하세요.
max_tokens — 응답 길이의 상한(토큰 단위). 컨텍스트 창을 설정하지는 않습니다.
messages — 지금까지의 대화. API는 **무상태(stateless)**입니다: 대화를 이어가려면 매번 전체 히스토리를 다시 보내야 합니다.
system (선택) — 이 호출에서 Claude의 역할을 설정하는 최상위 지시.

네 가지 핵심 필드

Enter 또는 스페이스 키를 눌러 카드를 뒤집습니다. 좌우 화살표 키로 카드를 이동할 수 있습니다.용어가 표시되었습니다.

1 / 4

Pro tip

API가 무상태이므로 멀티 턴 채팅은 그저 커지는 messages 배열일 뿐입니다: 각 응답을 추가하고 다음 호출에서 전체 목록을 다시 보내세요.

스스로 점검하기

0/3

max_tokens는 무엇을 제어하나요?
이 API로 멀티 턴 대화를 어떻게 이어가나요?
API 키는 어디에 있어야 하나요?

Key takeaways

세 단계: 키 발급, SDK 설치, messages 요청 보내기.
키를 ANTHROPIC_API_KEY에 저장하면 SDK가 자동으로 읽고 코드에 들어가지 않습니다.
요청은 메시지 목록이고, 응답은 content로 돌아옵니다.
API는 무상태입니다: 대화를 이어가려면 전체 대화 히스토리를 다시 보내세요.
model, max_tokens, messages, system이 가장 먼저 다루게 될 필드입니다.

알맞은 모델 고르기 & 비용 추정 → 모델 선택 · 토큰 & 가격
응답 스트리밍 & 대화 유지 → 스트리밍 & 멀티 턴
Claude가 함수를 호출하게 하기 → 도구 사용
프로덕션 준비된 스니펫 → API 스니펫

전체 여정을 세 단계로​

1. API 키 발급​