Claude API로 AI 기능 빠르게 추가하기

AI 기능을 서비스에 붙이고 싶은데 어디서부터 시작해야 할지 막막하셨나요? Anthropic의 Claude API는 강력한 언어 모델을 몇 줄의 코드로 바로 활용할 수 있게 해주는 REST API입니다. 이 글에서는 Claude API의 핵심 기능을 실전 예제와 함께 단계별로 알아봅니다.

Claude API란?

Claude API는 Anthropic이 제공하는 대형 언어 모델(LLM) 서비스입니다. GPT 시리즈와 유사하지만, 안전성과 명령 이해 능력에 특히 강점이 있습니다. 현재 제공되는 주요 모델은 다음과 같습니다.

모델명	특징	적합한 용도
claude-3-5-haiku	가장 빠르고 저렴	간단한 분류, 요약, 챗봇
claude-3-5-sonnet	속도와 성능의 균형	일반 코딩, 분석, 작문
claude-3-opus	최고 성능	복잡한 추론, 고품질 생성
claude-sonnet-4-6	최신 고성능	에이전트, 복합 작업

1단계: 설치와 API 키 설정

먼저 Anthropic Python SDK를 설치합니다.

bash

pip install anthropic

API 키는 console.anthropic.com에서 발급받을 수 있습니다. 환경 변수로 설정하는 것이 가장 안전합니다.

bash

export ANTHROPIC_API_KEY=your_api_key_here

Python 코드에서는 다음과 같이 클라이언트를 초기화합니다.

python

import os
import anthropic

client = anthropic.Anthropic(
    api_key=os.environ.get('ANTHROPIC_API_KEY')
)

2단계: 기본 메시지 생성

가장 기본적인 사용 패턴입니다. messages.create()를 호출하면 됩니다.

python

response = client.messages.create(
    model='claude-3-5-sonnet-20241022',
    max_tokens=1024,
    system='당신은 친절한 개발자 어시스턴트입니다.',
    messages=[
        {'role': 'user', 'content': 'Python에서 리스트를 딕셔너리로 변환하는 방법을 알려주세요.'}
    ]
)
print(response.content[0].text)

핵심 파라미터 설명:

model: 사용할 모델 이름
max_tokens: 응답의 최대 토큰 수 (비용과 직결)
system: Claude에게 역할과 지침을 부여하는 시스템 프롬프트
messages: 대화 기록 (role: user/assistant 교차)

3단계: 스트리밍으로 실시간 응답 받기

긴 응답을 기다리지 않고 실시간으로 텍스트를 표시할 수 있습니다. 챗봇 UI 구현 시 필수적인 기능입니다.

python

with client.messages.stream(
    model='claude-3-5-sonnet-20241022',
    max_tokens=1024,
    messages=[
        {'role': 'user', 'content': 'FastAPI로 REST API 서버를 만드는 방법을 설명해주세요.'}
    ],
) as stream:
    for text in stream.text_stream:
        print(text, end='', flush=True)
    print()

스트리밍을 사용하면 사용자가 응답이 생성되는 것을 실시간으로 볼 수 있어 UX가 크게 향상됩니다.

4단계: Tool Calling으로 외부 기능 연동

Claude가 단순 텍스트 생성을 넘어 외부 API나 함수를 호출할 수 있게 하는 핵심 기능입니다. 에이전트(Agent) 구현의 기반이 됩니다.

python

import anthropic
import json

client = anthropic.Anthropic()

tools = [
    {
        'name': 'get_stock_price',
        'description': '주식 종목의 현재가를 조회합니다.',
        'input_schema': {
            'type': 'object',
            'properties': {
                'ticker': {
                    'type': 'string',
                    'description': '주식 티커 심볼 (예: AAPL, TSLA)'
                }
            },
            'required': ['ticker']
        }
    }
]

response = client.messages.create(
    model='claude-3-5-sonnet-20241022',
    max_tokens=1024,
    tools=tools,
    messages=[{'role': 'user', 'content': '애플 주가가 얼마인지 알려줘.'}]
)

