Користите ThunderPhone са OpenAI Realtime клијентима

Усмерите серверски клијент компатибилан са OpenAI Realtime ка ThunderPhone-у, користећи сачуваног агента или уграђену конфигурацију сесије.

ThunderPhone примењује усмерени подскуп OpenAI Realtime модела догађаја. Постојећи клијент на серверској страни може да задржи свој ток WebSocket, аудио, сесијских догађаја и догађаја одговора док користи ThunderPhone гласовног агента.

Пре повезивања#

Потребни су Вам тајни API кључ ThunderPhone организације и серверско окружење за извршавање које може да отвори WebSocket везе. Немојте се повезивати из кода у прегледачу нити излагати кључ прегледачу. Да бисте користили сачуваног агента, прво га примените и копирајте његов нумерички ID агента.

Повежите се на:

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

Потврдите аутентичност WebSocket надоградње са свог сервера:

Authorization: Bearer sk_live_YOUR_API_KEY

Аутентификација путем стринга упита постоји за клијенте који не могу да поставе заглавља при успостављању везе, али URL-ови лакше доспевају у евиденције.

Изаберите ко управља конфигурацијом#

Сачувани агент#

Повежите се помоћу ID-а примењеног агента:

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

Агент се покреће док се утичница повезује. Његов поздрав остаје доступан, али Realtime онемогућава његове говорне провере тишине и изоставља transfer_call и send_keypad_input. Друге компатибилне алатке покрећу се у ThunderPhone. Немојте слати уметнута упутства или алатке које извршава клијент у овом режиму.

Подесите аудио формат преноса пре покретања агента помоћу параметара упита input_audio_format, output_audio_format, input_rate и output_rate. Не можете променити сачувану конфигурацију или аудио формате након повезивања.

Уметнута сесија#

Без agent_id, сачекајте session.created, а затим пошаљите 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"
    }
  }
}

Прво прихваћено ажурирање обезбеђује позив. session.updated значи да је сесија активна. Упутства, глас, производ, алатке и аудио формати не могу се мењати након тог тренутка.

Уметнуте сесије немају аутоматски поздрав нити говорне провере тишине. Да би агент први проговорио, додајте системску или корисничку поруку и пошаљите response.create. Потпуно неактивна сесија се и даље завршава на ограничењу платформе за тихе позиве, које подразумевано износи 600 секунди.

Користите званични OpenAI SDK#

Проследите основни WebSocket URL који се завршава са /v1; SDK додаје /realtime. Вредност model је назив за компатибилност и не бира ThunderPhone производ. Изаберите производ у конфигурацији сесије или сачуваном агенту.

Ова провера везе креира уграђену Bolt сесију, исписује догађаје до првог session.updated и затвара се. Користите минимални Python клијент за стримовање звука.

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

Задржите постојеће руковање додавањем улазног звука, делтама излазног звука, прекидима, позивима функција, грешкама и чистим затварањем сокета. Уграђене прилагођене функције извршавају се у Вашем клијенту; њихове резултате вратите путем Realtime протокола. Алатке сачуваног агента извршавају се у ThunderPhone-у.

Животни циклус сесије и грешке#

Један WebSocket представља један позив. Неважећи ИД агента или одбијена уграђена конфигурација производи догађај error. Сачекајте session.updated пре него што сесију сматрате активном. Наведите стварне формате улаза и излаза и стопе узорковања: неусклађена PCM стопа репродукује звук пребрзо или преспоро уместо да произведе грешку валидације.

Када сесија почне, чисто затворите сокет када Ваша апликација заврши. Уграђене сесије могу користити функције које извршава клијент. Сесије сачуваног агента користе компатибилне алатке које покреће ThunderPhone и не нуде пренос позива нити унос путем тастатуре.

Тестирајте интеграцију#

Почните са минималним Python WAV клијентом и моно PCM16 WAV датотеком при њеној наведеној стопи. Проверите:

1. Сервер прихвата конфигурацију и шаље session.updated.
2. Улаз производи догађаје транскрипта и излазног звука очекиваном брзином.
3. Прекид и отказивање одговора заустављају преостали излазни звук.
4. Резултати уграђених функција или резултати алатки сачуваног агента враћају се моделу.
5. Неважећи улаз производи догађај error којим Ваш клијент рукује.
6. Ваш клијент затвара сокет, а позив се појављује у историји позива.

Референца за Realtime WebSocket наводи прихваћене догађаје, формате звука, поља сесије и потпуне примере.

Цена#

Realtime позиви користе уобичајену цену по минуту изабраног производа. Омогућавање делти транскрипта уживо додаје доплату по минуту за целу сесију; погледајте Транскрипти уживо за цену и Цене за цене производа.

POST /v1/realtime/sessions је засебна управљана LiveKit путања. Она креира собу и ограничени токен учесника; није потребна за директну WebSocket везу.

За интеграције са оквирима, погледајте Користите ThunderPhone из Pipecat-а и Користите ThunderPhone из LiveKit Agents-а.