Voce in tempo reale

Crea agenti vocali bidirezionali con gpt-realtime — il modello ascolta il parlato e risponde a voce in tempo reale (come una telefonata), tramite una connessione WebSocket a /v1/realtime. Il tuo SDK OpenAI Realtime esistente funziona senza modifiche; basta puntarlo al nostro endpoint e usare la tua chiave Synthorai.

Endpoint e autenticazione

Apri un WebSocket verso /v1/realtime con il tuo modello nella query string. L'autenticazione viene eseguita prima dell'upgrade, quindi una chiave rifiutata non apre mai un socket.

# WebSocket, server-side (Node / Python / Go — anything that can set headers)
GET wss://synthorai.io/v1/realtime?model=gpt-realtime
Authorization: Bearer $YOUR_KEY
# Send only the Authorization header. Do NOT send OpenAI-Beta: realtime=v1
# (the beta protocol is retired; it makes the upstream reject the session).

• La tua chiave sk-syn non lascia mai il nostro gateway — la credenziale upstream viene sostituita dal nostro lato.
• Pensato per client lato server (Node, Python, Go — qualsiasi cosa in grado di impostare un header Authorization). I token effimeri del browser non sono supportati.
• Solo WebSocket. SIP (telefonia) e WebRTC collegano il client direttamente all'upstream e non vengono proxati — porta invece l'audio della telefonia dentro un WebSocket.

Configura la sessione

All'apertura della connessione ricevi session.created. Invia un session.update per impostare la voce, le modalità, il formato audio e il rilevamento del turno. Usa il formato GA (session.type: "realtime", l'audio sotto audio.input / audio.output) — il vecchio formato piatto in beta è stato ritirato.

{
  "type": "session.update",
  "session": {
    "type": "realtime",
    "output_modalities": ["audio"],
    "instructions": "You are a concise customer-support agent.",
    "audio": {
      "input":  { "format": { "type": "audio/pcm", "rate": 24000 },
                  "turn_detection": { "type": "server_vad" } },
      "output": { "format": { "type": "audio/pcm", "rate": 24000 } }
    }
  }
}

Un turno di conversazione minimo:

1. Trasmetti l'audio del microfono con input_audio_buffer.append (PCM in base64).
2. Conferma il turno con input_audio_buffer.commit, poi response.create.
3. Ricevi i delta audio (response.output_audio.delta) e la trascrizione testuale, poi response.done con l'usage.
4. Con il server VAD attivato, il modello rileva i turni al posto tuo; gli stessi eventi fluiscono senza commit manuali.

Strumenti, chiamata di funzioni e conoscenza

Dichiara le funzioni in session.update. Il modello le chiama nel mezzo della conversazione — è così che colleghi la ricerca degli ordini, la biglietteria o qualsiasi sistema aziendale. Restituisci il risultato e il modello continua a parlare basandosi su di esso:

// 1. Declare tools in session.update: "tools": [{ "type": "function", ... }]
// 2. The model emits a function_call in response.done.
// 3. Return the result, then ask the model to continue:
{ "type": "conversation.item.create",
  "item": { "type": "function_call_output",
            "call_id": "call_abc",
            "output": "{\"status\":\"shipped\"}" } }
{ "type": "response.create" }

Sono supportati anche i server MCP remoti ("type": "mcp") — l'upstream si connette direttamente al server MCP. Per una knowledge base, inserisci i fatti tramite instructions, uno strumento di funzione basato sul tuo RAG, o MCP; la conoscenza integrata nel modello non è una fonte affidabile per i fatti aziendali.

Fatturazione

Fatturato in base all'usage di ogni response.done al prezzo di listino ufficiale (senza ricarico) — audio e testo, input e output, con una tariffa per l'input in cache. Ogni sessione scrive una riga di registro alla fine.

I prezzi mostrati sono per gpt-realtime / gpt-realtime-2.1; gpt-realtime-2.1-mini è circa un terzo. L'input audio è di ~10 tokens/second, l'output di ~20 tokens/second. Mantenere la cronologia della conversazione in sola aggiunta consente alla tariffa in cache ($0.40/1M) di assorbire la maggior parte di una chiamata lunga.

Durata della sessione e cambio a caldo

• Per le chiamate che potrebbero prolungarsi, esegui il cambio a caldo ben prima del limite (ad es. a 50 minutes): apri una nuova sessione e riproduci la conversazione come testo con conversation.item.create (l'utente come input_text, l'assistente come output_text — l'audio dell'assistente non può essere riprodotto).
• Non esiste la ripresa della sessione: se il WebSocket cade, lo stato upstream è perso. La riconnessione usa lo stesso percorso di replay testuale, quindi integra la riconnessione fin dal primo giorno.
• Il contesto è di 128K per gpt-realtime-2.1 / -mini (≈3.5 hours di audio in ingresso); il vecchio gpt-realtime è di 32K — non usarlo per chiamate lunghe.

Accesso

gpt-realtime è in beta su invito. Compare nel catalogo e nei prezzi, ma per usarlo il tuo workspace deve avere l'accesso concesso — contattaci per abilitarlo.