DEV Community

Cover image for Como usar a API GPT-Realtime-2.1-mini
Lucas
Lucas

Posted on • Originally published at apidog.com

Como usar a API GPT-Realtime-2.1-mini

Antigamente, agentes de voz precisavam encadear três etapas: reconhecimento de fala (speech-to-text), modelo de linguagem e síntese de fala (text-to-speech). Cada etapa adicionava latência e podia perder tom, ritmo e contexto. A API Realtime da OpenAI reduz esse pipeline para um modelo fala-para-fala (speech-to-speech), e gpt-realtime-2.1-mini é a opção mais barata e rápida dessa família: ele ouve áudio, raciocina e responde por uma única conexão de streaming.

Experimente o Apidog hoje

Este guia mostra como usar o modelo de ponta a ponta: qual ID escolher, como conectar via WebSocket e WebRTC, como configurar uma sessão, como adicionar ferramentas e como testar os endpoints com o Apidog antes de integrar tudo ao seu app. Os exemplos seguem o guia oficial do OpenAI Realtime.

Primeiro: acerte o nome do modelo

A nomenclatura pode confundir. Para o modelo mini, você verá dois identificadores principais:

  • gpt-realtime-2.1-mini: ID versionado. É o identificador associado à geração 2.1 e aparece na página de preços da OpenAI.
  • gpt-realtime-mini: apelido da família. Ele aponta para o snapshot mini mais recente, atualmente gpt-realtime-mini-2025-12-15.

Use snapshots quando quiser comportamento estável em produção:

Identificador Para o que aponta
gpt-realtime-mini Snapshot mini mais recente, com atualizações automáticas
gpt-realtime-2.1-mini Mini da geração 2.1
gpt-realtime-mini-2025-12-15 Snapshot fixado atual
gpt-realtime-mini-2025-10-06 Snapshot fixado anterior

Recomendação prática:

  1. Use gpt-realtime-mini enquanto desenvolve.
  2. Valide comportamento, latência e custo.
  3. Antes de lançar, fixe um snapshot datado, como gpt-realtime-mini-2025-12-15, para evitar mudanças inesperadas.

Imagem do modelo gpt-realtime mini

O que o gpt-realtime-2.1-mini faz

gpt-realtime-2.1-mini é um modelo de fala-para-fala. Você transmite áudio de entrada e recebe áudio de volta com entonação natural, sem precisar montar um pipeline separado de transcrição e TTS.

Ele também aceita texto, então você pode misturar entrada digitada, áudio do usuário e saída falada na mesma sessão.

Especificações principais da página do modelo:

Propriedade Valor
Modalidades de entrada Texto, imagem, áudio
Modalidades de saída Texto, áudio
Janela de contexto 32.000 tokens
Saída máxima 4.096 tokens
Conexões WebRTC, WebSocket, SIP
Vozes alloy, ash, ballad, coral, echo, sage, shimmer, verse, marin, cedar

As vozes marin e cedar são as mais recentes e exclusivas da API Realtime. A OpenAI as recomenda para saída mais natural. As vozes antigas continuam disponíveis caso você precise de um timbre específico.

Use a camada mini quando você prioriza baixa latência e custo menor, como em:

  • bots de suporte;
  • atendimento por voz;
  • fluxos de pedidos;
  • assistentes em apps web ou mobile;
  • protótipos de agentes conversacionais.

Use gpt-realtime-2.1 completo somente quando a conversa exigir raciocínio mais pesado.

Quanto custa

O modelo mini custa aproximadamente um terço do modelo completo. Taxas de token da página de preços:

Modelo Entrada de texto Entrada em cache Entrada de áudio Saída de áudio
gpt-realtime-2.1-mini $0,60 / 1M $0,30 / 1M $10 / 1M $20 / 1M
gpt-realtime-2.1 $4,00 / 1M $0,40 / 1M $32 / 1M $64 / 1M

A saída de áudio tende a dominar o custo. Um agente que fala 35 segundos por minuto pode custar aproximadamente o dobro de um agente que fala 15 segundos por minuto.

