{"slug": "integrating-elevenlabs-with-next-js-step-by-step-guide", "title": "Integrating ElevenLabs with Next.js: Step-by-Step Guide", "summary": "A developer published a step-by-step guide for integrating ElevenLabs' text-to-speech API into a Next.js application, using a server-side API route to keep the ElevenLabs API key hidden from the browser. The walkthrough covers creating a Next.js app, storing credentials in environment variables, proxying synthesis requests through a Next.js API route that returns raw MP3 audio, and playing the streamed result in a React component.", "body_md": "If you’ve ever wanted to add realistic, AI‑generated voice to a web app—whether it’s a podcast generator, an interactive story, or a voice‑enabled chatbot—ElevenLabs is one of the most powerful text‑to‑speech (TTS) engines on the market today. Its neural models produce natural‑sounding speech, support multiple languages, and even let you clone a voice with a few minutes of audio.\n\nNext.js, with its hybrid rendering capabilities and built‑in API routes, makes it incredibly easy to call external services like ElevenLabs from both the client and the server. In this guide we’ll walk through a full‑stack implementation: a simple UI where users type text, hit “Speak”, and hear the audio streamed back instantly.\n\n`npx create-next-app@latest my-voice-app`)\nCreate a `.env.local` file at the root of your project and add the following:\n\n```\nELEVENLABS_API_KEY=your-elevenlabs-api-key\nELEVENLABS_VOICE_ID=your-default-voice-id # e.g., “EXAVITQu4vr4xnSDxMaL”\n```\n\n**Tip:** Keep your API key secret—Next.js automatically exposes only variables prefixed with `NEXT_PUBLIC_` to the browser. Since we’ll call ElevenLabs from the server, we don’t need to expose it.\n\nNext.js API routes run on the server, perfect for keeping the API key hidden. Create a new file: `pages/api/speak.ts`.\n\n``` python\nimport type { NextApiRequest, NextApiResponse } from 'next';\nimport fetch from 'node-fetch';\n\nexport default async function handler(req: NextApiRequest, res: NextApiResponse) {\n if (req.method !== 'POST') {\n return res.status(405).json({ error: 'Method not allowed' });\n }\n\n const { text, voiceId } = req.body;\n if (!text) {\n return res.status(400).json({ error: 'Missing text payload' });\n }\n\n const voice = voiceId || process.env.ELEVENLABS_VOICE_ID;\n const apiKey = process.env.ELEVENLABS_API_KEY;\n\n try {\n const response = await fetch(\n `https://api.elevenlabs.io/v1/text-to-speech/${voice}`,\n {\n method: 'POST',\n headers: {\n 'Content-Type': 'application/json',\n 'xi-api-key': apiKey!,\n },\n body: JSON.stringify({\n text,\n voice_settings: {\n stability: 0.5,\n similarity_boost: 0.75,\n },\n }),\n }\n );\n\n if (!response.ok) {\n const err = await response.text();\n throw new Error(`ElevenLabs error: ${err}`);\n }\n\n // The API returns raw audio (mp3) bytes\n const audioBuffer = await response.arrayBuffer();\n\n // Stream the audio back to the client\n res.setHeader('Content-Type', 'audio/mpeg');\n res.send(Buffer.from(audioBuffer));\n } catch (error: any) {\n console.error(error);\n res.status(500).json({ error: error.message });\n }\n}\n```\n\n**What’s happening?**\n\n`POST` request with `text` (the script) and an optional `voiceId`.\nCreate a component at `components/VoiceSynthesizer.tsx`:\n\n``` js\nimport { useState, useRef } from 'react';\n\nexport default function VoiceSynthesizer() {\n const [text, setText] = useState('');\n const [loading, setLoading] = useState(false);\n const audioRef = useRef(null);\n\n const handleSpeak = async () => {\n if (!text.trim()) return;\n setLoading(true);\n\n try {\n const response = await fetch('/api/speak', {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify({ text }),\n });\n\n if (!response.ok) throw new Error('Failed to synthesize');\n\n const blob = await response.blob();\n const url = URL.createObjectURL(blob);\n audioRef.current!.src = url;\n audioRef.current!.play();\n } catch (err) {\n console.error(err);\n alert('Something went wrong – check the console.');\n } finally {\n setLoading(false);\n }\n };\n\n return (\n
\n setText(e.target.value)}\n style={{ width: '100%', padding: '0.5rem' }}\n />\n \n {loading ? 'Generating…' : 'Speak'}\n \n\n
\n );\n}\n```\n\nAdd the component to your homepage (`pages/index.tsx`):\n\n``` python\nimport VoiceSynthesizer from '@/components/VoiceSynthesizer';\n\nexport default function Home() {\n return (\n <>\n

🗣️ Text‑to‑Speech with ElevenLabs + Next.js

\n \n \n );\n}\n```\n\nNow, run `npm run dev`, type a sentence, and hit **Speak**—you should hear the AI‑generated voice instantly.\n\nElevenLabs also lets you upload a short audio sample (≈30 seconds) to create a custom voice. Here’s a quick `curl` example for the cloning endpoint:\n\n```\ncurl -X POST \"https://api.elevenlabs.io/v1/voices/add\" \\\n -H \"xi-api-key: $ELEVENLABS_API_KEY\" \\\n -F \"name=MyCustomVoice\" \\\n -F \"files=@/path/to/voice_sample.wav\"\n```\n\nThe response includes a new `voice_id`. Store that ID and pass it to the `/api/speak` route:\n\n```\nawait fetch('/api/speak', {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify({ text, voiceId: 'YOUR_CLONED_VOICE_ID' })\n});\n```\n\nNow you can let users speak with *their* voice or any brand‑specific voice you’ve trained.\n\nIf you anticipate very long paragraphs, you might want to stream the audio in chunks instead of waiting for the entire MP3. ElevenLabs supports chunked responses via the `Accept: audio/mpeg` header. Here’s a minimal Node.js streaming example inside the API route:\n\n``` js\nconst response = await fetch(`https://api.elevenlabs.io/v1/text-to-speech/${voice}`, {\n method: 'POST',\n headers: {\n 'Content-Type': 'application/json',\n 'xi-api-key': apiKey!,\n Accept: 'audio/mpeg',\n },\n body: JSON.stringify({ text })\n});\n\nres.setHeader('Content-Type', 'audio/mpeg');\nresponse.body?.pipe(res); // pipe the streaming body directly\n```\n\nThis keeps memory usage low and lets the browser start playing as soon as the first bytes arrive.\n\nBecause the API route contains no server‑side dependencies beyond `node-fetch` (which is already bundled), you can push the repo to GitHub and connect it to Vercel with one click. Vercel automatically injects your environment variables, so the API key stays secure.\n\n| Issue | Likely Cause | Fix | \n|---|---|---|\n| 401 Unauthorized | Wrong or missing API key | Verify `ELEVENLABS_API_KEY` in`.env.local` and that it’s set in Vercel | \n| No audio output | `Content-Type` mismatch | Ensure you set `audio/mpeg` on the response and that the`