Salt la conținutul principal
Română— Alege o limbă
Meniu

Arhitectura WebSocket a API-ului Realtime

Lecția 1 din 18 Actualizată 3 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Arhitectura WebSocket a API-ului Realtime
  2. Trei arhitecturi vocale în 2026
  3. WebRTC, WebSocket sau SIP
  4. WebSocket vs. REST: De ce această alegere?
  5. Stabilirea unei conexiuni WebSocket
  6. Arhitectura aplicației Realtime
  7. Puncte cheie

Actualizat la 2 noiembrie 2026 — Modele audio. Mai multe modele din acest curs sunt depreciate: tts-1, tts-1-hd și gpt-4o-mini-tts vor înceta să funcționeze la 6 ianuarie 2027 (înlocuitor: gpt-realtime-2.1-mini, pe care ghidul OpenAI TTS îl declară necompatibil cu /v1/audio/speech: migrarea sintezei vocale se face către API-ul Realtime); gpt-realtime, gpt-4o-realtime și modelele audio legacy la 20 ianuarie 2027 (gpt-realtime-2.1, gpt-realtime-2.1-mini, gpt-audio-1.5); whisper-1, gpt-4o-transcribe și /v1/audio/translations la 26 februarie 2027 (gpt-transcribe, gpt-live-transcribe, v1/realtime/translations). Pentru voce full-duplex, GPT-Live 1 este disponibil în API din 10 septembrie 2026. Addendum 3 noiembrie 2026: secțiune despre cele trei arhitecturi vocale OpenAI (GPT-Live, API-ul Realtime, lanțul de procesare) și selecția transportului (WebRTC, WebSocket, SIP), bazată pe ghidurile Voice agents, Audio and voice și Getting started with the Realtime API; durata maximă a sesiunii: 60 de minute (Realtime conversations).

Arhitectura WebSocket a API-ului Realtime

API-ul Realtime de la OpenAI reprezintă o schimbare fundamentală de paradigmă în modul în care interacționați cu modelele lingvistice. Spre deosebire de API-urile REST tradiționale, care funcționează pe un ciclu de tip cerere-răspuns, API-ul Realtime utilizează protocolul WebSocket pentru a stabili o conexiune persistentă și bidirecțională între aplicația dumneavoastră și model.

Această arhitectură permite schimbul de audio în timp real: dumneavoastră trimiteți audio, modelul îl procesează și răspunde vocal cu o latență redusă, omitând pașii intermediari de transcriere sau de sinteză vocală (text-to-speech). Aceasta este una dintre componentele de bază pentru agenții vocali conversazionali și constituie nucleul acestui curs.

Trei arhitecturi vocale în 2026

Înainte de a deschide un WebSocket, este esențial să plasați API-ul Realtime în context alături de celelalte soluții OpenAI. Ghidul Voice agents distinge trei abordări:

ArhitecturăIdeal pentruDe ce să o alegeți
GPT-LiveConversații full-duplex cu un backend separatModelul vocal ascultă în timp ce vorbește și deleagă raționamentul și utilizarea instrumentelor către un backend la alegerea dumneavoastră; păstrează intact agentul text existent
API-ul RealtimeVorbire, raționament și instrumente într-o singură sesiuneUn singur model interpretează audio, decide ce trebuie făcut și rostește răspunsul
Lanț de procesareControl granular asupra fiecărui pasTranscriere, apoi agent text, apoi sinteză vocală: inspectați sau transformați textul între pași și înlocuiți independent fiecare componentă

Pentru noile aplicații de conversație vocală, pagina Audio and voice de la OpenAI recomandă acum începerea cu GPT-Live. API-ul Realtime rămâne punctul de plecare corect atunci când agentul trebuie să se încadreze într-o singură sesiune, suportând întreruperea de către utilizator, un prim răspuns audio rapid, preluarea naturală a cuvântului și apeluri directe de instrumente. Lanțul de procesare funcționează cel mai bine atunci când fiecare pas trebuie să rămână vizibil: păstrarea transcrierilor, aplicarea regulilor înainte ca agentul să răspundă sau emiterea vocii doar după validarea răspunsului.

Acest curs se concentrează pe API-ul Realtime și pe lanțul de procesare, ale căror componente (transcriere, sinteză vocală) sunt acoperite în secțiunile următoare.

WebRTC, WebSocket sau SIP

Alegerea transportului depinde de originea audio. Conform documentației: utilizați WebRTC pentru audio în browser, cu un secret efemer de client generat de serverul dumneavoastră; WebSocket pentru pipeline-uri audio lato-server; SIP pentru apeluri telefonice. O conexiune de control lato-server permite, de asemenea, unui backend de încredere să observe și să direcționeze o sesiune media. Această lecție detaliază WebSocket, cea mai simplă metodă de a înțelege evenimentele schimbate; într-un browser, preferați WebRTC. O sesiune Realtime durează cel mult 60 de minute.

