Vai al contenuto principale
Italiano— Scegli una lingua
Menu

L'API TTS: generare voce

Lezione 10 di 18 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. L’API TTS: generare voce
  2. La tua prima chiamata TTS
  3. Modelli disponibili
  4. Formati di output
  5. Generare audio in batch
  6. Limite di caratteri e suddivisione
  7. Dopo il 6 gennaio 2027: far parlare un modello Realtime
  8. Punti chiave

Aggiornamento 2 novembre 2026 — Modelli audio. Diversi modelli in questo corso sono deprecati: tts-1, tts-1-hd e gpt-4o-mini-tts verranno 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-realtime e 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-transcribe e /v1/audio/translations il 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 di speech.create() è deprecato dall’SDK (“A causa di un bug, questo metodo non effettua realmente lo streaming”) → usa with_streaming_response, come nella guida ufficiale; modelli e voci aggiornati (gpt-4o-mini-tts e le relative istruzioni vocali, 13 voci tra cui marin e cedar); nuova sezione sulla migrazione a gpt-realtime-2.1-mini prima 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.

ModelloSpecificitàVoci
gpt-4o-mini-ttsAccetta istruzioni: accento, emozione, intonazione, velocità, tono, sussurro13 voci, tra cui marin e cedar, raccomandate per la qualità
tts-1Latenza inferiore, qualità inferiore9 voci: alloy, ash, coral, echo, fable, onyx, nova, sage, shimmer
tts-1-hdQualità superiore a tts-1, latenza superioreLe 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:

FormatoUtilizzo
mp3 (default)Uso generale
opusStreaming internet e comunicazione, bassa latenza
aacCompressione digitale, preferito da YouTube, Android e iOS
flacCompressione lossless, per l’archiviazione
wavNon compresso, per evitare overhead di decodifica
pcmCampioni 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-1 e tts-1-hd verranno 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 semplice speech.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