Live API - WebSockets API reference

‫Live API הוא API עם שמירת מצב שמשתמש ב-WebSockets. בקטע הזה מופיעים פרטים נוספים על WebSockets API.

סשנים

חיבור WebSocket יוצר סשן בין הלקוח לבין שרת Gemini. אחרי שהלקוח יוזם חיבור חדש, הסשן יכול להעביר הודעות עם השרת כדי:

  • שליחת טקסט, אודיו או סרטון לשרת Gemini.
  • לקבל בקשות לאודיו, לטקסט או לבקשות להפעלת פונקציה משרת Gemini.

חיבור WebSocket

כדי להתחיל סשן, מתחברים לנקודת הקצה הזו של websocket:

‫
wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent

הגדרות הסשן

ההודעה הראשונית שנשלחת אחרי יצירת חיבור WebSocket מגדירה את הגדרות הסשן, שכוללות את המודל, פרמטרים של יצירה, הוראות מערכת וכלים.

אי אפשר לעדכן את ההגדרה כשהחיבור פתוח. עם זאת, אפשר לשנות את פרמטרים ההגדרה, למעט המודל, כשמשהים וממשיכים את השימוש באמצעות מנגנון חידוש הסשן.

דוגמה להגדרה: שימו לב שהאותיות הגדולות והקטנות בשמות ב-SDK עשויות להיות שונות. כאן אפשר למצוא את אפשרויות ההגדרה של Python SDK.


{
  "model": string,
  "generationConfig": {
    "candidateCount": integer,
    "maxOutputTokens": integer,
    "temperature": number,
    "topP": number,
    "topK": integer,
    "presencePenalty": number,
    "frequencyPenalty": number,
    "responseModalities": [string],
    "speechConfig": object,
    "mediaResolution": object,
    "translationConfig": object
  },
  "systemInstruction": string,
  "tools": [object]
}

מידע נוסף על שדה ה-API זמין במאמר בנושא generationConfig.

שליחת הודעות

כדי להחליף הודעות דרך חיבור WebSocket, הלקוח צריך לשלוח אובייקט JSON דרך חיבור WebSocket פתוח. אובייקט ה-JSON חייב להכיל בדיוק אחד מהשדות מתוך קבוצת האובייקטים הבאה:


{
  "setup": BidiGenerateContentSetup,
  "clientContent": BidiGenerateContentClientContent,
  "realtimeInput": BidiGenerateContentRealtimeInput,
  "toolResponse": BidiGenerateContentToolResponse
}

הודעות נתמכות לעסק

בטבלה הבאה מפורטות הודעות הלקוח הנתמכות:

שליחת הודעה תיאור
BidiGenerateContentSetup הגדרת הסשן שתישלח בהודעה הראשונה
BidiGenerateContentClientContent עדכון מצטבר של תוכן השיחה הנוכחית, שנשלח מהלקוח
BidiGenerateContentRealtimeInput קלט אודיו, וידאו או טקסט בזמן אמת
BidiGenerateContentToolResponse תגובה ל-ToolCallMessage שהתקבלה מהשרת

קבלת הודעות

כדי לקבל הודעות מ-Gemini, צריך להאזין לאירוע 'message' של WebSocket, ואז לנתח את התוצאה בהתאם להגדרה של הודעות השרת הנתמכות.

תוכלו לעיין במקורות המידע הבאים:

async with client.aio.live.connect(model='...', config=config) as session:
    await session.send(input='Hello world!', end_of_turn=True)
    async for message in session.receive():
        print(message)

יכול להיות שהודעות מהשרת יכללו את השדה usageMetadata, אבל הן יכללו בדיוק אחד מהשדות האחרים בהודעה BidiGenerateContentServerMessage. (האיחוד messageType לא מופיע ב-JSON, ולכן השדה יופיע ברמה העליונה של ההודעה).

הודעות ואירועים

ActivityEnd

בסוג הזה אין שדות.

מסמן את סוף פעילות המשתמש.

ActivityHandling

הדרכים השונות לטיפול בפעילות המשתמשים.

טיפוסים בני מנייה (enum)
ACTIVITY_HANDLING_UNSPECIFIED אם לא מצוין ערך, ההתנהגות שמוגדרת כברירת מחדל היא START_OF_ACTIVITY_INTERRUPTS.
START_OF_ACTIVITY_INTERRUPTS אם הערך הוא True, התחלת הפעילות תקטע את התשובה של המודל (נקרא גם "פריצה לשיחה"). התשובה הנוכחית של המודל תיקטע ברגע ההפרעה. זו התנהגות ברירת המחדל.
NO_INTERRUPTION התשובה של המודל לא תיקטע.

