Generating Speech

A developer at a language learning startup needed to generate audio for 12,000 vocabulary words in 14 languages by Friday. She had been recording native speakers at $0.15 per word -- $25,200 and six weeks of studio time. Instead, she wrote a 47-line script that called the TTS API, generating all 12,000 audio files in under three hours for about $18 total. The quality was good enough that user satisfaction scores actually increased -- the AI voices were more consistent in pronunciation and pacing than the rotating cast of human narrators.

This lesson teaches you how to make that API call, what every parameter does, and how to choose the right settings for your use case.

The Endpoint

All text-to-speech requests go to a single endpoint:

POST https://api.openai.com/v1/audio/speech

The request body is JSON with a small set of parameters that control everything about the output.

Required Parameters

model

One of gpt-4o-mini-tts, tts-1, or tts-1-hd. This determines voice quality, available features, and cost.

input

The text to convert to speech. Maximum length is 4,096 characters. For longer texts, you will need to chunk the input and concatenate the audio output -- more on this in the next lesson.

voice

The voice to use. Must be one of the voices supported by the chosen model. For gpt-4o-mini-tts: alloy, ash, ballad, coral, echo, fable, nova, onyx, sage, shimmer, verse, marin, or cedar. For tts-1 and tts-1-hd: alloy, ash, coral, echo, fable, nova, onyx, sage, or shimmer.

Optional Parameters

instructions (gpt-4o-mini-tts only)

A natural language string that tells the model how to speak. This is where the real power lies.

{
  "model": "gpt-4o-mini-tts",
  "input": "Your lab results are back and everything looks normal.",
  "voice": "cedar",
  "instructions": "Speak in a calm, reassuring tone. Pause slightly before delivering the results. Sound like a doctor who genuinely cares about the patient."
}

The instructions can control:

• Accent: "Speak with a British accent" or "Use a subtle French accent"
• Emotion: "Sound excited" or "Speak with gentle concern"
• Pacing: "Speak slowly and deliberately" or "Quick, energetic delivery"
• Character: "Sound like a friendly teacher" or "Professional news anchor"

response_format

The audio format of the output. Default is mp3. Options:

speed

A float between 0.25 and 4.0. Default is 1.0. Values below 1.0 slow the speech down; values above speed it up.

In practice, usable range is about 0.7 to 1.3. Below 0.7, speech sounds unnaturally stretched. Above 1.3, it becomes difficult to understand. The sweet spot for most applications is between 0.9 and 1.1.

A Complete Request

Here is a full example using gpt-4o-mini-tts with all parameters:

import requests
import os

response = requests.post(
    "https://api.openai.com/v1/audio/speech",
    headers={
        "Authorization": f"Bearer {os.environ['OPENAI_API_KEY']}",
        "Content-Type": "application/json"
    },
    json={
        "model": "gpt-4o-mini-tts",
        "input": "Welcome to your daily briefing. Markets opened strong this morning with tech leading the rally.",
        "voice": "ash",
        "instructions": "Professional news anchor tone. Clear enunciation. Moderate pace.",
        "response_format": "mp3",
        "speed": 1.0
    }
)

with open("briefing.mp3", "wb") as f:
    f.write(response.content)

Using the OpenAI Python SDK (recommended for production):

from openai import OpenAI
from pathlib import Path

client = OpenAI()

response = client.audio.speech.create(
    model="gpt-4o-mini-tts",
    input="Welcome to your daily briefing. Markets opened strong this morning.",
    voice="ash",
    instructions="Professional news anchor. Clear enunciation.",
    response_format="mp3",
    speed=1.0
)

response.stream_to_file(Path("briefing.mp3"))

Handling the Response

The API returns the audio file directly in the response body. The Content-Type header matches your requested format (audio/mpeg for mp3, audio/opus for opus, etc.).

For web applications, you can serve the audio directly to the browser:

// Next.js API route
export async function POST(req) {
  const { text } = await req.json();
  
  const response = await fetch('https://api.openai.com/v1/audio/speech', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.OPENAI_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      model: 'gpt-4o-mini-tts',
      input: text,
      voice: 'nova',
      response_format: 'mp3'
    })
  });

  return new Response(response.body, {
    headers: { 'Content-Type': 'audio/mpeg' }
  });
}

Error Handling

Common failure modes:

• 400 Bad Request: Input text exceeds 4,096 characters, invalid voice name, or invalid model
• 401 Unauthorized: Invalid or missing API key
• 429 Too Many Requests: Rate limit exceeded -- implement exponential backoff
• 500 Internal Server Error: Transient server issue -- retry with backoff