API TTS: Generovanie reči
Na tejto strane
Aktualizácia 2. novembra 2026 — Zvukové modely. Niekoľko modelov v tomto kurze je zastaraných:
tts-1,tts-1-hdagpt-4o-mini-ttsbudú vypnuté 6. januára 2027 (nástupca:gpt-realtime-2.1-mini, ktorý podľa príručky OpenAI TTS nie je podporovaný koncovým bodom/v1/audio/speech: migrácia syntézy reči prebieha do Realtime API);gpt-realtime,gpt-4o-realtimea staršie zvukové modely 20. januára 2027 (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5);whisper-1,gpt-4o-transcribea/v1/audio/translations26. februára 2027 (gpt-transcribe,gpt-live-transcribe,v1/realtime/translations). Pre plno duplexný hlas je GPT-Live 1 dostupné v API od 10. septembra 2026. Lekcia opravená 3. novembra 2026:response.stream_to_file()na výsledkuspeech.create()je zastarané SDK („kvôli chybe táto metóda v skutočnosti nestreamuje“) → použitewith_streaming_response, ako v oficiálnej príručke; aktualizované modely a hlasy (gpt-4o-mini-ttsa jeho pokyny pre hlas, 13 hlasov vrátanemarinacedar); nová sekcia o migrácii nagpt-realtime-2.1-minipred 6. januárom 2027 na základe príručky Realtime conversations. Zdroje: Text to speech · Create speech · Realtime conversations · Deprecations.
API TTS: Generovanie reči
API OpenAI Text-to-Speech (TTS) prevádza text na vysokokvalitné audio. Na rozdiel od Realtime API, ktoré spravuje kompletné hlasové konverzácie, je API TTS službou typu „jeden výstrel“: pošlete text a dostanete zvukový súbor. Je to ideálny nástroj na generovanie oznámení, hlasových upozornení, audiokníh alebo dostupného obsahu.
Tvoj prvý volanie TTS
Generovanie reči je pozoruhodne 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 vráti zvukový stream, ktorý môžeš buď uložiť, alebo streamovať priamo do prehrávača. Použi with_streaming_response, ako je ukázané tu: volanie stream_to_file() na výsledku obyčajného speech.create() je zastarané SDK, ktoré upozorňuje, že audio v skutočnosti nestreamuje.
Dostupné modely
Tri modely Audio API sú zastarané a budú vypnuté 6. januára 2027: toto je prechodné obdobie, počas ktorého ich budeš ešte používať.
| Model | Špecifikum | Hlasy |
|---|---|---|
gpt-4o-mini-tts | Prijíma pokyny: prízvuk, emócia, intonácia, rýchlosť, tón, šepot | 13 hlasov, vrátane marin a cedar, odporúčané pre kvalitu |
tts-1 | Nižšia latencia, nižšia kvalita | 9 hlasov: alloy, ash, coral, echo, fable, onyx, nova, sage, shimmer |
tts-1-hd | Vyššia kvalita ako tts-1, vyššia latencia | Rovnakých 9 hlasov |
Pokyny nefungujú s tts-1 a tts-1-hd. Parameter speed, od 0,25 do 4,0, upravuje rýchlosť pri všetkých modeloch. Podľa príručky sú hlasy optimalizované pre angličtinu: vypočuj si ich vo francúzštine na OpenAI.fm pred výberom. Politiky používania OpenAI tiež vyžadujú, aby si používateľov jasne informoval, že hlas, ktorý počujú, je generovaný AI.
Výstupné formáty
API produkuje šesť formátov, ktoré vyberieš pomocou response_format:
| Formát | Použitie |
|---|---|
mp3 (predvolený) | Všeobecné použitie |
opus | Internetové streamovanie a komunikácia, nízka latencia |
aac | Digitálna kompresia, preferované YouTube, Androidom a iOS |
flac | Bezstratová kompresia, na archiváciu |
wav | Nekompresné, aby sa predišlo nárokom na dekódovanie |
pcm | Surové vzorky pri 24 kHz, 16-bitové so znamienkom, 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}")
Pre hlasového agenta postaveného na Realtime API je formát pcm najvhodnejší: jeho vzorky 24 kHz, 16-bitové zodpovedajú formátu audio/pcm Realtime API pri 24 kHz.
Generovanie audia v dávkach
Pre veľké objemy textu spracúvaj segmenty paralelne:
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 znakov a rozdelenie
API TTS má limit 4 096 znakov na požiadavku. Pre dlhšie texty rozdeľuj rozumne:
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. januári 2027: Ako nechať hovoriť Realtime model
OpenAI označuje gpt-realtime-2.1-mini ako náhradu za tieto tri modely a upozorňuje: nie je to model pre koncový bod /v1/audio/speech; migrácia mení pracovný postup. Prejdeš cez reláciu Realtime. Príručka Realtime conversations ukazuje, ako získať odpoveď bez kontextu, ktorá ignoruje konverzáciu a nasleduje len jej pokyny: toto je spôsob, ako donútiť model povedať 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 produkcii záleží na dvoch rozdieloch oproti Audio API. Výsledok už nie je zaručený slovo od slova: Realtime model nasleduje pokyn; nečíta súbor. Porovnaj teda prepis toho, čo povedal, vrátený v response.output_audio_transcript.delta, s očakávaným textom a v prípade nezhody generuj znova. Mení sa aj fakturácia: riadi sa sadzbami Realtime modelu, v textových a audio tokenoch, uvedenými v jeho špecifikácii. Nakoniec, zamietnutý kľúč nezabráni pripojeniu: príde až následne, v udalosti error.
Kľúčové poznatky
gpt-4o-mini-tts,tts-1atts-1-hdbudú vypnuté 6. januára 2027;gpt-4o-mini-ttsje jediný, ktorý prijíma pokyny pre hlas (instructions)- Nahrávaj audio pomocou
with_streaming_response:stream_to_file()na obyčajnomspeech.create()je zastarané - Šesť výstupných formátov: MP3, Opus, AAC, FLAC, WAV a surové PCM
- Formát PCM je ideálny pre integráciu s Realtime API
- Limit 4 096 znakov na požiadavku: dlhé texty rozdeľuj na hraniciach viet
- Dávkové spracovanie s asynchrónnym klientom urýchľuje generovanie veľkého obsahu
- Migrácia prebieha cez reláciu Realtime s
gpt-realtime-2.1-mini: odpoveď bez kontextu, 24 kHz PCM audio, prepis na porovnanie s textom