Name: Expressive Text-to-Speech API (ElevenLabs v3)
Brand: magicapi
SKU: api-magicapi-expressive-text-to-speech-elevenlabs-v3
Availability: InStock
Author: API Market

Shashank Agarwal

# 🎤 Expressive Text-to-Speech API (ElevenLabs v3)

## Overview
The **Expressive Text-to-Speech API (ElevenLabs v3)** turns text into speech with ElevenLabs' v3 model, which ElevenLabs describes as its most expressive text-to-speech model.

You send the text, choose one of 26 preset voices, and tune how the voice sounds with stability, similarity boost, style and speed settings. You can also pass the text that comes before and after the current passage so the delivery fits its context. The API returns a URL to the generated audio file. Requests run asynchronously: you create a prediction, then poll it until the audio is ready.

## Features
- **26 preset voices:** Rachel (default), Drew, Clyde, Paul, Aria, Domi, Dave, Roger, Fin, Sarah, James, Jane, Juniper, Arabella, Hope, Bradford, Reginald, Gaming, Austin, Kuon, Blondie, Priyanka, Alexandra, Monika, Mark and Grimblewood.
- **Voice settings:** `stability` (0 to 1, default 0.5), `similarity_boost` (0 to 1, default 0.75) and `style` exaggeration (0 to 1, default 0).
- **Speed:** `speed` from 0.7 to 1.2 (default 1).
- **Context for longer scripts:** `previous_text` and `next_text` give the model the surrounding text when you generate a long script piece by piece.
- **Language code:** `language_code` (default `en`, for example `en`, `es`, `fr`).

## Use Cases
1. **Audiobooks and storytelling:** narrate chapters in sections, passing `previous_text` and `next_text` so each section flows into the next.
2. **Video and podcast voiceovers:** pick a preset voice and adjust `style` and `speed` to fit the content.
3. **Games and characters:** give different characters different preset voices.
4. **E-learning:** produce spoken lessons and explainers.
5. **Accessibility:** turn written content into audio for people who prefer to listen.

## Visual Examples
This is the real request we sent through api.market and the audio it produced. Only `prompt` was set, so the defaults applied (voice `Rachel`, `language_code` `en`, `speed` 1). The prompt includes the bracketed cues `[excited]` and `[whispers]`; listen to hear how the model delivered them.

**Prompt used:**
> [excited] Welcome to api.market! [whispers] Here is a little secret: your first API call takes less than a minute.

**Output:** [Listen to the example](https://blog.api.market/wp-content/uploads/2026/10/elevenlabs-v3-output-api-market.mp3)

## Pricing
- **Pay As You Go (PAYG) pricing:** you only pay for what you use.
- **Price:** $0.013 per API unit.
- **1 API unit:** each started 100 characters of input text.
- **Worked example:** a 250-character request is 3 units, so it costs 3 x $0.013 = $0.039. The 114-character example prompt above is 2 units ($0.026).
- There is a single price for every voice and setting.
- **Failed or cancelled predictions** are not billed.
- **GET requests to check prediction status** are free and don't count toward API unit usage.
- **No monthly subscription fee.**

## API Documentation
### Base URL
```
https://prod.api.market/api/v1/magicapi/expressive-text-to-speech-elevenlabs-v3
```

### Authentication
Include your api.market API key in the `x-api-market-key` header of every request:
```
x-api-market-key: YOUR_API_MARKET_KEY
```

### Asynchronous Processing
**IMPORTANT:** This API is asynchronous.
1. Send `POST /predictions` with the model `version` and your `input`. A successful call returns **201 Created** with a prediction `id` and a `status` of `starting` or `processing`. 201 means the prediction was accepted; it is not an error.
2. Poll `GET /predictions/{id}` every second or two.
3. Stop when `status` is `succeeded` (the `output` field holds the audio URL), `failed` (see the `error` field) or `canceled`.

### Endpoints

#### POST /predictions
Create a prediction.
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/expressive-text-to-speech-elevenlabs-v3/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "5c33c00998ca79ba4caed10d97f1aaad5ca22d286ac27cb20373e6f6a6bcc00b",
    "input": {
      "prompt": "[excited] Welcome to api.market! [whispers] Here is a little secret: your first API call takes less than a minute."
    }
  }'
