Name: ElevenLabs v3 TTS API: Eleven v4 and v3 Text to Speech
Brand: speakvela
SKU: api-speakvela-elevenlabs-tts
Availability: InStock
Author: API Market

# ElevenLabs v3 and v4 Text to Speech API

## Overview

The ElevenLabs v3 and v4 Text to Speech API turns text into speech with the Eleven v4, Eleven v4 Turbo and Eleven v3 models from ElevenLabs, using any public voice in the ElevenLabs Voice Library. It has 4 endpoints that work together as an asynchronous job flow. You send the text, a voice ID and a model ID to the create endpoint, which answers straight away with a job ID and `status: processing`. You then poll the job endpoint until `status` is `completed`, and download the finished MP3 from the audio endpoint with the same API key. The voices endpoint searches the Voice Library by name, language, gender, age and accent so you can pick a `voiceId` before you start. One job takes up to 250,000 characters of text and comes back as a single MP3, so long scripts do not have to be split and stitched together on your side.

It is built for developers adding narration to apps and videos, publishers producing audiobooks and e-learning courses, and teams that need the same script voiced in several languages. The job responses are JSON: the job `id`, `status`, `progress` from 0 to 100, the voice and model used, the resolved settings, an estimated finish window (`etaDoneMinSec`, `etaDoneMaxSec`) while the job runs, and once it is done an `output` object with the audio length in seconds plus `completedAt` and `filesExpireAt` timestamps. The audio itself is a standard MP3 file (`audio/mpeg`). Voice search results are paged JSON with each voice's ID, name, description, gender, age, accent, use case, tags, the languages it supports and preview links.

## Features

*   **4 endpoints**: Create a speech job, get a job, download the MP3, and search the Voice Library.
*   **Models**: Eleven v4, Eleven v4 Turbo and Eleven v3 (`eleven_v4`, `eleven_v4_turbo` and `eleven_v3`). Other model IDs are rejected and not billed.
*   **Simple inputs**: `text`, `voiceId` and `modelId` are all you need. Optional `settings` cover stability, similarity, speed and speaker boost, plus `language` (an ISO 639-1 code or `auto` to detect it from the text).
*   **Long texts in one job**: Up to 250,000 characters per job, returned as one MP3 file.
*   **Voice search**: Filter the ElevenLabs Voice Library by `search`, `language`, `gender`, `age` and `accent`, sorted by trending, latest, most cloned or most used. Our test search reported 19,158 voices in total.
*   **Asynchronous jobs**: The create call returns at once with a job ID, and the job reports `progress` and an estimated finish time, so long texts do not hit request timeouts.
*   **Safe retries**: Send an `Idempotency-Key` header and a retried request returns the same job instead of creating and billing a new one.
*   **Pay as you go**: $0.015 per started 1,000 characters of input text. The provider states that failed jobs are not billed and that polling, downloads and voice search are free.
*   **Data source**: Speech is generated with ElevenLabs models through the provider's service. This is not an official ElevenLabs product.
*   **Rate limit**: 10 requests per second on the PAYG plan.

## Use Cases

*   **Audiobook narration**: Send a full chapter of up to 250,000 characters as one job and get back one MP3.
*   **Video voiceover**: Voice YouTube scripts, explainers and product demos without recording studio time.
*   **E-learning**: Narrate course modules and lessons with a consistent voice across a whole course.
*   **Localization**: Voice the same script in several languages by setting `settings.language` or letting the model detect it.
*   **App and product audio**: Generate spoken prompts, onboarding messages and accessibility read-outs for apps and websites.
*   **Content pipelines**: Turn articles or newsletters into audio editions on a schedule, with idempotent retries so a failed network call does not create duplicate jobs.

## API Documentation

### Base URL

All requests go through the API.market gateway at this base URL:

```
https://prod.api.market/api/v1/speakvela/elevenlabs-tts
```

### Authentication

Every request needs your API.market key in the `x-api-market-key` header:

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Create a speech job

Starts an asynchronous text to speech job and returns it immediately with a job `id` and `status: processing` (or `queued`). The job is billed at $0.015 per started 1,000 characters of `text`, so a 38-character request is billed as 1,000 characters. If you send an `Idempotency-Key` that was already used, the existing job is returned with `200 OK` and is not billed again.

**Method:** `POST`

