ElevenLabs
Overview
ElevenLabs provides AI-powered text-to-speech and voice synthesis services. Integrating ElevenLabs into your Emergent project lets you generate natural-sounding speech from text, create custom voices, and build voice-enabled experiences.
This guide walks you through setting up the ElevenLabs integration so your agents can call its API directly from your application.
Prerequisites
Before you begin, you'll need:
- An active ElevenLabs account (sign up here)
- An API key from your ElevenLabs dashboard
- An Emergent project where you want to use voice synthesis
Note
ElevenLabs offers a free tier with limited character quota. Check your plan limits in the ElevenLabs dashboard to ensure they meet your project's needs.
Setup steps
Describe your voice synthesis feature
In your Emergent workspace, open the chat and describe what you want to build using ElevenLabs. For example:
Add a "Speak" button next to each article. When clicked, use ElevenLabs to convert the article text to speech and play it.
Create a voice settings page where users can choose from available ElevenLabs voices. Store their preference and use that voice for all text-to-speech playback.
When a user submits a story, generate an audio narration using ElevenLabs and display an audio player on the story detail page.
The agents will identify the ElevenLabs integration requirement and prompt you for the API key if it is needed.
Obtain your ElevenLabs API key
- Log in to your ElevenLabs account
- Navigate to your Profile Settings (click your avatar in the top-right corner)
- Select the API Keys tab
- Click Create API Key or copy an existing key
- Store the key securely
Warning
Treat your API key like a password. Do not commit it to version control or share it publicly.
Add the API key to your Emergent project
When Emergent asks for the ElevenLabs API key:
- Provide the API key.
- Agent will securely configure and wire the key into the project.
The agent will handle the required secret configuration and use the key to set up the integration.
Implement and test the integration
The agents will:
- Install the ElevenLabs SDK (if needed)
- Implement API calls using your stored key
- Build the UI components for playback or voice selection
- Handle error states (quota exceeded, network issues)
Once the agents publish your feature:
- Navigate to the part of your app that uses ElevenLabs
- Trigger the text-to-speech action
- Verify that audio is generated and plays correctly
- Check your ElevenLabs dashboard to confirm API usage is being tracked
Tip
Start with short text samples during testing to conserve your character quota.
If you encounter errors, describe the issue in chat:
The ElevenLabs audio isn't playing. I see an error: [paste error message].
The agents will debug and fix the integration.
Common use cases
Article narration
Generate audio versions of blog posts or articles for accessibility and multi-modal consumption.
Voice assistants
Build conversational interfaces that respond with natural-sounding speech.
Audiobook generation
Convert written content into audiobook-style narration with custom voices.
Notification voiceovers
Add spoken alerts or announcements to your app for visually impaired users.
Configuration options
You can customize how ElevenLabs is used in your project by describing preferences to the agents:
| Option | Description | Example instruction |
|---|---|---|
| Voice selection | Choose from ElevenLabs' library of pre-made voices | "Use the 'Rachel' voice for all narration" |
| Voice settings | Adjust stability, clarity, and style parameters | "Set voice stability to 0.75 and clarity to 0.8" |
| Model selection | Pick a specific ElevenLabs model (multilingual, turbo, etc.) | "Use the multilingual v2 model for better accent handling" |
| Streaming | Enable real-time audio streaming for low-latency playback | "Stream audio as it's generated instead of waiting for the full file" |
| Caching | Store generated audio to reduce API calls | "Cache generated speech for 24 hours per unique text input" |
Note
The agents will suggest sensible defaults based on your use case. You can always refine settings by describing adjustments in chat.
Monitoring usage
ElevenLabs tracks character usage against your plan quota. To monitor:
- Visit your ElevenLabs dashboard
- Review Character Usage for the current billing period
- Set up usage alerts if your plan supports them
Warning
If you exceed your quota, API requests will fail until you upgrade your plan or your quota resets. Build error handling into your app to gracefully inform users when synthesis is unavailable.
You can instruct the agents to implement quota-aware features:
Show a warning in the admin panel when ElevenLabs usage reaches 80% of the monthly quota.
Troubleshooting
| Issue | Solution |
|---|---|
| Audio doesn't play after generation | Possible causes: The audio file URL is expired or inaccessible; Browser autoplay policies are blocking playback; CORS issues if hosting audio on a different domain. Solutions: Describe the issue in chat: "Audio generated by ElevenLabs won't play in the browser"; Agents will add user-initiated playback controls or adjust CORS headers; For mobile apps, ensure audio permissions are requested |
| API key authentication fails | Check: The environment variable name is exactly |
| Quota exceeded errors | Error message: |
| Generated voice sounds unnatural | Tuning options: Try a different voice from the ElevenLabs library; Adjust stability and clarity settings (lower stability = more expressive, higher = more consistent); Use the higher-quality model if your plan supports it. Instruction example: "Switch to the 'Josh' voice and increase stability to 0.9 for clearer speech." |
Best practices
Tip
Cache aggressively: Store generated audio for repeated text to avoid redundant API calls. Truncate long inputs: ElevenLabs charges per character; summarize or chunk very long documents. Use streaming: For real-time applications, stream audio as it's generated to reduce perceived latency.
Note
ElevenLabs integrations are powerful for making content accessible to visually impaired users and those who prefer audio. Combine with transcripts or captions for full accessibility coverage.
Note
If you're building a public-facing app, implement rate limiting or user quotas to prevent abuse and unexpected billing spikes.
