cURL
Python
JavaScript
Go
Java
PHP
Ruby
Swift
C#
C
Objective-C
OCaml
Dart
R
curl https://api.apimart.ai/v1/messages \
-H "x-api-key: $API_KEY " \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-sonnet-4-5-20250929",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "Hello, world"}
]
}'
{
"code" : 200 ,
"data" : {
"id" : "msg_013Zva2CMHLNnXjNJJKqJ2EF" ,
"type" : "message" ,
"role" : "assistant" ,
"content" : [
{
"type" : "text" ,
"text" : "안녕하세요! 저는 Claude입니다. 만나서 반갑습니다."
}
],
"model" : "claude-sonnet-4-5-20250929" ,
"stop_reason" : "end_turn" ,
"stop_sequence" : null ,
"usage" : {
"input_tokens" : 12 ,
"output_tokens" : 18
}
}
}
API 버전 사용할 Claude API 버전을 지정합니다 예: 2023-06-01
요청 본문
모델 이름
claude-haiku-4-5-20251001 - Claude 4.5 빠른 응답 버전
claude-sonnet-4-5-20250929 - Claude 4.5 균형 버전
claude-opus-4-1-20250805 - 가장 강력한 Claude 4.1 플래그십 모델
claude-opus-4-1-20250805-thinking - Claude 4.1 Opus 심층 사고 버전
claude-sonnet-4-5-20250929-thinking - Claude 4.5 Sonnet 심층 사고 버전
메시지 목록 모델이 다음 응답을 생성하기 위한 메시지 배열입니다. user와 assistant 역할을 번갈아 사용할 수 있습니다. 각 메시지는 다음을 포함합니다:
role: 역할 (user 또는 assistant)
content: 콘텐츠 (문자열 또는 콘텐츠 블록 배열)
단일 사용자 메시지: [{ "role" : "user" , "content" : "안녕하세요, Claude" }]
다중 턴 대화: [
{ "role" : "user" , "content" : "안녕하세요." },
{ "role" : "assistant" , "content" : "안녕하세요, 저는 Claude입니다. 어떻게 도와드릴까요?" },
{ "role" : "user" , "content" : "LLM을 쉽게 설명해주실 수 있나요?" }
]
미리 채워진 어시스턴트 응답: [
{ "role" : "user" , "content" : "태양의 그리스 이름은? (A) Sol (B) Helios (C) Sun" },
{ "role" : "assistant" , "content" : "정답은 (" }
]
생성할 최대 토큰 수 중지하기 전에 생성할 최대 토큰 수입니다. 모델이 이 제한에 도달하기 전에 중지될 수 있습니다. 모델마다 최대값이 다릅니다. 최소값: 1
시스템 프롬프트 시스템 프롬프트는 Claude의 역할, 성격, 목표 및 지시사항을 설정합니다. 문자열 형식: {
"system" : "당신은 전문 Python 프로그래밍 튜터입니다"
}
구조화된 형식: {
"system" : [
{
"type" : "text" ,
"text" : "당신은 전문 Python 프로그래밍 튜터입니다"
}
]
}
Temperature 매개변수, 범위 0-1 출력의 무작위성을 제어합니다:
낮은 값 (예: 0.2): 더 결정적이고 보수적
높은 값 (예: 0.8): 더 무작위적이고 창의적
기본값: 1.0
핵 샘플링 매개변수, 범위 0-1 핵 샘플링을 사용합니다. temperature 또는 top_p 중 하나만 사용하는 것을 권장합니다. 기본값: 1.0
Top-K 샘플링 상위 K개 옵션에서만 샘플링하여 확률이 낮은 “롱테일” 응답을 제거합니다. 고급 사용 사례에만 권장됩니다.
스트리밍 활성화 true이면 Server-Sent Events (SSE)를 사용하여 응답을 스트리밍합니다.기본값: false
중지 시퀀스 모델이 생성을 중지하도록 하는 사용자 정의 텍스트 시퀀스입니다. 최대 4개의 시퀀스. 예: ["\n\nHuman:", "\n\nAssistant:"]
메타데이터 요청에 대한 메타데이터 객체입니다. 포함:
도구 정의 모델이 작업을 완료하는 데 사용할 수 있는 도구 목록입니다. 함수 도구 예: {
"tools" : [
{
"name" : "get_weather" ,
"description" : "주어진 위치의 현재 날씨 가져오기" ,
"input_schema" : {
"type" : "object" ,
"properties" : {
"location" : {
"type" : "string" ,
"description" : "도시 및 주, 예: San Francisco, CA"
},
"unit" : {
"type" : "string" ,
"enum" : [ "celsius" , "fahrenheit" ],
"description" : "온도 단위"
}
},
"required" : [ "location" ]
}
}
]
}
지원되는 도구 유형:
사용자 정의 함수 도구
컴퓨터 사용 도구 (computer_20241022)
텍스트 편집기 도구 (text_editor_20241022)
Bash 도구 (bash_20241022)
도구 선택 전략 모델이 도구를 사용하는 방법을 제어합니다:
{"type": "auto"}: 자동 결정 (기본값)
{"type": "any"}: 도구를 반드시 사용해야 함
{"type": "tool", "name": "tool_name"}: 특정 도구 사용
고유 메시지 식별자 예: "msg_013Zva2CMHLNnXjNJJKqJ2EF"
콘텐츠 블록 배열 모델에서 생성된 콘텐츠로, 콘텐츠 블록의 배열입니다. 텍스트 콘텐츠: [{ "type" : "text" , "text" : "안녕하세요! 저는 Claude입니다." }]
도구 사용: [
{
"type" : "tool_use" ,
"id" : "toolu_01A09q90qw90lq917835lq9" ,
"name" : "get_weather" ,
"input" : { "location" : "San Francisco, CA" , "unit" : "celsius" }
}
]
콘텐츠 유형:
text: 텍스트 콘텐츠
tool_use: 도구 호출
요청을 처리한 모델 예: "claude-sonnet-4-5-20250929"
중지 이유 가능한 값:
end_turn: 자연스러운 완료
max_tokens: 최대 토큰 도달
stop_sequence: 중지 시퀀스 도달
tool_use: 도구 호출됨
트리거된 중지 시퀀스 생성된 중지 시퀀스 (있는 경우), 그렇지 않으면 null
사용 예제
기본 대화
import anthropic
client = anthropic.Anthropic(
api_key = "YOUR_API_KEY" ,
base_url = "https://api.apimart.ai"
)
message = client.messages.create(
model = "claude-sonnet-4-5-20250929" ,
max_tokens = 1024 ,
messages = [
{ "role" : "user" , "content" : "양자 컴퓨팅의 기초를 설명해주세요" }
]
)
print (message.content[ 0 ].text)
다중 턴 대화
messages = [
{ "role" : "user" , "content" : "머신러닝이 무엇인가요?" },
{ "role" : "assistant" , "content" : "머신러닝은 AI의 한 분야입니다..." },
{ "role" : "user" , "content" : "실용적인 예를 들어주실 수 있나요?" }
]
message = client.messages.create(
model = "claude-sonnet-4-5-20250929" ,
max_tokens = 1024 ,
messages = messages
)
시스템 프롬프트 사용
message = client.messages.create(
model = "claude-sonnet-4-5-20250929" ,
max_tokens = 1024 ,
system = "당신은 코드 리뷰와 최적화 전문가인 시니어 Python 개발자입니다." ,
messages = [
{ "role" : "user" , "content" : "이 코드를 어떻게 최적화할 수 있나요? \n\n [code]" }
]
)
스트리밍 응답
with client.messages.stream(
model = "claude-sonnet-4-5-20250929" ,
max_tokens = 1024 ,
messages = [
{ "role" : "user" , "content" : "AI에 대한 짧은 에세이를 작성해주세요" }
]
) as stream:
for text in stream.text_stream:
print (text, end = "" , flush = True )
도구 사용
tools = [
{
"name" : "get_stock_price" ,
"description" : "실시간 주식 가격 가져오기" ,
"input_schema" : {
"type" : "object" ,
"properties" : {
"ticker" : {
"type" : "string" ,
"description" : "주식 티커 심볼, 예: AAPL"
}
},
"required" : [ "ticker" ]
}
}
]
message = client.messages.create(
model = "claude-sonnet-4-5-20250929" ,
max_tokens = 1024 ,
tools = tools,
messages = [
{ "role" : "user" , "content" : "테슬라의 주식 가격은 얼마인가요?" }
]
)
# 도구 호출 처리
if message.stop_reason == "tool_use" :
tool_use = next (block for block in message.content if block.type == "tool_use" )
print ( f "도구 호출: { tool_use.name } " )
print ( f "인수: { tool_use.input } " )
비전 이해
message = client.messages.create(
model = "claude-sonnet-4-5-20250929" ,
max_tokens = 1024 ,
messages = [
{
"role" : "user" ,
"content" : [
{
"type" : "image" ,
"source" : {
"type" : "url" ,
"url" : "https://example.com/image.jpg"
}
},
{
"type" : "text" ,
"text" : "이 이미지를 설명해주세요"
}
]
}
]
)
Base64 이미지
import base64
with open ( "image.jpg" , "rb" ) as image_file:
image_data = base64.b64encode(image_file.read()).decode( "utf-8" )
message = client.messages.create(
model = "claude-sonnet-4-5-20250929" ,
max_tokens = 1024 ,
messages = [
{
"role" : "user" ,
"content" : [
{
"type" : "image" ,
"source" : {
"type" : "base64" ,
"media_type" : "image/jpeg" ,
"data" : image_data
}
},
{
"type" : "text" ,
"text" : "이 이미지를 분석해주세요"
}
]
}
]
)
모범 사례
1. 프롬프트 엔지니어링
명확한 역할 정의:
system = """당신은 다음을 전문으로 하는 경험 많은 데이터 과학자입니다:
- 통계 분석 및 데이터 시각화
- 머신러닝 모델 개발
- Python 및 R 프로그래밍
전문적이고 정확한 조언을 제공하세요."""
구조화된 출력:
message = "분석 결과를 summary, key_findings, recommendations 필드가 포함된 JSON 형식으로 반환해주세요."
2. 오류 처리
from anthropic import APIError, RateLimitError
try :
message = client.messages.create(
model = "claude-sonnet-4-5-20250929" ,
max_tokens = 1024 ,
messages = [{ "role" : "user" , "content" : "안녕하세요" }]
)
except RateLimitError:
print ( "요청 한도 초과, 나중에 다시 시도해주세요" )
except APIError as e:
print ( f "API 오류: { e } " )
3. 토큰 최적화
# 더 짧은 프롬프트 사용
messages = [
{ "role" : "user" , "content" : "핵심 포인트 요약: \n\n [긴 텍스트]" }
]
# 출력 길이 제한
message = client.messages.create(
model = "claude-sonnet-4-5-20250929" ,
max_tokens = 500 , # 출력 제한
messages = messages
)
4. 응답 미리 채우기
# 모델을 특정 형식으로 안내
messages = [
{ "role" : "user" , "content" : "Python 모범 사례 5가지를 나열해주세요" },
{ "role" : "assistant" , "content" : "Python 모범 사례 5가지: \n\n 1." }
]
message = client.messages.create(
model = "claude-sonnet-4-5-20250929" ,
max_tokens = 1024 ,
messages = messages
)
스트리밍 응답 처리
Python 스트리밍
import anthropic
client = anthropic.Anthropic(
api_key = "YOUR_API_KEY" ,
base_url = "https://api.apimart.ai"
)
with client.messages.stream(
model = "claude-sonnet-4-5-20250929" ,
max_tokens = 1024 ,
messages = [
{ "role" : "user" , "content" : "Python 데코레이터 예제를 작성해주세요" }
]
) as stream:
for text in stream.text_stream:
print (text, end = "" , flush = True )
JavaScript 스트리밍
import Anthropic from '@anthropic-ai/sdk' ;
const client = new Anthropic ({
apiKey: process . env . API_KEY ,
baseURL: 'https://api.apimart.ai'
});
const stream = await client . messages . stream ({
model: 'claude-sonnet-4-5-20250929' ,
max_tokens: 1024 ,
messages: [
{ role: 'user' , content: 'React 컴포넌트 예제를 작성해주세요' }
]
});
for await ( const chunk of stream ) {
if ( chunk . type === 'content_block_delta' &&
chunk . delta . type === 'text_delta' ) {
process . stdout . write ( chunk . delta . text );
}
}
중요 참고사항
API 키 보안 :
API 키를 환경 변수에 저장하세요
소스 코드에 키를 하드코딩하지 마세요
정기적으로 키를 교체하세요
요청 제한 :
API 요청 제한에 유의하세요
재시도 메커니즘을 구현하세요
지수 백오프를 사용하세요
토큰 관리 :
토큰 사용량을 모니터링하세요
프롬프트 길이를 최적화하세요
적절한 max_tokens 값을 사용하세요
모델 선택 :
Opus: 복잡한 작업, 깊은 사고 필요
Sonnet: 균형잡힌 성능과 비용
Haiku: 빠른 응답, 간단한 작업
콘텐츠 필터링 :
사용자 입력을 검증하세요
민감한 정보를 필터링하세요
콘텐츠 조정을 구현하세요