Používejte ThunderPhone s klienty OpenAI Realtime

Nasměrujte klienta serveru kompatibilního s OpenAI Realtime na ThunderPhone pomocí uloženého agenta nebo vložené konfigurace relace.

ThunderPhone implementuje zaměřenou podmnožinu modelu událostí OpenAI Realtime. Stávající klient na straně serveru může zachovat svůj tok událostí WebSocketu, zvuku, relace a odpovědí při použití hlasového agenta ThunderPhone.

Než se připojíte#

Potřebujete tajný klíč API organizace ThunderPhone a běhové prostředí serveru, které dokáže otevřít WebSockety. Nepřipojujte se z kódu v prohlížeči ani klíč nevystavujte prohlížeči. Chcete-li použít uloženého agenta, nejprve ho nasaďte a zkopírujte jeho číselné ID agenta.

Připojte se k:

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

Ověřte upgrade WebSocketu ze svého serveru:

Authorization: Bearer sk_live_YOUR_API_KEY

Ověřování pomocí parametrů v řetězci dotazu je k dispozici pro klienty, kteří nemohou nastavit hlavičky handshake, ale adresy URL lze snáze zachytit v protokolech.

Zvolte vlastníka konfigurace#

Uložený agent#

Připojte se pomocí ID nasazeného agenta:

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

Agent se spustí během připojování soketu. Jeho pozdrav zůstává k dispozici, ale Realtime vypne jeho mluvené kontroly ticha a vynechá transfer_call a send_keypad_input. Ostatní kompatibilní nástroje běží na ThunderPhone. Pro tento režim neodesílejte vložené pokyny ani nástroje spouštěné klientem.

Před spuštěním agenta nastavte zvuk na úrovni přenosu pomocí parametrů dotazu input_audio_format, output_audio_format, input_rate a output_rate. Po připojení nemůžete změnit uloženou konfiguraci ani formáty zvuku.

Vložená relace#

Bez agent_id počkejte na session.created a poté odešlete 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"
    }
  }
}

První přijatá aktualizace zřídí hovor. session.updated znamená, že relace je aktivní. Pokyny, hlas, produkt, nástroje ani formáty zvuku nelze po tomto okamžiku změnit.

Vložené relace nemají automatický pozdrav ani mluvené kontroly ticha. Chcete-li, aby agent promluvil jako první, připojte systémovou nebo uživatelskou zprávu a odešlete response.create. Zcela neaktivní relace se přesto ukončí při limitu platformy pro tiché hovory, který je ve výchozím nastavení 600 sekund.

Použití oficiálního SDK OpenAI#

Předejte základní adresu URL WebSocketu končící na /v1; SDK připojí /realtime. Hodnota model je název pro kompatibilitu a nevybírá produkt ThunderPhone. Produkt vyberte v konfiguraci relace nebo uloženém agentovi.

Tato kontrola připojení vytvoří vloženou relaci Bolt, vypisuje události až do první události session.updated a poté se uzavře. Pro streamování zvuku použijte minimálního klienta v Pythonu.

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())

Zachovejte stávající zpracování přidávání vstupního zvuku, zvukových delt odpovědí, přerušení, volání funkcí, chyb a čistého uzavření socketu. Vložené vlastní funkce se spouštějí ve vašem klientovi; jejich výsledky vracejte prostřednictvím protokolu Realtime. Nástroje uloženého agenta se spouštějí v ThunderPhone.

Životní cyklus relace a selhání#

Jeden WebSocket představuje jeden hovor. Neplatné ID agenta nebo odmítnutá vložená konfigurace vytvoří událost error. Před považováním relace za aktivní vyčkejte na session.updated. Určete skutečné vstupní a výstupní formáty a vzorkovací frekvence: nesoulad frekvence PCM přehrává zvuk příliš rychle nebo příliš pomalu namísto vytvoření chyby ověření.

Po spuštění relace čistě uzavřete socket, když vaše aplikace skončí. Vložené relace mohou používat funkce spouštěné klientem. Relace uloženého agenta používají kompatibilní nástroje spouštěné ThunderPhone a nenabízejí přepojení ani vstup z klávesnice.

Testování integrace#

Začněte s minimálním klientem WAV v Pythonu a mono PCM16 WAV s deklarovanou frekvencí. Ověřte:

1. Server přijme konfiguraci a odešle session.updated.
2. Vstup vytváří události přepisu a zvukové odpovědi očekávanou rychlostí.
3. Přerušení a zrušení odpovědi zastaví zbývající výstupní zvuk.
4. Výsledky vložených funkcí nebo nástrojů uloženého agenta se vrátí do modelu.
5. Neplatný vstup vytvoří událost error, kterou váš klient zpracuje.
6. Váš klient uzavře socket a hovor se zobrazí v historii hovorů.

Referenční dokumentace WebSocketu Realtime uvádí podporované události, zvukové formáty, pole relace a kompletní příklady.

Cena#

Hovory Realtime používají běžnou minutovou sazbu vybraného produktu. Povolení živých delt přepisu přidá minutový příplatek za celou relaci; sazbu najdete v živých přepisech a sazby produktů v ceníku.

POST /v1/realtime/sessions je samostatná spravovaná cesta LiveKit. Vytvoří místnost a token účastníka s omezeným rozsahem; pro přímé připojení WebSocketem není vyžadována.

Informace o integracích s frameworky najdete v Použití ThunderPhone z Pipecat a Použití ThunderPhone z LiveKit Agents.