Claude API 사용 입문
Claude API 사용 입문 (API usage primer for Claude)
이 가이드는 Claude에게 Claude API 사용의 기초를 알려주도록 설계됐어요. 모델 ID, 기본 messages API, 도구 사용, 스트리밍, thinking에 대한 설명과 예시만 담고 그 외에는 다루지 않아요. Claude로 빠르게 시작하려는 분께 기초를 다져주는 입문서랍니다.
출처: 문서
본문
이 가이드는 Claude에게 Claude API 사용의 기초를 알려주도록 설계됐어요. 모델 ID, 기본 messages API, 도구 사용, 스트리밍, thinking에 대한 설명과 예시만 담고 그 외에는 다루지 않아요.
모델
Recommended default for most work, including complex agentic coding: Claude Opus 5.5: claude-opus-5-5
Step up for the hardest long-running agentic and research tasks, at 2.5x Claude Opus 5.5 pricing: Claude Fable 5.1: claude-fable-5-1
Previous Opus model: Claude Opus 5: claude-opus-5
Smart model: Claude Sonnet 5: claude-sonnet-5
For fast, cost-effective tasks: Claude Haiku 4.5: claude-haiku-4-5-20251001
API 호출하기
기본 요청과 응답
import anthropic
message = anthropic.Anthropic().messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message)
{
"id": "msg_01XFDUDYJgAACzvnptvVoYEL",
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "Hello!"
}
],
"model": "claude-opus-5-5",
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 12,
"output_tokens": 6
}
}
여러 대화 턴
Messages API는 무상태(stateless)라서 항상 전체 대화 기록을 API에 보내요. 이 패턴으로 시간이 지나며 대화를 쌓을 수 있어요. 이전 대화 턴이 실제로 Claude에서 비롯될 필요는 없어요. 합성 assistant 메시지를 사용할 수 있어요.
import anthropic
message = anthropic.Anthropic().messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[
{"role": "user", "content": "Hello, Claude"},
{"role": "assistant", "content": "Hello!"},
{"role": "user", "content": "Can you describe LLMs to me?"},
],
)
print(message)
Claude의 응답 프리필
입력 메시지 목록의 마지막 위치에서 Claude의 응답 일부를 프리필할 수 있어요. 이 기법으로 Claude의 응답을 형태화하세요. 다음 예시는 "max_tokens": 1을 써서 Claude로부터 단일 객관식 답을 얻어요.
import anthropic
message = anthropic.Anthropic().messages.create(
model="claude-sonnet-4-5",
max_tokens=1,
messages=[
{
"role": "user",
"content": "What is latin for Ant? (A) Apoidea, (B) Rhopalocera, (C) Formicidae",
},
{"role": "assistant", "content": "The answer is ("},
],
)
print(message.content[0].text)
Vision
Claude는 요청에서 텍스트와 이미지 둘 다 읽을 수 있어요. 이미지에 대해 base64와 url 소스 타입이 모두 지원되고, image/jpeg, image/png, image/gif, image/webp 미디어 타입과 함께요.
Option 1: Base64-encoded image (@ prefix auto-encodes binary files as base64)
curl -sSo vision-example.jpg "$IMAGE_URL"
ant messages create <<'YAML' model: claude-opus-5-5 max_tokens: 1024 messages: - role: user content: - type: image source: type: base64 media_type: image/jpeg data: "@./vision-example.jpg" - type: text text: What is in the above image? YAML
Option 2: URL-referenced image
ant messages create <<YAML model: claude-opus-5-5 max_tokens: 1024 messages: - role: user content: - type: image source: type: url url: $IMAGE_URL - type: text text: What is in the above image? YAML
```python Python
import anthropic
import base64
import httpx2
# Option 1: Base64-encoded image
image_url = "https://platform.claude.com/docs/images/vision-example.jpg"
image_media_type = "image/jpeg"
image_data = base64.standard_b64encode(httpx2.get(image_url).content).decode("utf-8")
message = anthropic.Anthropic().messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": [
{
"type": "image",
"source": {
"type": "base64",
"media_type": image_media_type,
"data": image_data,
},
},
{"type": "text", "text": "What is in the above image?"},
],
}
],
)
print(next(block.text for block in message.content if block.type == "text"))
# Option 2: URL-referenced image
message_from_url = anthropic.Anthropic().messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": [
{
"type": "image",
"source": {
"type": "url",
"url": "https://platform.claude.com/docs/images/vision-example.jpg",
},
},
{"type": "text", "text": "What is in the above image?"},
],
}
],
)
print(next(block.text for block in message_from_url.content if block.type == "text"))
Thinking
Thinking은 아주 어려운 과제에서 Claude를 도울 수 있어요. 현재 메커니즘은 적응형 thinking(thinking: {"type": "adaptive"})이에요. Claude가 언제, 얼마나 생각할지 결정하고, 여러분은 토큰 예산이 아니라 effort 파라미터로 thinking 깊이를 스티어링해요. 적응형 thinking은 Claude 4.6 이후 모델과 Claude Mythos Preview에서 지원돼요. Claude 5 모델과 Claude Mythos Preview에서는 thinking 파라미터를 생략하면 thinking이 기본으로 켜져 있어요.
모든 모델에서 thinking이 활성화되면 temperature는 1(혹은 설정 안 함)로 설정해야 해요. Claude 4.7 이후 모델과 Claude Mythos Preview에서는 temperature가 더 이상 사용되지 않고, thinking이 꺼져 있어도 기본값만 받아요.
Thinking은 다음 모델에서 지원돼요:
- Claude Opus 5.5 (
claude-opus-5-5, adaptive thinking 전용, 항상 켜짐) - Claude Opus 5 (claude-opus-5, adaptive thinking 전용, 기본으로 켜짐)
- Claude Sonnet 5 (
claude-sonnet-5, adaptive thinking 전용, 기본으로 켜짐) - Claude Opus 4.8 (claude-opus-4-8, adaptive thinking 전용)
- Claude Opus 4.7 (
claude-opus-4-7, adaptive thinking 전용) - Claude Opus 4.6 (
claude-opus-4-6, adaptive 또는 레거시 수동 thinking) - Claude Sonnet 4.6 (
claude-sonnet-4-6, adaptive 또는 레거시 수동 thinking) - Claude Opus 4.5 (
claude-opus-4-5-20251101, 레거시 수동 thinking 전용) - Claude Sonnet 4.5 (
claude-sonnet-4-5-20250929, 레거시 수동 thinking 전용) - Claude Haiku 4.5 (
claude-haiku-4-5-20251001, 레거시 수동 thinking 전용)
thinking이 동작하는 방식
thinking이 켜지면 Claude는 내부 추론을 출력하는 thinking 콘텐츠 블록을 만들어요. API 응답은 thinking 콘텐츠 블록 다음에 text 콘텐츠 블록을 포함해요.
import anthropic
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=16000,
thinking={"type": "adaptive", "display": "summarized"},
messages=[
{
"role": "user",
"content": "Are there an infinite number of prime numbers such that n mod 4 == 3?",
}
],
)
# The response contains summarized thinking blocks and text blocks
for block in response.content:
match block.type:
case "thinking":
print(f"\nThinking summary: {block.thinking}")
case "text":
print(f"\nResponse: {block.text}")
수동 확장 thinking(thinking: {"type": "enabled", "budget_tokens": N})은 레거시 메커니즘이에요. thinking을 지원하는 Claude 4~4.6 모델에서만 작동하고, Claude 4.7 이후 모델은 type: enabled를 400 오류로 거부하며 적응형 thinking을 사용해요. 수동 확장 thinking에서 budget_tokens는 Claude가 내부 추론 과정에 쓸 수 있는 최대 토큰 수를 설정해요. 한계는 요약된 출력이 아니라 전체 thinking 토큰에 적용돼요. 인터리브된 thinking을 쓰지 않는다면, budget_tokens는 max_tokens보다 작아야 해요. 그래야 thinking이 끝난 뒤 Claude가 응답을 쓸 공간이 있거든요.
도구 사용과 thinking
Thinking은 도구 사용과 함께 쓸 수 있어서, Claude가 도구 선택과 결과 처리를 추론하게 해요.
중요한 한계:
- 도구 선택 한계:
tool_choice: {"type": "auto"}(기본)나tool_choice: {"type": "none"}만 지원해요. - thinking 블록 보존: 도구 사용 중에는 마지막 어시스턴트 메시지의
thinking블록을 API에 다시 전달해야 해요.
thinking 블록 보존하기
TOOL_USE_ID=$(printf '%s' "$ASSISTANT_CONTENT"
| jq -r '.[] | select(.type == "tool_use") | .id')
Second request: pass the captured blocks back unchanged as the assistant
message. The thinking block must accompany the tool_use block.
ant messages create <<YAML model: claude-opus-5-5 max_tokens: 16000 thinking: type: adaptive display: summarized tools: - name: get_weather description: Get the current weather for a location. input_schema: type: object properties: location: type: string description: The city name. required: [location] messages: - role: user content: "What's the weather in Paris?" - role: assistant content: $ASSISTANT_CONTENT - role: user content: - type: tool_result tool_use_id: $TOOL_USE_ID content: "Current temperature: 72°F" YAML
```python Python
import anthropic
client = anthropic.Anthropic()
weather_tool = {
"name": "get_weather",
"description": "Get the current weather for a location.",
"input_schema": {
"type": "object",
"properties": {"location": {"type": "string", "description": "The city name."}},
"required": ["location"],
},
}
weather_data = {"temperature": 72}
# First request - Claude responds with thinking and tool request
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=16000,
thinking={"type": "adaptive", "display": "summarized"},
tools=[weather_tool],
messages=[{"role": "user", "content": "What's the weather in Paris?"}],
)
# Extract thinking block and tool use block
thinking_block = next(
(block for block in response.content if block.type == "thinking"), None
)
tool_use_block = next(
(block for block in response.content if block.type == "tool_use"), None
)
# Second request - Include thinking block and tool result
continuation = client.messages.create(
model="claude-opus-5-5",
max_tokens=16000,
thinking={"type": "adaptive", "display": "summarized"},
tools=[weather_tool],
messages=[
{"role": "user", "content": "What's the weather in Paris?"},
# Notice that the thinking_block is passed in as well as the tool_use_block
{"role": "assistant", "content": [thinking_block, tool_use_block]},
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": tool_use_block.id,
"content": f"Current temperature: {weather_data['temperature']}°F",
}
],
},
],
)
for block in continuation.content:
if block.type == "text":
print(block.text)
인터리브된 thinking
인터리브된 thinking은 Claude가 도구 호출 사이에 생각해서, 다음 단계를 결정하기 전에 도구 결과를 추론하게 해줘요.
수동 확장 thinking을 쓰는 이전 모델(Claude 4, 4.5, Sonnet 4.6 모델)에서는 API 요청에 베타 헤더 interleaved-thinking-2025-05-14을 추가해서 인터리브된 thinking을 활성화하세요:
import anthropic
client = anthropic.Anthropic()
calculator_tool = {
"name": "calculator",
"description": "Perform arithmetic calculations.",
"input_schema": {
"type": "object",
"properties": {
"expression": {
"type": "string",
"description": "The math expression to evaluate.",
}
},
"required": ["expression"],
},
}
database_tool = {
"name": "database_query",
"description": "Query the product database.",
"input_schema": {
"type": "object",
"properties": {
"query": {"type": "string", "description": "The database query."}
},
"required": ["query"],
},
}
response = client.beta.messages.create(
model="claude-sonnet-4-6",
max_tokens=16000,
thinking={"type": "enabled", "budget_tokens": 10000},
tools=[calculator_tool, database_tool],
messages=[
{
"role": "user",
"content": "What's the total revenue if we sold 150 units of product A at $50 each?",
}
],
betas=["interleaved-thinking-2025-05-14"],
)
for block in response.content:
match block.type:
case "thinking":
print(f"Thinking: {block.thinking}")
case "tool_use":
print(f"Tool call: {block.name}({block.input})")
case "text":
print(f"Response: {block.text}")
인터리브된 thinking으로, 그리고 오직 인터리브된 thinking에서만(일반 수동 확장 thinking이 아니라) budget_tokens가 max_tokens 파라미터를 초과할 수 있어요. 이 경우 budget_tokens는 한 어시스턴트 턴 안의 모든 thinking 블록에 걸친 총 예산을 나타내기 때문이에요.
도구 사용
클라이언트 도구 지정하기
클라이언트 도구는 API 요청의 최상위 tools 파라미터에 지정돼요. 각 도구 정의는 다음을 포함해요:
| Parameter | Description |
|---|---|
name |
도구의 이름. 정규식 ^[a-zA-Z0-9_-]{1,128}$와 일치해야 해요. |
description |
도구가 무엇을 하고, 언제 쓰여야 하며, 어떻게 동작하는지에 대한 상세한 평문 설명. |
input_schema |
도구의 기대 파라미터를 정의하는 JSON Schema 객체. |
{
"name": "get_weather",
"description": "Get the current weather in a given location",
"input_schema": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA"
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"],
"description": "The unit of temperature, either 'celsius' or 'fahrenheit'"
}
},
"required": ["location"]
}
}
도구 정의 모범 사례
매우 상세한 설명 제공하기. 이것이 도구 성능에서 가장 중요한 요소예요. 설명은 도구에 대한 모든 세부 사항을 설명해야 해요:
- 도구가 무엇을 하는지
- 언제 쓰여야 하는지(그리고 언제 쓰면 안 되는지)
- 각 파라미터가 무엇을 의미하고 도구 동작에 어떤 영향을 주는지
- 중요한 주의사항이나 한계
복잡한 도구에는 input_examples를 고려하세요. 중첩 객체, 선택 파라미터, 형식에 민감한 입력이 있는 도구에는 input_examples 필드(베타)로 구체적인 예시를 제공할 수 있어요. 이는 Claude가 기대하는 입력 패턴을 이해하는 데 도움이 돼요. 도구 사용 예시 제공 참고.
좋은 도구 설명의 예:
{
"name": "get_stock_price",
"description": "Retrieves the current stock price for a given ticker symbol. The ticker symbol must be a valid symbol for a publicly traded company on a major US stock exchange like NYSE or NASDAQ. The tool will return the latest trade price in USD. It should be used when the user asks about the current or most recent price of a specific stock. It will not provide any other information about the stock or company.",
"input_schema": {
"type": "object",
"properties": {
"ticker": {
"type": "string",
"description": "The stock ticker symbol, e.g. AAPL for Apple Inc."
}
},
"required": ["ticker"]
}
}
Claude의 출력 제어하기
도구 사용 강제하기
tool_choice 필드에 특정 도구를 지정해서 Claude가 그것을 쓰도록 강제할 수 있어요:
tool_choice = {"type": "tool", "name": "get_weather"}
tool_choice 파라미터로 작업할 때 네 가지 옵션이 있어요:
auto는 Claude가 제공된 도구를 호출할지 여부를 결정하게 해요(기본).any는 Claude에게 제공된 도구 중 하나를 반드시 쓰라고 지시해요.tool은 Claude가 특정 도구를 항상 쓰도록 강제해요.none은 Claude가 어떤 도구도 못 쓰게 해요.
Claude Opus 5.5, Claude Fable 5.1, Claude Mythos 5.1에서 any와 tool은 400 오류를 반환해요. tool_choice를 auto로 두고 도구 정의에 "strict": true를 설정해서 Claude가 하는 모든 호출이 도구의 input_schema와 일치하게 보장하세요. 엄격한 도구 사용 참고.
JSON 출력
도구가 반드시 클라이언트 함수일 필요는 없어요. 모델이 제공된 스키마를 따르는 JSON 출력을 반환하길 원할 때 언제든 도구를 쓸 수 있어요.
사고 흐름 (Chain of thought)
도구를 쓸 때 Claude는 종종 "사고 흐름", 즉 문제를 분해하고 어떤 도구를 쓸지 결정하는 단계별 추론을 보여줘요.
{
"role": "assistant",
"content": [
{
"type": "text",
"text": "<thinking>To answer this question, I will: 1. Use the get_weather tool to get the current weather in San Francisco. 2. Use the get_time tool to get the current time in the America/Los_Angeles timezone, which covers San Francisco, CA.</thinking>"
},
{
"type": "tool_use",
"id": "toolu_01A09q90qw90lq917835lq9",
"name": "get_weather",
"input": { "location": "San Francisco, CA" }
}
]
}
병렬 도구 사용
기본적으로 Claude는 사용자 질문에 답하려고 여러 도구를 쓸 수 있어요. disable_parallel_tool_use=true를 설정해서 이 동작을 끌 수 있어요.
도구 사용 및 도구 결과 콘텐츠 블록 처리하기
클라이언트 도구 결과 처리하기
응답은 tool_use의 stop_reason과 다음을 포함하는 하나 이상의 tool_use 콘텐츠 블록을 가져요:
id: 이 특정 도구 사용 블록의 고유 식별자.name: 사용 중인 도구의 이름.input: 도구에 전달되는 입력을 담은 객체.
도구 사용 응답을 받으면:
tool_use블록에서name,id,input을 추출하세요.- 코드 기반에서 그 도구 이름에 해당하는 실제 도구를 실행하세요.
tool_result로 새 메시지를 보내 대화를 계속하세요:
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "15 degrees"
}
]
}
max_tokens stop reason 처리하기
도구 사용 중 Claude의 응답이 max_tokens 한계에 닿아 잘렸다면, 더 높은 max_tokens 값으로 요청을 재시도하세요.
pause_turn stop reason 처리하기
웹 검색 같은 서버 도구를 쓸 때 API가 pause_turn stop reason을 반환할 수 있어요. 일시 중지된 응답을 그대로 후속 요청에 전달해 대화를 계속하세요.
오류 문제 해결
도구 실행 오류
도구 자체가 실행 중 오류를 던지면, "is_error": true로 오류 메시지를 반환하세요:
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "ConnectionError: the weather service API is not available (HTTP 500)",
"is_error": true
}
]
}
유효하지 않은 도구 이름
Claude의 도구 사용 시도가 유효하지 않으면(예: 필수 파라미터 누락), 도구 정의에서 더 상세한 description 값으로 요청을 다시 시도하세요.
메시지 스트리밍
Message를 만들 때 "stream": true를 설정해서 server-sent events(SSE)로 응답을 증분 스트리밍할 수 있어요.
SDK로 스트리밍하기
import anthropic
client = anthropic.Anthropic()
with client.messages.stream(
max_tokens=1024,
messages=[{"role": "user", "content": "Hello"}],
model="claude-opus-5-5",
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)
이벤트 타입
각 SSE 이벤트는 명명된 이벤트 타입과 관련 JSON 데이터를 포함해요. 각 스트림은 다음 이벤트 흐름을 사용해요:
message_start: 비어 있는content를 가진Message객체를 담아요.- 일련의 콘텐츠 블록. 각각
content_block_start, 하나 이상의content_block_delta이벤트,content_block_stop을 가져요. - 하나 이상의
message_delta이벤트. 최종Message객체의 최상위 변경을 나타내요. - 마지막
message_stop이벤트.
주의: message_delta 이벤트의 usage 필드에 보이는 토큰 수는 누적(cumulative) 이에요.
콘텐츠 블록 델타 타입
텍스트 델타
{
"type": "content_block_delta",
"index": 0,
"delta": { "type": "text_delta", "text": "Hello frien" }
}
입력 JSON 델타
tool_use 콘텐츠 블록의 경우 델타는 *부분 JSON 문자열(partial JSON strings)*이에요:
{"type": "content_block_delta","index": 1,"delta": {"type": "input_json_delta","partial_json": "{\"location\": \"San Fra"}}
Thinking 델타
스트리밍과 함께 thinking을 쓸 때:
{
"type": "content_block_delta",
"index": 0,
"delta": {
"type": "thinking_delta",
"thinking": "Let me solve this step by step..."
}
}
기본 스트리밍 요청 예시
event: message_start
data: {"type": "message_start", "message": {"id": "msg_1nZdL29xx5MUA1yADyHTEsnR8uuvGzszyY", "type": "message", "role": "assistant", "content": [], "model": "claude-opus-5-5", "stop_reason": null, "stop_sequence": null, "usage": {"input_tokens": 25, "output_tokens": 1}}}
event: content_block_start
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "text", "text": ""}}
event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "Hello"}}
event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "!"}}
event: content_block_stop
data: {"type": "content_block_stop", "index": 0}
event: message_delta
data: {"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence":null}, "usage": {"output_tokens": 15}}
event: message_stop
data: {"type": "message_stop"}