A API TTS: Gerar Fala
Nesta página
Atualização de 2 de novembro de 2026 — Modelos de áudio. Vários modelos neste curso estão obsoletos:
tts-1,tts-1-hdegpt-4o-mini-ttsserão desativados em 6 de janeiro de 2027 (sucessor:gpt-realtime-2.1-mini, que o guia da API TTS da OpenAI indica não ser suportado por/v1/audio/speech: a migração da síntese de fala passa para a API em Tempo Real);gpt-realtime,gpt-4o-realtimee modelos de áudio legados em 20 de janeiro de 2027 (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5);whisper-1,gpt-4o-transcribee/v1/audio/translationsem 26 de fevereiro de 2027 (gpt-transcribe,gpt-live-transcribe,v1/realtime/translations). Para voz full-duplex, o GPT-Live 1 está disponível na API desde 10 de setembro de 2026. Lição corrigida em 3 de novembro de 2026:response.stream_to_file()no resultado despeech.create()está obsoleto no SDK (“Devido a um erro, este método não faz realmente streaming”) → utilizewith_streaming_response, como no guia oficial; modelos e vozes atualizados (gpt-4o-mini-ttse as suas instruções de voz, 13 vozes incluindomarinecedar); nova secção sobre a migração paragpt-realtime-2.1-miniantes de 6 de janeiro de 2027, com base no guia Conversas em tempo real. Fontes: Text to speech · Create speech · Realtime conversations · Deprecations.
A API TTS: Gerar Fala
A API de Texto para Fala (TTS) da OpenAI converte texto em áudio de alta qualidade. Ao contrário da API em Tempo Real, que gere conversas de voz completas, a API TTS é um serviço de disparo único: envia texto e recebe um ficheiro de áudio. É a ferramenta ideal para gerar anúncios, notificações de voz, audiolivros ou conteúdo acessível.
A Sua Primeira Chamada TTS
Gerar fala é notavelmente simples:
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="Welcome to Corsen Academy. "
"Your training on voice agents starts now.",
instructions="Speak in a warm, measured tone.",
) as response:
response.stream_to_file(speech_file)
A API devolve um fluxo de áudio que pode guardar diretamente ou transmitir para um leitor. Utilize with_streaming_response, como mostrado aqui: chamar stream_to_file() no resultado de um speech.create() simples está obsoleto no SDK, que nota que este não faz realmente streaming do áudio.
Modelos Disponíveis
Os três modelos da API de Áudio estão obsoletos e serão desativados em 6 de janeiro de 2027: este é o período de transição durante o qual ainda os poderá utilizar.
| Modelo | Especificidade | Vozes |
|---|---|---|
gpt-4o-mini-tts | Aceita instruções: sotaque, emoção, entoação, velocidade, tom, sussurro | 13 vozes, incluindo marin e cedar, recomendadas pela qualidade |
tts-1 | Menor latência, menor qualidade | 9 vozes: alloy, ash, coral, echo, fable, onyx, nova, sage, shimmer |
tts-1-hd | Qualidade superior à tts-1, maior latência | As mesmas 9 vozes |
As instruções não funcionam com tts-1 e tts-1-hd. O parâmetro speed, de 0,25 a 4,0, ajusta a velocidade com todos os modelos. Segundo o guia, as vozes são otimizadas para inglês: ouça-as em francês em OpenAI.fm antes de escolher. As políticas de utilização da OpenAI exigem também que informe claramente os seus utilizadores de que a voz que ouvem é gerada por IA.
Formatos de Saída
A API produz seis formatos, selecionados com response_format:
| Formato | Utilização |
|---|---|
mp3 (padrão) | Uso geral |
opus | Streaming e comunicação na Internet, baixa latência |
aac | Compressão digital, preferido pelo YouTube, Android e iOS |
flac | Compressão sem perdas, para arquivamento |
wav | Sem compressão, para evitar sobrecarga de descodificação |
pcm | Amostras brutas a 24 kHz, 16 bits com sinal, sem cabeçalho |
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 to convert",
response_format=fmt,
) as response:
response.stream_to_file(f"example.{fmt}")
Para um agente de voz construído sobre a API em Tempo Real, o formato pcm é o mais conveniente: as suas amostras de 24 kHz e 16 bits correspondem ao formato audio/pcm da API em Tempo Real a 24 kHz.
Gerar Áudio em Lotes
Para grandes volumes de texto, processe segmentos em paralelo:
import asyncio
from openai import AsyncOpenAI
async_client = AsyncOpenAI()
async def generate_speech_batch(segments: list[dict]) -> list[bytes]:
"""Generate audio for multiple segments in parallel."""
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)
# Usage
segments = [
{"text": "Chapter one. Introduction to voice agents.", "voice": "onyx"},
{"text": "Voice agents transform human-computer interaction.", "voice": "onyx"},
{"text": "In this chapter, we'll explore the fundamentals.", "voice": "onyx"},
]
audio_chunks = asyncio.run(generate_speech_batch(segments))
# Concatenate files
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 de Caracteres e Divisão
A API TTS tem um limite de 4.096 caracteres por pedido. Para textos mais longos, divida inteligentemente:
def split_text_for_tts(text: str, max_chars: int = 4000) -> list[str]:
"""Split text into segments respecting TTS limits."""
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
Após 6 de Janeiro de 2027: Fazer um Modelo em Tempo Real Falar
A OpenAI designa gpt-realtime-2.1-mini como substituto dos três modelos e avisa: não é um modelo para o endpoint /v1/audio/speech; a migração altera o fluxo de trabalho. Passa por uma sessão em Tempo Real. O guia Conversas em tempo real mostra como obter uma resposta sem contexto, que ignora a conversa e segue apenas as suas instruções: esta é a forma de o fazer dizer um determinado texto.
import base64
import json
import os
import wave
import websocket # pip install websocket-client
TEXT = "Welcome to Corsen Academy. Your training on voice agents starts now."
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']}"],
)
# Audio output only, 16-bit PCM at 24 kHz, with chosen voice
ws.send(json.dumps({
"type": "session.update",
"session": {
"type": "realtime",
"output_modalities": ["audio"],
"audio": {"output": {"format": {"type": "audio/pcm", "rate": 24000}, "voice": "marin"}},
},
}))
# A context-free response (empty input), which must say the text as-is
ws.send(json.dumps({
"type": "response.create",
"response": {
"input": [],
"output_modalities": ["audio"],
"instructions": f"Say exactly the following text, without adding anything:\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("Spoken text:", "".join(transcription))
Duas diferenças com a API de Áudio são importantes em produção. O resultado já não é garantido palavra por palavra: um modelo em Tempo Real segue uma instrução; não lê um ficheiro. Compare, portanto, a transcrição do que foi dito, devolvida em response.output_audio_transcript.delta, com o texto esperado e regenere se houver discrepância. A faturação também muda: segue as tarifas do modelo em Tempo Real, em tokens de texto e áudio, listadas na sua ficha técnica. Finalmente, uma chave rejeitada não impede a ligação: esta chega logo a seguir, num evento error.
Pontos-chave
gpt-4o-mini-tts,tts-1etts-1-hdserão desativados em 6 de janeiro de 2027;gpt-4o-mini-ttsé o único que aceita instruções de voz (instructions)- Grave áudio com
with_streaming_response:stream_to_file()numspeech.create()simples está obsoleto - Seis formatos de saída: MP3, Opus, AAC, FLAC, WAV e PCM bruto
- O formato PCM é ideal para integração com a API em Tempo Real
- Limite de 4.096 caracteres por pedido: divida textos longos nos limites das frases
- O processamento em lote com o cliente assíncrono acelera a geração de grandes conteúdos
- A migração passa por uma sessão em Tempo Real com
gpt-realtime-2.1-mini: resposta sem contexto, áudio PCM a 24 kHz, transcrição para comparar com o texto