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, המשמעות היא שהמודל לא יוצר תוכן כי הוא ממתין לקלט נוסף מהמשתמש, למשל כי הוא מצפה שהמשתמש ימשיך לדבר.
speechState
(deprecated)

SpeechState

פלט בלבד. הוצא משימוש: במקומו, צריך להשתמש במאפיין VoiceActivity.

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

InteractionStatus

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

Content

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

BidiGenerateContentServerMessage

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

שדות
usageMetadata

UsageMetadata

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

BidiGenerateContentSetupComplete

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

BidiGenerateContentServerContent

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

BidiGenerateContentToolCall

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

BidiGenerateContentToolCallCancellation

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

GoAway

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

SessionResumptionUpdate

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

BidiGenerateContentSetup

ההודעה שתישלח ב-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

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

BidiGenerateContentSetupComplete

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

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

BidiGenerateContentToolCall

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

שדות
functionCalls[]

FunctionCall

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

BidiGenerateContentToolCallCancellation

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

שדות
ids[]

string

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

BidiGenerateContentToolResponse

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

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

שדות
functionResponses[]

FunctionResponse

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

BidiGenerateContentTranscription

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

שדות
text

string

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

string

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

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

הזמן שנותר לפני שהחיבור יסתיים כחיבור שבוטל.

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

HistoryConfig

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

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

שדות
initialHistoryInClientContent

bool

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

ProactivityConfig

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

שדות
proactiveAudio

bool

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

RealtimeInputConfig

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

שדות
automaticActivityDetection

AutomaticActivityDetection

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

ActivityHandling

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

TurnCoverage

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

SessionResumptionConfig

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

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

שדות
handle

string

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

מזהי סשן מגיעים מערכי SessionResumptionUpdate.token בחיבורים קודמים.

SessionResumptionUpdate

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

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

שדות
newHandle

string

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

bool

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

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

SlidingWindow

השיטה SlidingWindow פועלת על ידי השמטת תוכן בתחילת חלון ההקשר. ההקשר שיתקבל תמיד יתחיל בתחילת תור של תפקיד USER. ההוראות למערכת וכל 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

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

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

אפשר לקבל אסימוני אימות זמניים על ידי קריאה ל-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

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

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

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