Como Usar a API WebSocket Mode da OpenAI: Guia Completo

Em Resumo

A OpenAI oferece dois modos de API WebSocket para diferentes casos de uso: o modo WebSocket da API Responses para fluxos de trabalho agentivos com uso intensivo de ferramentas (até 40% mais rápido para 20+ chamadas de ferramentas), e a API em Tempo Real para aplicações de voz e áudio de baixa latência. Ambos utilizam conexões WebSocket persistentes em vez de requisições HTTP sem estado, reduzindo a latência ao eliminar a sobrecarga repetida de conexão e possibilitando interações orientadas a eventos e com estado.

Introdução

A API da OpenAI evoluiu para além de simples padrões de requisição-resposta. Para aplicações que exigem chamadas de ferramentas rápidas ou streaming de áudio em tempo real, o modelo HTTP tradicional cria uma sobrecarga desnecessária. Cada nova requisição exige configuração de conexão, autenticação e transmissão de estado — mesmo quando você está continuando a mesma conversa.

A API WebSocket da OpenAI resolve isso mantendo uma conexão persistente e bidirecional. Para fluxos de trabalho agentivos com mais de 20 chamadas de ferramentas sequenciais, isso se traduz em uma execução ponta a ponta aproximadamente 40% mais rápida. Para aplicações de voz, permite conversas naturais e com capacidade de interrupção, com latências abaixo de 500ms.

Este guia aborda ambos os modos WebSocket da OpenAI: a API Responses para fluxos de trabalho de agentes com muitas ferramentas, e a API em Tempo Real para streaming de áudio. Você aprenderá quando usar cada um, como implementá-los e como testá-los de forma eficaz.

O que é a API WebSocket da OpenAI?

A API WebSocket da OpenAI oferece um mecanismo de transporte alternativo ao HTTP para interagir com os modelos de linguagem da OpenAI. Em vez de criar uma nova conexão para cada chamada de API, o WebSocket estabelece uma única conexão de longa duração que permanece aberta durante a sua sessão.

Características Principais

Conexão Persistente: Uma vez estabelecida, a conexão WebSocket permanece aberta até ser explicitamente fechada, eliminando a sobrecarga de conexão por requisição.

Comunicação Bidirecional: Tanto o cliente quanto o servidor podem enviar mensagens a qualquer momento, permitindo arquiteturas verdadeiramente orientadas a eventos.

Sessões com Estado: O servidor mantém o contexto para a conexão atual, permitindo que você referencie respostas anteriores sem reenviar todo o histórico da conversa.

Modelo Orientado a Eventos: A comunicação acontece através de eventos discretos (mensagens JSON) em vez de pares de requisição-resposta.

Conceitos Básicos do Protocolo WebSocket

Conexões WebSocket começam com uma requisição de upgrade HTTP e então mudam para o protocolo WebSocket. Para a OpenAI, você se conectará a endpoints como:

• API Responses: wss://api.openai.com/v1/responses
• API em Tempo Real: wss://api.openai.com/v1/realtime?model=gpt-realtime

O esquema wss:// indica uma conexão WebSocket segura (análogo ao HTTPS para HTTP).

Dois Modos WebSocket Explicados

A OpenAI oferece dois modos WebSocket distintos, cada um otimizado para diferentes casos de uso.

Modo WebSocket da API Responses

A API Responses suporta conexões WebSocket para fluxos de trabalho agentivos onde você precisa fazer muitas chamadas de ferramentas sequenciais. Este modo é projetado para assistentes de codificação, sistemas de orquestração e agentes autônomos que chamam ferramentas repetidamente para realizar tarefas complexas.

Como Funciona:

Em uma conexão WebSocket ativa, o serviço mantém um estado de resposta anterior em um cache em memória local da conexão (a resposta mais recente). Quando você continua uma rodada, você envia apenas:

• previous_response_id (referência à última resposta)
• Novos itens de entrada (mensagens do usuário, resultados de ferramentas, etc.)

O servidor reutiliza o estado armazenado em cache em vez de reprocessar todo o histórico da conversa.

Benefícios de Desempenho:

Para fluxos de trabalho com mais de 20 chamadas de ferramentas, a OpenAI relata uma execução ponta a ponta até 40% mais rápida em comparação com o HTTP. Isso vem de:

