API-ul TTS: Generarea vorbirii
Pe această pagină
Actualizare 2 noiembrie 2026 — Modele audio. Mai multe modele din acest curs sunt depreciate:
tts-1,tts-1-hdșigpt-4o-mini-ttsvor fi închise pe 6 ianuarie 2027 (succesor:gpt-realtime-2.1-mini, pe care ghidul OpenAI TTS precizează că nu este suportat de/v1/audio/speech: migrarea sintezei vocale se mută către API-ul Realtime);gpt-realtime,gpt-4o-realtimeși modelele audio legacy pe 20 ianuarie 2027 (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5);whisper-1,gpt-4o-transcribeși/v1/audio/translationspe 26 februarie 2027 (gpt-transcribe,gpt-live-transcribe,v1/realtime/translations). Pentru voce full-duplex, GPT-Live 1 este disponibil în API din 10 septembrie 2026. Lecție corectată pe 3 noiembrie 2026:response.stream_to_file()pe rezultatul luispeech.create()este depreciat de SDK („Din cauza unei erori, această metodă nu face stream-ing real“) → utilizațiwith_streaming_response, ca în ghidul oficial; modelele și vocile au fost actualizate (gpt-4o-mini-ttsși instrucțiunile sale vocale, 13 voci inclusivmarinșicedar); nouă secțiune despre migrarea cătregpt-realtime-2.1-miniînainte de 6 ianuarie 2027, bazată pe ghidul Conversații în timp real. Surse: Text to speech · Create speech · Realtime conversations · Deprecations.
API-ul TTS: Generarea vorbirii
API-ul Text-to-Speech (TTS) de la OpenAI convertește textul în audio de înaltă calitate. Spre deosebire de API-ul Realtime, care gestionează conversații vocale complete, API-ul TTS este un serviciu de tip „single-shot“: trimiteți text și primiți un fișier audio. Este instrumentul ideal pentru generarea de anunțuri, notificări vocale, audiobooks sau conținut accesibil.
Primul dumneavoastră apel TTS
Generarea vorbirii este remarcabil de simplă:
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="Bine ați venit la Corsen Academy. "
"Instruirea dumneavoastră privind agenții vocali începe acum.",
instructions="Vorbește cu un ton cald și măsurat.",
) as response:
response.stream_to_file(speech_file)
API-ul returnează un flux audio pe care îl puteți salva direct sau reda către un player. Utilizați with_streaming_response, așa cum se arată aici: apelarea stream_to_file() pe rezultatul unui speech.create() simplu este depreciată de SDK, care menționează că aceasta nu face efectiv stream-ing audio.
Modele disponibile
Cele trei modele ale API-ului Audio sunt depreciate și vor fi închise pe 6 ianuarie 2027: aceasta este perioada de tranziție în care le veți mai utiliza.
| Model | Specificitate | Voci |
|---|---|---|
gpt-4o-mini-tts | Acceptă instrucțiuni: accent, emoție, intonație, viteză, ton, șoaptă | 13 voci, inclusiv marin și cedar, recomandate pentru calitate |
tts-1 | Latență mai mică, calitate inferioară | 9 voci: alloy, ash, coral, echo, fable, onyx, nova, sage, shimmer |
tts-1-hd | Calitate superioară față de tts-1, latență mai mare | Aceleași 9 voci |
Instrucțiunile nu funcționează cu tts-1 și tts-1-hd. Parametrul speed, de la 0.25 la 4.0, ajustează viteza pentru toate modelele. Conform ghidului, vocile sunt optimizate pentru engleză: ascultați-le în franceză pe OpenAI.fm înainte de a alege. Politicile de utilizare ale OpenAI vă cer, de asemenea, să informați clar utilizatorii că vocea pe care o aud este generată de IA.
Formate de ieșire
API-ul produce șase formate, selectate prin response_format:
| Format | Utilizare |
|---|---|
mp3 (implicit) | Uz general |
opus | Streaming și comunicații pe internet, latență redusă |
aac | Compresie digitală, preferat de YouTube, Android și iOS |
flac | Compresie fără pierderi, pentru arhivare |
wav | Necompresat, pentru a evita overhead-ul de decodare |
pcm | Eșantioane brute la 24 kHz, 16-bit semnat, fără antet |
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 de convertit",
response_format=fmt,
) as response:
response.stream_to_file(f"example.{fmt}")
Pentru un agent vocal construit pe API-ul Realtime, formatul pcm este cel mai convenabil: eșantioanele sale de 24 kHz, 16-bit corespund formatului audio/pcm al API-ului Realtime la 24 kHz.
Generarea audio în loturi
Pentru volume mari de text, procesați segmentele în paralel:
import asyncio
from openai import AsyncOpenAI
async_client = AsyncOpenAI()
async def generate_speech_batch(segments: list[dict]) -> list[bytes]:
"""Generează audio pentru multiple segmente în paralel."""
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)
# Utilizare
segments = [
{"text": "Capitolul unu. Introducere în agenții vocali.", "voice": "onyx"},
{"text": "Agenții vocali transformă interacțiunea om-calculator.", "voice": "onyx"},
{"text": "În acest capitol, vom explora fundamentele.", "voice": "onyx"},
]
audio_chunks = asyncio.run(generate_speech_batch(segments))
# Concatenarea fișierelor
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")
Limita de caractere și divizarea
API-ul TTS are o limită de 4.096 de caractere per cerere. Pentru texte mai lungi, divizați inteligent:
def split_text_for_tts(text: str, max_chars: int = 4000) -> list[str]:
"""Divide textul în segmente respectând limitele TTS."""
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
După 6 ianuarie 2027: Facerea unui model Realtime să vorbească
OpenAI desemnează gpt-realtime-2.1-mini ca înlocuitor pentru cele trei modele și avertizează: nu este un model pentru endpoint-ul /v1/audio/speech; migrarea schimbă fluxul de lucru. Treceți printr-o sesiune Realtime. Ghidul Conversații în timp real arată cum să obțineți un răspuns fără context, care ignoră conversația și urmează doar instrucțiunile sale: aceasta este modalitatea de a-l face să spună un text dat.
import base64
import json
import os
import wave
import websocket # pip install websocket-client
TEXT = "Bine ați venit la Corsen Academy. Instruirea dumneavoastră privind agenții vocali începe acum."
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']}"],
)
# Doar ieșire audio, PCM 16-bit la 24 kHz, cu vocea aleasă
ws.send(json.dumps({
"type": "session.update",
"session": {
"type": "realtime",
"output_modalities": ["audio"],
"audio": {"output": {"format": {"type": "audio/pcm", "rate": 24000}, "voice": "marin"}},
},
}))
# Un răspuns fără context (input gol), care trebuie să spună textul ca atare
ws.send(json.dumps({
"type": "response.create",
"response": {
"input": [],
"output_modalities": ["audio"],
"instructions": f"Spune exact următorul text, fără a adăuga nimic:\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 biți
wav.setframerate(24000)
wav.writeframes(bytes(audio))
print("Text rostit:", "".join(transcription))
Două diferențe față de API-ul Audio contează în producție. Rezultatul nu mai este garantat cuvânt cu cuvânt: un model Realtime urmează o instrucțiune; nu citește un fișier. Așadar, comparați transcrierea a ceea ce a spus, returnată în response.output_audio_transcript.delta, cu textul așteptat și regenerați dacă există o neconcordanță. Facturarea se schimbă și ea: urmează tarifele modelului Realtime, în tokeni de text și audio, listate în fișa sa tehnică. În final, o cheie respinsă nu împiedică conectarea: aceasta ajunge imediat după, într-un eveniment error.
Puncte cheie
gpt-4o-mini-tts,tts-1șitts-1-hdse închid pe 6 ianuarie 2027;gpt-4o-mini-ttseste singurul care acceptă instrucțiuni vocale (instructions)- Înregistrați audio cu
with_streaming_response:stream_to_file()pe unspeech.create()simplu este depreciat - Șase formate de ieșire: MP3, Opus, AAC, FLAC, WAV și PCM brut
- Formatul PCM este ideal pentru integrarea cu API-ul Realtime
- Limita de 4.096 de caractere per cerere: divizați textele lungi la limitele propozițiilor
- Procesarea în loturi cu clientul asincron accelerează generarea conținutului voluminos
- Migrarea trece printr-o sesiune Realtime cu
gpt-realtime-2.1-mini: răspuns fără context, audio PCM la 24 kHz, transcriere pentru comparare cu textul