Next.js와 ElevenLabs 통합: 단계별 가이드

왜 ElevenLabs를 Next.js와 결합해야 할까요?

만약 웹 앱에 사실적인 AI 생성 음성을 추가하고 싶었다면—팟캐스트 생성기, 대화형 스토리, 또는 음성 지원 챗봇이든 상관없이—ElevenLabs는 현재 시장에서 가장 강력한 텍스트-음성 변환(TTS) 엔진 중 하나입니다. ElevenLabs의 신경망 모델은 자연스러운 음성을 생성하며, 여러 언어를 지원하고 심지어 몇 분간의 오디오만으로 목소리를 복제할 수도 있습니다.

Next.js는 하이브리드 렌더링 기능과 내장된 API 라우트를 통해 클라이언트와 서버 양쪽에서 ElevenLabs 같은 외부 서비스를 호출하는 것을 매우 쉽게 만듭니다. 이 가이드에서는 전체 스택 구현 과정을 안내합니다: 사용자가 텍스트를 입력하고 '말하기(Speak)' 버튼을 누르면 오디오가 즉시 스트리밍되는 간단한 UI입니다.

사전 준비 사항 (Prerequisites)

• Node.js 18+ 및 npm (또는 yarn)
• 새로운 Next.js 14 프로젝트 (npx create-next-app@latest my-voice-app)
• ElevenLabs API 키 – 가입하고 대시보드에서 키를 가져오세요. 👉 ElevenLabs 시작하기: [https://try.elevenlabs.io/kr07zfuqn1bp]
• React hooks와 비동기(async) fetch 호출에 대한 기본적인 지식.

1. 환경 변수 설정 (Set Up Environment Variables)

프로젝트 루트에 .env.local 파일을 생성하고 다음 내용을 추가합니다:

ELEVENLABS_API_KEY=your-elevenlabs-api-key
ELEVENLABS_VOICE_ID=your-default-voice-id   # 예: “EXAVITQu4vr4xnSDxMaL”

팁: API 키는 비밀로 유지하세요. Next.js는 NEXT_PUBLIC_으로 접두사가 붙은 변수만 브라우저에 자동으로 노출합니다. ElevenLabs를 서버에서 호출할 것이므로, 이를 노출할 필요가 없습니다.

2. 서버 측 API 라우트 구축 (Build a Server-Side API Route)

Next.js API 라우트는 서버에서 실행되므로 API 키를 숨기기에 완벽합니다. 새 파일 pages/api/speak.ts를 생성하세요.

import type { NextApiRequest, NextApiResponse } from 'next';
import fetch from 'node-fetch';

...

무슨 일이 일어나고 있나요?

1. text (스크립트)와 선택적 voiceId를 포함하는 POST 요청을 받습니다.
2. 이 요청은 내부 비밀 API 키를 전달하며 ElevenLabs의 TTS 엔드포인트로 프록시됩니다.
3. 원본 MP3 바이트가 클라이언트에 직접 반환되어, 디스크에 파일을 저장할 필요 없이 즉시 재생이 가능합니다.

3. 프론트엔드 UI – 텍스트 입력 및 오디오 재생

components/VoiceSynthesizer.tsx에 컴포넌트를 생성하세요:

import { useState, useRef } from 'react';

export default function VoiceSynthesizer() {
...

홈페이지(pages/index.tsx)에 이 컴포넌트를 추가하세요:

import VoiceSynthesizer from '@/components/VoiceSynthesizer';

export default function Home() {
...

이제 npm run dev를 실행하고 문장을 입력한 후 Speak을 누르면, AI가 생성한 음성을 즉시 들을 수 있을 것입니다.

4. 선택 사항: 목소리 복제 (Voice Cloning)

ElevenLabs는 또한 짧은 오디오 샘플(약 30초)을 업로드하여 사용자 지정 목소리를 만들 수 있게 해줍니다. 여기 클로닝 엔드포인트에 대한 간단한 curl 예시가 있습니다:

curl -X POST "https://api.elevenlabs.io/v1/voices/add" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -F "name=MyCustomVoice" \
...

응답에는 새로운 voice_id가 포함됩니다. 이 ID를 저장하고 /api/speak 경로로 전달하세요:

await fetch('/api/speak', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
...

이제 사용자가 자신의 목소리나 훈련시킨 브랜드별 목소리로 말하게 할 수 있습니다.

5. 대용량 텍스트 스트리밍 처리 (Handling Streaming for Larger Texts)

매우 긴 단락을 예상하는 경우, 전체 MP3를 기다리는 대신 오디오를 청크(chunk) 단위로 스트리밍하는 것이 좋을 수 있습니다. ElevenLabs는 Accept: audio/mpeg 헤더를 통해 청크 응답을 지원합니다. API 경로 내에 최소한의 Node.js 스트리밍 예시가 있습니다:

const response = await fetch(`https://api.elevenlabs.io/v1/text-to-speech/${voice}`, {
  method: 'POST',
  headers: {
...

이 방식은 메모리 사용량을 낮게 유지하고, 첫 바이트가 도착하는 즉시 브라우저에서 재생을 시작할 수 있게 합니다.

6. Vercel 배포 (Deploying to Vercel)

API 라우트가 node-fetch 외에 서버 측 종속성이 없기 때문에 (이는 이미 번들링되어 있음), 이 저장소를 GitHub에 푸시하고 원클릭으로 Vercel에 연결할 수 있습니다. Vercel은 환경 변수를 자동으로 주입하므로 API 키는 안전하게 유지됩니다.

7. 디버깅 팁

마무리

ElevenLabs를 Next.js와 통합하면 고품질 TTS(Text-to-Speech) 및 음성 클로닝을 모든 웹 경험에 추가할 수 있는, 프로덕션 준비가 된 서버 보안 방식이 제공됩니다. 몇 줄의 코드로 다음 작업을 수행할 수 있습니다:

• API 키를 서버리스 함수 뒤에 숨깁니다.
• 빠른 UI를 위해 오디오를 즉시 스트리밍합니다.
• 브랜딩 또는 개인화를 위한 맞춤형 음성 생성을 제공합니다.

사용자에게 목소리를 부여할 준비가 되셨나요? ElevenLabs API 키를 확보하고 오늘 바로 구축을 시작하세요:

👉 ElevenLabs 사용해보기: [https://try.elevenlabs.io/kr07zfuqn1bp]

즐거운 코딩 되시고, 여러분의 앱이 타이핑하는 것처럼 부드럽게 말하기를 바랍니다!