• Sem configuração de conexão por requisição
• Sem sobrecarga de autenticação repetida
• O estado em cache reduz o tempo de processamento
• Menor latência de rede para mensagens de continuação pequenas

Compatibilidade:

O modo WebSocket funciona tanto com Retenção Zero de Dados (ZDR) quanto com as opções store=false, tornando-o adequado para aplicações sensíveis à privacidade.

Modo WebSocket da API em Tempo Real

A API em Tempo Real oferece recursos de áudio de streaming de baixa latência para aplicações orientadas por voz. Ela permite interações de fala para fala onde o modelo pode responder a uma entrada de áudio com uma saída de áudio, lidando com interrupções naturalmente.

Como Funciona:

A API em Tempo Real usa WebSocket para criar uma sessão com estado e orientada a eventos. Você transmite blocos de áudio para a API, e ela transmite de volta tanto transcrições quanto respostas de áudio geradas. A conexão suporta:

• Streaming de entrada de áudio (envia blocos de áudio conforme são capturados)
• Streaming de saída de áudio (recebe áudio gerado em tempo real)
• Entrada/saída de texto (para interações híbridas de texto+voz)
• Manipulação automática de interrupção (para a geração quando o usuário fala)

Recursos Principais:

Detecção de Atividade de Voz (VAD): A API inclui VAD semântica que entende quando um usuário terminou de falar versus apenas fez uma pausa. Isso cria um fluxo de conversa mais natural.

Capacidades Multimodais: Acesso direto às habilidades multimodais nativas do GPT-4o, processando áudio e texto em um modelo unificado.

Baixa Latência: Projetado para latências abaixo de 500ms para interações de voz, adequado para conversas em tempo real.

WebSocket vs HTTP: Comparação de Desempenho

A escolha entre WebSocket e HTTP depende das características da sua aplicação. Aqui está quando cada protocolo se destaca.

Quando o WebSocket Supera o HTTP

Alto Volume de Chamadas de Ferramentas:
Se o seu fluxo de trabalho faz mais de 10 chamadas de ferramentas sequenciais, a conexão persistente do WebSocket elimina a sobrecarga de configuração repetida. Cada requisição HTTP exige:

• Resolução DNS (se não estiver em cache)
• Handshake TCP (3 vias)
• Handshake TLS (2 idas e vindas para TLS 1.3)
• Cabeçalhos de requisição/resposta HTTP

O WebSocket faz isso uma vez e depois reutiliza a conexão.

Aplicações Sensíveis à Latência:
Para aplicações de voz ou chat em tempo real onde cada milissegundo conta, a conexão persistente e os recursos de streaming do WebSocket reduzem significativamente a latência percebida.

Atualizações Iniciadas pelo Servidor:
O WebSocket permite que o servidor envie dados para os clientes sem polling. Para tarefas de agente de longa duração, o servidor pode enviar atualizações de progresso conforme os eventos ocorrem.

Quando o HTTP é Suficiente

Requisição-Resposta Simples:
Para chamadas de API pontuais ou fluxos de trabalho com 1-2 chamadas de ferramentas, o HTTP é mais simples de implementar e depurar. A maioria dos desenvolvedores está familiarizada com clientes HTTP, e a infraestrutura (balanceadores de carga, proxies) lida bem com HTTP.

Operações Sem Estado:
Se você não precisa manter o estado da sessão entre as requisições, a natureza sem estado do HTTP é na verdade uma vantagem — nenhuma gerência de conexão é necessária.

Restrições de Infraestrutura:
Alguns ambientes de implantação (funções serverless, certos proxies) não suportam conexões WebSocket de longa duração. O HTTP funciona universalmente.

Métricas de Desempenho

Com base na documentação da OpenAI e em testes da comunidade:

Como Usar o Modo WebSocket da API Responses

Vamos implementar uma conexão WebSocket com a API Responses para um fluxo de trabalho agentivo.

Pré-requisitos

• Chave da API OpenAI com acesso à API Responses
• Biblioteca cliente WebSocket (ws para Node.js ou websocket-client para Python)
• Compreensão da chamada de ferramentas na API OpenAI

Configuração da Conexão

Exemplo em Node.js:

const WebSocket = require('ws');