Para controlar a conta:

  • instrua o modelo a responder em uma ou duas frases;
  • evite respostas longas por padrão;
  • encerre sessões ociosas;
  • fixe um snapshot em produção;
  • confirme preços atualizados antes de estimar custos.

Custos reais por minuto para o mini podem ficar em torno de $0,06 a $0,15, dependendo da verbosidade.

Pré-requisitos

Você vai precisar de:

  1. Uma chave de API da OpenAI com acesso Realtime, disponível como OPENAI_API_KEY.
  2. Node.js 18+ para os exemplos de servidor.
  3. O pacote ws se for usar WebSocket puro.
  4. Uma página em HTTPS ou localhost para usar getUserMedia no navegador.
  5. Um servidor backend para gerar tokens efêmeros quando usar WebRTC.

Regra importante:

Nunca envie sua chave de API real para o navegador ou app mobile.

Clientes web e mobile devem usar tokens efêmeros de curta duração.

Escolha o método de conexão

O modelo Realtime suporta três transportes. Escolha com base em onde o áudio é capturado e processado.

Transporte Use quando Autenticação
WebRTC O áudio é capturado/reproduzido em navegador ou app mobile Segredo de cliente efêmero
WebSocket Seu servidor já lida com áudio bruto ou você quer prototipar rápido Chave de API no servidor
SIP Você está integrando telefonia ou sistemas de chamada Chave de API

Fluxo comum de implementação:

  1. Comece com WebSocket no servidor para validar acesso e eventos.
  2. Adicione saída de áudio.
  3. Migre para WebRTC quando precisar capturar microfone no navegador.

Início rápido 1: WebSocket no servidor

WebSocket é o caminho mais simples para testar o modelo sem lidar com microfone.

Endpoint:

wss://api.openai.com/v1/realtime?model=gpt-realtime-2.1-mini
Enter fullscreen mode Exit fullscreen mode

Como a interface é GA, você autentica com Authorization: Bearer. O antigo cabeçalho OpenAI-Beta não é necessário.

Instale a dependência:

npm install ws
Enter fullscreen mode Exit fullscreen mode

Crie um arquivo realtime-text.js:

import WebSocket from "ws";

const url = "wss://api.openai.com/v1/realtime?model=gpt-realtime-2.1-mini";

const ws = new WebSocket(url, {
  headers: {
    Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
  },
});

ws.on("open", () => {
  // 1. Configurar a sessão
  ws.send(JSON.stringify({
    type: "session.update",
    session: {
      type: "realtime",
      model: "gpt-realtime-2.1-mini",
      output_modalities: ["text"],
      instructions: "Você é um agente de suporte de API conciso. Mantenha as respostas curtas.",
    },
  }));

  // 2. Adicionar uma mensagem do usuário
  ws.send(JSON.stringify({
    type: "conversation.item.create",
    item: {
      type: "message",
      role: "user",
      content: [
        {
          type: "input_text",
          text: "O que é uma requisição idempotente?",
        },
      ],
    },
  }));

  // 3. Solicitar resposta
  ws.send(JSON.stringify({
    type: "response.create",
  }));
});

ws.on("message", (raw) => {
  const event = JSON.parse(raw.toString());

  if (event.type === "response.output_text.delta") {
    process.stdout.write(event.delta);
  }

  if (event.type === "response.done") {
    ws.close();
  }
});

ws.on("error", console.error);
Enter fullscreen mode Exit fullscreen mode

Execute:

OPENAI_API_KEY=sk-... node realtime-text.js
Enter fullscreen mode Exit fullscreen mode

O ciclo básico é:

  1. configurar sessão com session.update;
  2. adicionar entrada com conversation.item.create;
  3. solicitar geração com response.create;
  4. consumir deltas de resposta.

Eventos úteis para observar:

Evento Uso
session.created Sessão criada
session.updated Configuração aceita
response.output_text.delta Trecho incremental de texto
response.output_audio.delta Trecho de áudio em base64
response.output_audio_transcript.delta Transcrição do áudio gerado
response.done Turno finalizado

Para trocar texto por voz, use output_modalities: ["audio"] e configure o bloco audio.

Início rápido 2: WebRTC no navegador

