تتيح واجهة برمجة التطبيقات Gemini Live التفاعل الثنائي الاتجاه مع نماذج Gemini في الوقت الفعلي، وتتوافق مع إدخالات الصوت والفيديو والنص ومخرجات الصوت الأصلية. يوضّح هذا الدليل كيفية الدمج مع واجهة برمجة التطبيقات باستخدام حزمة تطوير البرامج (SDK) من Google GenAI على الخادم.
نظرة عامة
تستخدم واجهة برمجة التطبيقات Gemini Live WebSockets للتواصل في الوقت الفعلي. توفّر حزمة تطوير البرامج (SDK) google-genai واجهة غير متزامنة عالية المستوى لإدارة هذه الاتصالات.
المفاهيم الأساسية:
- الجلسة: اتصال دائم بالنموذج
- الإعداد: إعداد طرق الإدخال (الصوت/النص) والصوت وتعليمات النظام
- الإدخال في الوقت الفعلي: إرسال إطارات الصوت والفيديو ككائنات ثنائية كبيرة الحجم
الاتصال بواجهة برمجة التطبيقات Live API
ابدأ جلسة Live API باستخدام مفتاح واجهة برمجة التطبيقات:
Python
import asyncio
from google import genai
client = genai.Client(api_key="YOUR_API_KEY")
model = "gemini-2.5-flash-native-audio-preview-12-2025"
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({ apiKey: "YOUR_API_KEY"});
const model = 'gemini-2.5-flash-native-audio-preview-12-2025';
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");
// Send content...
session.close();
}
main();
جارٍ إرسال الرسالة النصية
يمكن إرسال النص باستخدام send_realtime_input (Python) أو sendRealtimeInput (JavaScript).
Python
await session.send_realtime_input(text="Hello, how are you?")
JavaScript
session.sendRealtimeInput({
text: 'Hello, how are you?'
});
إرسال الصوت
يجب إرسال الصوت كبيانات PCM أولية (صوت PCM أولي 16 بت، 16 كيلوهرتز، ترتيب البايتات الصغير).
Python
# Assuming 'chunk' is your raw PCM audio bytes
await session.send_realtime_input(
audio=types.Blob(
data=chunk,
mime_type="audio/pcm;rate=16000"
)
)
JavaScript
// Assuming 'chunk' is a Buffer of raw PCM audio
session.sendRealtimeInput({
audio: {
data: chunk.toString('base64'),
mimeType: 'audio/pcm;rate=16000'
}
});
للاطّلاع على مثال حول كيفية الحصول على الصوت من جهاز العميل (مثل المتصفح)، راجِع المثال الشامل على GitHub.
إرسال الفيديو
يتم إرسال إطارات الفيديو كصور فردية (مثل JPEG أو PNG) بمعدّل عدد اللقطات في الثانية محدّد (بحد أقصى لقطة واحدة في الثانية).
Python
# Assuming 'frame' is your JPEG-encoded image bytes
await session.send_realtime_input(
video=types.Blob(
data=frame,
mime_type="image/jpeg"
)
)
JavaScript
// Assuming 'frame' is a Buffer of JPEG-encoded image data
session.sendRealtimeInput({
video: {
data: frame.toString('base64'),
mimeType: 'image/jpeg'
}
});
للاطّلاع على مثال حول كيفية الحصول على الفيديو من جهاز العميل (مثل المتصفح)، راجِع المثال الشامل على GitHub.
استلام الصوت
يتم تلقّي الردود الصوتية من النموذج على شكل أجزاء من البيانات.
Python
async for response in session.receive():
if response.server_content and response.server_content.model_turn:
for part in response.server_content.model_turn.parts:
if part.inline_data:
audio_data = part.inline_data.data
# Process or play the audio data
JavaScript
// Inside the onmessage callback
const content = response.serverContent;
if (content?.modelTurn?.parts) {
for (const part of content.modelTurn.parts) {
if (part.inlineData) {
const audioData = part.inlineData.data;
// Process or play audioData (base64 encoded string)
}
}
}
يمكنك الاطّلاع على مثال التطبيق على GitHub لمعرفة كيفية تلقّي الصوت على الخادم وتشغيله في المتصفح.
جارٍ استلام الرسالة النصية
تتوفّر نصوص لكلّ من بيانات أدخلها المستخدم ومخرجات النموذج في محتوى الخادم.
Python
async for response in session.receive():
content = response.server_content
if content:
if content.input_transcription:
print(f"User: {content.input_transcription.text}")
if content.output_transcription:
print(f"Gemini: {content.output_transcription.text}")
JavaScript
// Inside the onmessage callback
const content = response.serverContent;
if (content?.inputTranscription) {
console.log('User:', content.inputTranscription.text);
}
if (content?.outputTranscription) {
console.log('Gemini:', content.outputTranscription.text);
}
معالجة طلبات الأدوات
تتيح واجهة برمجة التطبيقات استخدام الأدوات (استدعاء الدوال). عندما يطلب النموذج إجراء مكالمة باستخدام أداة، عليك تنفيذ الدالة وإرسال الردّ.
Python
async for response in session.receive():
if response.tool_call:
function_responses = []
for fc in response.tool_call.function_calls:
# 1. Execute the function locally
result = my_tool_function(**fc.args)
# 2. Prepare the response
function_responses.append(types.FunctionResponse(
name=fc.name,
id=fc.id,
response={"result": result}
))
# 3. Send the tool response back to the session
await session.send_tool_response(function_responses=function_responses)
JavaScript
// Inside the onmessage callback
if (response.toolCall) {
const functionResponses = [];
for (const fc of response.toolCall.functionCalls) {
const result = myToolFunction(fc.args);
functionResponses.push({
name: fc.name,
id: fc.id,
response: { result }
});
}
session.sendToolResponse({ functionResponses });
}
الخطوات التالية
- اطّلِع على دليل الإمكانات الكامل لواجهة Live API لمعرفة الإمكانات والإعدادات الرئيسية، بما في ذلك ميزة "رصد النشاط الصوتي" وميزات الصوت الأصلية.
- اطّلِع على دليل استخدام الأدوات لمعرفة كيفية دمج Live API مع الأدوات واستدعاء الدوال.
- اطّلِع على دليل إدارة الجلسات لإدارة المحادثات الطويلة.
- اطّلِع على دليل الرموز المميزة المؤقتة لإجراء مصادقة آمنة في تطبيقات العميل إلى الخادم.
- لمزيد من المعلومات عن واجهة برمجة تطبيقات WebSockets الأساسية، يُرجى الاطّلاع على مرجع واجهة برمجة تطبيقات WebSockets.