Používanie ThunderPhone s klientmi OpenAI Realtime

Nakonfigurujte klienta servera kompatibilného s OpenAI Realtime tak, aby používal ThunderPhone, a to buď s uloženým agentom, alebo s vloženou konfiguráciou relácie.

ThunderPhone implementuje zameranú podmnožinu modelu udalostí OpenAI Realtime. Existujúci klient na strane servera môže zachovať svoj tok udalostí WebSocketu, zvuku, relácie a odpovedí a zároveň používať hlasového agenta ThunderPhone.

Pred pripojením#

Potrebujete tajný kľúč API organizácie ThunderPhone a serverové prostredie, ktoré dokáže otvárať WebSockety. Nepripájajte sa z kódu prehliadača ani nevystavujte kľúč prehliadaču. Ak chcete použiť uloženého agenta, najprv ho nasaďte a skopírujte jeho číselné ID agenta.

Pripojte sa k:

wss://api.thunderphone.com/v1/realtime

Overte aktualizáciu WebSocketu zo svojho servera:

Authorization: Bearer sk_live_YOUR_API_KEY

Overovanie pomocou reťazca dotazu je dostupné pre klientov, ktorí nemôžu nastaviť hlavičky handshaku, ale adresy URL môžu ľahšie uniknúť do protokolov.

Vyberte, kto spravuje konfiguráciu#

Uložený agent#

Pripojte sa pomocou ID nasadeného agenta:

wss://api.thunderphone.com/v1/realtime?agent_id=12

Agent sa spustí počas pripájania soketu. Jeho pozdrav zostáva dostupný, ale Realtime vypne jeho hovorené kontroly ticha a vynechá transfer_call a send_keypad_input. Ostatné kompatibilné nástroje sa spúšťajú na ThunderPhone. Pre tento režim neposielajte vložené pokyny ani nástroje vykonávané klientom.

Pred spustením agenta nastavte zvuk na linke pomocou parametrov dotazu input_audio_format, output_audio_format, input_rate a output_rate. Po pripojení nemôžete zmeniť uloženú konfiguráciu ani formáty zvuku.

Vložená relácia#

Bez agent_id počkajte na session.created a potom odošlite session.update:

{
  "type": "session.update",
  "session": {
    "type": "realtime",
    "instructions": "Answer questions clearly and keep responses brief.",
    "audio": {
      "input": {
        "format": { "type": "audio/pcm", "rate": 24000 }
      },
      "output": {
        "format": { "type": "audio/pcm", "rate": 24000 },
        "voice": "olivia"
      }
    },
    "config": {
      "product": "bolt"
    }
  }
}

Prvá prijatá aktualizácia vytvorí hovor. session.updated znamená, že relácia je aktívna. Pokyny, hlas, produkt, nástroje ani formáty zvuku potom už nemožno zmeniť.

Vložené relácie nemajú automatický pozdrav ani hovorené kontroly ticha. Ak chcete, aby agent prehovoril ako prvý, pridajte systémovú alebo používateľskú správu a odošlite response.create. Úplne nečinná relácia sa stále ukončí pri limite platformy pre tiché hovory, ktorý je predvolene 600 sekúnd.

Použite oficiálnu súpravu OpenAI SDK#

Odovzdajte základnú URL adresu WebSocketu končiacu na /v1; súprava SDK pridá /realtime. Hodnota model je názov kompatibility a nevyberá produkt ThunderPhone. Produkt vyberte v konfigurácii relácie alebo uloženom agentovi.

Táto kontrola pripojenia vytvorí vloženú reláciu Bolt, vypisuje udalosti až do prvej udalosti session.updated a potom sa zatvorí. Na streamovanie zvuku použite minimálneho klienta v jazyku Python.

import asyncio
import os
 
from openai import AsyncOpenAI
 
 
async def main():
    client = AsyncOpenAI(
        api_key=os.environ["THUNDERPHONE_API_KEY"],
        websocket_base_url="wss://api.thunderphone.com/v1",
    )
 
    async with client.realtime.connect(
        model="thunderphone-realtime"
    ) as connection:
        await connection.session.update(session={
            "type": "realtime",
            "instructions": "Listen to the caller and help them complete the call.",
            "config": {"product": "bolt"},
        })
        async for event in connection:
            print(event.type)
            if event.type == "session.updated":
                break
 
 
if __name__ == "__main__":
    asyncio.run(main())

Zachovajte existujúce spracovanie pripájania vstupného zvuku, delta udalostí zvuku odpovede, prerušení, volaní funkcií, chýb a čistého zatvorenia soketu. Vložené vlastné funkcie sa vykonávajú vo vašom klientovi; ich výsledky vráťte prostredníctvom protokolu Realtime. Nástroje uloženého agenta sa vykonávajú v ThunderPhone.

Životný cyklus relácie a zlyhania#

Jeden WebSocket predstavuje jeden hovor. Neplatné ID agenta alebo odmietnutá vložená konfigurácia vytvorí udalosť error. Pred považovaním relácie za aktívnu počkajte na session.updated. Zadajte skutočné vstupné a výstupné formáty a vzorkovacie frekvencie: nesúlad frekvencie PCM prehrá zvuk príliš rýchlo alebo príliš pomaly namiesto vytvorenia chyby overenia.

Po spustení relácie soket čisto zatvorte, keď vaša aplikácia skončí. Vložené relácie môžu používať funkcie vykonávané klientom. Relácie uloženého agenta používajú kompatibilné nástroje spúšťané ThunderPhone a neponúkajú presmerovanie ani vstup z klávesnice.

Otestujte integráciu#

Začnite s minimálnym klientom WAV v jazyku Python a mono PCM16 WAV s deklarovanou vzorkovacou frekvenciou. Overte:

1. Server prijme konfiguráciu a odošle session.updated.
2. Vstup vytvorí udalosti prepisu a zvuku odpovede očakávanou rýchlosťou.
3. Prerušenie a zrušenie odpovede zastavia zostávajúci výstupný zvuk.
4. Výsledky vložených funkcií alebo nástrojov uloženého agenta sa vrátia modelu.
5. Neplatný vstup vytvorí udalosť error, ktorú váš klient spracuje.
6. Váš klient zatvorí soket a hovor sa zobrazí v histórii hovorov.

Referenčná dokumentácia Realtime WebSocket uvádza prijímané udalosti, zvukové formáty, polia relácie a úplné príklady.

Cena#

Hovory Realtime používajú bežnú sadzbu za minútu vybraného produktu. Povolenie živých delta udalostí prepisu pridáva príplatok za minútu počas celej relácie; sadzbu nájdete v živých prepisoch a sadzby produktov v časti Cenník.

POST /v1/realtime/sessions je samostatná spravovaná cesta LiveKit. Vytvorí miestnosť a token účastníka s obmedzeným rozsahom; pre priame pripojenie WebSocket nie je potrebná.

Informácie o integráciách s frameworkmi nájdete v časti Použitie ThunderPhone s Pipecat a Použitie ThunderPhone s LiveKit Agents.