Para um app de voz real, use WebRTC. O navegador captura o microfone e reproduz a resposta com menor latência.

O ponto crítico é autenticação: o navegador não deve receber sua chave real. Seu backend precisa gerar um token efêmero.

Passo 1: gerar token efêmero no servidor

Exemplo em Node.js:

// lado do servidor
const r = await fetch("https://api.openai.com/v1/realtime/client_secrets", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    session: {
      type: "realtime",
      model: "gpt-realtime-2.1-mini",
    },
  }),
});

const { value } = await r.json(); // chave efêmera, começa com "ek_"
Enter fullscreen mode Exit fullscreen mode

Envie value para o navegador. Ele expira rapidamente, então o risco de vazamento é menor.

Passo 2: conectar pelo navegador

HTML mínimo:

<audio id="audio" autoplay></audio>
Enter fullscreen mode Exit fullscreen mode

Código do cliente:

// lado do navegador: EPHEMERAL_KEY veio do seu servidor
const pc = new RTCPeerConnection();

// Reproduzir áudio do modelo
pc.ontrack = (event) => {
  document.getElementById("audio").srcObject = event.streams[0];
};

// Capturar microfone
const mic = await navigator.mediaDevices.getUserMedia({ audio: true });
pc.addTrack(mic.getTracks()[0]);

// Canal de dados para eventos JSON
const channel = pc.createDataChannel("oai-events");

channel.onopen = () => {
  channel.send(JSON.stringify({
    type: "session.update",
    session: {
      type: "realtime",
      model: "gpt-realtime-2.1-mini",
      output_modalities: ["audio"],
      instructions: "Você é um assistente de suporte conciso. Responda em no máximo duas frases.",
      audio: {
        output: {
          voice: "marin",
        },
      },
    },
  }));
};

channel.onmessage = (event) => {
  console.log(JSON.parse(event.data));
};

// Handshake SDP
const offer = await pc.createOffer();
await pc.setLocalDescription(offer);

const sdpResp = await fetch(
  "https://api.openai.com/v1/realtime/calls?model=gpt-realtime-2.1-mini",
  {
    method: "POST",
    body: offer.sdp,
    headers: {
      Authorization: `Bearer ${EPHEMERAL_KEY}`,
      "Content-Type": "application/sdp",
    },
  }
);

await pc.setRemoteDescription({
  type: "answer",
  sdp: await sdpResp.text(),
});
Enter fullscreen mode Exit fullscreen mode

Depois que a conexão fica ativa:

  • o microfone é enviado pela trilha WebRTC;
  • o áudio do modelo chega em pc.ontrack;
  • eventos de configuração, texto e ferramentas passam pelo canal oai-events.

Moldando a sessão

O objeto session controla o comportamento do agente.

Exemplo com áudio:

{
  type: "session.update",
  session: {
    type: "realtime",
    model: "gpt-realtime-2.1-mini",
    output_modalities: ["audio"],
    instructions: "Você é um assistente de reservas amigável. Confirme os detalhes antes de agir.",
    audio: {
      input: {
        format: {
          type: "audio/pcm",
          rate: 24000,
        },
        turn_detection: {
          type: "semantic_vad",
        },
      },
      output: {
        format: {
          type: "audio/pcm",
          rate: 24000,
        },
        voice: "marin",
      },
    },
  },
}
Enter fullscreen mode Exit fullscreen mode

Campos mais importantes:

Campo Como usar
instructions Defina persona, limites, políticas e concisão
output_modalities Use ["audio"] para agente falante ou ["text"] para texto
audio.output.voice Escolha a voz, como marin ou cedar
audio.input.turn_detection Controle quando o modelo entende que o usuário terminou de falar

Sobre detecção de turno:

  • semantic_vad: espera uma pausa natural no significado. Tende a interromper menos.
  • server_vad: detecta silêncio. Pode ser mais simples, mas menos contextual.

Você pode alterar a sessão durante a chamada enviando outro session.update. Não precisa reconectar.

Adicionando ferramentas para o agente agir

Um agente de voz útil precisa executar ações: consultar pedido, verificar disponibilidade, reservar horário, abrir ticket, atualizar cadastro etc.

