Skip to navigation

Migrate from OpenAI Text to Speech

This guide shows you how to move an OpenAI Speech API integration to the ElevenLabs Text to Speech API.

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.

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 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

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 for details. To give the agent ElevenLabs-specific guidance for the migration, install the agent skills with npx skills add elevenlabs/skills.

1

Create an API key

Create an API key in the dashboard here, which you’ll use to securely access the API.

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
ELEVENLABS_API_KEY=<your_api_key_here>
2

Install the SDK

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

pip install elevenlabs
pip install python-dotenv

The SDKs read the key from the ELEVENLABS_API_KEY environment variable.

How parameters map

OpenAIElevenLabsNotes
POST /v1/audio/speechPOST /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.
inputtexttext is the only required body field.
voice (a name, such as coral)voice_id (an ID, such as JBFqnCBsd6RMkjVDRZzb)See Choose a voice.
modelmodel_idOptional, 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.
instructionsNo equivalentSee Replace instructions.

To change speaking speed, see 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 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, 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.

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

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"))

After: ElevenLabs

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)

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.

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),
)

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.

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),
)

Map output formats

OpenAI’s response_format defaults to mp3. ElevenLabs’ output_format defaults to mp3_44100_128.

OpenAI response_formatElevenLabs output_format
mp3mp3_44100_128 (default), or another mp3_* value
opusAn opus_48000_* value, such as opus_48000_128
pcm (24kHz)pcm_24000
wavA wav_* value, such as wav_24000
aac, flacNo 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.

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.

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

The Stream speech 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.

Pricing and limits

FAQ

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.

No. ElevenLabs voices are referenced by ID, and there is no mapping from OpenAI voice names. Choose replacement voices from the voice library.

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