Notas para desenvolvedores sobre a Realtime API

Recentemente, anunciamos nosso mais novo modelo de fala para fala, o gpt-realtime, além da disponibilidade geral da Realtime API e de vários novos recursos da API. A Realtime API e o modelo de fala para fala (s2s) chegaram à disponibilidade geral (GA) com melhorias significativas na qualidade do modelo, na confiabilidade e na facilidade de uso para desenvolvedores.

Você pode conhecer os novos recursos da API na documentação e na referência da API. Aqui, queremos destacar alguns que talvez tenham passado despercebidos e explicar quando usá-los. Se você está integrando a Realtime API ao seu aplicativo, esperamos que estas notas sejam úteis.

Melhorias no modelo

O novo modelo traz várias melhorias para aplicativos de voz em produção. Neste artigo, vamos nos concentrar nas mudanças da API. Para entender melhor o modelo e como usá-lo, recomendamos a leitura do artigo de anúncio e do guia de prompts para modelos em tempo real. Vale destacar alguns detalhes sobre o modelo.

Algumas recomendações para usar este modelo:

• Experimente diferentes prompts no Playground da Realtime API.
• Use uma das vozes marin ou cedar para obter a melhor qualidade de voz do assistente.
• Reescreva os prompts para o novo modelo. Como ele segue as instruções com mais precisão, instruções específicas agora têm muito mais efeito.
  • Por exemplo, o modelo anterior podia interpretar o prompt “Sempre diga X quando ocorrer Y” como uma orientação vaga. Já o novo modelo pode seguir essa instrução até em situações inesperadas.
  • Preste atenção às instruções específicas que você dá. Parta do princípio de que o modelo vai segui-las.

Mudanças na interface da API

Com o lançamento da versão GA, atualizamos a interface da Realtime API. Agora há duas interfaces, a beta e a GA. Recomendamos migrar os aplicativos clientes para a interface GA, que oferece novos recursos. No futuro, a interface beta será marcada como obsoleta.

A documentação de migração da versão beta para a GA traz a lista completa das alterações necessárias.

Você pode acessar o novo modelo gpt-realtime pela interface beta, mas talvez ela não ofereça suporte a alguns recursos. Veja os detalhes a seguir.

Disponibilidade dos recursos

A versão GA da Realtime API traz vários recursos novos. Apenas parte deles está disponível nos modelos anteriores.

*Como o modelo beta não oferece suporte a chamadas assíncronas de função, ele pode ter dificuldade para lidar com chamadas de ferramentas MCP que ainda não retornaram um resultado. Recomendamos usar o modelo GA com MCP.

Mudanças na temperatura

A interface GA deixou de aceitar temperature como parâmetro do modelo. A interface beta limita a temperatura à faixa de 0.6 - 1.2, com valor padrão de 0.8.

Você talvez se pergunte: “Por que os usuários não podem escolher livremente a temperatura para, por exemplo, tornar a resposta mais determinística?” Nessa arquitetura de modelo, a temperatura tem um efeito diferente. Quase sempre, a melhor opção é usar o valor recomendado de 0.8.

Pelo que observamos, reduzir a temperatura não torna essas respostas de áudio determinísticas, e temperaturas mais altas provocam distorções no áudio. Recomendamos experimentar diferentes prompts para controlar esses aspectos do comportamento do modelo.

Novos recursos

Além das mudanças na passagem da versão beta para a GA, adicionamos vários recursos à Realtime API.

A documentação e a referência da API descrevem todos os recursos. Aqui, vamos destacar o que levar em conta ao usar os novos recursos durante a integração e a migração.

Tempo limite de inatividade na conversa

Em alguns aplicativos, é incomum que o usuário fique muito tempo sem falar. Imagine uma ligação: se a pessoa do outro lado ficasse em silêncio, perguntaríamos se ela ainda está na linha. Talvez o modelo não tenha captado o que o usuário disse, ou talvez o usuário não saiba se o modelo terminou de falar. Adicionamos um recurso que faz o modelo perguntar automaticamente algo como “Você ainda está aí?”.

Para ativar esse recurso, defina idle_timeout_ms nas configurações de server_vad para a detecção de turnos. O prazo começa a contar quando termina a reprodução do áudio da última resposta do modelo. Para determinar quando ele expira, some ao instante do evento response.done a duração da reprodução do áudio e o tempo limite configurado. Se a detecção de atividade de voz (VAD) não identificar fala nesse intervalo, o tempo limite é atingido.

Quando o tempo limite é atingido, o servidor envia um evento input_audio_buffer.timeout_triggered, que registra o segmento de áudio vazio no histórico da conversa e aciona uma resposta do modelo. Registrar esse segmento permite que o modelo verifique se o usuário falou durante o intervalo e a VAD deixou de detectar a fala.

O cliente pode ativar o recurso assim:

{
  "type": "session.update",
  "session": {
    "type": "realtime",
    "instructions": "You are a helpful assistant.",
    "audio": {
      "input": {
        "turn_detection": {
          "type": "server_vad",
          "idle_timeout_ms": 6000
        }
      }
    }
  }
}

Conversas longas e gerenciamento de contexto

Ajustamos a forma como a Realtime API lida com sessões longas. Alguns pontos importantes:

• As sessões em tempo real agora podem durar até 60 minutos. Antes, o limite era de 30 minutos.
• O modelo gpt-realtime tem uma janela de contexto de 32.768 tokens. Cada resposta pode consumir até 4.096 tokens. Isso deixa no máximo 28.672 tokens para a entrada do modelo.
• As instruções da sessão e as ferramentas podem ocupar, juntas, até 16.384 tokens.
• Quando a sessão chega a 28.672 tokens, o serviço trunca o contexto automaticamente, descartando mensagens. Você pode configurar esse comportamento.
• Na versão GA, o serviço descarta automaticamente alguns tokens de áudio quando há uma transcrição disponível, para economizar tokens.

