For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Navegação principal
Theme

Tradução em tempo real

Traduza falas ao vivo e receba o áudio e a transcrição em fluxo contínuo.

Com a tradução em tempo real, você envia o áudio original em fluxo contínuo para uma sessão dedicada à tradução e recebe o áudio traduzido e trechos incrementais da transcrição enquanto a pessoa ainda está falando. Use esse recurso para interpretação ao vivo, chamadas multilíngues, transmissões, reuniões, aulas e salas de videoconferência.

Use gpt-realtime-translate quando seu aplicativo precisar traduzir o que uma pessoa diz. Se precisar de um assistente que responda a perguntas, chame ferramentas e conduza uma conversa, use gpt-realtime-2.1 com uma sessão padrão da Realtime API.

Diferenças entre os tipos de sessão

As sessões de tradução em tempo real têm uma arquitetura diferente da usada nas sessões de agentes de voz.

Sessão de agente de voz Sessão de tradução
Conecta-se a /v1/realtime. Conecta-se a /v1/realtime/translations.
O modelo atua como assistente. O modelo atua como intérprete.
Segue um ciclo de conversa e resposta. Traduz continuamente o áudio à medida que o recebe.
Pode chamar ferramentas e gerar turnos de fala do assistente. Gera áudio traduzido e trechos incrementais da transcrição.
Você pode chamar response.create. Você não chama response.create.

A tradução começa com o próprio fluxo de áudio. Continue enviando áudio, inclusive o silêncio entre as frases, e processe os eventos de saída à medida que chegarem.

Escolha do transporte

Use WebRTC quando o navegador capturar ou reproduzir áudio. O WebRTC envia o áudio original como uma faixa de mídia e recebe a fala traduzida como uma faixa de áudio remota. Assim, você não precisa reamostrar nem reproduzir manualmente os blocos de áudio PCM.

Use WebSockets quando o servidor já receber áudio bruto, por exemplo, do Twilio Media Streams, de mídia SIP, de um sistema de ingestão de transmissões ou de um processo de mídia. Com WebSockets, envie áudio PCM16 a 24 kHz codificado em base64 e implemente a reprodução dos trechos de áudio recebidos.

Crie uma sessão WebRTC no navegador

Para aplicativos de navegador, crie no servidor um segredo de cliente de curta duração. Não exponha sua chave de API padrão no navegador.

Crie um segredo de cliente para tradução
app.post("/session", async (req, res) => {
  const language = req.body.targetLanguage ?? "es";

  const response = await fetch(
    "https://api.openai.com/v1/realtime/translations/client_secrets",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
        "Content-Type": "application/json",
        "OpenAI-Safety-Identifier": "hashed-user-id",
      },
      body: JSON.stringify({
        session: {
          model: "gpt-realtime-translate",
          audio: {
            output: { language },
          },
        },
      }),
    }
  );

  res.status(response.status).json(await response.json());
});

No navegador, capture o áudio, crie uma conexão entre pares e envie a oferta SDP em uma solicitação POST ao endpoint de chamadas de tradução.

Estabeleça uma chamada com tradução no navegador
const { value: clientSecret } = await fetch("/session", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ targetLanguage: "es" }),
}).then((response) => response.json());

const sourceStream = await navigator.mediaDevices.getUserMedia({
  audio: true,
});

const pc = new RTCPeerConnection();
pc.addTrack(sourceStream.getAudioTracks()[0], sourceStream);

const translatedAudio = new Audio();
translatedAudio.autoplay = true;
pc.ontrack = ({ streams }) => {
  translatedAudio.srcObject = streams[0];
};

const events = pc.createDataChannel("oai-events");
events.onmessage = ({ data }) => {
  const event = JSON.parse(data);
  if (event.type === "session.output_transcript.delta") {
    subtitles.textContent += event.delta;
  }
};

const offer = await pc.createOffer();
await pc.setLocalDescription(offer);

