Bruk ThunderPhone med OpenAI Realtime-klienter

Koble en OpenAI Realtime-kompatibel serverklient til ThunderPhone ved å bruke enten en lagret agent eller innebygd øktkonfigurasjon.

ThunderPhone implementerer et fokusert delsett av OpenAI Realtime-hendelsesmodellen. En eksisterende klientside på serveren kan beholde flyten for WebSocket-, lyd-, økt- og svarhendelser mens den bruker en ThunderPhone-stemmeagent.

Før du kobler til#

Du trenger en hemmelig API-nøkkel for ThunderPhone-organisasjonen og et servermiljø som kan åpne WebSockets. Ikke koble til fra nettleserkode eller eksponer nøkkelen for en nettleser. Hvis du vil bruke en lagret agent, må du først distribuere den og kopiere den numeriske agent-ID-en.

Koble til:

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

Autentiser WebSocket-oppgraderingen fra serveren din:

Authorization: Bearer sk_live_YOUR_API_KEY

Autentisering med spørringsstreng finnes for klienter som ikke kan angi headers for handshake, men URL-er er enklere å lekke i logger.

Velg hvem som eier konfigurasjonen#

Lagret agent#

Koble til med den distribuerte agent-ID-en:

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

Agenten starter mens socketen kobler til. Hilsenen er fortsatt tilgjengelig, men Realtime deaktiverer talte sjekkpunkter ved stillhet og utelater transfer_call og send_keypad_input. Andre kompatible verktøy kjører på ThunderPhone. Ikke send innebygde instruksjoner eller verktøy som kjøres av klienten i denne modusen.

Angi lydformatene for overføringen før agenten starter med spørringsparameterne input_audio_format, output_audio_format, input_rate og output_rate. Du kan ikke endre den lagrede konfigurasjonen eller lydformatene etter tilkobling.

Innebygd økt#

Uten agent_id venter du på session.created, og sender deretter 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"
    }
  }
}

Den første godkjente oppdateringen klargjør samtalen. session.updated betyr at økten er aktiv. Instruksjoner, stemme, produkt, verktøy og lydformater kan ikke endres etter dette tidspunktet.

Innebygde økter har ingen automatisk hilsen eller talte sjekkpunkter ved stillhet. For å la agenten snakke først legger du til en system- eller brukermelding og sender response.create. En helt inaktiv økt avsluttes fortsatt ved plattformens grense for stille samtaler, 600 sekunder som standard.

Bruk det offisielle OpenAI SDK-et#

Send en WebSocket-base-URL som slutter på /v1; SDK-et legger til /realtime. Verdien for model er et kompatibilitetsnavn og velger ikke ThunderPhone-produktet. Velg produktet i øktkonfigurasjonen eller den lagrede agenten.

Denne tilkoblingskontrollen oppretter en innebygd Bolt-økt, skriver ut hendelser til den første session.updated, og lukker tilkoblingen. Bruk den minimale Python- klienten til å strømme lyd.

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

Behold eksisterende håndtering av tillegg av inndatalyd, deltaer for responslyd, avbrytelser, funksjonskall, feil og ryddig lukking av socketen. Innebygde egendefinerte funksjoner kjører i klienten din; returner resultatene gjennom Realtime- protokollen. Verktøy for lagrede agenter kjører på ThunderPhone.

Øktlivssyklus og feil#

Én WebSocket representerer én samtale. En ugyldig agent-ID eller avvist innebygd konfigurasjon utløser en error-hendelse. Vent på session.updated før du behandler økten som aktiv. Oppgi de faktiske inndata- og utdataformatene og samplingsfrekvensene: En PCM-frekvens som ikke samsvarer, spiller av lyd for raskt eller for sakte i stedet for å utløse en valideringsfeil.

Etter at økten starter, lukker du socketen ryddig når applikasjonen er ferdig. Innebygde økter kan bruke funksjoner som kjøres av klienten. Økter med lagrede agenter bruker kompatible verktøy som kjøres av ThunderPhone, og tilbyr ikke overføring eller tastaturinndata.

Test integrasjonen#

Start med den minimale Python WAV-klienten og en mono PCM16 WAV med den angitte frekvensen. Bekreft:

1. Serveren godtar konfigurasjonen og sender session.updated.
2. Inndata produserer transkripsjons- og responslydhendelser med forventet hastighet.
3. Avbrytelse og kansellering av respons stopper gjenværende utdata-lyd.
4. Resultater fra innebygde funksjoner eller verktøy for lagrede agenter returneres til modellen.
5. Ugyldige inndata produserer en error-hendelse som klienten din håndterer.
6. Klienten din lukker socketen, og samtalen vises i Samtalehistorikk.

Realtime WebSocket-referansen viser godkjente hendelser, lydformater, øktfelt og komplette eksempler.

Kostnad#

Realtime-samtaler bruker det valgte produktets vanlige pris per minutt. Aktivering av direkte transkripsjonsdeltaer legger til et pristillegg per minutt for hele økten; se Direkte transkripsjoner for pris og Priser for produktpriser.

POST /v1/realtime/sessions er en separat administrert LiveKit-bane. Den oppretter et rom og et avgrenset deltaker-token; den er ikke nødvendig for en direkte WebSocket- tilkobling.

For rammeverksintegrasjoner, se Bruk ThunderPhone fra Pipecat og Bruk ThunderPhone fra LiveKit Agents.