A API Realtime usa o mesmo modelo mental de function calling do restante da plataforma:

  1. Você declara as ferramentas na sessão.
  2. O modelo decide chamar uma função.
  3. Você recebe os argumentos.
  4. Seu backend executa a ação.
  5. Você devolve o resultado para a conversa.
  6. O modelo continua respondendo.

Exemplo conceitual de ferramenta:

{
  type: "session.update",
  session: {
    tools: [
      {
        type: "function",
        name: "consultar_pedido",
        description: "Consulta o status de um pedido pelo ID.",
        parameters: {
          type: "object",
          properties: {
            pedido_id: {
              type: "string",
              description: "ID do pedido informado pelo usuário",
            },
          },
          required: ["pedido_id"],
        },
      },
    ],
  },
}
Enter fullscreen mode Exit fullscreen mode

Quando o modelo finalizar os argumentos, trate o evento:

if (event.type === "response.function_call_arguments.done") {
  const args = JSON.parse(event.arguments);

  const resultado = await consultarPedido(args.pedido_id);

  ws.send(JSON.stringify({
    type: "conversation.item.create",
    item: {
      type: "function_call_output",
      call_id: event.call_id,
      output: JSON.stringify(resultado),
    },
  }));

  ws.send(JSON.stringify({
    type: "response.create",
  }));
}
Enter fullscreen mode Exit fullscreen mode

Se você já usou chamadas de função na API de chat, o contrato é o mesmo. Para aprofundar, veja os guias sobre chamadas de função da OpenAI e saídas estruturadas. Para fluxos multi-etapas, o AgentKit da OpenAI pode simplificar a orquestração.

Teste os endpoints com Apidog antes de integrar

Não espere o app inteiro estar pronto para descobrir que o problema era autenticação, JSON inválido ou sequência incorreta de eventos.

Use o Apidog para validar cada parte isoladamente.

1. Testar o endpoint de token

Crie uma requisição REST:

POST https://api.openai.com/v1/realtime/client_secrets
Enter fullscreen mode Exit fullscreen mode

Headers:

Authorization: Bearer YOUR_OPENAI_API_KEY
Content-Type: application/json
Enter fullscreen mode Exit fullscreen mode

Body:

{
  "session": {
    "type": "realtime",
    "model": "gpt-realtime-2.1-mini"
  }
}
Enter fullscreen mode Exit fullscreen mode

Resultado esperado:

{
  "value": "ek_...",
  "expires_at": 1234567890
}
Enter fullscreen mode Exit fullscreen mode

Se isso funcionar, você já validou:

  • chave de API;
  • acesso Realtime;
  • payload;
  • modelo escolhido.

A mesma abordagem vale para outras superfícies REST da OpenAI, como a API de Respostas.

2. Testar o fluxo WebSocket

No cliente WebSocket do Apidog:

  1. Abra conexão para: 
wss://api.openai.com/v1/realtime?model=gpt-realtime-2.1-mini
Enter fullscreen mode Exit fullscreen mode
  1. Adicione o header: 
