השתמשו ב-ThunderPhone עם לקוחות OpenAI Realtime

הפנו לקוח שרת התואם ל-OpenAI Realtime אל ThunderPhone, באמצעות סוכן שמור או הגדרת סשן מוטבעת.

ThunderPhone מיישם תת-קבוצה ממוקדת של מודל האירועים OpenAI Realtime. לקוח קיים בצד השרת יכול לשמור על זרימת אירועי ה-WebSocket, האודיו, ההפעלה והתגובה שלו תוך שימוש בסוכן קולי של ThunderPhone.

לפני החיבור#

נדרש מפתח API סודי של ארגון ThunderPhone וסביבת זמן ריצה בשרת שיכולה לפתוח חיבורי WebSocket. אל תתחברו מקוד דפדפן ואל תחשפו את המפתח לדפדפן. כדי להשתמש בסוכן שמור, פרסמו אותו תחילה והעתיקו את מזהה הסוכן המספרי שלו.

התחברו אל:

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

אמתו את שדרוג ה-WebSocket מהשרת שלכם:

Authorization: Bearer sk_live_YOUR_API_KEY

אימות באמצעות מחרוזת שאילתה זמין ללקוחות שאינם יכולים להגדיר כותרות לחיצת יד, אך כתובות URL נוטות יותר לדלוף ליומנים.

בחרו מי שולט בתצורה#

סוכן שמור#

התחברו באמצעות מזהה הסוכן שפורסם:

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 שניות כברירת מחדל.

השתמשו ב-SDK הרשמי של OpenAI#

העבירו כתובת בסיס של WebSocket המסתיימת ב-/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 ואינן מציעות העברה או קלט מקשים.

בדקו את האינטגרציה#

התחילו עם לקוח WAV המינימלי ב-Python ועם WAV מסוג PCM16 חד-ערוצי בקצב המוצהר שלו. ודאו:

1. השרת מקבל את התצורה ושולח session.updated.
2. הקלט מפיק אירועי תמלול ואודיו תגובה במהירות הצפויה.
3. הפרעה וביטול תגובה עוצרים את יתרת אודיו הפלט.
4. תוצאות של פונקציות מוטמעות או תוצאות של כלים בסוכן שמור חוזרות למודל.
5. קלט לא תקין מפיק אירוע error שהלקוח שלכם מטפל בו.
6. הלקוח שלכם סוגר את השקע והשיחה מופיעה בהיסטוריית השיחות.

מדריך העזר של Realtime WebSocket מפרט את האירועים המתקבלים, תבניות האודיו, שדות ההפעלה ודוגמאות מלאות.

עלות#

שיחות Realtime משתמשות בתעריף הרגיל לדקה של המוצר שנבחר. הפעלת דלתאות תמלול בזמן אמת מוסיפה תוספת תעריף לדקה עבור ההפעלה כולה; ראו תמלולים בזמן אמת עבור התעריף ותמחור עבור תעריפי המוצרים.

POST /v1/realtime/sessions הוא נתיב LiveKit מנוהל ונפרד. הוא יוצר חדר ואסימון משתתף מוגבל היקף; הוא אינו נדרש לחיבור WebSocket ישיר.

לאינטגרציות עם מסגרות עבודה, ראו שימוש ב-ThunderPhone מ-Pipecat ושימוש ב-ThunderPhone מ-LiveKit Agents.