Ir para o conteúdo principal
Português— Escolher um idioma
Menu

A API TTS: Gerar Fala

Aula 10 de 18 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. A API TTS: Gerar Fala
  2. A Sua Primeira Chamada TTS
  3. Modelos Disponíveis
  4. Formatos de Saída
  5. Gerar Áudio em Lotes
  6. Limite de Caracteres e Divisão
  7. Após 6 de Janeiro de 2027: Fazer um Modelo em Tempo Real Falar
  8. Pontos-chave

Atualização de 2 de novembro de 2026 — Modelos de áudio. Vários modelos neste curso estão obsoletos: tts-1, tts-1-hd e gpt-4o-mini-tts serã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-realtime e 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-transcribe e /v1/audio/translations em 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 de speech.create() está obsoleto no SDK (“Devido a um erro, este método não faz realmente streaming”) → utilize with_streaming_response, como no guia oficial; modelos e vozes atualizados (gpt-4o-mini-tts e as suas instruções de voz, 13 vozes incluindo marin e cedar); nova secção sobre a migração para gpt-realtime-2.1-mini antes 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.

ModeloEspecificidadeVozes
gpt-4o-mini-ttsAceita instruções: sotaque, emoção, entoação, velocidade, tom, sussurro13 vozes, incluindo marin e cedar, recomendadas pela qualidade
tts-1Menor latência, menor qualidade9 vozes: alloy, ash, coral, echo, fable, onyx, nova, sage, shimmer
tts-1-hdQualidade superior à tts-1, maior latênciaAs 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:

FormatoUtilização
mp3 (padrão)Uso geral
opusStreaming e comunicação na Internet, baixa latência
aacCompressão digital, preferido pelo YouTube, Android e iOS
flacCompressão sem perdas, para arquivamento
wavSem compressão, para evitar sobrecarga de descodificação
pcmAmostras 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-1 e tts-1-hd serã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() num speech.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