De TTS-API: Spraak genereren
Op deze pagina
Update 2 november 2026 — Audiomodellen. Verschillende modellen in deze cursus zijn verouderd:
tts-1,tts-1-hdengpt-4o-mini-ttsworden op 6 januari 2027 uitgeschakeld (opvolger:gpt-realtime-2.1-mini, waarvan de OpenAI TTS-gids aangeeft dat deze niet wordt ondersteund door/v1/audio/speech: de migratie van spraaksynthese verschuift naar de Realtime API);gpt-realtime,gpt-4o-realtimeen legacy audiomodellen op 20 januari 2027 (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5);whisper-1,gpt-4o-transcribeen/v1/audio/translationsop 26 februari 2027 (gpt-transcribe,gpt-live-transcribe,v1/realtime/translations). Voor full-duplex spraak is GPT-Live 1 beschikbaar in de API sinds 10 september 2026. Les gecorrigeerd op 3 november 2026:response.stream_to_file()op het resultaat vanspeech.create()is verouderd in de SDK (“Vanwege een bug streamt deze methode de audio niet daadwerkelijk”) → gebruikwith_streaming_response, zoals in de officiële gids; modellen en stemmen bijgewerkt (gpt-4o-mini-ttsen de bijbehorende steminstructies, 13 stemmen waarondermarinencedar); nieuwe sectie over migratie naargpt-realtime-2.1-minivóór 6 januari 2027, gebaseerd op de gids Realtime conversations. Bronnen: Text to speech · Create speech · Realtime conversations · Deprecations.
De TTS-API: Spraak genereren
De Text-to-Speech (TTS)-API van OpenAI zet tekst om in audio van hoge kwaliteit. In tegenstelling tot de Realtime API, die complete spraakgesprekken afhandelt, is de TTS-API een eenmalige service: u stuurt tekst en ontvangt een audiobestand. Het is het ideale hulpmiddel voor het genereren van omroepberichten, spraakmeldingen, luisterboeken of toegankelijke content.
Uw eerste TTS-oproep
Spraak genereren is opmerkelijk eenvoudig:
from openai import OpenAI
from pathlib import Path
client = OpenAI()
speech_file = Path("welcome.mp3")
with client.audio.speech.with_streaming_response.create(
model="gpt-4o-mini-tts",
voice="coral",
input="Welcome to Corsen Academy. "
"Your training on voice agents starts now.",
instructions="Speak in a warm, measured tone.",
) as response:
response.stream_to_file(speech_file)
De API retourneert een audiostream die u direct kunt opslaan of naar een speler kunt streamen. Gebruik with_streaming_response, zoals hier getoond: het aanroepen van stream_to_file() op het resultaat van een gewone speech.create() is verouderd in de SDK, die opmerkt dat dit de audio niet daadwerkelijk streamt.
Beschikbare modellen
De drie Audiomodellen zijn verouderd en worden op 6 januari 2027 uitgeschakeld: dit is de overgangsperiode waarin u ze nog kunt gebruiken.
| Model | Specificiteit | Stemmen |
|---|---|---|
gpt-4o-mini-tts | Accepteert instructies: accent, emotie, intonatie, snelheid, toon, fluisteren | 13 stemmen, waaronder marin en cedar, aanbevolen voor kwaliteit |
tts-1 | Lagere latentie, lagere kwaliteit | 9 stemmen: alloy, ash, coral, echo, fable, onyx, nova, sage, shimmer |
tts-1-hd | Hogere kwaliteit dan tts-1, hogere latentie | Dezelfde 9 stemmen |
Instructies werken niet met tts-1 en tts-1-hd. De parameter speed, van 0,25 tot 4,0, past de snelheid aan voor alle modellen. Volgens de gids zijn stemmen geoptimaliseerd voor Engels: luister ernaar in het Frans op OpenAI.fm voordat u kiest. Het gebruiksbeleid van OpenAI vereist ook dat u uw gebruikers duidelijk informeert dat de stem die ze horen door AI is gegenereerd.
Uitvoerformaten
De API produceert zes formaten, geselecteerd met response_format:
| Formaat | Gebruik |
|---|---|
mp3 (standaard) | Algemeen gebruik |
opus | Internetstreaming en communicatie, lage latentie |
aac | Digitale compressie, voorkeur van YouTube, Android en iOS |
flac | Lossless compressie, voor archivering |
wav | Ongecomprimeerd, om decoderingsoverhead te vermijden |
pcm | Ruwe samples op 24 kHz, 16-bit signed, geen header |
for fmt in ("mp3", "opus", "aac", "flac", "wav", "pcm"):
with client.audio.speech.with_streaming_response.create(
model="gpt-4o-mini-tts",
voice="marin",
input="Text to convert",
response_format=fmt,
) as response:
response.stream_to_file(f"example.{fmt}")
Voor een voice agent gebouwd op de Realtime API is het pcm-formaat het handigst: de samples van 24 kHz, 16-bit komen overeen met het audio/pcm-formaat van de Realtime API op 24 kHz.
Audio in batches genereren
Voor grote hoeveelheden tekst verwerkt u segmenten parallel:
import asyncio
from openai import AsyncOpenAI
async_client = AsyncOpenAI()
async def generate_speech_batch(segments: list[dict]) -> list[bytes]:
"""Generate audio for multiple segments in parallel."""
async def generate_one(segment):
response = await async_client.audio.speech.create(
model="gpt-4o-mini-tts",
voice=segment.get("voice", "alloy"),
input=segment["text"],
response_format="mp3"
)
return await response.aread()
tasks = [generate_one(seg) for seg in segments]
return await asyncio.gather(*tasks)
# Usage
segments = [
{"text": "Chapter one. Introduction to voice agents.", "voice": "onyx"},
{"text": "Voice agents transform human-computer interaction.", "voice": "onyx"},
{"text": "In this chapter, we'll explore the fundamentals.", "voice": "onyx"},
]
audio_chunks = asyncio.run(generate_speech_batch(segments))
# Concatenate files
from pydub import AudioSegment
import io
combined = AudioSegment.empty()
for chunk in audio_chunks:
segment = AudioSegment.from_mp3(io.BytesIO(chunk))
combined += segment
combined.export("chapter_1.mp3", format="mp3")
Tekstlimiet en splitsen
De TTS-API heeft een limiet van 4.096 tekens per verzoek. Voor langere teksten splitst u intelligent:
def split_text_for_tts(text: str, max_chars: int = 4000) -> list[str]:
"""Split text into segments respecting TTS limits."""
sentences = text.replace(". ", ".\n").split("\n")
segments = []
current = ""
for sentence in sentences:
if len(current) + len(sentence) + 1 > max_chars:
if current:
segments.append(current.strip())
current = sentence
else:
current += " " + sentence if current else sentence
if current:
segments.append(current.strip())
return segments
Na 6 januari 2027: Een Realtime-model laten spreken
OpenAI wijst gpt-realtime-2.1-mini aan als vervanger voor de drie modellen en waarschuwt: het is geen model voor het /v1/audio/speech-endpoint; migratie verandert de workflow. U doorloopt een Realtime-sessie. De gids Realtime conversations laat zien hoe u een respons krijgt zonder context, wat het gesprek negeert en alleen de instructies volgt: dit is de manier om het een bepaalde tekst te laten uitspreken.
import base64
import json
import os
import wave
import websocket # pip install websocket-client
TEXT = "Welcome to Corsen Academy. Your training on voice agents starts now."
ws = websocket.WebSocket()
ws.connect(
"wss://api.openai.com/v1/realtime?model=gpt-realtime-2.1-mini",
header=[f"Authorization: Bearer {os.environ['OPENAI_API_KEY']}"],
)
# Audio output only, 16-bit PCM at 24 kHz, with chosen voice
ws.send(json.dumps({
"type": "session.update",
"session": {
"type": "realtime",
"output_modalities": ["audio"],
"audio": {"output": {"format": {"type": "audio/pcm", "rate": 24000}, "voice": "marin"}},
},
}))
# A context-free response (empty input), which must say the text as-is
ws.send(json.dumps({
"type": "response.create",
"response": {
"input": [],
"output_modalities": ["audio"],
"instructions": f"Say exactly the following text, without adding anything:\n{TEXT}",
},
}))
audio, transcription = bytearray(), []
while True:
event = json.loads(ws.recv())
if event["type"] == "response.output_audio.delta":
audio += base64.b64decode(event["delta"])
elif event["type"] == "response.output_audio_transcript.delta":
transcription.append(event["delta"])
elif event["type"] == "error":
raise RuntimeError(event["error"]["message"])
elif event["type"] == "response.done":
break
ws.close()
with wave.open("welcome.wav", "wb") as wav:
wav.setnchannels(1)
wav.setsampwidth(2) # 16 bits
wav.setframerate(24000)
wav.writeframes(bytes(audio))
print("Spoken text:", "".join(transcription))
Twee verschillen met de Audio API zijn belangrijk in productie. Het resultaat is niet langer woord-voor-woord gegarandeerd: een Realtime-model volgt een instructie; het leest geen bestand. Vergelijk daarom de transcriptie van wat het zei, geretourneerd in response.output_audio_transcript.delta, met de verwachte tekst en genereer opnieuw bij een mismatch. De facturatie verandert ook: deze volgt de tarieven van het Realtime-model, in tekst- en audiotokens, vermeld op het specificatieblad. Tot slot voorkomt een geweigerde sleutel geen verbinding: deze komt net erna, in een error-event.
Belangrijkste punten
gpt-4o-mini-tts,tts-1entts-1-hdworden op 6 januari 2027 uitgeschakeld;gpt-4o-mini-ttsis de enige die steminstructies (instructions) accepteert- Neem audio op met
with_streaming_response:stream_to_file()op een gewonespeech.create()is verouderd - Zes uitvoerformaten: MP3, Opus, AAC, FLAC, WAV en ruwe PCM
- PCM-formaat is ideaal voor integratie met de Realtime API
- Limiet van 4.096 tekens per verzoek: splits lange teksten bij zinsgrenzen
- Batchverwerking met de async-client versnelt het genereren van grote inhoud
- Migratie verloopt via een Realtime-sessie met
gpt-realtime-2.1-mini: contextvrije respons, 24 kHz PCM-audio, transcriptie om te vergelijken met tekst