L'API TTS: generare voce
In questa pagina
Aggiornamento 2 novembre 2026 — Modelli audio. Diversi modelli in questo corso sono deprecati:
tts-1,tts-1-hdegpt-4o-mini-ttsverranno disattivati il 6 gennaio 2027 (successore:gpt-realtime-2.1-mini, che la guida TTS di OpenAI indica come non supportato da/v1/audio/speech: la migrazione della sintesi vocale passa all’API Realtime);gpt-realtime,gpt-4o-realtimee i modelli audio legacy il 20 gennaio 2027 (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5);whisper-1,gpt-4o-transcribee/v1/audio/translationsil 26 febbraio 2027 (gpt-transcribe,gpt-live-transcribe,v1/realtime/translations). Per la voce full-duplex, GPT-Live 1 è disponibile nell’API dal 10 settembre 2026. Lezione corretta il 3 novembre 2026:response.stream_to_file()sul risultato dispeech.create()è deprecato dall’SDK (“A causa di un bug, questo metodo non effettua realmente lo streaming”) → usawith_streaming_response, come nella guida ufficiale; modelli e voci aggiornati (gpt-4o-mini-ttse le relative istruzioni vocali, 13 voci tra cuimarinecedar); nuova sezione sulla migrazione agpt-realtime-2.1-miniprima del 6 gennaio 2027, basata sulla guida Realtime conversations. Fonti: Text to speech · Create speech · Realtime conversations · Deprecations.
L’API TTS: generare voce
L’API Text-to-Speech (TTS) di OpenAI converte il testo in audio di alta qualità. A differenza dell’API Realtime, che gestisce conversazioni vocali complete, l’API TTS è un servizio “one-shot”: invii del testo e ricevi un file audio. È lo strumento ideale per generare annunci, notifiche vocali, audiolibri o contenuti accessibili.
La tua prima chiamata TTS
Generare voce è estremamente semplice:
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="Benvenuto alla Corsen Academy. "
"La tua formazione sugli agenti vocali inizia ora.",
instructions="Parla con un tono caldo e misurato.",
) as response:
response.stream_to_file(speech_file)
L’API restituisce un flusso audio che puoi salvare direttamente o trasmettere a un player. Usa with_streaming_response, come mostrato qui: chiamare stream_to_file() sul risultato di un semplice speech.create() è deprecato dall’SDK, che segnala che non effettua realmente lo streaming dell’audio.
Modelli disponibili
I tre modelli dell’API Audio sono deprecati e verranno disattivati il 6 gennaio 2027: questo è il periodo di transizione durante il quale potrai ancora utilizzarli.
| Modello | Specificità | Voci |
|---|---|---|
gpt-4o-mini-tts | Accetta istruzioni: accento, emozione, intonazione, velocità, tono, sussurro | 13 voci, tra cui marin e cedar, raccomandate per la qualità |
tts-1 | Latenza inferiore, qualità inferiore | 9 voci: alloy, ash, coral, echo, fable, onyx, nova, sage, shimmer |
tts-1-hd | Qualità superiore a tts-1, latenza superiore | Le stesse 9 voci |
Le istruzioni non funzionano con tts-1 e tts-1-hd. Il parametro speed, da 0.25 a 4.0, regola la velocità con tutti i modelli. Secondo la guida, le voci sono ottimizzate per l’inglese: ascoltale in francese su OpenAI.fm prima di scegliere. Le politiche d’uso di OpenAI richiedono inoltre di informare chiaramente i tuoi utenti che la voce che ascoltano è generata dall’IA.
Formati di output
L’API produce sei formati, selezionabili tramite response_format:
| Formato | Utilizzo |
|---|---|
mp3 (default) | Uso generale |
opus | Streaming internet e comunicazione, bassa latenza |
aac | Compressione digitale, preferito da YouTube, Android e iOS |
flac | Compressione lossless, per l’archiviazione |
wav | Non compresso, per evitare overhead di decodifica |
pcm | Campioni grezzi a 24 kHz, 16-bit signed, senza 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="Testo da convertire",
response_format=fmt,
) as response:
response.stream_to_file(f"example.{fmt}")
Per un agente vocale costruito sull’API Realtime, il formato pcm è il più comodo: i suoi campioni a 24 kHz, 16-bit corrispondono al formato audio/pcm dell’API Realtime a 24 kHz.
Generare audio in batch
Per grandi volumi di testo, elabora i segmenti in parallelo:
import asyncio
from openai import AsyncOpenAI
async_client = AsyncOpenAI()
async def generate_speech_batch(segments: list[dict]) -> list[bytes]:
"""Genera audio per più segmenti in parallelo."""
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)
# Utilizzo
segments = [
{"text": "Capitolo uno. Introduzione agli agenti vocali.", "voice": "onyx"},
{"text": "Gli agenti vocali trasformano l'interazione uomo-computer.", "voice": "onyx"},
{"text": "In questo capitolo esploreremo i fondamenti.", "voice": "onyx"},
]
audio_chunks = asyncio.run(generate_speech_batch(segments))
# Concatena i file
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")
Limite di caratteri e suddivisione
L’API TTS ha un limite di 4.096 caratteri per richiesta. Per testi più lunghi, suddividi in modo intelligente:
def split_text_for_tts(text: str, max_chars: int = 4000) -> list[str]:
"""Suddivide il testo in segmenti rispettando i limiti 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
Dopo il 6 gennaio 2027: far parlare un modello Realtime
OpenAI indica gpt-realtime-2.1-mini come sostituto dei tre modelli e avverte: non è un modello per l’endpoint /v1/audio/speech; la migrazione cambia il flusso di lavoro. Devi passare attraverso una sessione Realtime. La guida Realtime conversations mostra come ottenere una risposta senza contesto, che ignora la conversazione e segue solo le sue istruzioni: questo è il modo per fargli dire un testo dato.
import base64
import json
import os
import wave
import websocket # pip install websocket-client
TEXT = "Benvenuto alla Corsen Academy. La tua formazione sugli agenti vocali inizia ora."
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']}"],
)
# Solo output audio, PCM 16-bit a 24 kHz, con voce scelta
ws.send(json.dumps({
"type": "session.update",
"session": {
"type": "realtime",
"output_modalities": ["audio"],
"audio": {"output": {"format": {"type": "audio/pcm", "rate": 24000}, "voice": "marin"}},
},
}))
# Una risposta senza contesto (input vuoto), che deve dire il testo così com'è
ws.send(json.dumps({
"type": "response.create",
"response": {
"input": [],
"output_modalities": ["audio"],
"instructions": f"Dici esattamente il seguente testo, senza aggiungere nulla:\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("Testo parlato:", "".join(transcription))
Due differenze con l’API Audio sono cruciali in produzione. Il risultato non è più garantito parola per parola: un modello Realtime segue un’istruzione; non legge un file. Quindi confronta la trascrizione di ciò che ha detto, restituita in response.output_audio_transcript.delta, con il testo previsto e rigenera se c’è una discrepanza. Cambia anche la fatturazione: segue le tariffe del modello Realtime, in token di testo e audio, elencate nella sua scheda tecnica. Infine, una chiave rifiutata non impedisce la connessione: arriva poco dopo, in un evento error.
Punti chiave
gpt-4o-mini-tts,tts-1etts-1-hdverranno disattivati il 6 gennaio 2027;gpt-4o-mini-ttsè l’unico che accetta istruzioni vocali (instructions)- Registra l’audio con
with_streaming_response:stream_to_file()su un semplicespeech.create()è deprecato - Sei formati di output: MP3, Opus, AAC, FLAC, WAV e PCM grezzo
- Il formato PCM è ideale per l’integrazione con l’API Realtime
- Limite di 4.096 caratteri per richiesta: suddividi i testi lunghi ai confini delle frasi
- L’elaborazione in batch con il client async accelera la generazione di grandi contenuti
- La migrazione passa attraverso una sessione Realtime con
gpt-realtime-2.1-mini: risposta senza contesto, audio PCM a 24 kHz, trascrizione da confrontare con il testo