כדאי לנסות את המודל החדש Veo 3.1 Lite ליצירת סרטונים בהיקף נרחב. המודל הזה מהיר וחסכוני.

Live Music API - WebSockets API reference

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

ביקורים

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

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

חיבור WebSocket

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

‫

wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1alpha.GenerativeService.BidiGenerateMusic

הגדרות הסשן

ההודעה הראשונית אחרי החיבור מגדירה את המודל שבו ישתמשו במהלך הסשן.

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


{
  "model": string
}

שליחת הודעות

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


{
  "setup": BidiGenerateMusicSetup,
  "client_content": BidiGenerateMusicClientContent,
  "music_generation_config": BidiGenerateMusicGenerationConfig,
  "playback_control": BidiGenerateMusicPlaybackControl
}

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

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

שליחת הודעה	תיאור
`BidiGenerateMusicSetup`	הגדרת סשן שתישלח רק בהודעה הראשונה
`BidiGenerateMusicClientContent`	הנחיות משוקללות כקלט למודל
`BidiGenerateMusicGenerationConfig`	הגדרות ליצירת מוזיקה
`BidiGenerateMusicPlaybackControl`	אותות של רכיבי UI להפעלה ליצירת מודלים

קבלת הודעות

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

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

async def receive_audio(session):
  """Example background task to process incoming audio."""
  while True:
    async for message in session.receive():
      audio_data = message.server_content.audio_chunks[0].data
      # Process audio...
      await asyncio.sleep(10**-12)

async with (
  client.aio.live.music.connect(model='models/lyria-realtime-exp') as session,
  asyncio.TaskGroup() as tg,
):
  # Set up task to receive server messages.
  tg.create_task(receive_audio(session))

  # Send initial prompts and config
  await session.set_weighted_prompts(
    prompts=[
      types.WeightedPrompt(text='minimal techno', weight=1.0),
    ]
  )
  await session.set_music_generation_config(
    config=types.LiveMusicGenerationConfig(bpm=90, temperature=1.0)
  )

  # Start streaming music
  await session.play()

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

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

AudioChunk

ייצוג של נתח אודיו.

שדות
שדה איחוד `content`. הערך `content` יכול להיות רק אחד מהבאים:
`data`	`bytes` בייטים גולמיים של נתח האודיו.
`mimeType`	`string` סוג ה-MIME של התוכן של קטע האודיו, כמו audio/wav.
`sourceMetadata`	`SourceMetadata` פלט בלבד. ההנחיות וההגדרות ששימשו ליצירת קטע האודיו הזה.

SourceMetadata

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

שדות

clientContent

BidiGenerateMusicClientContent

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

musicGenerationConfig

BidiGenerateMusicGenerationConfig

הגדרות ליצירת מוזיקה ליצירת קטע האודיו הזה.

BidiGenerateMusicClientContent

קלט משתמש כדי להתחיל את המוזיקה או לכוון אותה.

שדות

שדות
`weightedPrompts[]`	`WeightedPrompt` חובה. הנחיות משוקללות כקלט למודל.

weightedPrompts[]

WeightedPrompt

חובה. הנחיות משוקללות כקלט למודל.

BidiGenerateMusicClientMessage

הודעות שנשלחות על ידי הלקוח בשיחה BidiGenerateMusic.

שדות
שדה איחוד `messageType`. הערך `messageType` יכול להיות רק אחד מהבאים:
`setup`	`BidiGenerateMusicSetup` אופציונלי. הגדרת הסשן נשלחת רק בהודעת הלקוח הראשונה.
`clientContent`	`BidiGenerateMusicClientContent` אופציונלי. הנחיות משוקללות והגדרות ליצירת מוזיקה כקלט ליצירת מוזיקה.
`musicGenerationConfig`	`BidiGenerateMusicGenerationConfig` אופציונלי. הגדרה ליצירת מוזיקה.
`playbackControl`	`BidiGenerateMusicPlaybackControl` אופציונלי. אות בקרה להפעלת המוזיקה.

BidiGenerateMusicFilteredPrompt

הנחיה מסוננת עם סיבה.

שדות

שדות
`filteredReason`	`string` פלט בלבד. הסיבה לסינון ההנחיה.
שדה איחוד `prompt`. ההנחיה שסוננה. הערך `prompt` יכול להיות רק אחד מהבאים:
`text`	`string` אופציונלי. הנחיית טקסט.

filteredReason

string

פלט בלבד. הסיבה לסינון ההנחיה.

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

text

string

אופציונלי. הנחיית טקסט.

BidiGenerateMusicGenerationConfig

הגדרה ליצירת מוזיקה.

שדות
`temperature`	`float` אופציונלי. שליטה בשונות ביצירת האודיו. ערכים גבוהים יותר יוצרים שונות גבוהה יותר. הטווח הוא [0.0, 3.0]. ברירת המחדל היא 1.1.
`topK`	`int32` אופציונלי. ההגדרה הזו קובעת איך המודל בוחר אסימונים לפלט. דוגם את אסימוני ה-topK עם ההסתברויות הכי גבוהות. הטווח הוא [1, 1000]. ברירת המחדל היא 40.
`seed`	`int32` אופציונלי. יוצר אודיו מזרעים. אם לא מגדירים את הערך הזה, הבקשה משתמשת בערך seed שנוצר באופן אקראי.
`guidance`	`float` אופציונלי. ההגדרה הזו קובעת עד כמה המודל יפעל לפי ההנחיות. הדרכה מפורטת יותר תתבסס על ההנחיה בצורה מדויקת יותר, אבל המעברים יהיו פחות חלקים. הטווח הוא [0.0, 6.0]. ברירת המחדל היא 4.0.
`bpm`	`int32` אופציונלי. פעימות לדקה. הטווח הוא [60, 200].
`density`	`float` אופציונלי. צפיפות הצלילים. הטווח הוא [0.0, 1.0].
`brightness`	`float` אופציונלי. ערך גבוה יותר יוצר אודיו בהיר יותר. הטווח הוא [0.0, 1.0].
`scale`	`Scale` אופציונלי. הסולם של המוזיקה שנוצרה.
`muteBass`	`bool` אופציונלי. פלט האודיו לא צריך להכיל באס.
`muteDrums`	`bool` אופציונלי. פלט האודיו לא יכול להכיל תופים.
`onlyBassAndDrums`	`bool` אופציונלי. פלט האודיו צריך לכלול רק בס ותופים.
`musicGenerationMode`	`MusicGenerationMode` אופציונלי. מצב יצירת המוזיקה. ברירת המחדל היא QUALITY.

