Upotrebljavajte ThunderPhone s klijentima OpenAI Realtime

Usmjerite klijent poslužitelja kompatibilan s OpenAI Realtimeom na ThunderPhone, koristeći spremljenog agenta ili ugrađenu konfiguraciju sesije.

ThunderPhone implementira fokusirani podskup modela događaja OpenAI Realtime. Postojeći klijent na poslužiteljskoj strani može zadržati svoj tijek događaja za WebSocket, zvuk, sesiju i odgovore dok upotrebljava glasovnog agenta ThunderPhone.

Prije povezivanja#

Potreban Vam je tajni API ključ organizacije ThunderPhone i poslužiteljsko izvršno okruženje koje može otvoriti WebSocket veze. Nemojte se povezivati iz koda preglednika niti izlagati ključ pregledniku. Da biste upotrebljavali spremljenog agenta, najprije ga implementirajte i kopirajte njegov numerički ID agenta.

Povežite se s:

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

Autorizirajte nadogradnju WebSocket veze sa svojeg poslužitelja:

Authorization: Bearer sk_live_YOUR_API_KEY

Autentifikacija putem niza upita dostupna je za klijente koji ne mogu postaviti zaglavlja rukovanja, ali URL-ovi lakše mogu dospjeti u zapisnike.

Odaberite tko upravlja konfiguracijom#

Spremljeni agent#

Povežite se s ID-jem implementiranog agenta:

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

Agent se pokreće tijekom povezivanja utičnice. Njegova uvodna poruka ostaje dostupna, ali Realtime onemogućuje njegove glasovne provjere tijekom tišine te izostavlja transfer_call i send_keypad_input. Ostali kompatibilni alati izvršavaju se na ThunderPhoneu. Nemojte slati ugrađene upute ni alate koje izvršava klijent za ovaj način rada.

Postavite format zvuka u prijenosu prije pokretanja agenta pomoću parametara upita input_audio_format, output_audio_format, input_rate i output_rate. Nakon povezivanja ne možete promijeniti spremljenu konfiguraciju ni formate zvuka.

Ugrađena sesija#

Bez agent_id, pričekajte session.created, a zatim pošaljite 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"
    }
  }
}

Prvo prihvaćeno ažuriranje inicijalizira poziv. session.updated znači da je sesija aktivna. Upute, glas, proizvod, alati i formati zvuka nakon toga se ne mogu mijenjati.

Ugrađene sesije nemaju automatsku uvodnu poruku ni glasovne provjere tijekom tišine. Da bi agent prvi progovorio, dodajte poruku sustava ili korisnika i pošaljite response.create. Potpuno neaktivna sesija i dalje završava pri ograničenju platforme za tihi poziv, koje prema zadanim postavkama iznosi 600 sekundi.

Upotrijebite službeni OpenAI SDK#

Proslijedite osnovni URL za WebSocket koji završava s /v1; SDK dodaje /realtime. Vrijednost model naziv je za kompatibilnost i ne odabire proizvod ThunderPhone. Odaberite proizvod u konfiguraciji sesije ili spremljenom agentu.

Ova provjera veze stvara ugrađenu Bolt sesiju, ispisuje događaje do prvog session.updated i zatvara se. Upotrijebite minimalni Python klijent za strujanje zvuka.

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

Zadržite postojeću obradu za dodavanje ulaznog zvuka, delta promjene zvuka odgovora, prekide, pozive funkcija, pogreške i pravilno zatvaranje utičnice. Ugrađene prilagođene funkcije izvršavaju se u vašem klijentu; njihove rezultate vratite putem protokola Realtime. Alati spremljenog agenta izvršavaju se na ThunderPhoneu.

Životni ciklus sesije i neuspjesi#

Jedan WebSocket predstavlja jedan poziv. Nevažeći ID agenta ili odbijena ugrađena konfiguracija proizvodi događaj error. Pričekajte session.updated prije nego što sesiju smatrate aktivnom. Navedite stvarne ulazne i izlazne formate te frekvencije uzorkovanja: nepodudaranje PCM frekvencije reproducira zvuk prebrzo ili presporo umjesto da proizvede pogrešku provjere valjanosti.

Nakon pokretanja sesije pravilno zatvorite utičnicu kada vaša aplikacija završi. Ugrađene sesije mogu upotrebljavati funkcije koje izvršava klijent. Sesije spremljenog agenta upotrebljavaju kompatibilne alate koje pokreće ThunderPhone i ne nude prijenos poziva ni unos putem tipkovnice.

Testirajte integraciju#

Počnite s minimalnim Python WAV klijentom i mono PCM16 WAV datotekom pri deklariranoj frekvenciji. Provjerite:

1. Poslužitelj prihvaća konfiguraciju i šalje session.updated.
2. Ulaz proizvodi događaje prijepisa i zvuka odgovora očekivanom brzinom.
3. Prekid i otkazivanje odgovora zaustavljaju preostali izlazni zvuk.
4. Rezultati ugrađene funkcije ili rezultati alata spremljenog agenta vraćaju se modelu.
5. Nevažeći unos proizvodi događaj error koji vaš klijent obrađuje.
6. Vaš klijent zatvara utičnicu, a poziv se pojavljuje u Povijesti poziva.

Referenca za Realtime WebSocket navodi prihvaćene događaje, formate zvuka, polja sesije i potpune primjere.

Cijena#

Realtime pozivi upotrebljavaju standardnu cijenu odabranog proizvoda po minuti. Omogućavanje delta promjena prijepisa uživo dodaje naknadu po minuti za cijelu sesiju; pogledajte Prijepise uživo za cijenu i Cjenik za cijene proizvoda.

POST /v1/realtime/sessions zaseban je upravljani LiveKit put. Stvara sobu i token s ograničenim opsegom za sudionika; nije potreban za izravnu WebSocket vezu.

Za integracije s okvirima pogledajte Upotreba ThunderPhonea iz Pipecata i Upotreba ThunderPhonea s LiveKit Agents.