WebSocket vs. REST: De ce această alegere?

Într-o arhitectură REST tradițională, fiecare interacțiune necesită o cerere HTTP completă: deschiderea unei conexiuni TCP, negocierea TLS, trimiterea antetelor, așteptarea răspunsului și închiderea conexiunii. Pentru audio în timp real, această suprasolicitare este prohibitivă.

Criteriu REST (API-ul Responses) WebSocket (API-ul Realtime)
Latență 200–500 ms per cerere < 50 ms după conectare
Direcție Doar Client → Server Bidirecțional simultan
Conexiune Nouă pentru fiecare cerere Persistentă (sesiune)
Audio Fișier complet necesar Streaming bucată cu bucată

Protocolul WebSocket menține un canal deschis continuu. Odată stabilit, clientul și serverul pot trimite mesaje în orice moment, fără a aștepta ca celălalt să termine.

Stabilirea unei conexiuni WebSocket

Iată cum să stabiliți o conexiune la API-ul Realtime în Python:

import asyncio
import websockets
import json

OPENAI_API_KEY = "sk-..."
URL = "wss://api.openai.com/v1/realtime?model=gpt-realtime-2.1"

async def connect_realtime():
    headers = {
        "Authorization": f"Bearer {OPENAI_API_KEY}"
    }

    async with websockets.connect(URL, additional_headers=headers) as ws:
        print("Connected to Realtime API")

        # Receive the welcome event
        response = await ws.recv()
        event = json.loads(response)
        print(f"Type: {event['type']}")
        # → "session.created"

        # Keep the connection open
        await asyncio.Future()

asyncio.run(connect_realtime())

URL-ul de conexiune include modelul ca parametru de interogare. De când API-ul a devenit disponibil public, este necesar doar antetul de autentificare; antetul OpenAI-Beta: realtime=v1 din faza beta a fost eliminat.

Interfață notată la 5 august 2026 — API-ul Realtime evoluează (modele, nume de evenimente, formatul sesiunii): în caz de dubiu, consultați documentația oficială.

Arhitectura aplicației Realtime

O aplicație care utilizează API-ul Realtime urmează o arhitectură stratificată:

1

Stratul audio (captare/redare)

Captează microfonul, redă răspunsurile audio. Utilizează PyAudio, sounddevice sau Web Audio API în browser.

2

Stratul WebSocket (transport)

Gestionează conexiunea persistentă, encodează/decodează evenimentele JSON, gestionează reconectările.

3

Stratul aplicație (logică de afaceri)

Orchestrează conversația, gestionează contextul, apelează instrumente, procesează rezultatele.

4

Stratul server (proxy opțional)

În producție, un server intermediar protejează cheia API și adaugă logică de afaceri lato-server.

Rolul serverului Proxy

În timpul dezvoltării, vă puteți conecta aplicația direct la API-ul Realtime. În producție, un server proxy este esențial pentru a:

  • Proteja cheia API — nu o expuneți niciodată lato-client
  • Autentifica utilizatorii — verificați token-urile înainte de deschiderea sesiunii
  • Controla costurile — limitați durata sesiunii și utilizarea token-urilor
  • Jurnaliza interacțiunile — pentru depanare și conformitate
# Simplified example of a WebSocket proxy with FastAPI
from fastapi import FastAPI, WebSocket
import websockets

app = FastAPI()

@app.websocket("/ws/realtime")
async def proxy_realtime(client_ws: WebSocket):
    await client_ws.accept()

    headers = {"Authorization": f"Bearer {OPENAI_API_KEY}"}

    async with websockets.connect(URL, additional_headers=headers) as openai_ws:
        async def forward_to_openai():
            async for message in client_ws.iter_text():
                await openai_ws.send(message)

        async def forward_to_client():
            async for message in openai_ws:
                await client_ws.send_text(message)

        await asyncio.gather(forward_to_openai(), forward_to_client())

Puncte cheie

  • Trei arhitecturi vocale la OpenAI: GPT-Live (recomandat pentru noile aplicații conversaționale), API-ul Realtime (vorbire, raționament și instrumente într-o singură sesiune) și lanțul transcriere → agent → sinteză
  • WebRTC pentru audio în browser, WebSocket pentru pipeline-uri server, SIP pentru telefonie; sesiunile durează cel mult 60 de minute
  • API-ul Realtime utilizează WebSocket pentru comunicație bidirecțională cu latență redusă
  • Conexiunea este persistentă: o singură deschidere pentru întreaga sesiune conversațională
  • Arhitectura stratificată separă audio, transportul, logica de afaceri și proxy-ul server
  • În producție, un server proxy este esențial pentru securitate și controlul costurilor
  • Protocolul este orientat pe evenimente: fiecare mesaj este un obiect JSON cu un câmp type