Używaj ThunderPhone z klientami OpenAI Realtime

Skieruj klienta serwerowego zgodnego z OpenAI Realtime do ThunderPhone, używając zapisanego agenta lub wbudowanej konfiguracji sesji.

ThunderPhone implementuje wybrany podzbiór modelu zdarzeń OpenAI Realtime. Istniejący klient po stronie serwera może zachować przepływ zdarzeń WebSocket, audio, sesji i odpowiedzi podczas korzystania z agenta głosowego ThunderPhone.

Przed połączeniem#

Potrzebujesz tajnego klucza API organizacji ThunderPhone oraz środowiska uruchomieniowego serwera, które może otwierać połączenia WebSocket. Nie łącz się z kodu przeglądarki ani nie ujawniaj klucza przeglądarce. Aby użyć zapisanego agenta, najpierw go wdroż i skopiuj jego numeryczny identyfikator agenta.

Połącz się z:

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

Uwierzytelnij aktualizację połączenia WebSocket z serwera:

Authorization: Bearer sk_live_YOUR_API_KEY

Uwierzytelnianie za pomocą parametrów zapytania jest dostępne dla klientów, które nie mogą ustawiać nagłówków uzgadniania połączenia, ale adresy URL łatwiej trafiają do dzienników.

Wybierz właściciela konfiguracji#

Zapisany agent#

Połącz się z wdrożonym identyfikatorem agenta:

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

Agent uruchamia się podczas łączenia gniazda. Jego powitanie pozostaje dostępne, ale Realtime wyłącza wypowiadane sprawdzenia ciszy oraz pomija transfer_call i send_keypad_input. Pozostałe zgodne narzędzia działają w ThunderPhone. Nie wysyłaj wbudowanych instrukcji ani narzędzi wykonywanych przez klienta w tym trybie.

Ustaw formaty audio transmisji przed uruchomieniem agenta za pomocą parametrów zapytania input_audio_format, output_audio_format, input_rate i output_rate. Po połączeniu nie możesz zmienić zapisanej konfiguracji ani formatów audio.

Sesja wbudowana#

Bez agent_id poczekaj na session.created, a następnie wyślij 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"
    }
  }
}

Pierwsza zaakceptowana aktualizacja inicjuje połączenie. session.updated oznacza, że sesja jest aktywna. Po tym momencie nie można zmieniać instrukcji, głosu, produktu, narzędzi ani formatów audio.

Sesje wbudowane nie mają automatycznego powitania ani wypowiadanych sprawdzeń ciszy. Aby agent odezwał się pierwszy, dodaj wiadomość systemową lub użytkownika i wyślij response.create. Całkowicie bezczynna sesja nadal kończy się po osiągnięciu limitu cichego połączenia platformy, który domyślnie wynosi 600 sekund.

Użyj oficjalnego SDK OpenAI#

Przekaż bazowy adres URL WebSocket kończący się na /v1; SDK dodaje /realtime. Wartość model jest nazwą zgodności i nie wybiera produktu ThunderPhone. Wybierz produkt w konfiguracji sesji lub zapisanym agencie.

To sprawdzenie połączenia tworzy wbudowaną sesję Bolt, drukuje zdarzenia do pierwszego session.updated, a następnie zamyka połączenie. Użyj minimalnego klienta Python do strumieniowania dźwięku.

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

Zachowaj istniejącą obsługę dodawania wejściowego dźwięku, delt dźwięku odpowiedzi, przerwań, wywołań funkcji, błędów i prawidłowego zamykania gniazda. Wbudowane funkcje niestandardowe są wykonywane w kliencie; zwracaj ich wyniki przez protokół Realtime. Narzędzia zapisanego agenta są wykonywane w ThunderPhone.

Cykl życia sesji i błędy#

Jeden WebSocket reprezentuje jedno połączenie. Nieprawidłowy identyfikator agenta lub odrzucona konfiguracja wbudowana powoduje zdarzenie error. Przed uznaniem sesji za aktywną poczekaj na session.updated. Określ rzeczywiste formaty wejściowe i wyjściowe oraz częstotliwości próbkowania: niezgodność częstotliwości PCM powoduje odtwarzanie dźwięku zbyt szybko lub zbyt wolno zamiast błędu walidacji.

Po rozpoczęciu sesji prawidłowo zamknij gniazdo, gdy aplikacja zakończy działanie. Sesje wbudowane mogą używać funkcji wykonywanych przez klienta. Sesje zapisanych agentów używają zgodnych narzędzi uruchamianych przez ThunderPhone i nie obsługują przekazywania połączeń ani wprowadzania danych z klawiatury.

Przetestuj integrację#

Zacznij od minimalnego klienta Python WAV i monofonicznego pliku WAV PCM16 z deklarowaną przez niego częstotliwością próbkowania. Sprawdź:

1. Serwer akceptuje konfigurację i wysyła session.updated.
2. Dane wejściowe generują zdarzenia transkrypcji i dźwięku odpowiedzi z oczekiwaną prędkością.
3. Przerwanie i anulowanie odpowiedzi zatrzymują pozostały dźwięk wyjściowy.
4. Wyniki funkcji wbudowanych lub narzędzi zapisanego agenta wracają do modelu.
5. Nieprawidłowe dane wejściowe generują zdarzenie error, które obsługuje klient.
6. Klient zamyka gniazdo, a połączenie pojawia się w Historii połączeń.

Dokumentacja WebSocket Realtime zawiera listę akceptowanych zdarzeń, formatów dźwięku, pól sesji i kompletne przykłady.

Koszt#

Połączenia Realtime korzystają ze standardowej stawki minutowej wybranego produktu. Włączenie delt transkrypcji na żywo dodaje dopłatę za minutę dla całej sesji; stawkę znajdziesz w Transkrypcjach na żywo, a stawki produktów w Cenniku.

POST /v1/realtime/sessions to osobna zarządzana ścieżka LiveKit. Tworzy pokój i token uczestnika o ograniczonym zakresie; nie jest wymagana do bezpośredniego połączenia WebSocket.

Informacje o integracjach z frameworkami znajdziesz w Używaj ThunderPhone z Pipecat oraz Używaj ThunderPhone z LiveKit Agents.