> This is a page from the ElevenLabs documentation. For an index of the documentation, fetch https://elevenlabs.io/docs/llms.txt.

# Migrate from OpenAI Text to Speech

> **Note**
>
> **How-to guide** · Assumes your app calls OpenAI's Speech API (`/v1/audio/speech`) today.

OpenAI has deprecated its `tts-1`, `tts-1-hd` and `gpt-4o-mini-tts` models, including the `gpt-4o-mini-tts-2025-03-20` and `gpt-4o-mini-tts-2025-12-15` snapshots. They shut down on **January 6, 2027**. See OpenAI's [deprecations page](https://developers.openai.com/api/docs/deprecations).

OpenAI's recommended replacement, `gpt-realtime-2.1-mini`, runs on the Realtime API and isn't a supported model for `/v1/audio/speech`. Every integration that uses these models needs a code change before the shutdown date.

The ElevenLabs [Text to Speech API](/docs/api-reference/text-to-speech/convert) keeps the same shape of work: one HTTP request that returns audio. The authentication header, parameter names, voice identifiers and model IDs are different, so you need to update each request.

## Find the code to change

Search your codebase for:

* Calls to `client.audio.speech.create(...)` or `client.audio.speech.with_streaming_response.create(...)`.
* Direct requests to `POST https://api.openai.com/v1/audio/speech`.
* The model IDs `tts-1`, `tts-1-hd` and `gpt-4o-mini-tts`.

To check which OpenAI models in your account are affected, call OpenAI's `GET /v1/models` endpoint and read each model's optional `shutdown_date` field.

## Set up ElevenLabs

> **Tip**
>
> A coding agent can do this setup for you. Run `npx -y @elevenlabs/cli@latest onboard init`, which
> needs no account or API key beforehand, and see the [quickstart](/docs/eleven-api/quickstart) for
> details. To give the agent ElevenLabs-specific guidance for the migration, install the [agent skills](/docs/eleven-api/resources/agent-tooling) with `npx skills add elevenlabs/skills`.

#### Create an API key