// Connect to Responses API WebSocket endpoint
const ws = new WebSocket('wss://api.openai.com/v1/responses', {
  headers: {
    'Authorization': `Bearer ${process.env.OPENAI_API_KEY}`,
    'OpenAI-Beta': 'responses-api=v1'
  }
});

ws.on('open', () => {
  console.log('Connected to OpenAI Responses API');

  // Send initial request
  const initialMessage = {
    model: 'gpt-4o',
    messages: [
      { role: 'user', content: 'Help me analyze this codebase and suggest improvements.' }
    ],
    tools: [
      {
        type: 'function',
        function: {
          name: 'read_file',
          description: 'Read contents of a file',
          parameters: {
            type: 'object',
            properties: {
              path: { type: 'string', description: 'File path to read' }
            },
            required: ['path']
          }
        }
      },
      {
        type: 'function',
        function: {
          name: 'search_code',
          description: 'Search for code patterns',
          parameters: {
            type: 'object',
            properties: {
              pattern: { type: 'string', description: 'Regex pattern to search' }
            },
            required: ['pattern']
          }
        }
      }
    ]
  };

  ws.send(JSON.stringify(initialMessage));
});

ws.on('message', (data) => {
  const response = JSON.parse(data);
  console.log('Received:', response);

  // Check if model wants to call tools
  if (response.choices[0].finish_reason === 'tool_calls') {
    const toolCalls = response.choices[0].message.tool_calls;

    // Execute tools (simplified)
    const toolResults = toolCalls.map(call => ({
      tool_call_id: call.id,
      output: executeToolLocally(call.function.name, call.function.arguments)
    }));

    // Continue the conversation with tool results
    const continuation = {
      previous_response_id: response.id, // Reference previous response
      input: toolResults
    };

    ws.send(JSON.stringify(continuation));
  }
});

ws.on('error', (error) => {
  console.error('WebSocket error:', error);
});

ws.on('close', () => {
  console.log('Connection closed');
});

function executeToolLocally(name, args) {
  // Your tool execution logic
  if (name === 'read_file') {
    const { path } = JSON.parse(args);
    return fs.readFileSync(path, 'utf-8');
  }
  // ... other tools
}

Exemplo em Python:

import websocket
import json
import os

def on_message(ws, message):
    response = json.loads(message)
    print(f"Received: {response}")

    # Handle tool calls
    if response['choices'][0]['finish_reason'] == 'tool_calls':
        tool_calls = response['choices'][0]['message']['tool_calls']

        # Execute tools
        tool_results = []
        for call in tool_calls:
            result = execute_tool(call['function']['name'],
                                 json.loads(call['function']['arguments']))
            tool_results.append({
                'tool_call_id': call['id'],
                'output': result
            })

        # Send continuation with only new input + previous_response_id
        continuation = {
            'previous_response_id': response['id'],
            'input': tool_results
        }
        ws.send(json.dumps(continuation))

def on_error(ws, error):
    print(f"Error: {error}")

def on_close(ws, close_status_code, close_msg):
    print("Connection closed")

def on_open(ws):
    print("Connected to OpenAI Responses API")

    # Send initial request
    initial_message = {
        'model': 'gpt-4o',
        'messages': [
            {'role': 'user', 'content': 'Analyze this codebase and suggest improvements.'}
        ],
        'tools': [
            {
                'type': 'function',
                'function': {
                    'name': 'read_file',
                    'description': 'Read file contents',
                    'parameters': {
                        'type': 'object',
                        'properties': {
                            'path': {'type': 'string'}
                        },
                        'required': ['path']
                    }
                }
            }
        ]
    }
    ws.send(json.dumps(initial_message))

def execute_tool(name, args):
    if name == 'read_file':
        with open(args['path'], 'r') as f:
            return f.read()
    # ... other tools

# Create WebSocket connection
ws = websocket.WebSocketApp(
    "wss://api.openai.com/v1/responses",
    header={
        "Authorization": f"Bearer {os.environ['OPENAI_API_KEY']}",
        "OpenAI-Beta": "responses-api=v1"
    },
    on_open=on_open,
    on_message=on_message,
    on_error=on_error,
    on_close=on_close
)

ws.run_forever()

Detalhes Chave da Implementação