ActivityStart

בסוג הזה אין שדות.

סימון תחילת פעילות המשתמש.

AudioTranscriptionConfig

הגדרת תמלול האודיו.

שדות
languageCodes[]

string

אופציונלי. קודי שפה בתקן BCP-47 שמספקים רמזים לגבי השפות שמופיעות באודיו. אם לא מציינים שפה או אם השדה ריק, המערכת תבצע זיהוי שפה אוטומטי.
customVocabulary[]

string

אופציונלי. רשימה של ביטויים מותאמים אישית באוצר המילים, כדי להטות את מודל זיהוי הדיבור לזיהוי מונחים ספציפיים (שמות מוצרים, שמות עצם, ז'רגון).
wordTimestamp

bool

אופציונלי. המדיניות מגדירה יצירה של חותמות זמן ברמת המילה.
diarization

bool

אופציונלי. הגדרת חלוקת קובץ האודיו לפי דוברים.
mode

Mode

אופציונלי. ההגדרה קובעת את מצב התמלול. ערכים נתמכים: VERBATIM, ‏ SMART. אם לא מציינים ערך, ברירת המחדל היא תמלול VERBATIM. במצב SMART, המודל מסיר הססנות (מחיקת מילות מילוי, חזרות והתחלות שגויות), מבצע ניקוי דקדוקי קל, מבצע עיצוב אוטומטי (פסקאות, תבליטים, רשימות ממוספרות) ועריכות קלות של המשתמש (תיקונים עצמיים בשורה). אי אפשר להשתמש בחותמות זמן ובחלוקה לדוברים במצב SMART.

מצב

מצב תמלול.

טיפוסים בני מנייה (enum)
MODE_UNSPECIFIED מצב תמלול לא מוגדר.
VERBATIM מצב תמלול מילולי.
SMART מצב תמלול חכם.

AutomaticActivityDetection

ההגדרה קובעת את אפשרויות הזיהוי האוטומטי של פעילות.

שדות
disabled

bool

אופציונלי. אם ההגדרה מופעלת (ברירת המחדל), דיבור וטקסט שזוהו נספרים כפעילות. אם ההגדרה מושבתת, הלקוח צריך לשלוח אותות פעילות.
startOfSpeechSensitivity

StartSensitivity

אופציונלי. קובע את הסבירות לזיהוי דיבור.
prefixPaddingMs

int32

אופציונלי. המשך הנדרש של הדיבור שזוהה לפני שמתחילים לתמלל. ככל שהערך הזה נמוך יותר, כך זיהוי תחילת הדיבור רגיש יותר, ואפשר לזהות דיבור קצר יותר. עם זאת, זה גם מגדיל את הסבירות לתוצאות חיוביות כוזבות.
endOfSpeechSensitivity

EndSensitivity

אופציונלי. קובע את הסבירות לכך שהדיבור שזוהה הסתיים.
silenceDurationMs

int32

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

BidiGenerateContentClientContent

עדכון מצטבר של השיחה הנוכחית שמועבר מהלקוח. כל התוכן שמופיע כאן מצורף להיסטוריית השיחות ללא תנאי ומשמש כחלק מהפרומפט למודל ליצירת תוכן.

הודעה כאן תקטע כל יצירת תוכן נוכחית של מודל.

שדות
turns[]

Content

אופציונלי. התוכן שמצורף לשיחה הנוכחית עם המודל.

בשאלות עם תשובה אחת, מדובר במופע יחיד. בשאילתות מרובות, זהו שדה חוזר שמכיל את היסטוריית השיחות ואת הבקשה האחרונה.
turnComplete

bool

אופציונלי. אם הערך הוא true, המשמעות היא שיצירת התוכן בשרת צריכה להתחיל עם ההנחיה שנצברה עד עכשיו. אחרת, השרת ימתין להודעות נוספות לפני שיתחיל ליצור את התוכן.

BidiGenerateContentRealtimeInput

קלט מהמשתמש שנשלח בזמן אמת.

המודליות השונות (אודיו, וידאו וטקסט) מטופלות כזרמים מקבילים. אין ערובה לסדר של הנתונים בזרמים האלה.

יש כמה הבדלים בין BidiGenerateContentClientContent לבין:

  • אפשר לשלוח אותם ברציפות בלי להפריע ליצירת המודל.
  • אם יש צורך לשלב נתונים שמופיעים לסירוגין ב- BidiGenerateContentClientContent וב- BidiGenerateContentRealtimeInput, השרת ינסה לבצע אופטימיזציה כדי להשיג את התגובה הטובה ביותר, אבל אין ערובה לכך.
  • סוף התור לא מצוין באופן מפורש, אלא נגזר מפעילות המשתמש (לדוגמה, סוף הדיבור).
  • גם לפני סוף התור, הנתונים מעובדים באופן מצטבר כדי לייעל את תחילת התגובה של המודל.
שדות
mediaChunks[]

Blob

אופציונלי. נתוני בייטים מוטבעים לקלט מדיה. אין תמיכה בכמה ערכים של mediaChunks, המערכת תתעלם מכל הערכים מלבד הראשון.

יצא משימוש: במקומה יש להשתמש ב-audio, ב-video או ב-text.
audio

Blob

אופציונלי. הם יוצרים את זרם קלט האודיו בזמן אמת.
video

Blob

אופציונלי. הם יוצרים את זרם קלט הווידאו בזמן אמת.
activityStart

ActivityStart

אופציונלי. סימון תחילת פעילות המשתמש. אפשר לשלוח את הנתונים האלה רק אם השבתתם את הזיהוי האוטומטי של פעילות (כלומר, בצד השרת).
activityEnd

ActivityEnd

אופציונלי. מסמן את סוף פעילות המשתמש. אפשר לשלוח את הנתונים האלה רק אם השבתתם את הזיהוי האוטומטי של פעילות (כלומר, בצד השרת).
mediaResolution

MediaResolution

אופציונלי. הרזולוציה של המדיה שבה רוצים להשתמש. אם לא מציינים ערך, המערכת משתמשת ב-setup.generationConfig.mediaResolution או בערך ברירת מחדל אם ההגדרה לא מסופקת.
audioStreamEnd

bool

אופציונלי. מציין שסטרימינג האודיו הסתיים, למשל כי המיקרופון כובה.

הנתונים האלה צריכים להישלח רק כשההגדרה 'זיהוי אוטומטי של פעילות' מופעלת (זו הגדרת ברירת המחדל).

הלקוח יכול לפתוח מחדש את השיחה על ידי שליחת הודעה קולית.
text

string

אופציונלי. הם יוצרים את זרם הקלט של הטקסט בזמן אמת.

BidiGenerateContentServerContent

עדכון מצטבר של השרת שנוצר על ידי המודל בתגובה להודעות מהלקוח.

התוכן נוצר במהירות האפשרית, ולא בזמן אמת. יכול להיות שהלקוחות יבחרו לשמור את הנתונים במאגר זמני ולהפעיל אותם בזמן אמת.

שדות
generationComplete

bool

פלט בלבד. אם הערך הוא True, המשמעות היא שהמודל סיים את הגנרציה.

אם המודל מופסק במהלך יצירה, לא תהיה הודעה מסוג 'generation_complete' בתור שהופסק, והוא יעבור דרך 'interrupted > turn_complete'.

כשהמודל מניח הפעלה בזמן אמת, יהיה עיכוב בין generation_complete לבין turn_complete, כי המודל יחכה שההפעלה תסתיים.
turnComplete

bool

פלט בלבד. אם הערך הוא True, המודל סיים את התור שלו. היצירה תתחיל רק בתגובה להודעות נוספות של הלקוח. הערה: כשמופעל דיווח על סטטוס ההפעלה, הנתון הזה מופק רק כשסטטוס ההפעלה מציין שההפעלה הסתיימה. המערכת תתעלם מסטטוס ההפעלה העתידי של אותה גנרציה.
interrupted

bool

פלט בלבד. אם הערך הוא true, המשמעות היא שהודעה של לקוח קטעה את יצירת המודל הנוכחית. אם הלקוח מפעיל את התוכן בזמן אמת, זהו אות טוב להפסיק ולרוקן את תור ההפעלה הנוכחי.
groundingMetadata

GroundingMetadata

פלט בלבד. מטא-נתונים של ביסוס התוכן שנוצר.
inputTranscription

BidiGenerateContentTranscription

פלט בלבד. תמלול קלט האודיו. התמלול נשלח בנפרד מההודעות האחרות בשרת, ואין הבטחה לגבי הסדר.
interimInputTranscription

BidiGenerateContentTranscription

פלט בלבד. תמלול עם זמן אחזור נמוך מתעדכן בזמן שהמשתמש מדבר. השדה הזה מתעדכן לעיתים קרובות.
outputTranscription

BidiGenerateContentTranscription

פלט בלבד. תמלול האודיו. התמלילים האלה הם חלק מהפלט של הדור בשרת. תמליל הפלט האחרון של התור הזה נשלח לפני generationComplete או interrupted, שאחריהם מופיע turnComplete. אין סדר מדויק מובטח בין התמלילים לבין פלט אחר של modelTurn, אבל השרת מנסה לשלוח את התמלילים קרוב לפלט האודיו התואם.
urlContextMetadata

UrlContextMetadata
waitingForInput

bool

פלט בלבד. אם הערך הוא true, המשמעות היא שהמודל לא יוצר תוכן כי הוא ממתין לקלט נוסף מהמשתמש, למשל כי הוא מצפה שהמשתמש ימשיך לדבר.
interactionStatus

InteractionStatus

פלט בלבד. הסטטוס הנוכחי של הפעילות בסשן הפעיל. תמיד נשלח לצד turnComplete.
modelTurn

Content

פלט בלבד. התוכן שהמודל יצר כחלק מהשיחה הנוכחית עם המשתמש.

BidiGenerateContentServerMessage

הודעת התגובה לקריאה של BidiGenerateContent.

שדות
usageMetadata

UsageMetadata

פלט בלבד. מטא-נתונים של השימוש לגבי התשובות.
voiceActivity

VoiceActivity

פלט בלבד. זוהתה פעילות קולית בזרם האודיו.
שדה איחוד messageType. סוג ההודעה. הערך messageType יכול להיות רק אחד מהבאים:
setupComplete

BidiGenerateContentSetupComplete

פלט בלבד. ההודעה נשלחת בתגובה להודעה BidiGenerateContentSetup מהלקוח כשההגדרה מסתיימת.
serverContent

BidiGenerateContentServerContent

פלט בלבד. תוכן שנוצר על ידי המודל בתגובה להודעות של לקוחות.
toolCall

BidiGenerateContentToolCall

פלט בלבד. בקשה מהלקוח להפעיל את functionCalls ולהחזיר את התשובות עם הערכים התואמים של id.
toolCallCancellation

BidiGenerateContentToolCallCancellation

פלט בלבד. הודעה ללקוח שצריך לבטל את ToolCallMessage שהונפק בעבר עם ids שצוינו.
goAway

GoAway

פלט בלבד. הודעה שהשרת יתנתק בקרוב.
sessionResumptionUpdate

SessionResumptionUpdate

פלט בלבד. עדכון של מצב חידוש הסשן.

BidiGenerateContentSetup

ההודעה שתישלח בBidiGenerateContentClientMessage הראשון (ורק בBidiGenerateContentClientMessage הראשון). מכיל הגדרה שתחול למשך ה-RPC של הסטרימינג.

הלקוחות צריכים להמתין להודעה BidiGenerateContentSetupComplete לפני שליחת הודעות נוספות.

שדות
model

string

חובה. שם המשאב של המודל. השם הזה משמש כמזהה לשימוש במודל.

פורמט: models/{model}
generationConfig

GenerationConfig

אופציונלי. הגדרות ליצירה.

השדות הבאים לא נתמכים:

  • responseLogprobs
  • responseMimeType
  • logprobs
  • responseSchema
  • responseJsonSchema
  • stopSequence
  • skipResponseCache
  • routingConfig
  • audioTimestamp
systemInstruction

Content

אופציונלי. ההוראות למודל שסופקו על ידי המשתמש.

הערה: צריך להשתמש רק בטקסט בחלקים, והתוכן בכל חלק יהיה בפסקה נפרדת.
tools[]

Tool

אופציונלי. רשימה של Tools שהמודל יכול להשתמש בהם כדי ליצור את התשובה הבאה.

Tool הוא קטע קוד שמאפשר למערכת ליצור אינטראקציה עם מערכות חיצוניות כדי לבצע פעולה או סדרת פעולות מחוץ לידע ולתחום של המודל.
realtimeInputConfig

RealtimeInputConfig

אופציונלי. הגדרת הטיפול בקלט בזמן אמת.
sessionResumption

SessionResumptionConfig

אופציונלי. הגדרת מנגנון לחידוש סשן.

אם הוא כלול, השרת ישלח SessionResumptionUpdate הודעות.
contextWindowCompression

ContextWindowCompressionConfig

אופציונלי. הגדרה של מנגנון דחיסה של חלון הקשר.

אם הוא נכלל, השרת יקטין אוטומטית את גודל ההקשר כשהוא יעלה על האורך שהוגדר.
inputAudioTranscription

AudioTranscriptionConfig

אופציונלי. אם ההגדרה מופעלת, מתבצע תמלול של קלט קולי. התמלול מותאם לשפת האודיו של הקלט, אם היא מוגדרת.
outputAudioTranscription

AudioTranscriptionConfig

אופציונלי. אם ההגדרה הזו מופעלת, מתבצע תמלול של פלט האודיו של המודל. התמליל מותאם לקוד השפה שצוין לאודיו של הפלט, אם הוא הוגדר.
proactivity

ProactivityConfig

אופציונלי. הגדרת הפרואקטיביות של המודל.

כך המודל יכול להגיב באופן יזום לקלט ולהתעלם מקלט לא רלוונטי.
historyConfig

HistoryConfig

אופציונלי. הגדרת חילופי ההיסטוריה בין הלקוח לבין השרת.
labels

map<string, string>

אופציונלי. תוויות עם מטא-נתונים שהוגדרו על ידי המשתמש לבקשה.

אופציונלי. התוויות צריכות לעמוד בדרישות התוויות המאוחדות הרגילות של Cloud: - המפתחות של התוויות צריכים להתחיל באות. – המפתחות והערכים של התוויות יכולים להכיל עד 63 תווים (נקודות קוד של Unicode) ומורכבים רק מאותיות קטנות, ספרות, קווים תחתונים ומקפים. – אפשר להשתמש בתווים בינלאומיים.

שימוש: – מזהי בטיחות מצד צוברים: משתמשים במפתח safety_identifier (למשל, {"safety_identifier": "user_session_123"})

BidiGenerateContentSetupComplete

בסוג הזה אין שדות.

נשלח בתגובה להודעה BidiGenerateContentSetup מהלקוח.

BidiGenerateContentToolCall

בקשה מהלקוח להפעיל את functionCalls ולהחזיר את התשובות עם הערכים התואמים של id.

שדות
functionCalls[]

FunctionCall

פלט בלבד. הבקשה להפעלת הפונקציה שרוצים להריץ.

BidiGenerateContentToolCallCancellation

הודעה ללקוח שToolCallMessage שהונפק בעבר עם ids שצוינו לא אמור היה להתבצע וצריך לבטל אותו. אם היו תופעות לוואי לקריאות הכלים האלה, יכול להיות שהלקוחות ינסו לבטל את קריאות הכלים. ההודעה הזו מופיעה רק במקרים שבהם הלקוחות קוטעים את תורות השרת.

שדות
ids[]

string

פלט בלבד. המזהים של קריאות הכלים שרוצים לבטל.

BidiGenerateContentToolResponse

תגובה שנוצרה על ידי הלקוח לתגובה ToolCall שהתקבלה מהשרת. אובייקטים ספציפיים מסוג FunctionResponse מותאמים לאובייקטים המתאימים מסוג FunctionCall לפי השדה id.

שימו לב שבפונקציות של GenerateContent API מסוג unary ו-server-streaming, קריאה להפעלת פונקציות מתבצעת על ידי החלפת החלקים של Content, בעוד שבפונקציות של GenerateContent API מסוג bidi, קריאה להפעלת פונקציות מתבצעת באמצעות קבוצת ההודעות הייעודית הזו.

שדות
functionResponses[]

FunctionResponse

אופציונלי. התשובה לקריאות לפונקציות.

BidiGenerateContentTranscription

תמלול של אודיו (קלט או פלט).

שדות
text

string

טקסט התמלול.
languageCode

string

קוד השפה של התמליל בתקן BCP-47.
startOffset

Duration

אופציונלי. ההיסט של התחלת התמלול ביחס להתחלת האודיו.
endOffset

Duration

אופציונלי. היסט הסיום בזמן של התמלול ביחס לתחילת האודיו.

ContextWindowCompressionConfig

הפעלה של דחיסת חלון הקשר – מנגנון לניהול חלון הקשר של המודל כך שהוא לא יעלה על אורך נתון.

שדות
שדה איחוד compressionMechanism. מנגנון הדחיסה של חלון ההקשר שבו נעשה שימוש. הערך compressionMechanism יכול להיות רק אחד מהבאים:
slidingWindow

SlidingWindow

מנגנון חלון הזזה.
triggerTokens

int64

מספר הטוקנים (לפני הרצת תור) שנדרשים להפעלת דחיסה של חלון ההקשר.

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

אם לא מגדירים את המדיניות, ברירת המחדל היא 80% ממגבלת חלון ההקשר של המודל. זה משאיר 20% לבקשת המשתמש הבאה או לתשובת המודל.

EndSensitivity

קובע איך מזוהה סוף הדיבור.

טיפוסים בני מנייה (enum)
END_SENSITIVITY_UNSPECIFIED ערך ברירת המחדל הוא END_SENSITIVITY_HIGH.
END_SENSITIVITY_HIGH הזיהוי האוטומטי מסיים את הדיבור לעיתים קרובות יותר.
END_SENSITIVITY_LOW הזיהוי האוטומטי מסיים את הדיבור בתדירות נמוכה יותר.

GoAway

הודעה שהשרת יתנתק בקרוב.

שדות
timeLeft

Duration

הזמן שנותר עד שהחיבור יסתיים כ-ABORTED.

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

HistoryConfig

הגדרת ההיסטוריה.

ההודעה הזו כלולה בהגדרות הסשן כ-BidiGenerateContentSetup.historyConfig. הגדרת חילופי הודעות היסטוריה.

שדות
initialHistoryInClientContent

bool

אופציונלי. אם הערך הוא True, אחרי שליחת setupComplete, השרת ימתין ויעבד בהתחלה clientContent הודעות עד ש-turnComplete יהיה true. ההיסטוריה הראשונית הזו לא תפעיל קריאה למודל, והיא עשויה להסתיים בתפקיד MODEL. אחרי ש-turnComplete הוא true, הלקוח יכול להתחיל את השיחה בזמן אמת דרך realtimeInput.

InteractionStatus

מצבי הפעילות השונים של הסשן בזמן אמת. השדה הזה תמיד נשלח יחד עם turnComplete כדי לציין אם השרת סיים את כל העיבוד.

טיפוסים בני מנייה (enum)
INTERACTION_STATUS_UNSPECIFIED לא צוין סטטוס האינטראקציה.
IN_PROGRESS השרת עדיין מעבד באופן פעיל את קלט המשתמש או מריץ ניתוח רקע. יכול להיות שיוצג פלט נוסף מהמודל.
REQUIRES_ACTION

הוצא משימוש: במקומו צריך להשתמש ב-IDLE.
IDLE השרת סיים את כל העיבוד וההסקה ברקע.

ProactivityConfig

הגדרות לתכונות פרואקטיביות.

שדות
proactiveAudio

bool

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

RealtimeInputConfig

הגדרה של התנהגות הקלט בזמן אמת ב-BidiGenerateContent.

שדות
automaticActivityDetection

AutomaticActivityDetection

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

ActivityHandling

אופציונלי. הגדרה של ההשפעה של הפעילות.
turnCoverage

TurnCoverage

אופציונלי. הגדרה של הקלט שייכלל בתור של המשתמש.
interimTranscriptTimestampEnabled

bool

אופציונלי. הגדרת חותמות זמן לתמליל ביניים.

SessionResumptionConfig

הגדרת חידוש הסשן.

ההודעה הזו כלולה בהגדרות הסשן כ-BidiGenerateContentSetup.sessionResumption. אם הוגדר, השרת ישלח הודעות SessionResumptionUpdate.

שדות
handle

string

הכינוי של סשן קודם. אם הוא לא קיים, נוצר סשן חדש.

הערכים של ה-Session handle מגיעים מהערכים של SessionResumptionUpdate.token בחיבורים קודמים.

SessionResumptionUpdate

עדכון של מצב חידוש הסשן.

הערך נשלח רק אם הוגדר BidiGenerateContentSetup.sessionResumption.

שדות
newHandle

string

כינוי חדש שמייצג מצב שאפשר להמשיך ממנו. השדה ריק אם הערך של resumable הוא false.
resumable

bool

הערך הוא True אם אפשר לחדש את הסשן הנוכחי בשלב הזה.

בנקודות מסוימות בסשן אי אפשר לחדש את הפעילות. לדוגמה, כשהמודל מבצע קריאה להפעלת פונקציות או יוצר תוכן. אם תנסו להמשיך את הסשן (באמצעות טוקן לסשן קודם) במצב כזה, חלק מהנתונים יאבדו. במקרים כאלה, newHandle יהיה ריק ו-resumable יהיה false.

SlidingWindow

השיטה SlidingWindow פועלת על ידי השמטת תוכן בתחילת חלון ההקשר. ההקשר שיתקבל תמיד יתחיל בתחילת תור של תפקיד המשתמש. ההוראות למערכת וכל BidiGenerateContentSetup.prefixTurns תמיד יישארו בתחילת התוצאה.

שדות
targetTokens

int64

מספר הטוקנים שרוצים לשמור. ערך ברירת המחדל הוא trigger_tokens/2.

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

StartSensitivity

קובע איך מזוהה תחילת הדיבור.

טיפוסים בני מנייה (enum)
START_SENSITIVITY_UNSPECIFIED ערך ברירת המחדל הוא START_SENSITIVITY_HIGH.
START_SENSITIVITY_HIGH הזיהוי האוטומטי יזהה את תחילת הדיבור לעיתים קרובות יותר.
START_SENSITIVITY_LOW הזיהוי האוטומטי יזהה את תחילת הדיבור בתדירות נמוכה יותר.

TurnCoverage

אפשרויות לגבי הקלט שנכלל בתור של המשתמש.

טיפוסים בני מנייה (enum)
TURN_COVERAGE_UNSPECIFIED אם לא מציינים התנהגות, המערכת בוחרת התנהגות שמוגדרת כברירת מחדל על סמך המודל. לדוגמה, ב-Gemini 2.5, ברירת המחדל היא TURN_INCLUDES_ONLY_ACTIVITY, וב-Gemini 3.1 ואילך, היא TURN_INCLUDES_AUDIO_ACTIVITY_AND_ALL_VIDEO.
TURN_INCLUDES_ONLY_ACTIVITY כולל פעילות מאז התור האחרון, לא כולל חוסר פעילות (למשל, שקט בזרם האודיו).
TURN_INCLUDES_ALL_INPUT כולל את כל הקלט בזמן אמת מאז התור האחרון, כולל חוסר פעילות (למשל שקט בזרם האודיו).
TURN_INCLUDES_AUDIO_ACTIVITY_AND_ALL_VIDEO כולל את פעילות האודיו וכל הווידאו מאז התור האחרון. בזיהוי אוטומטי של פעילות, פעילות אודיו כוללת דיבור ולא כוללת שקט.

TranslationConfig

הגדרות לתכונות התרגום.

שדות
targetLanguageCode

string

חובה. שפת היעד של התרגום. הערכים הנתמכים הם קודי שפה בתקן BCP-47 (למשל 'en',‏ 'es',‏ 'fr').
echoTargetLanguage

bool

אופציונלי. אם הערך הוא true, המודל ייצור אודיו כשהשפה הממוקדת מדוברת, כלומר הוא יחזור על הקלט. אם הערך הוא False, לא ניצור אודיו בשפת היעד.

UrlContextMetadata

מטא-נתונים שקשורים לכלי לאחזור הקשר של כתובת URL.

שדות
urlMetadata[]

UrlMetadata

רשימה של כתובות URL בהקשר.

UsageMetadata

מטא-נתונים של השימוש לגבי התשובות.

שדות
promptTokenCount

int32

פלט בלבד. מספר הטוקנים בהנחיה. גם כשהערך של cachedContent מוגדר, זה עדיין הגודל הכולל של ההנחיה בפועל, כלומר הוא כולל את מספר הטוקנים בתוכן שבמטמון.
cachedContentTokenCount

int32

מספר הטוקנים בחלק של ההנחיה שנשמר במטמון (התוכן שנשמר במטמון)
responseTokenCount

int32

פלט בלבד. המספר הכולל של הטוקנים בכל התשובות האפשריות שנוצרו.
toolUsePromptTokenCount

int32

פלט בלבד. מספר הטוקנים בהנחיות לשימוש בכלי.
thoughtsTokenCount

int32

פלט בלבד. מספר הטוקנים של המחשבות למודלים חושבים.
totalTokenCount

int32

פלט בלבד. המספר הכולל של הטוקנים בבקשת היצירה (הנחיה + מועמדים לתגובה).
promptTokensDetails[]

ModalityTokenCount

פלט בלבד. רשימת אופנויות שעברו עיבוד בקלט של הבקשה.
cacheTokensDetails[]

ModalityTokenCount

פלט בלבד. רשימת אופנויות של התוכן שנשמר במטמון בקלט של הבקשה.
responseTokensDetails[]

ModalityTokenCount

פלט בלבד. רשימת המודאליות שהוחזרו בתשובה.
toolUsePromptTokensDetails[]

ModalityTokenCount

פלט בלבד. רשימה של אופנים שונים של קלט שעברו עיבוד לבקשות לשימוש בכלי.

VoiceActivity

זוהתה פעילות קולית בזרם האודיו.

שדות
type

Type

פלט בלבד. הסוג של אות ה-VAD(זיהוי דיבור).
audioOffset

Duration

פלט בלבד. הזמן שבו זוהה דיבור באודיו, ביחס לתחילת שידור האודיו.

סוג

סוג אות ה-VAD.

טיפוסים בני מנייה (enum)
TYPE_UNSPECIFIED ברירת המחדל היא UNSPECIFIED.
ACTIVITY_START אות לתחילת משפט.
ACTIVITY_END אות לסיום המשפט.

טוקנים זמניים לאימות

אפשר לקבל אסימוני אימות זמניים על ידי קריאה ל-AuthTokenService.CreateToken ואז להשתמש בהם עם GenerativeService.BidiGenerateContentConstrained, על ידי העברת האסימון בפרמטר שאילתה access_token או בכותרת HTTP Authorization עם הקידומת Token.

CreateAuthTokenRequest

יצירת אסימון אימות זמני.

שדות
authToken

AuthToken

חובה. הטוקן שרוצים ליצור.

AuthToken

בקשה ליצירת טוקן אימות זמני.

שדות
name

string

פלט בלבד. מזהה. הטוקן עצמו.
expireTime

Timestamp

אופציונלי. קלט בלבד. אי אפשר לשנות. זמן אופציונלי שאחריו, כשמשתמשים בטוקן שנוצר, הודעות בסשנים של BidiGenerateContent יידחו. ‫(Gemini עשוי לסגור את הסשן לפני הזמן הזה).

אם לא מגדירים את התדירות, ברירת המחדל היא 30 דקות. אם הוא מוגדר, הערך הזה צריך להיות פחות מ-20 שעות בעתיד.
newSessionExpireTime

Timestamp

אופציונלי. קלט בלבד. אי אפשר לשנות. הזמן שאחריו בקשות חדשות להפעלת Live API באמצעות הטוקן שנוצר מהבקשה הזו יידחו.

אם לא מגדירים את ההגדרה הזו, ברירת המחדל בעתיד תהיה 60 שניות. אם הוא מוגדר, הערך הזה צריך להיות פחות מ-20 שעות בעתיד.
fieldMask

FieldMask

אופציונלי. קלט בלבד. אי אפשר לשנות. אם field_mask ריק, ו-bidiGenerateContentSetup לא קיים, אז הודעת BidiGenerateContentSetup האפקטיבית נלקחת מהחיבור הפעיל ל-API.

אם field_mask ריק, ו-bidiGenerateContentSetup is קיים, אז ההודעה האפקטיבית BidiGenerateContentSetup נלקחת כולה מ-bidiGenerateContentSetup בבקשה הזו. הודעת ההגדרה מחיבור Live API מוזנחת.

אם field_mask לא ריק, השדות התואמים מ-bidiGenerateContentSetup יחליפו את השדות מהודעת ההגדרה בחיבור הפעיל ל-API.
שדה איחוד config. ההגדרה הספציפית לשיטה של הטוקן שנוצר. הערך config יכול להיות רק אחד מהבאים:
bidiGenerateContentSetup

BidiGenerateContentSetup

אופציונלי. קלט בלבד. אי אפשר לשנות. ההגדרה ספציפית ל-BidiGenerateContent.
uses

int32

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

מידע נוסף על סוגים נפוצים

מידע נוסף על סוגי משאבי ה-API הנפוצים Blob, Content, FunctionCall, FunctionResponse, GenerationConfig, GroundingMetadata, ModalityTokenCount ו-Tool זמין במאמר בנושא יצירת תוכן.