API ReferenceText-to-Speech ModelsElevenLabs
Multi-Speaker Dialogue
ElevenLabs Text-to-Dialogue — multi-speaker conversations in one render (Eleven v3).
Render a multi-speaker conversation in a single call. You provide an ordered list of turns ({ text, voice }); the speakers are stitched into one audio file. Powered by ElevenLabs Text-to-Dialogue (Eleven v3). Synchronous — returns the audio URL directly.
| Endpoint | POST /api/v1/tts/synthesize-dialogue |
| Provider / model | ElevenLabs · eleven_v3 (fixed) |
| Max total characters | 2,000 (across all turns) |
| Max speakers | 10 unique voices (ElevenLabs cap) |
| Cost | 2,100 / 1K chars (Eleven v3 rate) |
Shared conventions
Auth, paid-access, rate limits, and the base error set live on the Speech API page. Below is only what's specific to dialogue.
Model-specific notes
- All turns must use ElevenLabs voices. A non-ElevenLabs voice returns
400 PROVIDER_MISMATCH. - The total text across all turns must be ≤ 2,000 characters (
400 TEXT_TOO_LONGotherwise). - Use inline audio tags (
[laughs],[whispers]) per turn for expression — see Enhance to add them automatically.
Request body
| Parameter | Type | Required | Description |
|---|---|---|---|
turns | object[] | Yes | Ordered { text, voice } pairs. voice = a Sonna voice ID whose provider is ElevenLabs. Total ≤ 2,000 chars. (inputs is accepted as an alias.) |
title | string | No | Title for the saved project |
response_format | string | No | Output format · Default: "mp3" |
{
"turns": [
{ "text": "Hi! How can I help you today?", "voice": "voice-id-agent" },
{ "text": "I need help generating audio.", "voice": "voice-id-customer" },
{ "text": "Of course — let's get started.", "voice": "voice-id-agent" }
],
"title": "Support Call Demo"
}Response (200 OK)
{
"url": "https://cdn.sonnalabs.app/sonna/api-ephemeral/tts/paid/user123/dialogue123.mp3",
"remainingCredits": 99790,
"turns": 3,
"totalChars": 105,
"projectCreated": true
}Dialogue-specific errors
| Status | Code | Reason |
|---|---|---|
| 400 | TEXT_TOO_LONG | Total characters exceed 2,000 |
| 400 | PROVIDER_MISMATCH | A turn uses a non-ElevenLabs voice |
Common errors (402, 403 PAID_ACCESS_REQUIRED, 409, 429, 503) follow the shared Speech API table.