Gerenciamento de Estado:
A diferença crucial em relação ao HTTP é o uso de previous_response_id nas continuações. Isso informa à API para reutilizar o estado em cache da última resposta.

Continuações Somente com Entrada:
Ao continuar uma rodada, envie apenas:

• previous_response_id: Referencia a resposta em cache
• input: Novos dados (resultados de ferramentas, mensagens do usuário, etc.)

Não reenvie o array completo de messages — o servidor já possui esse contexto.

Retenção Zero de Dados:
Para usar ZDR com o modo WebSocket, inclua store: false em sua requisição inicial.

Como Usar o Modo WebSocket da API em Tempo Real

A API em Tempo Real permite interações de voz de baixa latência. Veja como implementá-la.

Pré-requisitos

• Chave da API OpenAI com acesso à API em Tempo Real
• Capacidades de captura/reprodução de áudio
• Biblioteca cliente WebSocket
• Codificação de áudio (PCM mono de 24kHz, 16 bits para melhores resultados)

Configuração da Conexão

Exemplo em JavaScript (Navegador):

// Connect to Realtime API
const ws = new WebSocket(
  `wss://api.openai.com/v1/realtime?model=gpt-realtime`,
  ['realtime', 'openai-insecure-api-key.' + process.env.OPENAI_API_KEY]
);

ws.addEventListener('open', () => {
  console.log('Connected to Realtime API');

  // Configure session
  ws.send(JSON.stringify({
    type: 'session.update',
    session: {
      modalities: ['text', 'audio'],
      voice: 'alloy',
      input_audio_format: 'pcm16',
      output_audio_format: 'pcm16',
      turn_detection: {
        type: 'server_vad', // or 'semantic_vad' for smarter detection
        threshold: 0.5,
        prefix_padding_ms: 300,
        silence_duration_ms: 500
      }
    }
  }));
});

ws.addEventListener('message', (event) => {
  const message = JSON.parse(event.data);

  switch (message.type) {
    case 'session.created':
      console.log('Session created:', message.session);
      break;

    case 'conversation.item.created':
      console.log('New item:', message.item);
      break;

    case 'response.audio.delta':
      // Received audio chunk - play it
      const audioChunk = base64ToArrayBuffer(message.delta);
      playAudioChunk(audioChunk);
      break;

    case 'response.audio_transcript.delta':
      // Received transcript chunk
      console.log('Transcript:', message.delta);
      break;

    case 'input_audio_buffer.speech_started':
      console.log('User started speaking');
      break;

    case 'input_audio_buffer.speech_stopped':
      console.log('User stopped speaking');
      break;

    case 'error':
      console.error('API error:', message.error);
      break;
  }
});

// Send audio from microphone
async function streamMicrophoneToAPI() {
  const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
  const audioContext = new AudioContext({ sampleRate: 24000 });
  const source = audioContext.createMediaStreamSource(stream);
  const processor = audioContext.createScriptProcessor(4096, 1, 1);

  processor.onaudioprocess = (e) => {
    const inputData = e.inputBuffer.getChannelData(0);

    // Convert Float32 to Int16 PCM
    const pcmData = new Int16Array(inputData.length);
    for (let i = 0; i < inputData.length; i++) {
      pcmData[i] = Math.max(-32768, Math.min(32767, inputData[i] * 32768));
    }

    // Send to API
    ws.send(JSON.stringify({
      type: 'input_audio_buffer.append',
      audio: arrayBufferToBase64(pcmData.buffer)
    }));
  };

  source.connect(processor);
  processor.connect(audioContext.destination);
}

// Send text input
function sendTextMessage(text) {
  ws.send(JSON.stringify({
    type: 'conversation.item.create',
    item: {
      type: 'message',
      role: 'user',
      content: [
        { type: 'input_text', text: text }
      ]
    }
  }));

  // Request response generation
  ws.send(JSON.stringify({
    type: 'response.create'
  }));
}

function playAudioChunk(arrayBuffer) {
  const audioContext = new AudioContext({ sampleRate: 24000 });
  audioContext.decodeAudioData(arrayBuffer, (buffer) => {
    const source = audioContext.createBufferSource();
    source.buffer = buffer;
    source.connect(audioContext.destination);
    source.start();
  });
}

