A TTS API: Beszéd előállítása
Ezen az oldalon
Frissítés: 2026. november 2. – Hangmodellek. A tanfolyam több modellje elavult: a
tts-1,tts-1-hdés agpt-4o-mini-ttsleáll 2027. január 6-án (utód:gpt-realtime-2.1-mini, amelyet az OpenAI TTS útmutatója szerint nem támogat a/v1/audio/speech: a beszédszintézis migrációja a Realtime API-ra helyeződik át); agpt-realtime,gpt-4o-realtimeés a régi hangmodellek 2027. január 20-án (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5); awhisper-1,gpt-4o-transcribeés a/v1/audio/translations2027. február 26-án (gpt-transcribe,gpt-live-transcribe,v1/realtime/translations). A teljes duplex hangkommunikációhoz a GPT-Live 1 már 2026. szeptember 10. óta elérhető az API-ban. A lecke javítva: 2026. november 3. Aspeech.create()eredményén hívottresponse.stream_to_file()elavult az SDK szerint („Egy hiba miatt ez a módszer valójában nem streamel“) → használd awith_streaming_responselehetőséget, ahogy a hivatalos útmutató is javasolja; modellek és hangok frissítve (gpt-4o-mini-ttsés annak hangutasításai, 13 hang, köztük amarinés acedar); új szakasz agpt-realtime-2.1-minimodellre való átállásról 2027. január 6. előtt, a Realtime conversations útmutató alapján. Források: Text to speech · Create speech · Realtime conversations · Deprecations.
A TTS API: Beszéd előállítása
Az OpenAI Text-to-Speech (TTS) API-ja szöveget alakít át kiváló minőségű hanganyaggá. Ellentétben a Realtime API-val, amely teljes hangalapú beszélgetéseket kezel, a TTS API egy egyszeri szolgáltatás: szöveget küldesz, és hangfájlt kapsz vissza. Ideális eszköz bejelentések, hangértesítések, hangoskönyvek vagy akadálymentesített tartalmak generálásához.
Az első TTS hívásod
A beszéd előállítása rendkívül egyszerű:
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="Üdvözöllek a Corsen Academy-n. "
"Most kezdődik a hangügynökökről szóló képzésed.",
instructions="Beszélj meleg, mérlegelt hangnemben.",
) as response:
response.stream_to_file(speech_file)
Az API egy hangstreamet ad vissza, amelyet közvetlenül elmenthetsz, vagy lejátszóba streamelhetsz. Használd a with_streaming_response lehetőséget, ahogy itt látható: a sima speech.create() eredményén hívott stream_to_file() elavult az SDK szerint, amely megjegyzi, hogy ez valójában nem streameli a hangot.
Elérhető modellek
A három Audio API modell elavult, és 2027. január 6-án leáll: ez az az átmeneti időszak, amikor még használhatod őket.
| Modell | Sajátosság | Hangok |
|---|---|---|
gpt-4o-mini-tts | Elfogad utasításokat: hangsúly, érzelem, hanglejtés, sebesség, hangnem, suttogás | 13 hang, köztük a marin és a cedar, minőség szempontjából ajánlott |
tts-1 | Alacsonyabb késleltetés, alacsonyabb minőség | 9 hang: alloy, ash, coral, echo, fable, onyx, nova, sage, shimmer |
tts-1-hd | Magasabb minőség, mint a tts-1, nagyobb késleltetés | Ugyanaz a 9 hang |
Az utasítások nem működnek a tts-1 és tts-1-hd modellekkel. A speed paraméter, 0,25 és 4,0 között, az összes modellnél állítja a sebességet. Az útmutató szerint a hangok angol nyelvre vannak optimalizálva: mielőtt választasz, hallgasd meg őket franciául az OpenAI.fm oldalon. Az OpenAI használati szabályzata előírja továbbá, hogy egyértelműen tájékoztasd felhasználóidat arról, hogy a hallott hangot mesterséges intelligencia generálta.
Kimeneti formátumok
Az API hat formátumot állít elő, amelyeket a response_format paraméterrel választhatsz ki:
| Formátum | Használat |
|---|---|
mp3 (alapértelmezett) | Általános használat |
opus | Internetes streamelés és kommunikáció, alacsony késleltetés |
aac | Digitális tömörítés, a YouTube, Android és iOS preferálja |
flac | Veszteségmentes tömörítés, archiváláshoz |
wav | Tömörítetlen, a dekódolási overhead elkerülésére |
pcm | Nyers minták 24 kHz-en, 16 bites előjeles, fejléc nélkül |
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="Átalakítandó szöveg",
response_format=fmt,
) as response:
response.stream_to_file(f"example.{fmt}")
Egy Realtime API-ra épülő hangügynök esetén a pcm formátum a legkényelmesebb: 24 kHz-es, 16 bites mintái megegyeznek a Realtime API 24 kHz-es audio/pcm formátumával.
Hanganyag generálása kötegekben
Nagy mennyiségű szöveg esetén dolgozd fel a szegmenseket párhuzamosan:
import asyncio
from openai import AsyncOpenAI
async_client = AsyncOpenAI()
async def generate_speech_batch(segments: list[dict]) -> list[bytes]:
"""Hang előállítása több szegmenshez párhuzamosan."""
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)
# Használat
segments = [
{"text": "Első fejezet. Bevezetés a hangügynökök világába.", "voice": "onyx"},
{"text": "A hangügynökök átalakítják az ember-számítógép interakciót.", "voice": "onyx"},
{"text": "Ebben a fejezetben az alapokat vizsgáljuk meg.", "voice": "onyx"},
]
audio_chunks = asyncio.run(generate_speech_batch(segments))
# Fájlok összefűzése
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")
Karakterkorlát és felosztás
A TTS API kérésenként 4096 karakteres korláttal rendelkezik. Hosszabb szövegeknél osszd fel őket intelligensen:
def split_text_for_tts(text: str, max_chars: int = 4000) -> list[str]:
"""Szöveg felosztása szegmensekre a TTS korlátainak betartásával."""
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
2027. január 6. után: Egy Realtime modell megszólaltatása
Az OpenAI a gpt-realtime-2.1-mini modellt jelöli ki a három modell utódjaként, és figyelmeztet: ez nem modell a /v1/audio/speech végponthoz; a migráció megváltoztatja a munkafolyamatot. Egy Realtime munkameneten keresztül kell haladnod. A Realtime conversations útmutató bemutatja, hogyan kaphatsz választ kontextus nélkül, ami figyelmen kívül hagyja a beszélgetést, és csak az utasításokat követi: ez a módja annak, hogy kimondass vele egy adott szöveget.
import base64
import json
import os
import wave
import websocket # pip install websocket-client
TEXT = "Üdvözöllek a Corsen Academy-n. Most kezdődik a hangügynökökről szóló képzésed."
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']}"],
)
# Csak hangkimenet, 16 bites PCM 24 kHz-en, választott hanggal
ws.send(json.dumps({
"type": "session.update",
"session": {
"type": "realtime",
"output_modalities": ["audio"],
"audio": {"output": {"format": {"type": "audio/pcm", "rate": 24000}, "voice": "marin"}},
},
}))
# Kontextus nélküli válasz (üres bemenet), amelynek pontosan ezt a szöveget kell kimondania
ws.send(json.dumps({
"type": "response.create",
"response": {
"input": [],
"output_modalities": ["audio"],
"instructions": f"Mondjad ki pontosan a következő szöveget, semmit sem hozzáadva:\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 bit
wav.setframerate(24000)
wav.writeframes(bytes(audio))
print("Kimondott szöveg:", "".join(transcription))
Két különbség az Audio API-hoz képest fontos a production környezetben. Az eredmény már nem garantált szóról szóra: egy Realtime modell egy utasítást követ; nem olvas fel egy fájlt. Hasonlítsd tehát össze a response.output_audio_transcript.delta által visszaadott átírást a várt szöveggel, és generáld újra, ha eltérés van. A számlázás is megváltozik: az a Realtime modell díjszabását követi, szöveg- és hangtokenek alapján, amely a specifikációs lapján szerepel. Végül, egy elutasított kulcs nem akadályozza meg a kapcsolódást: ez csak utóbb következik be, egy error eseményben.
Főbb megállapítások
- A
gpt-4o-mini-tts,tts-1éstts-1-hdmodellek leállnak 2027. január 6-án; agpt-4o-mini-ttsaz egyetlen, amely elfogad hangutasításokat (instructions) - A hang rögzítéséhez használd a
with_streaming_responselehetőséget: a simaspeech.create()eredményén hívottstream_to_file()elavult - Hat kimeneti formátum: MP3, Opus, AAC, FLAC, WAV és nyers PCM
- A PCM formátum ideális a Realtime API-val való integrációhoz
- Kérésenkénti 4096 karakteres korlát: a hosszú szövegeket mondatvégeknél érdemes felosztani
- A kötegelt feldolgozás az aszinkron klienssel felgyorsítja a nagy tartalmak generálását
- A migráció egy Realtime munkameneten keresztül történik a
gpt-realtime-2.1-minimodellel: kontextus nélküli válasz, 24 kHz-es PCM hang, átírás a szöveggel való összehasonlításhoz