جرِّب نموذج 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. يمكنك البحث عن خيارات إعداد حزمة تطوير البرامج (SDK) في Python هنا.


{
  "model": string
}

إرسال الرسائل

لتبادل الرسائل عبر اتصال WebSocket، يجب أن يرسل العميل عنصر JSON عبر اتصال WebSocket مفتوح. يجب أن يحتوي عنصر JSON على حقل واحد فقط من مجموعة العناصر التالية:


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

رسائل العميل المتوافقة

اطّلِع على رسائل العميل المتوافقة في الجدول التالي:

رسالة	الوصف
`BidiGenerateMusicSetup`	إعدادات الجلسة التي سيتم إرسالها فقط في الرسالة الأولى
`BidiGenerateMusicClientContent`	طلبات مرجّحة كمدخلات للنموذج
`BidiGenerateMusicGenerationConfig`	إعدادات إنشاء الموسيقى
`BidiGenerateMusicPlaybackControl`	إشارات التحكّم في التشغيل لإنشاء النماذج

تلقي الرسائل

لتلقّي رسائل من الخادم، استمع إلى حدث WebSocket "message"، ثم حلِّل النتيجة وفقًا لتعريف رسائل الخادم المتوافقة.

يُرجى الاطّلاع على ما يلي:

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` اختياريّ. إنشاء محتوى صوتي من البذور في حال عدم ضبط هذه القيمة، يستخدم الطلب قيمة أولية تم إنشاؤها عشوائيًا.
`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

عمليات التعداد
`MUSIC_GENERATION_MODE_UNSPECIFIED`	هذه القيمة غير مستخدَمة.
`QUALITY`	يوجه هذا الوضع الطلبات النصية إلى مناطق في المساحة الكامنة تحتوي على موسيقى بجودة أعلى.
`DIVERSITY`	يوجه هذا الوضع طلبات النص إلى مناطق في المساحة الكامنة تتضمّن تنوّعًا أكبر في الموسيقى.
`VOCALIZATION`	يوجه هذا الوضع طلبات النص إلى مناطق في المساحة الكامنة من المرجح أن تنشئ موسيقى صوتية.

مقياس

مقياس الموسيقى التي تم إنشاؤها

عمليات التعداد
`SCALE_UNSPECIFIED`	القيمة التلقائية هذه القيمة غير مستخدَمة.
`C_MAJOR_A_MINOR`	C major or A minor
`D_FLAT_MAJOR_B_FLAT_MINOR`	D flat major or B flat minor
`D_MAJOR_B_MINOR`	D major or B minor
`E_FLAT_MAJOR_C_MINOR`	E flat major or C minor
`E_MAJOR_D_FLAT_MINOR`	مقام "مي" الكبير أو "ري بيمول" الصغير
`F_MAJOR_D_MINOR`	مفتاح F الكبير أو مفتاح D الصغير
`G_FLAT_MAJOR_E_FLAT_MINOR`	G flat major or E flat minor
`G_MAJOR_E_MINOR`	السلم الموسيقي G الكبير أو السلم الموسيقي E الصغير
`A_FLAT_MAJOR_F_MINOR`	مفتاح فا الكبير أو فا الصغير
`A_MAJOR_G_FLAT_MINOR`	مقام كبير أو مقام صغير ذو خمس علامات خفض
`B_FLAT_MAJOR_G_MINOR`	مقام سي بيمول الكبير أو مقام صول الصغير
`B_MAJOR_A_FLAT_MINOR`	B major or A flat minor

BidiGenerateMusicPlaybackControl

عناصر التحكّم في تشغيل الموسيقى التي تم إنشاؤها

عمليات التعداد
`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

الطلب النصي

مزيد من المعلومات حول الأنواع

لمزيد من المعلومات حول الأنواع التي تستخدمها واجهة برمجة التطبيقات، راجِع حزمة تطوير البرامج (SDK) للغة Python.