Exemplo em Python:

import websocket
import json
import base64
import pyaudio

# Audio configuration
RATE = 24000
CHUNK = 4096
FORMAT = pyaudio.paInt16
CHANNELS = 1

audio = pyaudio.PyAudio()

def on_open(ws):
    print("Connected to Realtime API")

    # Configure session
    ws.send(json.dumps({
        'type': 'session.update',
        'session': {
            'modalities': ['text', 'audio'],
            'voice': 'alloy',
            'input_audio_format': 'pcm16',
            'output_audio_format': 'pcm16',
            'turn_detection': {
                'type': 'server_vad',
                'threshold': 0.5,
                'silence_duration_ms': 500
            }
        }
    }))

    # Start streaming microphone
    stream_microphone(ws)

def on_message(ws, message):
    data = json.loads(message)

    if data['type'] == 'response.audio.delta':
        # Decode and play audio
        audio_chunk = base64.b64decode(data['delta'])
        play_audio(audio_chunk)

    elif data['type'] == 'response.audio_transcript.delta':
        print(f"Transcript: {data['delta']}", end='', flush=True)

    elif data['type'] == 'input_audio_buffer.speech_started':
        print("\n[User speaking...]")

    elif data['type'] == 'error':
        print(f"Error: {data['error']}")

def stream_microphone(ws):
    stream = audio.open(
        format=FORMAT,
        channels=CHANNELS,
        rate=RATE,
        input=True,
        frames_per_buffer=CHUNK
    )

    def audio_thread():
        while True:
            audio_data = stream.read(CHUNK)
            ws.send(json.dumps({
                'type': 'input_audio_buffer.append',
                'audio': base64.b64encode(audio_data).decode('utf-8')
            }))

    import threading
    threading.Thread(target=audio_thread, daemon=True).start()

def play_audio(audio_chunk):
    stream = audio.open(
        format=FORMAT,
        channels=CHANNELS,
        rate=RATE,
        output=True
    )
    stream.write(audio_chunk)
    stream.stop_stream()
    stream.close()

# Create WebSocket connection
ws = websocket.WebSocketApp(
    f"wss://api.openai.com/v1/realtime?model=gpt-realtime",
    header={
        "Authorization": f"Bearer {os.environ['OPENAI_API_KEY']}"
    },
    on_open=on_open,
    on_message=on_message
)

ws.run_forever()

Detalhes Chave da Implementação

Tipos de Eventos:

A API em Tempo Real usa comunicação orientada a eventos. Eventos comuns:

Cliente → Servidor:

• session.update - Configura parâmetros da sessão
• input_audio_buffer.append - Envia blocos de áudio
• conversation.item.create - Adiciona mensagens de texto
• response.create - Solicita resposta da IA

Servidor → Cliente:

• session.created - Confirma a configuração da sessão
• response.audio.delta - Bloco de áudio da IA
• response.audio_transcript.delta - Transcrição do áudio da IA
• input_audio_buffer.speech_started/stopped - Eventos VAD
• error - Notificações de erro

Detecção de Atividade de Voz:

Escolha entre dois modos VAD:

server_vad: Detecção básica de atividade de voz baseada no volume do áudio e duração do silêncio.

semantic_vad: Detecção mais inteligente que entende pausas naturais versus conclusão de uma fala. Use isso para conversas mais naturais onde os usuários podem pausar no meio de um pensamento.

Testando Conexões WebSocket com Apidog

Testar APIs WebSocket difere do teste HTTP — você precisa manter uma conexão, enviar eventos e monitorar o fluxo de mensagens bidirecional. O Apidog oferece recursos especializados de teste WebSocket.

Configurando Testes WebSocket no Apidog

Passo 1: Criar Requisição WebSocket

No Apidog, crie uma nova requisição e selecione "WebSocket" como protocolo. Digite sua URL de conexão:

wss://api.openai.com/v1/responses

Passo 2: Configurar Cabeçalhos

Adicione os cabeçalhos de autenticação:

Authorization: Bearer YOUR_OPENAI_API_KEY
OpenAI-Beta: responses-api=v1

Para a API em Tempo Real, você também pode usar autenticação baseada em URL:

wss://api.openai.com/v1/realtime?model=gpt-realtime