const sdpResponse = await fetch(
  "https://api.openai.com/v1/realtime/translations/calls",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${clientSecret}`,
      "Content-Type": "application/sdp",
    },
    body: offer.sdp,
  }
);

if (!sdpResponse.ok) {
  throw new Error(await sdpResponse.text());
}

await pc.setRemoteDescription({
  type: "answer",
  sdp: await sdpResponse.text(),
});

Crie uma sessão WebSocket

Conecte-se ao endpoint dedicado à tradução e selecione o modelo na URL.

Antes de executar este exemplo, instale ws para Node.js, websocket-client e sounddevice para Python ou async-websocket para Ruby (gem install async-websocket). Para Java, adicione a dependência Maven com.openai:openai-java:4.75.1.

Os exemplos em Java mostram separadamente como estabelecer a conexão, configurar o idioma e enviar áudio. O SDK Java também permite receber eventos e encerrar uma sessão, mas este guia não inclui exemplos em Java para essas etapas. Para acompanhar o fluxo completo de tradução a seguir, use os exemplos em Node.js ou Python.

Conecte-se a uma sessão de tradução
import WebSocket from "ws";

const ws = new WebSocket(
  "wss://api.openai.com/v1/realtime/translations?model=gpt-realtime-translate",
  {
    headers: {
      Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
      "OpenAI-Safety-Identifier": "hashed-user-id",
    },
  }
);

Em Ruby, insira os trechos de código de configuração e envio de áudio a seguir dentro do bloco Async::WebSocket::Client.connect, depois de verificar se a sessão foi criada e antes do fim do bloco. Mantenha a conexão aberta enquanto envia áudio e recebe eventos de tradução.

No exemplo de conexão em Java, o socket é fechado ao fim do bloco try. Os exemplos em Java de configuração e envio de áudio exigem uma TranslationConnection aberta. Mantenha essa conexão aberta enquanto envia áudio e recebe os resultados. Antes de sair do bloco, encerre a sessão e leia todos os eventos até receber session.closed, conforme descrito em Encerre uma sessão WebSocket.

Configure o idioma de destino após a abertura do socket.

Configure o idioma de destino
ws.on("open", () => {
  ws.send(
    JSON.stringify({
      type: "session.update",
      session: {
        audio: {
          output: {
            language: "es",
          },
        },
      },
    })
  );
});

Em seguida, envie áudio continuamente.

Adicione áudio de origem
ws.send(
  JSON.stringify({
    type: "session.input_audio_buffer.append",
    audio: base64Pcm16,
  })
);

Monitore os eventos para receber o áudio traduzido e as transcrições.

Receba áudio traduzido e transcrições
ws.on("message", (data) => {
  const event = JSON.parse(data.toString());

  if (event.type === "session.output_audio.delta") {
    playPcm16(event.delta);
  }

  if (event.type === "session.output_transcript.delta") {
    process.stdout.write(event.delta);
  }

  if (event.type === "session.input_transcript.delta") {
    updateSourceTranscript(event.delta);
  }
});

Em Go, execute listen em paralelo com o envio de áudio. Essa função fecha a conexão de transporte após receber session.closed.

Encerre uma sessão WebSocket

Quando o fluxo de áudio original terminar, envie um evento session.close antes de fechar o WebSocket. Esse evento instrui o serviço a concluir o processamento do áudio de entrada pendente, emitir os trechos restantes de áudio traduzido e de transcrição e, em seguida, enviar um evento session.closed. Apenas as sessões de tradução aceitam o evento session.close.

Depois de enviar session.close, pare de adicionar áudio e continue lendo os eventos no loop de recebimento habitual até receber session.closed. Se você fechar o socket imediatamente, poderá perder trechos da tradução que a sessão ainda está enviando.

Encerre uma sessão de tradução
let translationSessionClosing = false;
let gotTranslationClosed = false;
let drainDeadline;

ws.on("close", () => {
  clearTimeout(drainDeadline);
  if (!gotTranslationClosed) {
    console.error("Translation disconnected before final session.closed");
    process.exitCode = 1;
  }
});

function closeTranslationSession() {
  if (translationSessionClosing) {
    return;
  }

  translationSessionClosing = true;
  // Adjust this deadline for your application's finalization requirements.
  drainDeadline = setTimeout(() => {
    console.error("Translation finalization timed out");
    process.exitCode = 1;
    ws.close();
  }, 15_000);
  ws.send(JSON.stringify({ type: "session.close" }));
}

// Use this in place of the earlier output handler, so audio plays only once.
ws.on("message", (data) => {
  const event = JSON.parse(data.toString());

  if (event.type === "session.output_audio.delta") {
    playPcm16(event.delta);
  }

  if (event.type === "session.output_transcript.delta") {
    process.stdout.write(event.delta);
  }

  if (event.type === "session.input_transcript.delta") {
    updateSourceTranscript(event.delta);
  }

  if (event.type === "error") {
    clearTimeout(drainDeadline);
    console.error("Translation error", event.error?.code);
    process.exitCode = 1;
    ws.close();
  }

  if (event.type === "session.closed") {
    clearTimeout(drainDeadline);
    gotTranslationClosed = true;
    ws.close();
  }
});

// Call this when the source stream ends.
closeTranslationSession();

Implemente a tradução para ouvintes

Use a tradução para ouvintes quando o público precisar ouvir a tradução do áudio de uma única pessoa ou de um único fluxo. É o caso de transmissões ao vivo, palestras em conferências, webinars, teleconferências de divulgação de resultados, aulas expositivas e vídeos.

A arquitetura típica segue este fluxo.

source audio -> translation session -> translated audio + subtitles

Crie uma sessão de tradução para cada idioma de destino. Se você precisar traduzir o mesmo áudio em inglês para espanhol e francês, crie uma sessão de inglês para espanhol e outra de inglês para francês.

Em aplicativos de navegador que oferecem tradução para ouvintes, capture o áudio da aba com getDisplayMedia(), envie-o via WebRTC e reproduza a faixa remota de áudio traduzido. Para transmissões em produção, execute a tradução em um processo de mídia no servidor e disponibilize faixas de áudio traduzido ou legendas para o público.

Implemente a tradução de conversas

Use a tradução de conversas quando dois ou mais participantes conversarem em idiomas diferentes. Alguns exemplos são chamadas de suporte ou vendas, aulas particulares e salas de videoconferência.

Mantenha separadas as faixas de áudio dos participantes. Misturar as vozes em um único fluxo dificulta identificar quem está falando, associar as legendas a cada pessoa e lidar com falas simultâneas.

Para uma chamada entre duas pessoas, crie uma sessão de tradução para cada direção.

Caller A audio -> translate into Caller B language -> play to Caller B
Caller B audio -> translate into Caller A language -> play to Caller A

Em salas com vários participantes, o número de sessões depende de quantas pessoas estão falando e dos idiomas de destino.

translation sessions ~= active source speaker tracks x distinct target languages

Em salas pequenas, cada ouvinte pode criar no navegador processos auxiliares de tradução para os participantes remotos cuja fala deseja ouvir traduzida. Em salas maiores, use no servidor um participante ou processo de mídia que se inscreva uma única vez na faixa de áudio de cada pessoa que fala, crie uma sessão de tradução por idioma de destino e republique as faixas traduzidas.

Teste a qualidade e a latência

Teste a tradução com áudio real e peça a pessoas que dominem os dois idiomas que revisem os resultados. As métricas automatizadas podem ajudar, mas não detectam todos os erros que os usuários percebem.

Nos testes, avalie os seguintes aspectos.

  • Qualidade da tradução para cada par de idiomas
  • Tradução de nomes, números, datas, valores monetários e números de telefone
  • Uso de terminologia específica da área
  • Alternância de idiomas durante a fala e conversas que misturam idiomas
  • Tradução de falas com diferentes sotaques, ritmo acelerado ou vozes sobrepostas
  • Latência até o primeiro trecho de áudio traduzido
  • Latência após o fim de cada fala
  • Sincronização das legendas
  • Consistência da voz
  • Comportamento durante a reconexão

Se o seu caso de uso exigir precisão em nomes ou termos específicos da área, crie um conjunto de exemplos de referência antes do lançamento e revise as falhas manualmente.

Lista de verificação para produção

  • Use WebRTC para mídia no navegador e WebSockets para mídia no servidor.
  • Use o endpoint dedicado /v1/realtime/translations.
  • Transmita o áudio continuamente, inclusive o silêncio entre as frases.
  • Use session.close e aguarde session.closed antes de fechar uma sessão WebSocket.
  • Mantenha separadas as faixas de áudio de cada participante ao traduzir conversas.
  • Use uma sessão por idioma de saída.
  • Exiba as transcrições nos idiomas de origem e de destino quando isso for útil.
  • Ofereça controles para o áudio original, o áudio traduzido e as legendas, além de opções para silenciar e ajustar o volume.
  • Indique quando houver reconexão em andamento, atraso ou indisponibilidade.
  • Monitore a latência separadamente da qualidade da tradução.

Guias relacionados

Visão geral da Realtime API e dos recursos de áudio

Compare sessões de agentes de voz, de tradução e de transcrição.

Conexão WebRTC

Conecte a mídia do navegador a uma sessão em tempo real.

Conexão WebSocket

Transmita áudio bruto por um pipeline de mídia no servidor.

Transcrição em tempo real

Receba trechos incrementais da transcrição de áudio ao vivo.