Claude API 파이썬 입문 — Anthropic SDK로 첫 호출까지

채팅창에서 쓰던 것을 코드로 부르기 시작하면 처음 막히는 자리는 대개 같습니다. 무엇을 설치하고, 키를 어디에 두고, 첫 줄을 어떻게 쓰느냐입니다. 그다음은 문서를 읽으면 되는데 그 앞이 안 넘어갑니다.

이 글은 그 앞부분만 다룹니다. 파이썬에서 Anthropic SDK로 첫 응답을 받는 데까지입니다. 프레임워크도 쓰지 않고, 에이전트도 만들지 않습니다.

한 가지 먼저 말씀드리면, 응답을 문자열로 바로 꺼낼 수 없습니다. 여기서 대부분 한 번 걸립니다. 그 이유는 본문에서 짚습니다.

먼저 요약
· 설치 : pip install anthropic 하나면 됩니다
· 키 : 환경변수 ANTHROPIC_API_KEY 에 두면 코드에 적지 않아도 잡힙니다
· 첫 호출 : client.messages.create(...) 한 줄
· 🔴 응답은 «블록의 목록»입니다 — response.text 같은 건 없습니다

준비물은 두 가지뿐입니다

설치는 한 줄입니다.

pip install anthropic

그다음은 키입니다. 키는 코드에 적지 않는 편이 낫습니다. 환경변수에 넣어 두면 클라이언트가 알아서 찾습니다.

import anthropic

# ANTHROPIC_API_KEY 환경변수를 자동으로 읽는다
client = anthropic.Anthropic()

키를 코드에 직접 넣는 방법도 있지만, 그 파일을 그대로 커밋해서 키가 새는 일이 흔합니다. 처음부터 환경변수로 시작하는 편이 뒤탈이 없습니다.

첫 호출 — 여기까지가 절반입니다

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    messages=[
        {"role": "user", "content": "프랑스의 수도는?"}
    ],
)

필요한 것은 세 가지입니다. 어느 모델에게(model), 얼마까지 받을지(max_tokens), 무엇을 물을지(messages).

max_tokens 는 «받을 답의 최대 길이»입니다. 너무 작게 잡으면 문장 중간에서 잘립니다. 짧은 분류 작업이 아니라면 처음엔 넉넉히 두는 편이 낫습니다.

messages 는 대화 기록 전체입니다. 여러 번 주고받으려면 이 배열에 이전 대화를 계속 쌓아서 다시 보냅니다. 서버가 대화를 기억해 주지 않습니다.

응답은 «블록의 목록»입니다

여기가 처음 걸리는 자리입니다. response.text 를 찍으면 원하는 게 안 나옵니다. 응답 본문은 «블록»들의 리스트이기 때문입니다.

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

블록에는 여러 종류가 있습니다. 글자가 담긴 text, 생각 과정이 담긴 thinking, 도구를 부르겠다는 tool_use 같은 것들입니다. 그래서 꺼내기 전에 종류를 확인해야 합니다.

response.content[0].text 로 첫 블록을 바로 집는 예제를 흔히 보는데, 이건 첫 블록이 항상 글자일 때만 맞습니다. 생각 블록이 앞에 오면 그 자리에서 깨집니다.

같이 봐 둘 것 — stop_reason
응답에는 «왜 멈췄는지»가 함께 옵니다. end_turn 이면 정상, max_tokens 면 길이 제한에 걸려 잘린 것입니다.
답이 이상하게 끊겼다면 먼저 이 값을 보십시오.

답이 길어질 것 같으면 스트리밍으로 받는 방법도 있습니다. 한 번에 다 받는 대신 생성되는 대로 조각으로 흘려받는 방식이라, 화면에 바로 찍어 주고 싶을 때와 답이 아주 길 때 씁니다. 호출 모양은 거의 같고 create 자리에 stream 을 쓰는 정도의 차이입니다. 설치부터 도구 사용까지 이어지는 전체 흐름은 junetapa.com 원문에 단계별로 정리해 뒀습니다.

모델은 무엇을 쓰고, 얼마가 드나

모델 이름은 문자열로 정확히 넣어야 합니다. 날짜를 뒤에 붙이는 옛 표기를 그대로 쓰면 없는 모델이 됩니다.

모델	모델 ID	입력 / 출력 (100만 토큰당)
Claude Opus 5	claude-opus-5	$5 / $25
Claude Sonnet 5	claude-sonnet-5	$3 / $15
Claude Haiku 4.5	claude-haiku-4-5	$1 / $5

요금은 입력과 출력이 따로 계산되고, 출력이 훨씬 비쌉니다. 그래서 «질문을 길게 넣는 것»보다 «답을 길게 받는 것»이 비용에 더 크게 작용합니다. 위 금액은 2026년 8월 기준이므로 공식 요금 페이지에서 한 번 확인하시는 편이 안전합니다.

요즘 모델은 «생각»을 하고 답합니다. Claude Opus 5 는 그 기능이 기본으로 켜져 있어서, 따로 켜지 않아도 어려운 질문에서는 알아서 더 오래 생각합니다. 그래서 응답 블록에 thinking 이 섞여 나오는 것이고, 앞에서 «블록의 종류를 확인하라»고 한 이유도 여기에 있습니다.

처음에는 가장 좋은 모델로 시작해 보고, 결과가 충분하면 그때 값싼 쪽으로 내리는 순서를 권합니다. 반대로 하면 «모델이 부족한 것»과 «내 프롬프트가 부족한 것»이 섞여서 원인을 못 가립니다.

자주 묻는 질문

Q. 키를 코드에 적으면 안 되나요?
동작은 합니다. 다만 그 파일을 커밋하면 그대로 새어 나갑니다. 환경변수에 두는 습관이 결국 편합니다.

Q. 대화를 이어 가려면요?
서버가 기억하지 않으므로 messages 배열에 주고받은 내용을 계속 쌓아 다시 보냅니다. 그만큼 입력 토큰이 늘어납니다.

Q. 답이 중간에 잘립니다.
stop_reason 이 max_tokens 인지 보십시오. 맞다면 그 값을 올리거나 스트리밍으로 받으면 됩니다.

Q. 에러는 어떻게 잡나요?
SDK가 종류별 예외를 줍니다. 인증 실패와 요청 초과는 대응이 다르니 한 덩어리로 묶지 말고 나눠서 받는 편이 낫습니다.

정리하면

첫 호출까지는 설치 한 줄, 환경변수 하나, 함수 하나면 끝납니다. 어렵게 만드는 것은 그다음에 오는 개념들이지 시작 자체가 아닙니다.

시작에서 꼭 하나만 기억한다면 «응답은 블록의 목록»입니다. 이걸 알고 시작하면 첫날 한 시간은 아낍니다.

여기서 한 걸음 더 — 도구 사용, 스트리밍, 비용을 줄이는 캐싱까지는 junetapa.com 원문에 이어서 적어 두었습니다.