Notas para desenvolvedores sobre a Realtime API

Recentemente, anunciamos nosso mais novo modelo de fala para fala, 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 grandes melhorias na qualidade do modelo, na confiabilidade e na experiência de desenvolvimento.

Você pode conhecer os novos recursos da API na documentação e na referência da API, mas queremos destacar alguns que talvez tenham passado despercebidos e orientar sobre quando usá-los. Se você está integrando a Realtime API, esperamos que estas notas sejam interessantes.

Melhorias no modelo

O novo modelo inclui várias melhorias para atender melhor aos aplicativos de voz em produção. Neste post, vamos nos concentrar nas mudanças da API. Para entender e usar melhor o modelo, recomendamos o post de anúncio no blog e o guia de criação de prompts em tempo real. Ainda assim, vamos destacar alguns pontos específicos.

Algumas recomendações importantes para usar este modelo:

• Experimente criar prompts no playground em tempo real.
• Use as vozes marin ou cedar para obter a melhor qualidade de voz do assistente.
• Reescreva os prompts para o novo modelo. Com as melhorias na capacidade de seguir instruções, instruções específicas agora têm muito mais força.
  • Por exemplo, um prompt que dizia "Sempre diga X quando Y" pode ter sido tratado pelo modelo antigo como uma orientação vaga, enquanto o novo modelo pode segui-lo em situações inesperadas.
  • Preste atenção às instruções específicas que você fornece. Parta do princípio de que elas serão seguidas.

Mudanças na estrutura da API

Atualizamos a estrutura da Realtime API com o lançamento da versão GA, então agora há uma interface beta e uma interface GA. Recomendamos que os clientes migrem suas integrações para a interface GA, pois ela oferece novos recursos e a interface beta será considerada obsoleta no futuro.

A lista completa das mudanças necessárias para a migração está na documentação de migração da versão beta para a GA.

Você pode acessar o novo modelo gpt-realtime pela interface beta, mas alguns recursos podem não ter suporte. Veja mais detalhes abaixo.

Disponibilidade dos recursos

A versão GA da Realtime API inclui vários novos recursos. Alguns estão habilitados nos modelos mais antigos, outros não.

*Como o modelo beta não oferece chamada de função assíncrona, ele pode não lidar bem com chamadas pendentes de ferramentas MCP que ainda não retornaram um resultado. Recomendamos usar o modelo GA com MCP.

Mudanças na temperatura

A interface GA removeu temperature dos parâmetros do modelo, e a interface beta limita a temperatura ao intervalo de 0.6 - 1.2, com valor padrão de 0.8.

Você talvez esteja se perguntando: "Por que os usuários não podem definir a temperatura livremente e usá-la, por exemplo, para tornar a resposta mais determinística?" A resposta é que a temperatura se comporta de forma diferente nesta arquitetura de modelo, e os usuários quase sempre obtêm melhores resultados ao defini-la no valor recomendado de 0.8.

Pelo que observamos, não há como tornar essas respostas de áudio determinísticas com temperaturas baixas, e temperaturas mais altas causam anomalias no áudio. Recomendamos experimentar diferentes prompts para controlar esses aspectos do comportamento do modelo.

Novos recursos

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

Todos os recursos estão descritos na documentação e na referência da API, mas aqui vamos destacar o que levar em conta sobre os novos recursos durante a integração e a migração.

Tempos limite de inatividade da conversa

Em alguns aplicativos, seria inesperado passar muito tempo sem receber nenhuma entrada do usuário. Imagine uma ligação: se não ouvíssemos a pessoa do outro lado da linha, perguntaríamos se estava tudo bem. Talvez o modelo não tenha captado o que o usuário disse, ou talvez o usuário não tenha certeza se o modelo ainda está falando. Adicionamos um recurso que aciona automaticamente o modelo para dizer algo como: "Você ainda está aí?"

Habilite esse recurso definindo idle_timeout_ms nas configurações de server_vad para detecção de turnos. O tempo limite será contado após o término da reprodução do áudio da última resposta do modelo. Ou seja, o instante em que o tempo limite expira é calculado somando o horário de response.done, a duração da reprodução do áudio e o tempo limite. Se o VAD não for acionado nesse período, o tempo limite será 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 o áudio vazio dá ao modelo a oportunidade de verificar se o VAD falhou e se o usuário falou algo durante o período em questão.

Os clientes podem habilitar esse 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 a ter em mente:

• As sessões em tempo real agora podem durar até 60 minutos, em vez dos 30 minutos anteriores.
• O modelo gpt-realtime tem uma janela de 32.768 tokens. As respostas podem consumir no máximo 4.096 tokens. Isso significa que o modelo aceita no máximo 28.672 tokens de entrada.
• As instruções da sessão e as ferramentas, juntas, podem ter no máximo 16.384 tokens.
• O serviço trunca (descarta) mensagens automaticamente quando a sessão atinge 28.672 tokens, mas esse comportamento é configurável.
• O serviço em disponibilidade geral descarta automaticamente alguns tokens de áudio quando há uma transcrição disponível, para economizar tokens.