Com a chave da API no cabeçalho do subprotocolo.

Passo 3: Estabelecer Conexão

Clique em "Conectar" para estabelecer a conexão WebSocket. O Apidog mostrará:

• Status da conexão (conectado/desconectado)
• Métricas de latência
• Duração da conexão

Passo 4: Enviar Eventos

Use o compositor de mensagens do Apidog para enviar eventos JSON. Para a API Responses:

{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": "What's the weather in San Francisco?"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get current weather",
        "parameters": {
          "type": "object",
          "properties": {
            "location": { "type": "string" }
          }
        }
      }
    }
  ]
}

Passo 5: Monitorar Respostas

O Apidog exibe:

• Todas as mensagens recebidas em ordem cronológica
• Timestamps e tamanhos das mensagens
• Formatação JSON e destaque de sintaxe
• Recursos de copiar/exportar para depuração

Testando Continuações

Para testar o padrão de continuação com previous_response_id:

1. Envie a mensagem inicial, anote o response.id na resposta
2. Envie a continuação com apenas a nova entrada:

{
  "previous_response_id": "resp_abc123",
  "input": [
    {
      "tool_call_id": "call_xyz789",
      "output": "{\"temperature\": 72, \"conditions\": \"sunny\"}"
    }
  ]
}

1. Observe a latência reduzida em comparação com o reenvio do contexto completo

Testando a API em Tempo Real

Para a API em Tempo Real, o Apidog permite que você:

• Envie blocos de áudio codificados em base64
• Monitore eventos session.update
• Acompanhe eventos VAD (início/fim da fala)
• Visualize deltas de transcrição em tempo real

Isso é particularmente útil para depurar por que seu assistente de voz pode estar cortando usuários ou não detectando a fala corretamente.

Variáveis de Ambiente

Armazene chaves de API com segurança usando as variáveis de ambiente do Apidog:

{{OPENAI_API_KEY}}

Isso permite alternar entre chaves de desenvolvimento e produção sem editar as requisições.

Casos de Uso do Mundo Real

Vamos explorar cenários práticos onde os modos WebSocket da OpenAI se destacam.

Caso de Uso 1: Agente de Codificação Autônomo

Cenário: Um assistente de codificação que analisa bases de código, identifica problemas e faz melhorias de forma autônoma.

Por que o WebSocket da API Responses:

• Fluxo de trabalho típico: Ler arquivo → Analisar → Buscar padrões semelhantes → Ler mais arquivos → Sugerir alterações
• Isso cria 15-30 chamadas de ferramentas por tarefa
• O modo WebSocket reduz o tempo total de execução em ~40%
• A conexão persistente mantém o contexto em todas as chamadas de ferramentas

Padrão de Implementação:

// Initial task
ws.send({ messages: [{ role: 'user', content: 'Audit security vulnerabilities' }], tools: [...] })

// First response: model calls read_file
ws.on('message', (resp1) => {
  ws.send({ previous_response_id: resp1.id, input: [tool_result_1] })
})

// Second response: model calls search_code
ws.on('message', (resp2) => {
  ws.send({ previous_response_id: resp2.id, input: [tool_result_2] })
})

// Continue for 20+ iterations...

Caso de Uso 2: Bot de Atendimento ao Cliente por Voz

Cenário: Um bot de suporte telefônico que lida com as dúvidas dos clientes com um fluxo de conversa natural.

Por que o WebSocket da API em Tempo Real:

• Baixa latência crítica (<500ms para conversas naturais)
• Precisa lidar com interrupções (cliente fala por cima do bot)
• Processa a entrada de voz diretamente sem transcrição separada
• Transmite respostas em tempo real (não espera por uma frase completa)

Padrão de Implementação:

// Stream phone audio to API
phoneSystem.on('audio', (chunk) => {
  ws.send({
    type: 'input_audio_buffer.append',
    audio: base64Encode(chunk)
  })
})

// Play AI responses immediately
ws.on('message', (event) => {
  if (event.type === 'response.audio.delta') {
    phoneSystem.playAudio(base64Decode(event.delta))
  }
})

Solução de Problemas Comuns

A Conexão Falha ao Ser Estabelecida

Sintomas: A conexão WebSocket nunca é aberta, evento de fechamento imediato.