Authorization: Bearer YOUR_OPENAI_API_KEY
Enter fullscreen mode Exit fullscreen mode
  1. Envie uma mensagem session.update. 
{
  "type": "session.update",
  "session": {
    "type": "realtime",
    "model": "gpt-realtime-2.1-mini",
    "output_modalities": ["text"],
    "instructions": "Você é um assistente técnico conciso."
  }
}
Enter fullscreen mode Exit fullscreen mode
  1. Envie uma mensagem do usuário. 
{
  "type": "conversation.item.create",
  "item": {
    "type": "message",
    "role": "user",
    "content": [
      {
        "type": "input_text",
        "text": "Explique WebRTC em uma frase."
      }
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode
  1. Solicite resposta. 
{
  "type": "response.create"
}
Enter fullscreen mode Exit fullscreen mode

Você deve ver eventos como session.updated, response.output_text.delta e response.done.

Essa validação se encaixa bem em uma rotina de estratégias de teste de API. Quando algo quebrar no app, você saberá se o problema está no contrato da API ou na sua integração.

Se quiser acompanhar localmente, baixe o Apidog.

Mantenha a conta sob controle

A saída de áudio costuma ser a parte mais cara. Algumas práticas ajudam bastante:

  • Instrua o modelo a ser breve. Exemplo: “Responda em no máximo duas frases.”
  • Fixe snapshot em produção. Use algo como gpt-realtime-mini-2025-12-15.
  • Use semantic_vad. Reduz interrupções e respostas desperdiçadas.
  • Reutilize instruções estáveis. Entrada em cache custa menos que entrada nova.
  • Feche sessões ociosas. Não deixe conexões abertas sem usuário ativo.
  • Evite confirmações longas. Confirme apenas o necessário.
  • Monitore duração de fala. Segundos falados por minuto são um bom indicador de custo.

Erros comuns e soluções

Problema Causa provável Correção
401 Unauthorized Chave inválida ou token efêmero expirado Gere novo token e valide Authorization
Modelo não encontrado ID incorreto Use gpt-realtime-2.1-mini, não gpt-realtime-mini-2.1
Sem áudio no navegador pc.ontrack não configurado ou página sem HTTPS/localhost Anexe o stream remoto e sirva corretamente
Microfone não abre Permissão negada ou contexto inseguro Use HTTPS/localhost e trate permissões
Modelo fala por cima do usuário Detecção de turno ruim Teste semantic_vad
Eventos não chegam Canal de dados não abriu Espere channel.onopen antes de enviar eventos
Cabeçalho beta enviado Uso de configuração antiga Remova OpenAI-Beta: realtime=v1
Resposta muito longa Prompt permissivo demais Adicione instruções explícitas de concisão

Perguntas frequentes

gpt-realtime-2.1-mini é o mesmo que gpt-realtime-mini?

Efetivamente, sim. gpt-realtime-2.1-mini é o ID versionado. gpt-realtime-mini é o apelido que aponta para o snapshot mini mais recente, atualmente gpt-realtime-mini-2025-12-15.

Use o apelido para desenvolver e fixe um snapshot para produção.

Posso usar para transcrição simples?

Pode, mas a API Realtime foi criada para conversa interativa de baixa latência. Para transcrição única, modelos dedicados de transcrição costumam ser mais adequados.

Use o Realtime mini quando você precisa de ida e volta em tempo real.

Preciso de WebRTC ou WebSocket basta?

Depende do ambiente:

  • Use WebSocket para protótipos e pipelines server-side.
  • Use WebRTC quando o navegador ou app mobile captura e reproduz áudio diretamente.

WebRTC lida melhor com mídia, jitter e reprodução em tempo real.

Qual voz escolher?

Comece com marin ou cedar, que são as vozes mais novas e naturais da API Realtime.

As outras vozes disponíveis são:

  • alloy
  • ash
  • ballad
  • coral
  • echo
  • sage
  • shimmer
  • verse

Como a cobrança funciona?

A cobrança é por token e separada por modalidade.

Para o mini:

  • $0,60 por 1M de tokens de entrada de texto;
  • $0,30 por 1M de entrada em cache;
  • $10 por 1M de entrada de áudio;
  • $20 por 1M de saída de áudio.

A saída de áudio geralmente é o principal custo. Controle a verbosidade.

Ele pode chamar funções?

Sim. O Realtime usa o mesmo contrato de chamada de função. Um agente de voz pode consultar pedidos, verificar estoque, acionar workflows ou chamar APIs internas durante a conversa.

Próximos passos

Você agora tem o fluxo básico para implementar um agente com gpt-realtime-2.1-mini:

  1. Valide o modelo com WebSocket e saída de texto.
  2. Ative output_modalities: ["audio"].
  3. Configure voz, formato de áudio e semantic_vad.
  4. Gere tokens efêmeros no backend.
  5. Conecte o navegador com WebRTC.
  6. Adicione ferramentas para ações reais.
  7. Teste REST e WebSocket no Apidog.
  8. Fixe um snapshot antes de produção.

Comece simples, meça a duração das respostas e instrua o modelo a ser conciso. Isso reduz latência, melhora a experiência do usuário e evita surpresas na fatura.

Top comments (0)