Next.js에서 Claude API 연결하는 가장 쉬운 예제
Next.js App Router에서 Anthropic SDK로 Claude API를 붙이는 최소 예제를 라우트 핸들러 코드와 함께 정리했어요.
AI 모델을 처음 붙일 때 제일 먼저 막히는 게 "그래서 이걸 내 앱에 어떻게 붙이지?"인 경우가 많아요. Claude도 비슷해요. 문서는 많은데, 정작 "Next.js에서 최소한으로 붙이는 코드"만 딱 찾으려면 은근히 번거롭죠.
이번 글은 그 부분만 담았어요. App Router 기준으로, 서버에서 안전하게 API를 부르는 가장 짧은 예제예요.
준비물은 세 가지
- Next.js 프로젝트 (App Router)
- Anthropic API 키
- 패키지 하나:
@anthropic-ai/sdk
설치는 한 줄이면 돼요.
npm install @anthropic-ai/sdk키는 .env.local에 넣어요.
ANTHROPIC_API_KEY=sk-ant-...여기서 중요한 점 하나. 이 키는 브라우저(클라이언트)로 넘어가면 안 돼요. NEXT_PUBLIC_ 접두사를 붙이지 마세요. 그래서 호출은 항상 서버에서 해요.
라우트 핸들러 만들기
app/api/chat/route.ts 파일을 하나 만들어요.
import Anthropic from "@anthropic-ai/sdk";
import { NextResponse } from "next/server";
const anthropic = new Anthropic({
apiKey: process.env.ANTHROPIC_API_KEY,
});
export async function POST(request: Request) {
const { message } = await request.json();
const response = await anthropic.messages.create({
model: "claude-sonnet-4-6",
max_tokens: 1024,
messages: [{ role: "user", content: message }],
});
const text =
response.content[0].type === "text" ? response.content[0].text : "";
return NextResponse.json({ reply: text });
}응답의 content는 여러 블록이 올 수 있어요. 그래서 type이 "text"인지 확인하고 꺼내는 게 안전해요. 모델명은 claude-sonnet-4-6, 그 자리에만 넣으면 됩니다.
클라이언트에서 불러오기
이제 화면에서 이 라우트를 호출해요.
"use client";
import { useState } from "react";
export default function Chat() {
const [reply, setReply] = useState("");
async function send() {
const res = await fetch("/api/chat", {
method: "POST",
body: JSON.stringify({ message: "안녕하세요" }),
});
const data = await res.json();
setReply(data.reply);
}
return (
<div>
<button onClick={send}>보내기</button>
<p>{reply}</p>
</div>
);
}버튼을 누르면 서버 라우트가 Claude에 요청을 보내고, 답을 받아 화면에 보여줘요. 여기까지가 최소 구성이에요.
- 키는 서버에만
- 모델명 claude-sonnet-4-6
- content는 type 확인 후 사용
조금 더 다듬는다면
실제 서비스라면 몇 가지를 더 챙기면 좋아요.
- 에러 처리:
try/catch로 감싸고, 실패하면 상황·원인·다음 행동을 사용자에게 안내해요. - 스트리밍: 응답을 한 번에 받지 말고
messages.stream으로 흘려보내면 체감 속도가 빨라져요. - 입력 검증: 서버에서
message가 비었는지, 너무 긴지 확인해요.
혼자 운영하다 보면 이런 API 연결을 여러 제품에서 반복하게 돼요. 라이프케어로그의 플랜티(plan-t)도 서버에서 모델을 부르는 이런 구조 위에서 움직여요. 패턴을 한 번 잡아두면, 다음 제품에선 붙여넣기 수준으로 줄어들죠.
마무리
새 모델이라고 연결법이 크게 다르진 않아요. 서버 라우트 하나, 패키지 하나, 키 하나면 시작할 수 있어요. 작게 붙여보고, 필요해질 때 스트리밍과 에러 처리를 얹는 순서를 추천해요.
관련 글
댓글
아직 댓글이 없어요. 첫 댓글을 남겨주세요.