La API TTS: Generación de voz
En esta página
Actualización 2 de noviembre de 2026 — Modelos de audio. Varios modelos de este curso están obsoletos:
tts-1,tts-1-hdygpt-4o-mini-ttsdejarán de funcionar el 6 de enero de 2027 (sustituto:gpt-realtime-2.1-mini, que la guía de TTS de OpenAI indica que no es compatible con/v1/audio/speech: la migración de síntesis de voz se traslada a la API en tiempo real);gpt-realtime,gpt-4o-realtimey los modelos de audio heredados el 20 de enero de 2027 (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5);whisper-1,gpt-4o-transcribey/v1/audio/translationsel 26 de febrero de 2027 (gpt-transcribe,gpt-live-transcribe,v1/realtime/translations). Para voz full-duplex, GPT-Live 1 está disponible en la API desde el 10 de septiembre de 2026. Lección corregida el 3 de noviembre de 2026:response.stream_to_file()sobre el resultado despeech.create()está obsoleto en el SDK («Debido a un error, este método no transmite realmente») → usawith_streaming_response, como en la guía oficial; modelos y voces actualizados (gpt-4o-mini-ttsy sus instrucciones de voz, 13 voces incluyendomarinycedar); nueva sección sobre migración agpt-realtime-2.1-miniantes del 6 de enero de 2027, basada en la guía de Conversaciones en tiempo real. Fuentes: Text to speech · Create speech · Realtime conversations · Deprecations.
La API TTS: Generación de voz
La API de texto a voz (TTS) de OpenAI convierte texto en audio de alta calidad. A diferencia de la API en tiempo real, que gestiona conversaciones de voz completas, la API TTS es un servicio de disparo único: envías texto y recibes un archivo de audio. Es la herramienta ideal para generar anuncios, notificaciones de voz, audiolibros o contenido accesible.
Tu primera llamada a TTS
Generar voz es extremadamente sencillo:
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="Bienvenido a Corsen Academy. "
"Tu formación sobre agentes de voz comienza ahora.",
instructions="Habla con un tono cálido y pausado.",
) as response:
response.stream_to_file(speech_file)
La API devuelve un flujo de audio que puedes guardar directamente o transmitir a un reproductor. Usa with_streaming_response, como se muestra aquí: llamar a stream_to_file() sobre el resultado de un speech.create() simple está obsoleto en el SDK, que indica que realmente no transmite el audio.
Modelos disponibles
Los tres modelos de la API de Audio están obsoletos y dejarán de funcionar el 6 de enero de 2027: este es el periodo de transición durante el cual todavía podrás usarlos.
| Modelo | Especificidad | Voces |
|---|---|---|
gpt-4o-mini-tts | Acepta instrucciones: acento, emoción, entonación, velocidad, tono, susurro | 13 voces, incluyendo marin y cedar, recomendadas por su calidad |
tts-1 | Menor latencia, menor calidad | 9 voces: alloy, ash, coral, echo, fable, onyx, nova, sage, shimmer |
tts-1-hd | Mayor calidad que tts-1, mayor latencia | Las mismas 9 voces |
Las instrucciones no funcionan con tts-1 ni tts-1-hd. El parámetro speed, de 0,25 a 4,0, ajusta la velocidad con todos los modelos. Según la guía, las voces están optimizadas para inglés: escúchalas en francés en OpenAI.fm antes de elegir. Las políticas de uso de OpenAI también exigen que informes claramente a tus usuarios de que la voz que escuchan está generada por IA.
Formatos de salida
La API produce seis formatos, seleccionados con response_format:
| Formato | Uso |
|---|---|
mp3 (predeterminado) | Uso general |
opus | Streaming y comunicación por internet, baja latencia |
aac | Compresión digital, preferido por YouTube, Android e iOS |
flac | Compresión sin pérdida, para archivado |
wav | Sin compresión, para evitar sobrecarga de decodificación |
pcm | Muestras brutas a 24 kHz, 16 bits con signo, sin cabecera |
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="Texto que convertir",
response_format=fmt,
) as response:
response.stream_to_file(f"example.{fmt}")
Para un agente de voz construido sobre la API en tiempo real, el formato pcm es el más conveniente: sus muestras de 24 kHz y 16 bits coinciden con el formato audio/pcm de la API en tiempo real a 24 kHz.
Generación de audio por lotes
Para grandes volúmenes de texto, procesa segmentos en paralelo:
import asyncio
from openai import AsyncOpenAI
async_client = AsyncOpenAI()
async def generate_speech_batch(segments: list[dict]) -> list[bytes]:
"""Genera audio para múltiples segmentos en paralelo."""
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)
# Uso
segments = [
{"text": "Capítulo uno. Introducción a los agentes de voz.", "voice": "onyx"},
{"text": "Los agentes de voz transforman la interacción humano-computadora.", "voice": "onyx"},
{"text": "En este capítulo, exploraremos los fundamentos.", "voice": "onyx"},
]
audio_chunks = asyncio.run(generate_speech_batch(segments))
# Concatenar archivos
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")
Límite de caracteres y división
La API TTS tiene un límite de 4.096 caracteres por solicitud. Para textos más largos, divide inteligentemente:
def split_text_for_tts(text: str, max_chars: int = 4000) -> list[str]:
"""Divide el texto en segmentos respetando los límites de 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
Después del 6 de enero de 2027: hacer hablar a un modelo en tiempo real
OpenAI designa gpt-realtime-2.1-mini como sustituto de los tres modelos y advierte: no es un modelo para el endpoint /v1/audio/speech; la migración cambia el flujo de trabajo. Debes pasar por una sesión en tiempo real. La guía de Conversaciones en tiempo real muestra cómo obtener una respuesta sin contexto, que ignora la conversación y sigue solo sus instrucciones: esta es la forma de hacer que diga un texto dado.
import base64
import json
import os
import wave
import websocket # pip install websocket-client
TEXT = "Bienvenido a Corsen Academy. Tu formación sobre agentes de voz comienza ahora."
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 salida de audio, PCM de 16 bits a 24 kHz, con la voz elegida
ws.send(json.dumps({
"type": "session.update",
"session": {
"type": "realtime",
"output_modalities": ["audio"],
"audio": {"output": {"format": {"type": "audio/pcm", "rate": 24000}, "voice": "marin"}},
},
}))
# Una respuesta sin contexto (entrada vacía), que debe decir el texto tal cual
ws.send(json.dumps({
"type": "response.create",
"response": {
"input": [],
"output_modalities": ["audio"],
"instructions": f"Di exactamente el siguiente texto, sin añadir nada:\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("Texto hablado:", "".join(transcription))
Dos diferencias con la API de Audio son cruciales en producción. El resultado ya no está garantizado palabra por palabra: un modelo en tiempo real sigue una instrucción; no lee un archivo. Por tanto, compara la transcripción de lo que ha dicho, devuelta en response.output_audio_transcript.delta, con el texto esperado, y regenera si hay discrepancia. La facturación también cambia: sigue las tarifas del modelo en tiempo real, en tokens de texto y audio, listadas en su ficha técnica. Finalmente, una clave rechazada no impide la conexión: llega justo después, en un evento error.
Puntos clave
gpt-4o-mini-tts,tts-1ytts-1-hddejarán de funcionar el 6 de enero de 2027;gpt-4o-mini-ttses el único que acepta instrucciones de voz (instructions)- Graba el audio con
with_streaming_response:stream_to_file()sobre unspeech.create()simple está obsoleto - Seis formatos de salida: MP3, Opus, AAC, FLAC, WAV y PCM bruto
- El formato PCM es ideal para integración con la API en tiempo real
- Límite de 4.096 caracteres por solicitud: divide textos largos en límites de frase
- El procesamiento por lotes con el cliente asíncrono acelera la generación de contenido extenso
- La migración pasa por una sesión en tiempo real con
gpt-realtime-2.1-mini: respuesta sin contexto, audio PCM a 24 kHz, transcripción para comparar con el texto