**Endpoint:** `/text-to-speech/elevenlabs`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `Idempotency-Key` | header | Your own key for safe retries, 8 to 128 characters from `A-Z a-z 0-9 . _ : -`. The same key returns the same job and is not billed again. | string | No | - | 128 characters |
| `text` | body | The text to speak. Billed per started 1,000 characters. | string | Yes | - | 250,000 characters |
| `voiceId` | body | Voice ID from the voices endpoint or the ElevenLabs Voice Library. | string | Yes | - | - |
| `modelId` | body | Model to use: `eleven_v4`, `eleven_v4_turbo` or `eleven_v3`. | string | Yes | - | - |
| `name` | body | Your own label for the job. | string | No | - | 120 characters |
| `settings.stability` | body | Voice stability, 0 to 1. | number | No | `0.5` | 1 |
| `settings.similarity` | body | Similarity boost, 0 to 1. | number | No | `0.75` | 1 |
| `settings.style` | body | Style exaggeration, 0 to 1. Not used by the v3 and v4 models. | number | No | `0` | 1 |
| `settings.speed` | body | Speaking speed, 0.7 to 1.2. | number | No | `1` | 1.2 |
| `settings.speakerBoost` | body | Speaker boost on or off. | boolean | No | `true` | - |
| `settings.language` | body | ISO 639-1 language code such as `en`, `es`, `de` or `vi`, or `auto` to detect the language from the text. | string | No | `auto` | - |

**Example Request:**

```bash
curl -X POST "https://prod.api.market/api/v1/speakvela/elevenlabs-tts/text-to-speech/elevenlabs" \
  -H "x-api-market-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello from the API.market review team.", "voiceId": "auq43ws1oslv0tO4BDa7", "modelId": "eleven_v3"}'
```

**Example Response (201 Created):**

```json
{
  "id": "tsk_8b3a673266efcd80dadb4af7",
  "kind": "tts",
  "provider": "elevenlabs",
  "name": "Hello from the API.market review team.",
  "text": "Hello from the API.market review team.",
  "status": "processing",
  "progress": 0,
  "voiceId": "auq43ws1oslv0tO4BDa7",
  "voiceName": "Adam Stone - Smooth and Relaxed",
  "modelId": "eleven_v3",
  "language": "auto",
  "settings": {
    "speed": 1,
    "stability": 0.5,
    "similarity": 0.75,
    "style": 0,
    "speakerBoost": true,
    "language": "auto"
  },
  "createdAt": "2026-10-19T19:54:35.523Z",
  "etaDoneMinSec": 60,
  "etaDoneMaxSec": 90
}
```

Keep the `id`: you need it to poll the job and download the audio. Settings you leave out are filled with their defaults in the response.

#### 2. Get a job

Returns the current state of a job. Poll it every 3 to 5 seconds until `status` is `completed` (or `failed`). While the job is queued or processing, `progress` and `etaDoneMinSec` / `etaDoneMaxSec` show how far along it is. A completed job has an `output` object with the audio length in `durationSec`, and `filesExpireAt` tells you how long the file is kept. A failed job carries an `error` message and, where it applies, an `errorCode`: `content_blocked` (with a `blocked` object showing the refused part of the text) or `voice_unavailable`.

**Method:** `GET`

**Endpoint:** `/history/{id}`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `id` | path | The job ID returned by the create endpoint, for example `tsk_8b3a673266efcd80dadb4af7`. | string | Yes | - | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/speakvela/elevenlabs-tts/history/tsk_8b3a673266efcd80dadb4af7" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK, abridged):**

```json
{
  "id": "tsk_8b3a673266efcd80dadb4af7",
  "kind": "tts",
  "provider": "elevenlabs",
  "name": "Hello from the API.market review team.",
  "text": "Hello from the API.market review team.",
  "status": "completed",
  "progress": 100,
  "voiceId": "auq43ws1oslv0tO4BDa7",
  "voiceName": "Adam Stone - Smooth and Relaxed",
  "modelId": "eleven_v3",
  "language": "auto",
  "settings": {
    "speed": 1,
    "stability": 0.5,
    "similarity": 0.75,
    "style": 0,
    "speakerBoost": true,
    "language": "auto"
  },
  "createdAt": "2026-10-19T19:54:35.523Z",
  "output": {
    "durationSec": 3,
    "audioUrlExpiresAt": "2026-10-26T19:54:57.000Z"
  },
  "completedAt": "2026-10-19T19:54:55.912Z",
  "filesExpireAt": "2026-11-18T19:54:55.912Z"
}
```

