클로드 API 시작하기
클로드 API를 사용하면, 강력한 AI 모델의 기능을 자신의 애플리케이션에 통합할 수 있어요. 기본적인 사용법은 매우 간단하며, 몇 줄의 코드만으로 시작할 수 있습니다. 이 가이드는 Python을 기준으로 설명하지만, JavaScript와 다른 언어에서도 유사하게 사용할 수 있어요.
API를 사용하기 전에, API Key를 발급받아야 해요. 또한 공식 클라이언트 라이브러리를 설치하는 것이 좋아요. 라이브러리를 사용하면, API 인증과 요청-응답 처리가 자동으로 이루어져서 개발이 훨씬 쉬워집니다.
라이브러리 설치
Python 설치
Python을 사용한다면, pip를 이용해서 Anthropic 공식 라이브러리를 설치하세요:
“`bash
pip install anthropic
“`
설치 후, Python 코드에서 라이브러리를 import할 수 있어요. 최신 버전이 설치되도록 하려면, 다음 명령어를 사용하세요:
“`bash
pip install –upgrade anthropic
“`
JavaScript 설치
JavaScript/Node.js를 사용한다면, npm을 이용해서 설치하세요:
“`bash
npm install @anthropic-ai/sdk
“`
TypeScript 타입 정의도 함께 포함되어 있으므로, TypeScript 프로젝트에서도 바로 사용할 수 있어요.
기본 API 호출
Python으로 간단한 예제
“`python
import os
from anthropic import Anthropic
client = Anthropic(
api_key=os.environ.get(“ANTHROPIC_API_KEY”)
)
message = client.messages.create(
model=”claude-3-5-sonnet-20241022″,
max_tokens=1024,
messages=[
{“role”: “user”, “content”: “안녕하세요!”}
]
)
print(message.content[0].text)
“`
이 코드는 클로드에게 간단한 인사말을 보내고, 응답을 받아서 출력해요. 매우 간단하지만, 클로드 API의 핵심을 담고 있습니다.
JavaScript로 간단한 예제
“`javascript
import Anthropic from “@anthropic-ai/sdk”;
const client = new Anthropic({
apiKey: process.env.ANTHROPIC_API_KEY,
});
async function main() {
const message = await client.messages.create({
model: “claude-3-5-sonnet-20241022”,
max_tokens: 1024,
messages: [
{ role: “user”, content: “안녕하세요!” },
],
});
console.log(message.content[0].text);
}
main();
“`
메시지 구조 이해하기
역할(Role) 설정
메시지 객체는 ‘role’과 ‘content’로 구성돼요. role은 ‘user’ 또는 ‘assistant’ 중 하나예요. ‘user’는 사용자의 메시지를, ‘assistant’는 클로드의 이전 응답을 나타냅니다.
일반적으로 첫 메시지는 항상 ‘user’ role이어요. 대화를 이어가려면, 이전 assistant 응답을 messages 배열에 포함시켜야 해요. 이렇게 하면 클로드가 대화의 맥락을 이해할 수 있습니다.
멀티턴 대화
“`python
messages = [
{“role”: “user”, “content”: “파이썬이란 뭐예요?”},
{“role”: “assistant”, “content”: “파이썬은 프로그래밍 언어입니다…”},
{“role”: “user”, “content”: “그럼 자바와 뭐가 다른가요?”}
]
response = client.messages.create(
model=”claude-3-5-sonnet-20241022″,
max_tokens=1024,
messages=messages
)
“`
이렇게 이전 대화 내용을 포함시키면, 클로드는 대화의 흐름을 이해하고 일관된 답변을 할 수 있어요.
모델 선택
사용 가능한 모델들
Anthropic은 여러 모델을 제공해요:
– Claude 3.5 Sonnet: 성능과 속도 균형이 좋아요
– Claude 3 Opus: 가장 강력하지만 비싸요
– Claude 3 Haiku: 빠르고 저렴해요
각 모델의 성능과 가격이 다르므로, 자신의 용도에 맞는 모델을 선택해야 해요. 텍스트 분류나 간단한 작업에는 Haiku, 복잡한 작업에는 Sonnet이나 Opus를 사용하는 것이 좋습니다.
모델 ID 지정
API 호출 시 ‘model’ 파라미터에 정확한 모델 ID를 지정해야 해요. 예를 들어 ‘claude-3-5-sonnet-20241022’ 같은 형식이에요. 최신 모델 ID는 Anthropic 공식 문서에서 확인할 수 있습니다.
파라미터 설정
max_tokens
max_tokens는 API 응답의 최대 길이를 제한해요. 1부터 8000 정도까지 설정할 수 있어요. 값이 작으면 빠르고 저렴하지만, 응답이 잘릴 수 있어요. 충분한 길이를 주는 것이 좋지만, 필요 이상으로 크게 설정할 필요는 없어요.
temperature
temperature는 응답의 창의성을 조절해요. 0에 가까울수록 일관된 답변을 하고, 1에 가까울수록 창의적이고 변동 있는 답변을 해요. 기본값은 1이에요.
“`python
message = client.messages.create(
model=”claude-3-5-sonnet-20241022″,
max_tokens=1024,
temperature=0.5,
messages=[{“role”: “user”, “content”: “시를 써주세요”}]
)
“`
system 파라미터
system 파라미터를 사용하면, 클로드의 동작을 미리 지정할 수 있어요. 예를 들어 “당신은 친절한 고객 서비스 담당자입니다”라는 지시를 주면, 클로드가 그 역할을 수행해요.
“`python
message = client.messages.create(
model=”claude-3-5-sonnet-20241022″,
max_tokens=1024,
system=”당신은 한국어 영어 번역가입니다. 한국어를 영어로 정확히 번역하세요.”,
messages=[{“role”: “user”, “content”: “안녕하세요”}]
)
“`
응답 처리
응답 구조
API 응답은 메시지 객체 형태로 반환돼요. 주요 필드는:
– content: 실제 응답 내용을 포함한 배열
– stop_reason: 응답 종료 이유 (‘end_turn’, ‘max_tokens’ 등)
– usage: 입력/출력 토큰 수
“`python
response = client.messages.create(…)
text = response.content[0].text
print(text)
input_tokens = response.usage.input_tokens
output_tokens = response.usage.output_tokens
print(f”입력: {input_tokens}, 출력: {output_tokens}”)
“`
에러 처리
API 호출 시 여러 에러가 발생할 수 있어요. 네트워크 오류, 인증 실패, 요청 한도 초과 등이 있어요. 이런 에러들을 처리하기 위해 try-except 블록을 사용하세요:
“`python
try:
message = client.messages.create(…)
except Exception as e:
print(f”에러 발생: {e}”)
“`
스트리밍 응답
스트리밍이란?
기본적으로 API는 전체 응답이 완성될 때까지 기다렸다가 한 번에 반환해요. 하지만 스트리밍을 사용하면, 응답이 생성되는 즉시 부분적으로 받을 수 있어요. 이는 긴 응답을 기다릴 때 더 나은 사용자 경험을 제공합니다.
스트리밍 예제
“`python
with client.messages.stream(
model=”claude-3-5-sonnet-20241022″,
max_tokens=1024,
messages=[{“role”: “user”, “content”: “긴 글을 써주세요”}]
) as stream:
for text in stream.text_stream:
print(text, end=””, flush=True)
“`
스트리밍을 사용하면, 응답이 도착하는 대로 바로 출력할 수 있어요. 이는 채팅 애플리케이션이나 실시간 피드백이 필요한 경우에 매우 유용합니다.
고급 사용법
이미지 처리
클로드 API는 이미지를 입력으로 받을 수 있어요. base64로 인코딩된 이미지나 URL을 메시지에 포함시킬 수 있습니다:
“`python
message = client.messages.create(
model=”claude-3-5-sonnet-20241022″,
max_tokens=1024,
messages=[
{
“role”: “user”,
“content”: [
{
“type”: “image”,
“source”: {
“type”: “base64”,
“media_type”: “image/jpeg”,
“data”: base64_image_data,
},
},
{
“type”: “text”,
“text”: “이 이미지를 설명해주세요”
}
],
}\br/> ],
)
“`
배치 처리
대량의 요청을 처리해야 한다면, 배치 API를 사용하면 비용을 절약할 수 있어요. 배치 API는 24시간 이내에 완료되지만, 통상 API보다 50% 저렴합니다.
결론
클로드 API의 기본 사용법은 매우 간단해요. 라이브러리를 설치하고, API Key를 설정한 후, 몇 줄의 코드만으로 강력한 AI의 기능을 활용할 수 있습니다.
이 가이드의 예제들을 참고해서 자신의 프로젝트에 맞는 방식으로 클로드 API를 통합해보세요. 더 복잡한 기능이 필요하다면, 공식 문서를 참고하거나 Anthropic 지원팀에 문의할 수 있어요.