API TTS: Generování řeči
Na této stránce
Aktualizace 2. listopadu 2026 — Zvukové modely. Několik modelů v tomto kurzu je zastaralých:
tts-1,tts-1-hdagpt-4o-mini-ttsbudou vypnuty 6. ledna 2027 (nástupce:gpt-realtime-2.1-mini, který podle průvodce OpenAI TTS není podporován koncovým bodem/v1/audio/speech: migrace syntézy řeči přechází na Realtime API);gpt-realtime,gpt-4o-realtimea starší zvukové modely 20. ledna 2027 (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5);whisper-1,gpt-4o-transcribea/v1/audio/translations26. února 2027 (gpt-transcribe,gpt-live-transcribe,v1/realtime/translations). Pro plně duplexní hlas je GPT-Live 1 dostupné v API od 10. září 2026. Lekce opravena 3. listopadu 2026:response.stream_to_file()na výsledkuspeech.create()je v SDK zastaralá („kvůli chybě tato metoda ve skutečnosti nestreamuje“) → použijwith_streaming_response, jak je uvedeno v oficiálním průvodci; modely a hlasy aktualizovány (gpt-4o-mini-ttsa jeho pokyny pro hlas, 13 hlasů včetněmarinacedar); nová sekce o migraci nagpt-realtime-2.1-minipřed 6. lednem 2027 na základě průvodce Realtime conversations. Zdroje: Text to speech · Create speech · Realtime conversations · Deprecations.
API TTS: Generování řeči
API OpenAI pro převod textu na řeč (TTS) převádí text na vysoce kvalitní zvuk. Na rozdíl od Realtime API, které zpracovává kompletní hlasové konverzace, je API TTS službou typu „jeden výstřel“: odešleš text a obdržíš zvukový soubor. Je to ideální nástroj pro generování oznámení, hlasových upozornění, audioknih nebo obsahu pro usnadnění přístupu.
Tvůj první volání TTS
Generování řeči je překvapivě jednoduché:
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)
API vrací zvukový stream, který můžeš buď přímo uložit, nebo streamovat do přehrávače. Použij with_streaming_response, jak je zde ukázáno: volání stream_to_file() na výsledku prostého speech.create() je v SDK zastaralé, protože upozorňuje, že ve skutečnosti nestreamuje zvuk.
Dostupné modely
Tři modely Audio API jsou zastaralé a budou vypnuty 6. ledna 2027: toto je přechodné období, během kterého je budeš stále používat.
| Model | Specifičnost | Hlasy |
|---|---|---|
gpt-4o-mini-tts | Přijímá pokyny: přízvuk, emoce, intonace, rychlost, tón, šepot | 13 hlasů, včetně marin a cedar, doporučeno pro kvalitu |
tts-1 | Nižší latence, nižší kvalita | 9 hlasů: alloy, ash, coral, echo, fable, onyx, nova, sage, shimmer |
tts-1-hd | Vyšší kvalita než tts-1, vyšší latence | Stejných 9 hlasů |
Pokyny nefungují s tts-1 a tts-1-hd. Parametr speed od 0,25 do 4,0 upravuje rychlost u všech modelů. Podle průvodce jsou hlasy optimalizovány pro angličtinu: poslechni si je ve francouzštině na OpenAI.fm před výběrem. Zásady používání OpenAI také vyžadují, abys své uživatele jasně informoval, že hlas, který slyší, je generován umělou inteligencí.
Výstupní formáty
API produkuje šest formátů, které vybereš pomocí response_format:
| Formát | Použití |
|---|---|
mp3 (výchozí) | Obecné použití |
opus | Streamování a komunikace přes internet, nízká latence |
aac | Digitální komprese, preferováno YouTube, Androidem a iOS |
flac | Bezztrátová komprese, pro archivaci |
wav | Nekompresní, aby se předešlo režii dekódování |
pcm | Surové vzorky při 24 kHz, 16bitové se znaménkem, bez hlavičky |
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}")
Pro hlasového agenta postaveného na Realtime API je formát pcm nejvhodnější: jeho vzorky 24 kHz, 16bitové odpovídají formátu audio/pcm Realtime API při 24 kHz.
Generování zvuku v dávkách
Pro velké objemy textu zpracovávej segmenty paralelně:
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")
Limit znaků a rozdělování
API TTS má limit 4 096 znaků na žádost. U delších textů je rozděluj inteligentně:
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
Po 6. lednu 2027: Jak nechat mluvit model Realtime
OpenAI označuje gpt-realtime-2.1-mini jako náhradu za tyto tři modely a varuje: není to model pro koncový bod /v1/audio/speech; migrace mění pracovní postup. Procházíš relací Realtime. Průvodce Realtime conversations ukazuje, jak získat odpověď bez kontextu, která ignoruje konverzaci a řídí se pouze pokyny: takto donutíš model říct daný text.
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))
V produkci záleží na dvou rozdílech oproti Audio API. Výsledek již není zaručen slovo od slova: model Realtime se řídí pokynem; nečte soubor. Porovnej tedy přepis toho, co řekl, vrácený v response.output_audio_transcript.delta, s očekávaným textem a v případě neshody generování opakuj. Změní se také fakturace: řídí se sazbami modelu Realtime, v textových a zvukových tokenech, uvedenými v jeho specifikaci. Nakonec, zamítnutý klíč nezabrání připojení: přijde až poté, v události error.
Klíčové poznatky
gpt-4o-mini-tts,tts-1atts-1-hdbudou vypnuty 6. ledna 2027;gpt-4o-mini-ttsje jediný, který přijímá pokyny pro hlas (instructions)- Zaznamenávej zvuk pomocí
with_streaming_response:stream_to_file()na prostémspeech.create()je zastaralé - Šest výstupních formátů: MP3, Opus, AAC, FLAC, WAV a surové PCM
- Formát PCM je ideální pro integraci s Realtime API
- Limit 4 096 znaků na žádost: dlouhé texty rozděluj na hranicích vět
- Dávkové zpracování s asynchronním klientem urychluje generování velkého obsahu
- Migrace probíhá prostřednictvím relace Realtime s
gpt-realtime-2.1-mini: odpověď bez kontextu, zvuk PCM 24 kHz, přepis pro porovnání s textem