Claude API 튜토리얼: 초보자를 위한 완벽 가이드 (Python, 2026)

Originally published at kalyna.pro

The Claude API는 모든 Python 애플리케이션에서 Anthropic의 언어 모델에 직접 접근할 수 있게 해줍니다. 텍스트 생성, 이미지 분석, 토큰 단위 스트리밍 응답, 또는 Claude가 사용자의 함수를 호출하도록 도구를 연결하는 등 모든 것이 동일한 client.messages.create() 호출을 통해 이루어집니다. 이 튜토리얼은 첫

전체 Message 객체가 필요한 경우 루프가 끝난 뒤 stream.get_final_message()를 호출하십시오.

Vision을 이용한 이미지 분석

이미지를 base64로 인코딩된 콘텐츠 블록 (content blocks)으로 전달하십시오:

import base64
from anthropic import Anthropic

...

지원되는 유형: image/jpeg, image/png, image/gif, image/webp. 또한 "type": "url"을 사용하여 URL로 이미지를 전달할 수도 있습니다.

도구 사용 (Tool Use / Function Calling)

JSON Schema로 도구를 정의하고, stop_reason == "tool_use"를 처리하며, 결과를 tool_result 블록으로 반환하십시오:

from anthropic import Anthropic

client = Anthropic()
...

시스템 프롬프트 (System Prompts)

system 파라미터는 대화 목록 (turn list) 외부에서 지속적인 지침을 설정합니다:

from anthropic import Anthropic

client = Anthropic()
...

팁: 형식을 구체적으로 지정하고, 제약 사항을 긍정문으로 기술하며, 대화가 진행되는 동안 시스템 프롬프트를 안정적으로 유지하십시오. 또한 긴 시스템 프롬프트의 경우 비용 절감을 위해 프롬프트 캐싱 (prompt caching)을 사용하십시오.

모델 선택

• claude-opus-4-7 — 가장 뛰어난 성능; 복잡한 추론 및 다단계 에이전트 작업 (agentic tasks)에 최적
• claude-sonnet-4-6 — 품질, 비용, 속도의 균형; 대부분의 애플리케이션에 적합한 기본 모델
• claude-haiku-4-5 — 가장 빠르고 저렴함; 대량 처리, 실시간 또는 추출 작업에 이상적

세 모델 모두 동일한 API 인터페이스를 지원합니다. claude-sonnet-4-6으로 시작하여 필요에 따라 조정하십시오.

요약

• pip install anthropic으로 설치하십시오. SDK가 ANTHROPIC_API_KEY를 자동으로 읽어옵니다.
• 모든 기능은 client.messages.create()를 통해 이루어집니다.
• 멀티턴 채팅 (Multi-turn chat): 각 대화 내용을 messages 리스트에 추가하십시오.
• 스트리밍 (Streaming): client.messages.stream()을 사용하고 stream.text_stream을 반복(iterate)하십시오.
• Vision: base64로 인코딩된 이미지를 콘텐츠 블록으로 전달하십시오.
• 도구 사용 (Tool use): JSON Schema로 도구를 정의하고, tool_use 중단 사유 (stop reason)를 처리하며, tool_result 블록을 반환하십시오.
• 시스템 프롬프트 (System prompts): 메시지 목록 외부에서 system 파라미터를 사용하십시오.
• 기본값으로 claude-sonnet-4-6을 사용하십시오. 품질이 필요하면 Opus로 업그레이드하고, 속도가 필요하면 Haiku로 다운그레이드하십시오.

추가 읽을거리:

• Python으로 AI 에이전트(AI Agent)를 구축하는 방법
• Claude API 비용 가이드 (Claude API Cost Guide)