Brug ThunderPhone med OpenAI Realtime-klienter

Peg en OpenAI Realtime-kompatibel serverklient mod ThunderPhone ved hjælp af enten en gemt agent eller integreret sessionskonfiguration.

ThunderPhone implementerer et fokuseret undersæt af OpenAI Realtime-hændelsesmodellen. En eksisterende serversideklient kan beholde sit WebSocket-, lyd-, session- og svarhændelsesflow, mens den bruger en ThunderPhone-stemmeagent.

Før du opretter forbindelse#

Du skal bruge en hemmelig API-nøgle til en ThunderPhone-organisation og et servermiljø, der kan åbne WebSockets. Opret ikke forbindelse fra browserkode, og eksponer ikke nøglen for en browser. Hvis du vil bruge en gemt agent, skal du først udrulle den og kopiere dens numeriske agent-id.

Opret forbindelse til:

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

Godkend WebSocket-opgraderingen fra din server:

Authorization: Bearer sk_live_YOUR_API_KEY

Godkendelse via forespørgselsstreng findes til klienter, der ikke kan angive handshake- headere, men URL'er er lettere at lække i logfiler.

Vælg, hvem der ejer konfigurationen#

Gemt agent#

Opret forbindelse med det udrullede agent-id:

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

Agenten starter, mens soklen opretter forbindelse. Dens hilsen er fortsat tilgængelig, men Realtime deaktiverer dens talte indtjekninger ved stilhed og udelader transfer_call og send_keypad_input. Andre kompatible værktøjer kører på ThunderPhone. Send ikke indlejrede instruktioner eller værktøjer, der køres af klienten, i denne tilstand.

Angiv lyd på forbindelsen, før agenten starter, med forespørgselsparametrene input_audio_format, output_audio_format, input_rate og output_rate. Du kan ikke ændre den gemte konfiguration eller lydformaterne efter forbindelsen er oprettet.

Indlejret session#

Uden agent_id skal du vente på session.created og derefter sende 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 accepterede opdatering klargør opkaldet. session.updated betyder, at sessionen er aktiv. Instruktioner, stemme, produkt, værktøjer og lydformater kan ikke ændres efter det tidspunkt.

Indlejrede sessioner har ingen automatisk hilsen eller talte indtjekninger ved stilhed. Hvis agenten skal tale først, skal du tilføje en system- eller brugermeddelelse og sende response.create. En helt inaktiv session afsluttes stadig ved platformens grænse for tavse opkald, som som standard er 600 sekunder.

Brug det officielle OpenAI SDK#

Angiv en WebSocket-base-URL, der slutter med /v1; SDK'et tilføjer /realtime. Værdien model er et kompatibilitetsnavn og vælger ikke ThunderPhone-produktet. Vælg produktet i sessionskonfigurationen eller den gemte agent.

Denne forbindelseskontrol opretter en indlejret Bolt-session, udskriver hændelser indtil den første session.updated og lukker derefter. Brug den minimale Python-klient til at streame 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 din eksisterende håndtering af tilføjelse af inputlyd, deltaer for responslyd, afbrydelser, funktionskald, fejl og ren lukning af socketforbindelsen. Indlejrede brugerdefinerede funktioner udføres i din klient; returner deres resultater gennem Realtime-protokollen. Værktøjer for gemte agenter udføres på ThunderPhone.

Sessionens livscyklus og fejl#

Én WebSocket repræsenterer ét opkald. Et ugyldigt agent-id eller en afvist indlejret konfiguration producerer en error-hændelse. Vent på session.updated, før du betragter sessionen som aktiv. Angiv de faktiske input- og outputformater samt samplerater: En PCM-samplerate, der ikke matcher, afspiller lyd for hurtigt eller for langsomt i stedet for at producere en valideringsfejl.

Når sessionen er startet, skal du lukke socketforbindelsen korrekt, når din applikation er færdig. Indlejrede sessioner kan bruge funktioner, der udføres i klienten. Sessioner med gemte agenter bruger kompatible værktøjer, der køres af ThunderPhone, og tilbyder ikke viderestilling eller tastaturinput.

Test integrationen#

Start med den minimale Python WAV-klient og en mono PCM16 WAV ved dens angivne samplerate. Kontrollér:

1. Serveren accepterer konfigurationen og sender session.updated.
2. Input producerer hændelser for transskription og responslyd ved den forventede hastighed.
3. Afbrydelse og annullering af respons stopper resterende outputlyd.
4. Resultater fra indlejrede funktioner eller værktøjer for gemte agenter returneres til modellen.
5. Ugyldigt input producerer en error-hændelse, som din klient håndterer.
6. Din klient lukker socketforbindelsen, og opkaldet vises i Opkaldshistorik.

Realtime WebSocket-referencen viser de accepterede hændelser, lydformater, sessionsfelter og komplette eksempler.

Pris#

Realtime-opkald bruger det valgte produkts normale minutpris. Aktivering af live-transskriptionsdeltaer tilføjer et tillæg pr. minut for hele sessionen; se Live-transskriptioner for prisen og Priser for produktpriser.

POST /v1/realtime/sessions er en separat administreret LiveKit-sti. Den opretter et rum og et afgrænset deltagertoken; den er ikke påkrævet for en direkte WebSocket-forbindelse.

For framework-integrationer, se Brug ThunderPhone fra Pipecat og Brug ThunderPhone fra LiveKit Agents.