Claude API Node.js 사용법 완전 가이드 (2026)
Claude API를 Node.js에서 사용하려면 @anthropic-ai/sdk 패키지를 설치하고, ANTHROPIC_API_KEY 환경변수를 설정한 뒤, 10줄 미만의 코드로 첫 번째 메시지를 전송할 수 있습니다. 이 가이드에서는 설치부터 스트리밍, 툴 사용(function calling), 프롬프트 캐싱, 오류 처리까지 단계별로 설명합니다. 모든 코드 예제는 현재 API 기준으로 동작 확인되었습니다.
설치 및 환경 설정
npm install @anthropic-ai/sdk
API 키를 환경변수로 설정합니다:
export ANTHROPIC_API_KEY="sk-ant-..."
또는 .env 파일 사용:
npm install dotenv
// .env 파일
ANTHROPIC_API_KEY=sk-ant-...
// index.js
import 'dotenv/config';
import Anthropic from '@anthropic-ai/sdk';
첫 번째 API 호출
import Anthropic from '@anthropic-ai/sdk';
const client = new Anthropic();
const message = await client.messages.create({
model: 'claude-sonnet-4-5',
max_tokens: 1024,
messages: [
{ role: 'user', content: '프롬프트 캐싱이 무엇인지 한 문단으로 설명해주세요.' }
]
});
console.log(message.content[0].text);
client는 자동으로 환경변수에서 ANTHROPIC_API_KEY를 읽습니다. 별도 설정이 필요 없습니다.
응답 객체 이해하기
console.log(message.id); // msg_01...
console.log(message.model); // claude-sonnet-4-5
console.log(message.stop_reason); // end_turn
console.log(message.usage.input_tokens); // 입력 토큰 수
console.log(message.usage.output_tokens); // 출력 토큰 수
console.log(message.content[0].text); // 실제 응답 텍스트
비용 계산: input_tokens × 입력 단가 + output_tokens × 출력 단가 = 호출당 비용. 모델별 정확한 단가는 Claude API 비용 및 프롬프트 캐싱 손익분기 가이드를 참고하세요.
벤치마크: Node.js 환경에서 claude-sonnet-4-5의 첫 토큰 수신까지 평균 300500ms가 소요됩니다. 500토큰 응답의 전체 수신은 평균 35초입니다.
시스템 프롬프트와 멀티턴 대화
import Anthropic from '@anthropic-ai/sdk';
const client = new Anthropic();
// 대화 히스토리 관리
const history = [];
async function chat(userMessage) {
history.push({ role: 'user', content: userMessage });
const response = await client.messages.create({
model: 'claude-sonnet-4-5',
max_tokens: 1024,
system: '당신은 Node.js 전문 개발자입니다. 간결하게 답변하고 코드 예제를 포함해 주세요.',
messages: history
});
const assistantText = response.content[0].text;
history.push({ role: 'assistant', content: assistantText });
return assistantText;
}
// 멀티턴 대화 예시
console.log(await chat('async/await와 Promise의 차이점은 무엇인가요?'));
console.log(await chat('어떤 경우에 Promise.all을 사용해야 하나요?'));
console.log(await chat('코드 예제를 보여주세요.'));
history 배열이 전체 대화 맥락을 담고 있습니다. Claude는 자체적인 메모리가 없으므로 클라이언트에서 상태를 직접 관리해야 합니다.
스트리밍 응답
긴 응답이나 인터랙티브 UI에서는 스트리밍을 사용해 텍스트가 생성되는 즉시 표시할 수 있습니다:
import Anthropic from '@anthropic-ai/sdk';
const client = new Anthropic();
const stream = client.messages.stream({
model: 'claude-sonnet-4-5',
max_tokens: 1024,
messages: [
{ role: 'user', content: 'Node.js에서 Event Loop 동작 원리를 자세히 설명해주세요.' }
]
});
// 텍스트 청크 수신
for await (const chunk of stream) {
if (
chunk.type === 'content_block_delta' &&
chunk.delta.type === 'text_delta'
) {
process.stdout.write(chunk.delta.text);
}
}
// 스트리밍 완료 후 전체 메시지 정보
const finalMessage = await stream.finalMessage();
console.log('\n\n총 사용 토큰:', finalMessage.usage.input_tokens + finalMessage.usage.output_tokens);
Node.js와 Python으로 Claude API를 활용하는 30개 이상의 레시피
Agent SDK Cookbook ($49)은 스트리밍 파이프라인, 멀티에이전트 조율, 툴 체이닝, 오류 처리, 비용 최적화 패턴을 포함합니다.
툴 사용 (Function Calling)
툴 사용을 통해 Claude가 필요할 때 외부 함수를 호출하도록 할 수 있습니다:
import Anthropic from '@anthropic-ai/sdk';
const client = new Anthropic();
const tools = [
{
name: 'get_stock_price',
description: '주식 종목 코드로 현재 주가를 조회합니다',
input_schema: {
type: 'object',
properties: {
ticker: {
type: 'string',
description: '주식 종목 코드 (예: 005930 for 삼성전자)'
}
},
required: ['ticker']
}
}
];
const response = await client.messages.create({
model: 'claude-sonnet-4-5',
max_tokens: 1024,
tools,
messages: [{ role: 'user', content: '삼성전자 현재 주가가 얼마인가요?' }]
});
// Claude가 툴 호출을 요청하는지 확인
if (response.stop_reason === 'tool_use') {
const toolUse = response.content.find(b => b.type === 'tool_use');
console.log(`Claude가 호출하려는 툴: ${toolUse.name}`);
console.log(`입력값: ${JSON.stringify(toolUse.input)}`);
// 실제 함수 호출 (예시)
const stockData = { price: 72000, currency: 'KRW' };
// 결과를 Claude에게 반환
const finalResponse = await client.messages.create({
model: 'claude-sonnet-4-5',
max_tokens: 1024,
tools,
messages: [
{ role: 'user', content: '삼성전자 현재 주가가 얼마인가요?' },
{ role: 'assistant', content: response.content },
{
role: 'user',
content: [{
type: 'tool_result',
tool_use_id: toolUse.id,
content: JSON.stringify(stockData)
}]
}
]
});
console.log(finalResponse.content[0].text);
}
더 복잡한 멀티에이전트 패턴은 Claude Agent SDK 가이드를 참고하세요.
프롬프트 캐싱으로 비용 절감
긴 시스템 프롬프트나 문서를 반복 사용할 때 프롬프트 캐싱을 활용하면 비용을 크게 줄일 수 있습니다:
import Anthropic from '@anthropic-ai/sdk';
const client = new Anthropic();
// 긴 시스템 프롬프트 — 캐시 적용
const SYSTEM_PROMPT = `당신은 한국 법인 회계 전문가입니다.
다음 규정에 따라 답변해 주세요:
1. 한국 법인세법 기준으로 설명
2. K-IFRS 회계기준 적용
3. 실무에서 자주 발생하는 사례 포함
[... 일반적으로 2,000토큰 이상의 상세 지침 ...]`;
async function askAccountingQuestion(question) {
const response = await client.messages.create({
model: 'claude-sonnet-4-5',
max_tokens: 2048,
system: [
{
type: 'text',
text: SYSTEM_PROMPT,
cache_control: { type: 'ephemeral' } // 이 블록을 캐시
}
],
messages: [{ role: 'user', content: question }]
});
// 캐시 상태 확인
const cacheRead = response.usage.cache_read_input_tokens ?? 0;
const cacheCreated = response.usage.cache_creation_input_tokens ?? 0;
console.log(`캐시 읽기: ${cacheRead}토큰, 캐시 생성: ${cacheCreated}토큰`);
return response.content[0].text;
}
비용 효과: 캐시된 토큰은 일반 입력 토큰 대비 90% 저렴합니다. 2,000토큰 시스템 프롬프트를 하루 500회 호출한다고 가정하면, 캐싱 적용 시 월 약 $27 절감 (Sonnet 기준). 상세한 손익분기 계산은 Claude API 비용 가이드를 참고하세요.
오류 처리 및 재시도 로직
import Anthropic from '@anthropic-ai/sdk';
import {
RateLimitError,
APIConnectionError,
AuthenticationError,
APIError
} from '@anthropic-ai/sdk';
const client = new Anthropic();
async function callClaudeSafely(prompt, maxRetries = 3) {
for (let attempt = 0; attempt < maxRetries; attempt++) {
try {
return await client.messages.create({
model: 'claude-sonnet-4-5',
max_tokens: 1024,
messages: [{ role: 'user', content: prompt }]
});
} catch (error) {
if (error instanceof RateLimitError) {
if (attempt < maxRetries - 1) {
// 지수 백오프: 1초, 2초, 4초
const delay = Math.pow(2, attempt) * 1000;
console.log(`요청 한도 초과. ${delay}ms 후 재시도...`);
await new Promise(resolve => setTimeout(resolve, delay));
continue;
}
}
if (error instanceof AuthenticationError) {
throw new Error('API 키가 올바르지 않습니다. ANTHROPIC_API_KEY를 확인하세요.');
}
if (error instanceof APIConnectionError) {
console.error('네트워크 연결 오류:', error.message);
}
if (error instanceof APIError) {
console.error(`API 오류 ${error.status}: ${error.message}`);
}
throw error;
}
}
throw new Error('최대 재시도 횟수 초과');
}
모델 선택 가이드
// 작업 복잡도에 따른 모델 선택
function selectModel(taskType) {
switch (taskType) {
case 'simple': return 'claude-haiku-4-5'; // 단순 분류, 번역 — 가장 저렴
case 'standard': return 'claude-sonnet-4-5'; // 일반 개발, 분석 — 균형
case 'complex': return 'claude-opus-4-5'; // 복잡한 추론, 아키텍처 설계
}
}
각 모델의 성능 대비 비용 벤치마크는 Claude Haiku vs Sonnet vs Opus: 어떤 모델을 선택해야 할까 가이드를 참고하세요.
Express.js API 서버 통합 예시
실제 프로덕션 환경에서 Claude API를 Express.js 서버에 통합하는 패턴:
import express from 'express';
import Anthropic from '@anthropic-ai/sdk';
const app = express();
const client = new Anthropic();
app.use(express.json());
// 스트리밍 응답 엔드포인트
app.post('/api/chat/stream', async (req, res) => {
const { message, history = [] } = req.body;
// SSE 헤더 설정
res.setHeader('Content-Type', 'text/event-stream');
res.setHeader('Cache-Control', 'no-cache');
res.setHeader('Connection', 'keep-alive');
try {
const stream = client.messages.stream({
model: 'claude-sonnet-4-5',
max_tokens: 2048,
messages: [...history, { role: 'user', content: message }]
});
for await (const chunk of stream) {
if (
chunk.type === 'content_block_delta' &&
chunk.delta.type === 'text_delta'
) {
res.write(`data: ${JSON.stringify({ text: chunk.delta.text })}\n\n`);
}
}
res.write('data: [DONE]\n\n');
res.end();
} catch (error) {
res.write(`data: ${JSON.stringify({ error: error.message })}\n\n`);
res.end();
}
});
app.listen(3000, () => console.log('서버 시작: http://localhost:3000'));
자주 묻는 질문 (FAQ)
Claude API Node.js SDK를 어떻게 설치하나요?
npm install @anthropic-ai/sdk 명령으로 설치합니다. 그런 다음 ANTHROPIC_API_KEY 환경변수를 설정하고 import Anthropic from '@anthropic-ai/sdk'로 가져옵니다. TypeScript를 사용하는 경우 타입 정의가 SDK에 포함되어 있어 별도 패키지가 필요 없습니다.
Node.js에서 ESM(ES Module)과 CommonJS 중 어떤 것을 사용해야 하나요?
SDK는 두 방식 모두 지원합니다. 신규 프로젝트라면 package.json에 "type": "module"을 추가하고 import/export 문법을 사용하는 ESM을 권장합니다. 기존 CommonJS 프로젝트는 const Anthropic = require('@anthropic-ai/sdk')로 사용 가능합니다.
API 호출 비용을 어떻게 계산하나요?
각 응답의 message.usage.input_tokens와 message.usage.output_tokens를 확인합니다. (input_tokens × 입력 단가) + (output_tokens × 출력 단가)가 호출당 비용입니다. Claude Sonnet 기준으로 입력 토큰은 $3/1M, 출력 토큰은 $15/1M입니다 (2026년 4월 기준). 정확한 계산은 비용 가이드를 참고하세요.
429 Rate Limit 오류가 발생할 때 어떻게 처리해야 하나요?
지수 백오프(exponential backoff)를 구현하세요: 첫 번째 재시도 1초, 두 번째 2초, 세 번째 4초. 응답 헤더의 retry-after 값이 있다면 그 시간을 우선 사용합니다. 동시 요청이 많은 경우 세마포어로 최대 동시 요청 수를 제한하세요. 자세한 내용은 Claude API 동시 요청 및 Rate Limit 가이드를 참고하세요.
Node.js에서 비동기(async) 처리를 어떻게 하나요?
client.messages.create()는 Promise를 반환하므로 await로 처리합니다. 여러 요청을 병렬로 처리할 때는 Promise.all()을 사용합니다. 스트리밍은 for await...of 문법으로 처리합니다. 모든 Claude API 호출은 비동기이므로 항상 async 함수 내에서 사용하거나 .then().catch()로 처리해야 합니다.
한국어 텍스트 처리 시 토큰 수는 어떻게 계산되나요?
한국어는 영어보다 토큰 효율이 낮습니다. 한국어 문자는 평균 1.5~2.5토큰/글자 정도로 영어(0.75토큰/단어)보다 토큰을 더 많이 사용합니다. 실제 호출 전에 client.messages.count_tokens() API로 정확한 토큰 수를 사전 확인할 수 있습니다.
Node.js와 Python으로 Claude API를 활용하는 30개 이상의 레시피
Agent SDK Cookbook ($49)은 스트리밍, 툴 사용, 멀티에이전트 파이프라인, 오류 처리 패턴 등 프로덕션 수준의 예제를 포함합니다.