```

Response (201 Created):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "version": "5c33c00998ca79ba4caed10d97f1aaad5ca22d286ac27cb20373e6f6a6bcc00b",
  "status": "starting",
  "created_at": "2026-10-11T19:10:31.361Z"
}
```

#### GET /predictions/{id}
Check the status of a prediction.
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/expressive-text-to-speech-elevenlabs-v3/predictions/ufawqhfynnddngldkgtslldrkq" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

Response when finished (200 OK):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "status": "succeeded",
  "output": "https://blog.api.market/wp-content/uploads/2026/10/elevenlabs-v3-output-api-market.mp3",
  "error": null,
  "created_at": "2026-10-11T19:10:31.361Z",
  "started_at": "2026-10-11T19:10:31.402Z",
  "completed_at": "2026-10-11T19:10:34.118Z"
}
```

`output` is a single URL to the generated audio file.

### Input Parameters
| Parameter | Type | Default | Allowed values | Required | Description |
|---|---|---|---|---|---|
| `prompt` | string | none | Any text | Yes | The text to convert to speech. |
| `voice` | string | `Rachel` | `Rachel`, `Drew`, `Clyde`, `Paul`, `Aria`, `Domi`, `Dave`, `Roger`, `Fin`, `Sarah`, `James`, `Jane`, `Juniper`, `Arabella`, `Hope`, `Bradford`, `Reginald`, `Gaming`, `Austin`, `Kuon`, `Blondie`, `Priyanka`, `Alexandra`, `Monika`, `Mark`, `Grimblewood` | No | Voice choice for speech generation. |
| `stability` | number | `0.5` | 0 to 1 | No | Stability setting for voice generation. |
| `similarity_boost` | number | `0.75` | 0 to 1 | No | Similarity boost setting. |
| `style` | number | `0` | 0 to 1 | No | Style exaggeration. |
| `speed` | number | `1` | 0.7 to 1.2 | No | Speed of speech. |
| `previous_text` | string | `""` | Any text | No | Previous text for context. |
| `next_text` | string | `""` | Any text | No | Next text for context. |
| `language_code` | string | `en` | A language code, e.g. `en`, `es`, `fr` | No | Language code. |

### Status Codes
- **201 Created:** Prediction created (POST). This is the normal success response.
- **200 OK:** Prediction details returned (GET).
- **400 Bad Request:** Invalid input, for example a missing `prompt`, a voice that is not in the list, or a value outside the allowed range.
- **401 Unauthorized:** Missing or invalid API key.
- **404 Not Found:** No prediction with that ID.
- **429 Too Many Requests:** Too many requests in a short time. Wait and retry.
- **500 Internal Server Error:** Server-side error. Retry after a short wait.

### Error Handling
- A 201 response only means the prediction was accepted. Always poll until `status` is `succeeded`, `failed` or `canceled`.
- When `status` is `failed`, read the `error` field, fix the input and send a new request. Failed predictions are not billed.
- For 429 and 5xx responses, retry with exponential backoff.

## Rate Limits

All plans allow 10 requests per second. Requests above that return `429 Too Many Requests`; back off before retrying and honour any `Retry-After` header. Polling a prediction with GET is free but still counts toward the per-second limit, so poll every 1 to 5 seconds rather than in a tight loop.

## Implementation Guide
### JavaScript
```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/expressive-text-to-speech-elevenlabs-v3";
const version = "5c33c00998ca79ba4caed10d97f1aaad5ca22d286ac27cb20373e6f6a6bcc00b";