if response.stop_reason == 'tool_use':
    tool_use = next(b for b in response.content if b.type == 'tool_use')
    print(f'Claude가 호출 요청한 도구: {tool_use.name}')
    tool_result = {'price': 189.50, 'currency': 'USD'}
    final = client.messages.create(
        model='claude-3-5-sonnet-20241022',
        max_tokens=1024,
        tools=tools,
        messages=[
            {'role': 'user', 'content': '애플 주가가 얼마인지 알려줘.'},
            {'role': 'assistant', 'content': response.content},
            {'role': 'user', 'content': [{'type': 'tool_result', 'tool_use_id': tool_use.id, 'content': json.dumps(tool_result)}]}
        ]
    )
    print(final.content[0].text)

5단계: 실전 응용 - 문서 요약 서비스

실제 서비스에서 자주 쓰이는 패턴입니다. 긴 문서를 받아서 요약하고 키워드를 추출합니다.

python

import anthropic, json

client = anthropic.Anthropic()

def summarize_document(text: str) -> dict:
    response = client.messages.create(
        model='claude-3-5-haiku-20241022',
        max_tokens=512,
        system='문서를 요약하고 JSON 형식으로 반환하세요. 형식: {summary: str, keywords: list}',
        messages=[{'role': 'user', 'content': f'다음 문서를 요약해주세요:\n\n{text}'}]
    )
    return json.loads(response.content[0].text)

document = '인공지능(AI)은 인간의 지능을 모방하여 학습하고 문제를 해결하는 기술입니다. 최근 ChatGPT, Claude 등 대형 언어 모델의 등장으로 AI 활용 범위가 크게 확대되었습니다.'
result = summarize_document(document)
print('요약:', result['summary'])
print('키워드:', result['keywords'])

비용 최적화 팁

Claude API는 입력/출력 토큰에 따라 비용이 발생합니다. 효율적으로 사용하려면:

작업 난이도에 맞는 모델 선택 - 간단한 분류는 Haiku, 복잡한 추론은 Sonnet/Opus
max_tokens 적절히 설정 - 필요 이상으로 크게 설정하지 말 것
시스템 프롬프트 캐싱 활용 - 반복 호출 시 동일한 시스템 프롬프트 캐싱
배치 처리 - 여러 요청을 묶어서 처리하면 효율적

JavaScript/TypeScript에서 사용하기

Node.js 환경에서도 동일하게 사용할 수 있습니다.

javascript

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

async function generateText(prompt) {
  const message = await client.messages.create({
    model: 'claude-3-5-sonnet-20241022',
    max_tokens: 1024,
    messages: [{ role: 'user', content: prompt }],
  });
  return message.content[0].text;
}

const result = await generateText('Next.js 14 App Router의 장점을 설명해줘.');
console.log(result);

마무리

Claude API는 설치부터 실전 활용까지 진입 장벽이 낮으면서도 Tool Calling, 스트리밍 같은 고급 기능으로 충분히 확장 가능한 API입니다. 기본 패턴을 익히면 챗봇, 문서 분석, 자동화 에이전트 등 다양한 AI 기능을 빠르게 서비스에 통합할 수 있습니다.

코드벤터는 Claude API를 비롯한 최신 AI 기술을 실전 서비스에 빠르게 적용하는 노하우를 쌓아가고 있습니다. 기술 선택부터 구현까지 실용적인 접근으로 여러분의 AI 도입을 함께 고민합니다.

Claude API로 AI 기능 빠르게 추가하기

Claude API로 AI 기능 빠르게 추가하기

Claude API란?

1단계: 설치와 API 키 설정

2단계: 기본 메시지 생성

3단계: 스트리밍으로 실시간 응답 받기

4단계: Tool Calling으로 외부 기능 연동

5단계: 실전 응용 - 문서 요약 서비스

비용 최적화 팁

JavaScript/TypeScript에서 사용하기

마무리

AI 서비스나 플랫폼 개발을고민 중이신가요?

AI 서비스나 플랫폼 개발을
고민 중이신가요?