Causas Comuns:

1. Chave da API inválida - Verifique novamente seu cabeçalho Authorization
2. Cabeçalho beta ausente - A API Responses requer OpenAI-Beta: responses-api=v1
3. Restrições de rede - Algumas redes corporativas bloqueiam o WebSocket
4. URL incorreta - Verifique wss:// (não ws://) e o caminho do endpoint

Solução:
Use o Apidog para testar a conexão com mensagens de erro detalhadas. O inspetor de requisições mostra exatamente quais cabeçalhos são enviados, tornando fácil identificar chaves de API ausentes ou incorretas.

Código de Depuração:

ws.on('error', (error) => {
  console.error('Connection error:', error);
});

ws.on('close', (code, reason) => {
  console.log(`Closed with code ${code}: ${reason}`);
  // Common codes:
  // 1006: Abnormal closure (often auth issues)
  // 1008: Policy violation (invalid headers)
});

Alta Latência Apesar do WebSocket

Sintomas: A conexão WebSocket funciona, mas não é mais rápida que o HTTP.

Causas Comuns:

1. Não usar previous_response_id - Você está reenviando o contexto completo
2. Inicialização a frio (cold start) - A primeira requisição em uma nova conexão é mais lenta
3. Latência de rede - Distância geográfica dos servidores da API
4. Cargas úteis grandes (large payloads) - Envio de dados desnecessários em continuações

Solução:
Verifique se você está enviando apenas a nova entrada nas continuações:

// ERRADO - envia o contexto completo todas as vezes
ws.send({
  messages: [...allPreviousMessages, newMessage],
  tools: [...]
})

// CORRETO - referencia o estado em cache
ws.send({
  previous_response_id: lastResponse.id,
  input: [newMessage]
})

Vazamentos de Memória em Conexões de Longa Duração

Sintomas: A memória da aplicação aumenta ao longo do tempo com a conexão persistente.

Causas Comuns:

1. Listeners de eventos não removidos - Acúmulo de listeners na reconexão
2. Buffers de áudio não liberados - Mantendo referências a áudios reproduzidos
3. Histórico de mensagens crescendo - Armazenando todas as mensagens recebidas

Solução:

// Limpar listeners de eventos na reconexão
function cleanupAndReconnect(ws) {
  ws.removeAllListeners();
  ws.close();

  const newWs = createConnection();
  return newWs;
}

// Liberar buffers de áudio após a reprodução
function playAndRelease(audioBuffer) {
  const source = audioContext.createBufferSource();
  source.buffer = audioBuffer;
  source.connect(audioContext.destination);
  source.start();

  source.onended = () => {
    source.disconnect();
    // Buffer will be garbage collected
  };
}

// Limitar histórico de mensagens
const messageHistory = [];
const MAX_HISTORY = 100;

ws.on('message', (data) => {
  messageHistory.push(data);
  if (messageHistory.length > MAX_HISTORY) {
    messageHistory.shift(); // Remove oldest
  }
});

Conclusão

Os modos WebSocket da API OpenAI abrem novas possibilidades para aplicações de IA. O modo WebSocket da API Responses oferece uma execução até 40% mais rápida para fluxos de trabalho agentivos com chamadas de ferramentas intensivas, tornando-o ideal para assistentes de codificação autônomos e sistemas de orquestração. A API em Tempo Real proporciona latência inferior a 500ms para aplicações de voz, permitindo conversas naturais e com capacidade de interrupção.

A escolha do modo certo depende do seu caso de uso:

• WebSocket da API Responses: Agentes com muitas ferramentas, assistentes de codificação, ferramentas de pesquisa (10+ chamadas de ferramentas)
• WebSocket da API em Tempo Real: Assistentes de voz, bots telefônicos, tutores de idiomas (streaming de áudio)
• HTTP: Requisições simples, ambientes serverless, 1-5 chamadas de API

A natureza persistente e orientada a eventos das conexões WebSocket exige abordagens de teste diferentes das do HTTP. Teste as APIs WebSocket da OpenAI com o cliente WebSocket em tempo real do Apidog — importe sua chave de API, estabeleça conexões, envie eventos e monitore as respostas com registros detalhados. Experimente gratuitamente para validar suas integrações antes da implantação em produção.