const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function generateSpeech(input) {
  const createResponse = await fetch(`${baseUrl}/predictions`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-market-key": apiKey
    },
    body: JSON.stringify({ version, input })
  });
  if (createResponse.status !== 201 && createResponse.status !== 200) {
    throw new Error(`API error: ${createResponse.status} ${await createResponse.text()}`);
  }
  const { id } = await createResponse.json();

  const deadline = Date.now() + 10 * 60 * 1000;
  while (Date.now() < deadline) {
    const pollResponse = await fetch(`${baseUrl}/predictions/${id}`, {
      headers: { "x-api-market-key": apiKey }
    });
    if (!pollResponse.ok) {
      throw new Error(`API error: ${pollResponse.status} ${await pollResponse.text()}`);
    }
    const prediction = await pollResponse.json();
    if (prediction.status === "succeeded") return prediction.output;
    if (prediction.status === "failed" || prediction.status === "canceled") {
      throw new Error(`Prediction ${prediction.status}: ${prediction.error || "unknown error"}`);
    }
    await delay(1000);
  }
  throw new Error("Prediction timed out after 10 minutes");
}

generateSpeech({
  prompt: "[excited] Welcome to api.market! [whispers] Here is a little secret: your first API call takes less than a minute."
}).then((audioUrl) => console.log("Audio:", audioUrl));
```

### Python
```python
import time
import requests

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/expressive-text-to-speech-elevenlabs-v3"
VERSION = "5c33c00998ca79ba4caed10d97f1aaad5ca22d286ac27cb20373e6f6a6bcc00b"

def generate_speech(input_data, timeout_seconds=600):
    headers = {"Content-Type": "application/json", "x-api-market-key": API_KEY}
    response = requests.post(
        f"{BASE_URL}/predictions",
        headers=headers,
        json={"version": VERSION, "input": input_data},
    )
    if response.status_code not in (200, 201):
        raise Exception(f"API error: {response.status_code} {response.text}")
    prediction_id = response.json()["id"]

    deadline = time.time() + timeout_seconds
    while time.time() < deadline:
        poll = requests.get(
            f"{BASE_URL}/predictions/{prediction_id}",
            headers={"x-api-market-key": API_KEY},
        )
        poll.raise_for_status()
        prediction = poll.json()
        if prediction["status"] == "succeeded":
            return prediction["output"]
        if prediction["status"] in ("failed", "canceled"):
            raise Exception(f"Prediction {prediction['status']}: {prediction.get('error')}")
        time.sleep(1)
    raise TimeoutError("Prediction timed out")

audio_url = generate_speech({
    "prompt": "[excited] Welcome to api.market! [whispers] Here is a little secret: your first API call takes less than a minute."
})
print("Audio:", audio_url)
```

### cURL
```bash
# Step 1: create the prediction (returns 201 with an id)
curl -X POST "https://prod.api.market/api/v1/magicapi/expressive-text-to-speech-elevenlabs-v3/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "5c33c00998ca79ba4caed10d97f1aaad5ca22d286ac27cb20373e6f6a6bcc00b",
    "input": {
      "prompt": "[excited] Welcome to api.market! [whispers] Here is a little secret: your first API call takes less than a minute."
    }
  }'

# Step 2: poll with the id from step 1 until status is succeeded, failed or canceled
curl -X GET "https://prod.api.market/api/v1/magicapi/expressive-text-to-speech-elevenlabs-v3/predictions/PREDICTION_ID" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

### Tips
- Start with the default voice settings (`stability` 0.5, `similarity_boost` 0.75, `style` 0) and change one at a time.
- For long scripts, split the text into passages and send the neighbouring passages in `previous_text` and `next_text`.
- `speed` only accepts values from 0.7 to 1.2.
- Cost depends on text length, so trimming unneeded text lowers the price.

## FAQ
### Which voices can I use?
The 26 preset voices listed in the `voice` parameter. Rachel is the default. Custom or cloned voices are not available through this API.

### Which languages are supported?
Set `language_code` to a language code such as `en` (the default), `es` or `fr`.

### What do `previous_text` and `next_text` do?
They give the model the text around the passage you are generating, as context. Use them when you produce a long script in several requests.

### What happens if a prediction fails?
It is not billed. Read the `error` field, fix the input and try again.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


ElevenLabs v3 text-to-speech API: expressive speech from text with 26 preset voices, stability, similarity, style and speed settings, and context text.