MusicGenerationMode

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

קנה מידה

הסולם של המוזיקה שנוצרה.

טיפוסים בני מנייה (enum)
`SCALE_UNSPECIFIED`	ערך ברירת המחדל. הערך הזה לא בשימוש.
`C_MAJOR_A_MINOR`	דו מז'ור או לה מינור
`D_FLAT_MAJOR_B_FLAT_MINOR`	D flat major או B flat minor
`D_MAJOR_B_MINOR`	D major or B minor
`E_FLAT_MAJOR_C_MINOR`	מי במול מז'ור או דו מינור
`E_MAJOR_D_FLAT_MINOR`	מי מז'ור או רה במול מינור
`F_MAJOR_D_MINOR`	פה מז'ור או רה מינור
`G_FLAT_MAJOR_E_FLAT_MINOR`	סול במול מז'ור או מי במול מינור
`G_MAJOR_E_MINOR`	סול מז'ור או מינור
`A_FLAT_MAJOR_F_MINOR`	להשתמש ב-A♭ major או ב-F minor
`A_MAJOR_G_FLAT_MINOR`	סול מז'ור או סול במול מינור
`B_FLAT_MAJOR_G_MINOR`	B flat major או G minor
`B_MAJOR_A_FLAT_MINOR`	סי מז'ור או לה במול מינור

BidiGenerateMusicPlaybackControl

רכיבי UI להפעלת המוזיקה שנוצרה.

טיפוסים בני מנייה (enum)
`PLAYBACK_CONTROL_UNSPECIFIED`	הערך הזה לא בשימוש.
`PLAY`	מתחילים ליצור את המוזיקה.
`PAUSE`	תשהה את יצירת המוזיקה. משתמשים בלחצן PLAY כדי להמשיך מהמיקום הנוכחי.
`STOP`	הפסקת יצירת המוזיקה ואיפוס ההקשר (ההנחיות נשמרות). משתמשים בלחצן PLAY כדי להפעיל מחדש את יצירת המוזיקה.
`RESET_CONTEXT`	לאפס את ההקשר (ההנחיות נשמרות) בלי להפסיק את יצירת המוזיקה.

BidiGenerateMusicServerContent

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

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

שדות

שדות
`audioChunks[]`	`AudioChunk` פלט בלבד. קטעי אודיו שהמודל יצר.

audioChunks[]

AudioChunk

פלט בלבד. קטעי אודיו שהמודל יצר.

BidiGenerateMusicServerMessage

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

שדות
שדה איחוד `messageType`. סוג ההודעה. הערך `messageType` יכול להיות רק אחד מהבאים:
`setupComplete`	`BidiGenerateMusicSetupComplete` פלט בלבד. ההודעה נשלחת בתגובה להודעה של `BidiGenerateMusicSetup` מהלקוח, כשההגדרה מסתיימת.
`serverContent`	`BidiGenerateMusicServerContent` פלט בלבד. תוכן שנוצר על ידי המודל בתגובה להודעות של לקוחות.
`filteredPrompt`	`BidiGenerateMusicFilteredPrompt` פלט בלבד. הנחיה מסוננת עם סיבה.
`warning`	`string` פלט בלבד. הודעת האזהרה מהשרת. האזהרות לא יגרמו לסיום השידור.

BidiGenerateMusicSetup

ההודעה שתישלח בפעם הראשונה (ורק בפעם הראשונה) BidiGenerateMusicClientMessage.

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

שדות

שדות
`model`	`string` חובה. שם המשאב של המודל. המזהה הזה משמש את המודל. פורמט: `models/{model}`

model

string

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

פורמט: models/{model}

BidiGenerateMusicSetupComplete

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

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

WeightedPrompt

הנחיה משוקללת כקלט למודל.

שדות

שדות
`weight`	`float` חובה. משקל ההנחיה. המשקל משמש לשליטה בחשיבות היחסית של ההנחיה. משקלים גבוהים חשובים יותר ממשקלים נמוכים. המשקלים של כל ה-weighted_prompts ב-BidiGenerateMusicClientContent לא יכולים להיות כולם 0. המשקלים של כל ה-weighted_prompts בהודעה הזו מסוג BidiGenerateMusicClientContent יעברו נורמליזציה.
שדה איחוד `prompt`. הערך `prompt` יכול להיות רק אחד מהבאים:
`text`	`string` הנחיית טקסט.

weight

float

חובה. משקל ההנחיה.

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

המשקלים של כל ה-weighted_prompts ב-BidiGenerateMusicClientContent לא יכולים להיות כולם 0. המשקלים של כל ה-weighted_prompts בהודעה הזו מסוג BidiGenerateMusicClientContent יעברו נורמליזציה.

שדה איחוד prompt.

הערך prompt יכול להיות רק אחד מהבאים:

text

string

הנחיית טקסט.

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

מידע נוסף על הסוגים שבהם נעשה שימוש ב-API מופיע ב-Python SDK.