מדריך ליכולות של ממשק API בזמן אמת

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

לפני שמתחילים

  • כדאי להכיר את המושגים העיקריים: אם עדיין לא עשיתם את זה, קודם כדאי לקרוא את המאמר תחילת העבודה עם Live API . במאמר הזה נסביר על העקרונות הבסיסיים של Live API, איך הוא עובד ועל גישות שונות להטמעה.
  • התנסות ב-Live API ב-AI Studio: מומלץ להתנסות ב-Live API ב-Google AI Studio לפני שמתחילים לפתח. כדי להשתמש ב-Live API ב-Google AI Studio, בוחרים באפשרות Stream (שידור).

השוואה בין מודלים

בטבלה הבאה מפורטים ההבדלים העיקריים בין המודלים של Gemini 3.1 Flash בגרסת טרום-השקה לבין Gemini 2.5 Flash בגרסת טרום-השקה:

תכונה ‫Gemini 3.1 Flash Live Preview גרסת טרום-השקה של Gemini 2.5 Flash Live
חשיבה משתמש ב-thinkingLevel כדי לשלוט בעומק החשיבה באמצעות הגדרות כמו minimal, low, medium ו-high. ברירת המחדל היא minimal כדי לבצע אופטימיזציה לזמן האחזור הנמוך ביותר. מידע נוסף על רמות ותקציבים הפרמטר הזה מגדיר למודל בכמה טוקנים להשתמש כשהוא חושב ויוצר את התשובה.thinkingBudget התכונה 'חשיבה דינמית' מופעלת כברירת מחדל. כדי להשבית, מגדירים את thinkingBudget להיות 0. מידע נוסף על רמות ותקציבים
קבלת תגובה אירוע יחיד בשרת יכול להכיל כמה חלקי תוכן בו-זמנית (לדוגמה, inlineData ותמליל). כדי למנוע מצב שבו תוכן לא יופיע, חשוב לוודא שהקוד מעבד את כל החלקים בכל אירוע. כל אירוע שרת מכיל רק חלק תוכן אחד. החלקים מועברים באירועים נפרדים.
תוכן של לקוחות ‫send_client_content נתמך רק כדי להזין את ההיסטוריה של ההקשר הראשוני (נדרשת הגדרה של initial_history_in_client_content בהגדרות הסשן). כדי לשלוח עדכוני טקסט במהלך השיחה, משתמשים במקום זאת בsend_realtime_input. send_client_content נתמך לאורך השיחה כדי לשלוח עדכוני תוכן מצטברים וליצור הקשר.
הפעלת כיסוי ברירת המחדל היא TURN_INCLUDES_AUDIO_ACTIVITY_AND_ALL_VIDEO. התור של המודל כולל פעילות אודיו שזוהתה וכל פריים של הסרטון. ברירת המחדל היא TURN_INCLUDES_ONLY_ACTIVITY. התור של המודל כולל רק את הפעילות שזוהתה.
VAD מותאם אישית (activity_start/activity_end) נתמך. משביתים את ה-VAD האוטומטי ושולחים הודעות activityStart ו-activityEnd באופן ידני כדי לשלוט בגבולות של כל תור. נתמך. משביתים את ה-VAD האוטומטי ושולחים הודעות activityStart ו-activityEnd באופן ידני כדי לשלוט בגבולות של כל תור.
הגדרה אוטומטית של VAD נתמך. מגדירים פרמטרים כמו start_of_speech_sensitivity, end_of_speech_sensitivity, prefix_padding_ms ו-silence_duration_ms. נתמך. מגדירים פרמטרים כמו start_of_speech_sensitivity, end_of_speech_sensitivity, prefix_padding_ms ו-silence_duration_ms.
קריאה אסינכרונית לפונקציה (behavior: NON_BLOCKING) לא נתמך. הפעלת פונקציות היא רציפה בלבד. המודל לא יתחיל להגיב עד שתשלחו את התשובה של הכלי. נתמך. כדי שהמודל ימשיך את האינטראקציה בזמן שהפונקציה פועלת, צריך להגדיר את behavior ל-NON_BLOCKING בהצהרת הפונקציה. אפשר לשלוט באופן שבו המודל מטפל בתשובות באמצעות הפרמטר scheduling (INTERRUPT,‏ WHEN_IDLE או SILENT).
סינון אודיו יזום לא נתמך נתמך. כשההגדרה הזו מופעלת, המודל יכול להחליט באופן יזום לא להגיב אם תוכן הקלט לא רלוונטי. מגדירים את proactive_audio ל-true בתצורה proactivity (נדרש v1beta).
שיחה מותאמת-רגש לא נתמך נתמך. סגנון התשובה של המודל מותאם לסגנון הביטוי ולטון של הקלט. מגדירים את enable_affective_dialog ל-true בהגדרות הסשן (נדרש v1beta).

כדי לעבור מ-Gemini 2.5 Flash Live ל-Gemini 3.1 Flash Live, אפשר לעיין במדריך להעברת נתונים.

יצירת חיבור

בדוגמה הבאה מוצג איך ליצור חיבור באמצעות מפתח API:

Python

import asyncio
from google import genai

client = genai.Client()

model = "gemini-3.1-flash-live-preview"
config = {"response_modalities": ["AUDIO"]}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        print("Session started")
        # Send content...

if __name__ == "__main__":
    asyncio.run(main())

JavaScript

import { GoogleGenAI, Modality } from '@google/genai';

const ai = new GoogleGenAI({});
const model = 'gemini-3.1-flash-live-preview';
const config = { responseModalities: [Modality.AUDIO] };

async function main() {

  const session = await ai.live.connect({
    model: model,
    callbacks: {
      onopen: function () {
        console.debug('Opened');
      },
      onmessage: function (message) {
        console.debug(message);
      },
      onerror: function (e) {
        console.debug('Error:', e.message);
      },
      onclose: function (e) {
        console.debug('Close:', e.reason);
      },
    },
    config: config,
  });

  console.debug("Session started");