The `output` object also holds a temporary direct file link (`audioUrl`, valid until `audioUrlExpiresAt`), left out above. Download the file through the audio endpoint below with your API key instead.

#### 3. Download the audio

Returns the finished MP3 for a completed job through the API.market gateway. If the job is still processing, the request waits up to about 30 seconds for it to finish. HTTP `Range` requests are supported (`206 Partial Content`), and files are kept for 30 days after the job completes.

**Method:** `GET`

**Endpoint:** `/audio/{id}/{file}`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `id` | path | The job ID. | string | Yes | - | - |
| `file` | path | The file to download. The only value is `audio.mp3`. | string | Yes | - | - |
| `download` | query | Optional file name. The response is then sent as an attachment with this name. `download=1` also works. | string | No | - | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/speakvela/elevenlabs-tts/audio/tsk_8b3a673266efcd80dadb4af7/audio.mp3" \
  -H "x-api-market-key: YOUR_API_KEY" \
  -o speech.mp3
```

**Example Response (200 OK):**

The response body is the MP3 file itself with `Content-Type: audio/mpeg`, not JSON. In our test the 3-second clip from the example above (Eleven v3, 38 characters) was 48,065 bytes. The same request with `?download=1` returned the same 48,065-byte file.

#### 4. Search voices

Searches the public ElevenLabs Voice Library and returns a page of voices you can use as `voiceId`. Each voice has a name, description, gender, age, main language and accent, use case, tags, a preview link, and a `languages` list with the accent and a preview link for every language the voice supports. `total` and `hasMore` help you page through results.

**Method:** `GET`

**Endpoint:** `/voices`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `provider` | query | Voice provider. The only value is `elevenlabs`. | string | Yes | - | - |
| `search` | query | Free text search term. | string | No | - | 100 characters |
| `language` | query | ISO 639-1 language code, for example `en`, `es`, `de` or `vi`. | string | No | - | - |
| `gender` | query | `male`, `female` or `neutral`. | string | No | - | - |
| `age` | query | `young`, `middle_aged` or `old`. | string | No | - | - |
| `accent` | query | Accent, for example `american`. | string | No | - | - |
| `sort` | query | `trending`, `latest`, `most_cloned` or `most_used`. | string | No | `trending` | - |
| `page` | query | Page number, starting at 1. | integer | No | `1` | - |
| `pageSize` | query | Voices per page. | integer | No | `24` | 100 |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/speakvela/elevenlabs-tts/voices?provider=elevenlabs&pageSize=2" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK, abridged):**

```json
{
  "items": [
    {
      "id": "Gfpl8Yo74Is0W6cPUWWT",
      "provider": "elevenlabs",
      "name": "Max - Elearning and Documentary",
      "tags": [
        "professional",
        "informative_educational"
      ],
      "languages": [
        {
          "language": "en",
          "accent": "american",
          "previewUrl": "https://api.us.elevenlabs.io/v1/voices/Gfpl8Yo74Is0W6cPUWWT/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ1c2VyX2lkIjoiQ0VaWHhmZENmRWZ5WEQ3eVVOS0lQY3VDS2FCMyIsImZpbGVuYW1lIjoiMWVkMGU2YWYtNTcxYi00YjhlLTlhYTItNzcxNWNmMjRkMDFiLm1wMyIsInRpbWVzdGFtcCI6MTc5MjQzNjQwMDAwMDAwMH0%3D"
        }
      ],
      "quality": "high",
      "description": "A friendly, articulate eLearning voice, great for teaching, documentaries, and explainers",
      "previewUrl": "https://api.us.elevenlabs.io/v1/voices/Gfpl8Yo74Is0W6cPUWWT/previews/audio?payload=eyJ2b2ljZV9zb3VyY2UiOiJjdXN0b20iLCJ1c2VyX2lkIjoiQ0VaWHhmZENmRWZ5WEQ3eVVOS0lQY3VDS2FCMyIsImZpbGVuYW1lIjoiMWVkMGU2YWYtNTcxYi00YjhlLTlhYTItNzcxNWNmMjRkMDFiLm1wMyIsInRpbWVzdGFtcCI6MTc5MjQzNjQwMDAwMDAwMH0%3D",
      "gender": "male",
      "age": "middle_aged",
      "language": "en",
      "accent": "american",
      "useCase": "informative_educational",
      "category": "informative_educational"
    }
  ],
  "total": 19158,
  "page": 1,
  "pageSize": 2,
  "hasMore": true
}
```

The response above is cut to the first of the 2 voices returned, and that voice's `languages` list is cut to 1 of its 24 entries.

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The job, voice page or MP3 file was returned. The create endpoint also returns `200` when you repeat an `Idempotency-Key`, with the existing job and no new charge. |
| 201 | Created | A new speech job was created and is queued or processing. |
| 206 | Partial Content | The audio endpoint answered a `Range` request with part of the MP3. |
| 400 | Bad Request | A required field (`text`, `voiceId`, `modelId`) is missing, the text is longer than 250,000 characters, a setting is out of range, or the model is not one of `eleven_v4`, `eleven_v4_turbo` or `eleven_v3` (`model_not_in_plan`, not billed). |
| 401 | Unauthorized | The `x-api-market-key` value is invalid or expired. |
| 403 | Forbidden | Your subscription does not include this endpoint. |
| 404 | Not Found | No job exists with that ID, or the audio file was not found. |
| 410 | Gone | The audio file for this job is no longer available, for example after the 30-day retention period. |
| 429 | Too Many Requests | You went over the PAYG plan's 10 requests per second limit or its usage quota. |
| 500 | Internal Server Error | Something failed while processing the request. Retry after a short delay. |
| 503 | Service Unavailable | The service could not accept a new job at that moment. Retry after a short delay. |

Error bodies are JSON with a `code` and a `message`.

## Rate Limits

The PAYG plan allows 10 requests per second across all endpoints, including job polling, downloads and voice search. Requests above that limit return `429 Too Many Requests`. Back off before retrying and honour the `Retry-After` header when it is present. Polling one job every 3 to 5 seconds uses only a small part of the limit, so you can track many jobs at once. The provider states that jobs beyond its rendering capacity wait in a queue rather than being rejected. In our test the create call returned in about 3 seconds, and a 38-character job finished about 20 seconds after it was created, sooner than the 60 to 90 second estimate the job reported.

## FAQ

**How do I get the MP3 for my text?**

Create a job with `POST /text-to-speech/elevenlabs`, keep the `id` from the response, and poll `GET /history/{id}` every 3 to 5 seconds until `status` is `completed`. Then download the file with `GET /audio/{id}/audio.mp3` using the same `x-api-market-key` header.

**How is a request billed?**

Each create request is billed at $0.015 per started 1,000 characters of `text` ($0.0015 per 100 characters, $15 per million). Every request rounds up to the next 1,000 characters, so a 300-character request is billed as 1,000 and a 1,001-character request as 2,000. The provider states that polling, audio downloads and voice search are free, and that a failed job is not billed: the charge is reversed when you fetch the failed job.

**Which models can I use, and where are the others?**

This API accepts `eleven_v4`, `eleven_v4_turbo` or `eleven_v3` in `modelId`, all at the same price. Any other model ID returns `400` with `model_not_in_plan` and is not billed. Multilingual v2, Flash v2.5 and Turbo v2.5 are sold separately in the "ElevenLabs Multilingual v2 and Flash v2.5 TTS API" product at $0.01 per 1,000 characters.

**How do I avoid paying twice when I retry a request?**

Send an `Idempotency-Key` header (8 to 128 characters) with the create request. If the request is sent again with the same key, the API returns the existing job with `200 OK` instead of creating and billing a new one.

**How long does a job take, and how long is the audio kept?**

Short texts finish quickly: in our test a 38-character job was done about 20 seconds after it was created. Long texts take longer, and `etaDoneMinSec` and `etaDoneMaxSec` give an estimate while the job runs. Files are kept for 30 days; `filesExpireAt` on the completed job shows the exact time.

**What happens if part of my text is refused?**

The job ends with `status: failed`. `errorCode: content_blocked` means the content policy refused part of the text, and the `blocked` object shows which part (`text`, `start`, `end`), so you can edit it and send the job again. `voice_unavailable` means the chosen voice can no longer be used.

**Can I use cloned or private voices?**

No. The provider states that only public voices from the ElevenLabs Voice Library are supported. Use `GET /voices` to find one by language, gender, age or accent.

## 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 TTS API with Eleven v4, v4 Turbo and v3 models and Voice Library voices. Returns one MP3 per job, $0.015 per 1,000 characters.