Tradução Automática
Nesta página
Lição reescrita a 3 de novembro de 2026. Anteriormente, dependia do endpoint
/v1/audio/translationse do modelowhisper-1, ambos preteridos e descontinuados a 26 de fevereiro de 2027, bem como de uma sessão de assistente em tempo real reutilizada como intérprete. A OpenAI oferece agora dois caminhos: para gravações, transcrição no idioma original comgpt-transcribe, seguida de tradução de texto; para fala em direto, uma sessão de tradução dedicada comgpt-realtime-translate. O código foi verificado com o SDKopenai3.42.1 e a bibliotecawebsocket-client. Fontes: Transcrição de ficheiros · Tradução em tempo real · Preterições.
Duas necessidades, duas ferramentas
A tradução de áudio abrange dois cenários muito distintos, e a OpenAI trata-os com ferramentas diferentes:
| Necessidade | Ferramenta (novembro de 2026) | Resultado |
|---|---|---|
| Uma gravação para traduzir (reunião, podcast, chamada arquivada) | gpt-transcribe para transcrever no idioma original, depois um modelo de texto para traduzir | Texto traduzido no seu idioma de destino |
| Fala em direto para interpretar (chamada, conferência, aula) | Sessão de tradução em tempo real com gpt-realtime-translate | Áudio traduzido e transcrições, gerados à medida que a fala ocorre |
Caminho legado: /v1/audio/translations com whisper-1 | Preterido, descontinuado a 26 de fevereiro de 2027 | Apenas texto em inglês |
O guia da OpenAI enfatiza um ponto crucial: simplesmente alterar o ID do modelo num pedido /v1/audio/translations não realiza qualquer migração. O antigo endpoint, que só conseguia traduzir para inglês, não tem substituto direto.
Traduzir uma gravação
Este método primeiro transcreve fielmente no idioma falado e, em seguida, traduz o texto. Funciona para qualquer idioma de destino — ao contrário do antigo endpoint, que produzia apenas inglês — e fornece ambos os textos, o que é útil para verificação:
from openai import OpenAI
client = OpenAI()
def translate_recording(path: str, target_language: str) -> dict[str, str]:
"""Transcreve uma gravação no seu idioma original e, em seguida, traduz o texto."""
with open(path, "rb") as f:
transcription = client.audio.transcriptions.create(model="gpt-transcribe", file=f)
response = client.responses.create(
model="gpt-6-luna",
instructions=(
f"Translate the text provided by the user into {target_language}. "
"Keep the tone and style. Respond only with the translation."
),
input=transcription.text,
)
return {"original": transcription.text, "translation": response.output_text}
result = translate_recording("reunion_fr.mp3", "German")
print(result["translation"])
Duas escolhas merecem explicação. A instrução de tradução vai em instructions, enquanto a transcrição chega como dados simples em input: uma gravação pode conter qualquer coisa, incluindo uma frase que pareça um comando, e não deve poder modificar a instrução. O modelo gpt-6-luna é o que a OpenAI recomenda para processamento em larga escala e sensível ao custo; para textos jurídicos ou técnicos delicados, escolha um modelo mais capaz, como o gpt-6.1-sol.
Interpretar fala em direto
Para traduzir enquanto alguém fala, a OpenAI oferece um tipo especial de sessão em tempo real. O guia distingue claramente esta sessão de uma sessão de agente de voz:
| Sessão de agente de voz | Sessão de tradução |
|---|---|
Liga-se a /v1/realtime | Liga-se a /v1/realtime/translations |
| O modelo atua como assistente | O modelo atua como intérprete |
Ciclo de conversa e resposta (response.create) | Fluxo contínuo a partir do áudio de entrada, sem response.create |
| Pode chamar ferramentas | Produz áudio traduzido e transcrições |
O transporte depende de onde o áudio chega. Num navegador, o WebRTC envia a entrada do microfone e recebe a voz traduzida como faixas de áudio; o seu servidor cria um segredo de cliente de curta duração para isto através de /v1/realtime/translations/client_secrets, para que a sua chave de API nunca saia do servidor. Do lado do servidor, quando o áudio já chega em bruto (um fluxo telefónico, uma captura), uma ligação WebSocket é suficiente:
import base64
import json
import os
import websocket # pip install websocket-client
ws = websocket.WebSocket()
ws.connect(
"wss://api.openai.com/v1/realtime/translations?model=gpt-realtime-translate",
header=[
f"Authorization: Bearer {os.environ['OPENAI_API_KEY']}",
"OpenAI-Safety-Identifier: hashed-user-id", # hashed identifier of your user
],
)
# Idioma de saída do intérprete
ws.send(json.dumps({"type": "session.update", "session": {"audio": {"output": {"language": "en"}}}}))
def send_audio(pcm16: bytes) -> None:
"""Anexa um fragmento de áudio de origem: PCM de 16 bits, mono, 24 kHz."""
ws.send(json.dumps({"type": "session.input_audio_buffer.append", "audio": base64.b64encode(pcm16).decode()}))
Enquanto envia o áudio, incluindo os silêncios, a sessão devolve eventos para processar em tempo real: session.output_audio.delta transporta o áudio traduzido em base64, session.output_transcript.delta o texto traduzido e session.input_transcript.delta a transcrição do original. Quando a fonte para, envie session.close: o serviço termina a tradução atual e responde com session.closed.
translation: list[str] = []
while True:
event = json.loads(ws.recv())
if event["type"] == "session.output_transcript.delta":
translation.append(event["delta"])
elif event["type"] == "error":
raise RuntimeError(f"Translation error: {event['error']['code']}")
elif event["type"] == "session.closed":
break
ws.close()
print("".join(translation))
Não negligencie o evento error: uma chave rejeitada não falha a própria ligação; chega logo a seguir como um evento error com o código invalid_api_key (observado a 3 de novembro de 2026). Em produção, a receção corre em paralelo com o envio, num thread ou tarefa separada, e o áudio traduzido vai para o leitor ou linha telefónica à medida que chega: o guia oficial fornece uma versão completa, incluindo a reprodução de áudio.
Pontos-chave
/v1/audio/translationsewhisper-1foram desativados a 26 de fevereiro de 2027, sem substituto direto: mudar o modelo não é suficiente- Para uma gravação:
gpt-transcribeno idioma original, depois tradução de texto por um modelo de texto, para qualquer idioma - Mantenha a instrução de tradução em
instructionse a transcrição como dados simples - Para fala em direto: uma sessão de tradução (
/v1/realtime/translations,gpt-realtime-translate), que atua como intérprete, semresponse.create - WebRTC no navegador, com um segredo de cliente criado pelo servidor; WebSocket do lado do servidor, com áudio PCM de 16 bits a 24 kHz