[Create an API key in the dashboard here](https://elevenlabs.io/app/api/api-keys), which you’ll use to securely [access the API](/docs/api-reference/authentication).

Store the key as a managed secret and pass it to the SDKs either as an environment variable via an `.env` file, or directly in your app’s configuration depending on your preference.

**`.env`**

```js title=".env"
ELEVENLABS_API_KEY=<your_api_key_here>
```

#### Install the SDK

#### SDK

We'll also use the `dotenv` library to load our API key from an environment variable.

```python
pip install elevenlabs
pip install python-dotenv
```

```typescript
npm install @elevenlabs/elevenlabs-js
npm install dotenv
```

#### CLI

Install the ElevenLabs CLI. Homebrew (macOS) and Scoop (Windows) are recommended.

**`Homebrew (macOS)`**

```bash title="Homebrew (macOS)"
brew install elevenlabs/tap/elevenlabs
```

**`Scoop (Windows)`**

```powershell title="Scoop (Windows)"
scoop bucket add elevenlabs https://github.com/elevenlabs/scoop-bucket
scoop install elevenlabs
```

**`npm`**

```bash title="npm"
npm install -g @elevenlabs/cli
```

**`curl`**

```bash title="curl"
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/elevenlabs/cli/releases/latest/download/elevenlabs-cli-installer.sh | sh
```

> **Tip**
>
> Working with an AI coding assistant? Run `elevenlabs generate-skills` in your project to write a
> `SKILL.md` for every command group into `skills/`, so your assistant knows the CLI's full surface
> without you pasting docs. Use `--output-dir` to put them elsewhere. This reads the CLI's own
> embedded API definition, so it needs no API key and works offline — and it stays in step with
> whichever CLI version you have installed.

Then authenticate — this opens your browser to authorize the CLI:

```bash
elevenlabs auth login
```

The SDKs read the key from the `ELEVENLABS_API_KEY` environment variable.

## How parameters map

| OpenAI                            | ElevenLabs                                         | Notes                                                                                     |
| --------------------------------- | -------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `POST /v1/audio/speech`           | `POST /v1/text-to-speech/{voice_id}`               | The voice moves from the body to the URL path.                                            |
| `Authorization: Bearer <key>`     | `xi-api-key: <key>`                                | The SDKs set this header for you.                                                         |
| `input`                           | `text`                                             | `text` is the only required body field.                                                   |
| `voice` (a name, such as `coral`) | `voice_id` (an ID, such as `JBFqnCBsd6RMkjVDRZzb`) | See [Choose a voice](#choose-a-voice).                                                    |
| `model`                           | `model_id`                                         | Optional, but defaults to `eleven_multilingual_v2`. Set it to `eleven_v4`.                |
| `response_format` (body field)    | `output_format` (query parameter)                  | Written as codec, sample rate and bitrate. See [Map output formats](#map-output-formats). |
| `instructions`                    | No equivalent                                      | See [Replace `instructions`](#replace-instructions).                                      |

To change speaking speed, see [Control speaking speed](#control-speaking-speed).

## Choose a model

Use `eleven_v4`. It's the flagship model, with the highest fidelity, richest emotional expression and broadest language support: 90+ languages and up to 10,000 characters per request. See the [models reference](/docs/overview/models) for full specifications.

## Choose a voice

OpenAI voices are built-in names. ElevenLabs voices are referenced by ID, and there is no built-in mapping from OpenAI voice names to ElevenLabs voices.

1. Browse the [voice library](https://elevenlabs.io/app/voice-library), which has 10,000+ voices, and listen for one that fits your use case.
2. Copy its voice ID. This guide uses `JBFqnCBsd6RMkjVDRZzb` ("George").
3. Pass the ID as `voice_id`. To list voices programmatically, use the [voices endpoint](/docs/api-reference/voices/search).

If your app lets users pick from OpenAI voice names, replace that list with the ElevenLabs voice IDs you choose.

## Update the request

The following examples generate the same sentence and save it as an MP3 file.

### Before: OpenAI

```python
from pathlib import Path
from openai import OpenAI

client = OpenAI()

with client.audio.speech.with_streaming_response.create(
    model="gpt-4o-mini-tts",
    voice="coral",
    input="Today is a wonderful day to build something people love!",
) as response:
    response.stream_to_file(Path("speech.mp3"))
```

```typescript
import fs from "fs";
import OpenAI from "openai";

const openai = new OpenAI();

const mp3 = await openai.audio.speech.create({
  model: "gpt-4o-mini-tts",
  voice: "coral",
  input: "Today is a wonderful day to build something people love!",
});

await fs.promises.writeFile("speech.mp3", Buffer.from(await mp3.arrayBuffer()));
```

```bash
curl https://api.openai.com/v1/audio/speech \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini-tts",
    "input": "Today is a wonderful day to build something people love!",
    "voice": "coral"
  }' \
  --output speech.mp3
```

### After: ElevenLabs

```python
import os
from dotenv import load_dotenv
from elevenlabs.client import ElevenLabs

load_dotenv()

elevenlabs = ElevenLabs(api_key=os.getenv("ELEVENLABS_API_KEY"))

audio = elevenlabs.text_to_speech.convert(
    voice_id="JBFqnCBsd6RMkjVDRZzb",  # "George"
    text="Today is a wonderful day to build something people love!",
    model_id="eleven_v4",
    output_format="mp3_44100_128",
)

with open("speech.mp3", "wb") as f:
    for chunk in audio:
        f.write(chunk)
```

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
import "dotenv/config";
import { writeFile } from "node:fs/promises";

const elevenlabs = new ElevenLabsClient();

const audio = await elevenlabs.textToSpeech.convert(
  "JBFqnCBsd6RMkjVDRZzb", // "George"
  {
    text: "Today is a wonderful day to build something people love!",
    modelId: "eleven_v4",
    outputFormat: "mp3_44100_128",
  }
);

await writeFile("speech.mp3", Buffer.from(await new Response(audio).arrayBuffer()));
```

```bash
curl "https://api.elevenlabs.io/v1/text-to-speech/JBFqnCBsd6RMkjVDRZzb?output_format=mp3_44100_128" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Today is a wonderful day to build something people love!",
    "model_id": "eleven_v4"
  }' \
  --output speech.mp3
```

## Replace `instructions`

The ElevenLabs Text to Speech API has no `instructions` parameter. Remove it from your requests.

Delivery comes from the voice you choose and from `voice_settings`, which apply to that request only. With Eleven v4, set `stability`: lower values give a broader emotional range, and higher values are more stable between generations but can sound monotonous.

```python
from elevenlabs import VoiceSettings

audio = elevenlabs.text_to_speech.convert(
    voice_id="JBFqnCBsd6RMkjVDRZzb",
    text="Today is a wonderful day to build something people love!",
    model_id="eleven_v4",
    voice_settings=VoiceSettings(stability=0.4),
)
```

```typescript
const audio = await elevenlabs.textToSpeech.convert("JBFqnCBsd6RMkjVDRZzb", {
  text: "Today is a wonderful day to build something people love!",
  modelId: "eleven_v4",
  voiceSettings: { stability: 0.4 },
});
```

### Control speaking speed

Eleven v4 doesn't apply `voice_settings.speed`. If your app changes speaking speed, use `eleven_multilingual_v2` or `eleven_flash_v2_5`, which do. `1.0` is the default; values from 0.7 to 1.0 slow speech down, and values from 1.0 to 1.2 speed it up.

```python
audio = elevenlabs.text_to_speech.convert(
    voice_id="JBFqnCBsd6RMkjVDRZzb",
    text="Today is a wonderful day to build something people love!",
    model_id="eleven_multilingual_v2",
    voice_settings=VoiceSettings(speed=1.1),
)
```

```typescript
const audio = await elevenlabs.textToSpeech.convert("JBFqnCBsd6RMkjVDRZzb", {
  text: "Today is a wonderful day to build something people love!",
  modelId: "eleven_multilingual_v2",
  voiceSettings: { speed: 1.1 },
});
```

## Map output formats

OpenAI's `response_format` defaults to `mp3`. ElevenLabs' `output_format` defaults to `mp3_44100_128`.

| OpenAI `response_format` | ElevenLabs `output_format`                                                       |
| ------------------------ | -------------------------------------------------------------------------------- |
| `mp3`                    | `mp3_44100_128` (default), or another `mp3_*` value                              |
| `opus`                   | An `opus_48000_*` value, such as `opus_48000_128`                                |
| `pcm` (24kHz)            | `pcm_24000`                                                                      |
| `wav`                    | A `wav_*` value, such as `wav_24000`                                             |
| `aac`, `flac`            | No equivalent. Request another format and convert it in your app if you need to. |

ElevenLabs also offers μ-law (`ulaw_8000`) and A-law (`alaw_8000`), which are common in telephony.

> **Info**
>
> MP3 at 192kbps requires the Creator tier or above. PCM and WAV at 44.1kHz require the Pro tier or
> above.

## Stream audio

OpenAI streams speech with chunked transfer encoding, and so does ElevenLabs. Replace `with_streaming_response.create(...)` with the `stream` method, which takes the same parameters as `convert` and returns audio chunks as they are generated.

```python
audio_stream = elevenlabs.text_to_speech.stream(
    voice_id="JBFqnCBsd6RMkjVDRZzb",
    text="Today is a wonderful day to build something people love!",
    model_id="eleven_v4",
    output_format="mp3_44100_128",
)

for chunk in audio_stream:
    ...  # Send each chunk to your player or client
```

```typescript
const audioStream = await elevenlabs.textToSpeech.stream("JBFqnCBsd6RMkjVDRZzb", {
  text: "Today is a wonderful day to build something people love!",
  modelId: "eleven_v4",
  outputFormat: "mp3_44100_128",
});

for await (const chunk of audioStream) {
  // Send each chunk to your player or client
}
```

> **Warning**
>
> The [Stream speech](/docs/api-reference/text-to-speech/stream) endpoint doesn't accept `wav_*`
> output formats. If you streamed `wav` or `pcm` from OpenAI for low latency, use `pcm_24000`.

For a complete example, see [Streaming text to speech](/docs/eleven-api/guides/how-to/text-to-speech/streaming).

## Pricing and limits

* Text to Speech is priced per character. See the [API pricing page](https://elevenlabs.io/pricing/api) for current rates.
* Your subscription plan sets how many requests run at once. See [concurrency and priority](/docs/overview/models#concurrency-and-priority).
* The maximum characters per request depends on the model. See [character limits](/docs/overview/models#character-limits).

## FAQ

#### Is there an OpenAI-compatible Text to Speech endpoint?

No. The ElevenLabs Text to Speech API uses its own request shape, authentication header and
voice IDs, so you need to update each request as shown in this guide.

#### Can I keep using OpenAI voice names?

No. ElevenLabs voices are referenced by ID, and there is no mapping from OpenAI voice names.
Choose replacement voices from the [voice library](https://elevenlabs.io/app/voice-library).

#### Do I have to migrate before January 6, 2027?

OpenAI says existing integrations can keep using the Speech API until the shutdown date. After
that, requests to the deprecated models stop working.

## Next steps

#### [Streaming text to speech](/docs/eleven-api/guides/how-to/text-to-speech/streaming)

Stream audio as it is generated for lower latency playback.

#### [API reference](/docs/api-reference/text-to-speech/convert)

Complete parameter reference for the Create speech endpoint.