Configuração do truncamento

Quando a janela de contexto da conversa atinge o limite de tokens, a Realtime API começa automaticamente a truncar (descartar) mensagens do início da sessão (as mensagens mais antigas). Você pode desativar esse comportamento de truncamento definindo "truncation": "disabled". Nesse caso, a API retorna um erro quando uma resposta tem tokens de entrada em excesso. O truncamento, porém, é útil porque permite que a sessão continue mesmo quando a entrada fica grande demais para o modelo. A Realtime API não resume nem compacta as mensagens descartadas, mas você pode implementar isso por conta própria.

Um efeito negativo do truncamento é que alterar mensagens no início da conversa invalida o cache de tokens dos prompts. O cache de prompts funciona identificando conteúdo exatamente igual no início dos seus prompts. A cada turno subsequente, apenas os tokens que não mudaram são armazenados em cache. Quando o truncamento altera o início da conversa, ele reduz o número de tokens que podem ser armazenados em cache.

Implementamos um recurso para atenuar esse efeito negativo, truncando mais do que o necessário sempre que ocorre um truncamento. Defina a proporção de retenção como 0.8 para truncar 20% da janela de contexto, em vez de truncar apenas o suficiente para manter a contagem de tokens de entrada abaixo do limite. A ideia é truncar uma parte maior da janela de contexto de uma só vez, em vez de truncar um pouco a cada vez, para invalidar o cache com menos frequência. Essa abordagem, que favorece o uso do cache, pode manter os custos baixos em sessões longas que atingem os limites de entrada.

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

Chamada de função assíncrona

Enquanto a Responses API exige uma resposta da função imediatamente após a chamada de função, a Realtime API permite que os clientes continuem uma sessão enquanto uma chamada de função está pendente. Essa continuidade melhora a experiência do usuário, pois permite que as conversas em tempo real prossigam naturalmente, mas às vezes o modelo alucina o conteúdo de uma resposta de função inexistente.

Para atenuar esse problema, a Responses API em disponibilidade geral adiciona respostas provisórias com conteúdo que avaliamos e ajustamos em experimentos para garantir que o modelo se comporte adequadamente, mesmo enquanto aguarda uma resposta da função. Se você perguntar ao modelo sobre os resultados de uma chamada de função, ele dirá algo como: "Ainda estou aguardando o resultado." Esse recurso é ativado automaticamente para os novos modelos, sem que você precise fazer alterações.

Residência de dados na UE

Agora há suporte à residência de dados na UE especificamente para gpt-realtime-2025-08-28 e gpt-4o-realtime-preview-2025-06-03. A residência de dados precisa ser explicitamente ativada para a organização, e o acesso deve ser feito por https://eu.api.openai.com.

Rastreamento

A Realtime API armazena registros de rastreamento no console do desenvolvedor, registrando os principais eventos durante uma sessão em tempo real, o que pode ajudar em investigações e na depuração. Com o lançamento em disponibilidade geral, introduzimos alguns novos tipos de evento:

• Sessão atualizada (quando eventos session.updated são enviados ao cliente)
• Geração de texto de saída (para texto gerado pelo modelo)

Prompts hospedados

Agora você pode usar prompts com a Realtime API para que o código do seu aplicativo faça referência, de forma prática, a um prompt que pode ser editado separadamente. Os prompts incluem tanto instruções quanto configurações da sessão, como as de detecção de turnos.

Você pode criar um prompt no Playground em tempo real, refiná-lo e criar versões conforme necessário. Depois, um 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 uma configuração do prompt também for definida nas configurações passadas à sessão, como no exemplo acima, a configuração da sessão terá prioridade. Assim, o cliente pode usar a configuração do prompt ou alterá-la durante a sessão.

Conexões por canal lateral

A Realtime API permite que os clientes se conectem diretamente ao servidor da API via WebRTC ou SIP. No entanto, é muito provável que você queira manter o uso de ferramentas e o restante da lógica de negócio no servidor do seu aplicativo, para que essa lógica permaneça privada e independente do cliente.

Mantenha o uso de ferramentas, a lógica de negócio e outros detalhes seguros no servidor conectando-se por um canal lateral de controle. Agora oferecemos opções de canal lateral tanto para conexões SIP quanto WebRTC.

Uma conexão por canal lateral significa que há duas conexões ativas com a mesma sessão em tempo real: uma do cliente do usuário e outra do servidor do seu aplicativo. A conexão do servidor pode ser usada para monitorar a sessão, atualizar instruções e responder a chamadas de ferramentas.

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

Comece a desenvolver

Esperamos que estas informações tenham ajudado você a entender o que mudou com a disponibilidade geral da Realtime API e os novos modelos em tempo real.

Agora que você está por dentro das novidades, consulte a documentação da Realtime API para criar um agente de voz, iniciar uma conexão ou começar a criar prompts para modelos em tempo real.