Como configurar o truncamento

Quando a janela de contexto da conversa atinge o limite de tokens, a Realtime API começa a truncar o contexto automaticamente, descartando primeiro as mensagens mais antigas da sessão. Você pode desativar o truncamento com "truncation": "disabled". Nesse caso, a API retorna um erro se houver tokens de entrada demais para gerar uma resposta. A vantagem do truncamento é que a sessão continua mesmo quando a entrada fica grande demais para o modelo. A Realtime API não faz o resumo nem a compactação das mensagens descartadas, mas você pode implementar essas operações no seu aplicativo.

Uma desvantagem do truncamento é que alterar as mensagens no início da conversa invalida o cache de prompts. Esse cache identifica trechos idênticos no início dos prompts. A cada novo turno, só é possível reaproveitar os tokens do prefixo que permaneceu idêntico. Quando o truncamento altera o início da conversa, diminui o número de tokens que podem ser reaproveitados do cache.

Para reduzir esse efeito, implementamos um recurso que descarta uma parcela maior do contexto a cada truncamento. Defina a proporção de retenção como 0.8 para descartar 20% da janela de contexto, em vez de descartar apenas o suficiente para manter a entrada abaixo do limite de tokens. A ideia é descartar uma parcela maior da janela de contexto de uma só vez, em vez de descartar um pouco a cada turno. Assim, o cache é invalidado com menos frequência, o que pode reduzir os custos de sessões longas que atingem o limite de entrada.

{
  "type": "session.update",
  "session": {
    "truncation": {
      "type": "retention_ratio",
      "retention_ratio": 0.8
    }
  }
}

Chamada assíncrona de função

A Responses API exige que a resposta de uma função venha imediatamente após a chamada. Já a Realtime API permite que o cliente continue a sessão enquanto aguarda o resultado. Isso melhora a experiência do usuário, pois a conversa em tempo real segue naturalmente. Às vezes, porém, o modelo inventa o conteúdo de uma resposta que a função ainda não retornou.

Para reduzir esse problema, a versão GA da Responses API inclui respostas provisórias. Avaliamos e ajustamos o conteúdo dessas respostas em experimentos para garantir que o modelo responda de forma adequada enquanto aguarda o retorno da função. Se você perguntar ao modelo pelo resultado da chamada, ele dirá algo como “Ainda estou aguardando o resultado”. Esse recurso já vem ativado nos novos modelos, sem necessidade de alterações no seu aplicativo.

Residência de dados na UE

A residência de dados na UE agora está disponível especificamente para os modelos gpt-realtime-2025-08-28 e gpt-4o-realtime-preview-2025-06-03. Para usar esse recurso, é preciso ativá-lo explicitamente para a organização e acessar a API por https://eu.api.openai.com.

Rastreamento

A Realtime API registra os rastros de execução no console do desenvolvedor. Eles mostram os principais eventos de uma sessão em tempo real e podem ajudar na investigação e na depuração de problemas. Com a versão GA, lançamos novos tipos de evento:

• Atualização da sessão (quando o servidor envia eventos session.updated ao cliente)
• Geração de texto de saída (para o texto gerado pelo modelo)

Prompts hospedados

Agora você pode usar prompts com a Realtime API. Assim, o código do aplicativo pode fazer referência a um prompt que você edita separadamente. Os prompts incluem tanto as instruções quanto a configuração da sessão, como os ajustes de detecção de turnos.

Você pode criar um prompt no Playground da Realtime API, refiná-lo e criar novas versões conforme necessário. Depois, o cliente pode fazer referência a esse prompt pelo ID, assim:

{
  "type": "session.update",
  "session": {
    "type": "realtime",
    "prompt": {
      "id": "pmpt_123", // your stored prompt ID
      "version": "89", // optional: pin a specific version
      "variables": {
        "city": "Paris" // example variable used by your prompt
      }
    },
    // You can still set direct session fields; these override prompt fields if they overlap:
    "instructions": "Speak clearly and briefly. Confirm understanding before taking actions."
  }
}

Se um campo do prompt também estiver definido na configuração enviada à sessão, como no exemplo acima, o valor definido na sessão tem prioridade. Assim, o cliente pode usar a configuração do prompt ou ajustá-la durante a sessão.

Conexões por canal auxiliar

A Realtime API permite que os clientes se conectem diretamente ao servidor da API via WebRTC ou SIP. Em geral, convém manter o uso de ferramentas e as demais regras de negócio no servidor do aplicativo para que essa lógica permaneça privada e independente do cliente.

Use um canal de controle auxiliar para proteger, no servidor, o uso de ferramentas, as regras de negócio e outros detalhes da implementação. Agora esse canal está disponível tanto para conexões SIP quanto para WebRTC.

Com o canal auxiliar, há duas conexões ativas com a mesma sessão em tempo real: uma do cliente do usuário e outra do servidor do aplicativo. Pela conexão do servidor, você pode monitorar a sessão, atualizar as instruções e responder a chamadas de ferramentas.

Para saber mais, consulte a documentação sobre conexões por canal auxiliar.

Comece a criar

Esperamos que estas notas tenham ajudado você a entender o que mudou com a disponibilidade geral da Realtime API e a chegada dos novos modelos em tempo real.

Agora que você conhece as mudanças, consulte a documentação da Realtime API para criar um agente de voz, estabelecer uma conexão ou começar a enviar prompts aos modelos em tempo real.