تتيح واجهة برمجة التطبيقات Gemini Live API ترجمة الكلام في الوقت الفعلي بين أكثر من 70 لغة باستخدام نموذج gemini-3.5-live-translate-preview. من خلال ضبط Live API باستخدام إعدادات الترجمة، يمكنك بث الصوت بلغة معيّنة وتلقّي مصدر إخراج الصوت مترجَمًا بلغة أخرى، ما يتيح ترجمة سلسة من صوت إلى صوت في الوقت الفعلي.
الفرق بين ميزة "الرد المباشر على المكالمات الهاتفية" وميزة "الترجمة المباشرة"
مع أنّ كلتا الميزتَين تستخدمان واجهة Live API، يختلف النموذج الذهني لميزة "الترجمة المباشرة" عن التفاعلات الحوارية في الوقت الفعلي مع الوكيل.
| موظّف دعم يقدّم خدمة مباشرة | الترجمة المباشرة |
|---|---|
| يعمل النموذج كمساعد. يستمع إليك، ويفكّر، ويتّخذ إجراءات نيابةً عنك. | يعمل النموذج كمترجم. وهي تعمل كمسار ترجمة في الوقت الفعلي. |
| تستخدِم تفاعلات بالتناوب. تعتمد على التوقف المؤقت ورصد النية وتتعامل مع المقاطعات. | استخدام معالجة البث المستمر: تترجم الميزة الكلام أثناء تحدث المتحدث بدون انتظار دوره. |
| يتوافق مع الأدوات وموظفي الدعم إتاحة ميزة "استدعاء الدوال" و"بحث Google" و"التعليمات" بشكلٍ مدمج | يتيح هذا التطبيق الترجمة فقط. الترجمة بوقت استجابة منخفض جدًا بدون دعم للأدوات أو التعليمات |
| متعدد الوسائط بالكامل: يتيح إدخال النصوص والمقاطع الصوتية والفيديوهات والصور. | تم حظر الصوت. يقتصر الإدخال على الصوت لضمان الالتزام الصارم بحدود زمن الاستجابة في الوقت الفعلي. |
| الإعدادات الدقيقة: تستخدم هذه النماذج إنشاء المحتوى والكلام والأدوات وتعليمات النظام. | إعدادات مبسّطة: اضبط target_language_code وعناصر التحكّم مثل echo_target_language. |
البدء
توضّح الأمثلة التالية كيفية تهيئة عميل والاتصال بواجهة Live API باستخدام إعدادات الترجمة.
Python
import asyncio
from google import genai
from google.genai import types
client = genai.Client()
model = "gemini-3.5-live-translate-preview"
config = types.LiveConnectConfig(
response_modalities=["AUDIO"],
input_audio_transcription=types.AudioTranscriptionConfig(),
output_audio_transcription=types.AudioTranscriptionConfig(),
translation_config=types.TranslationConfig(
target_language_code="pl",
echo_target_language=True
)
)
async def main():
async with client.aio.live.connect(model=model, config=config) as session:
print("Session started with translation")
# Start receiving the translated audio stream
async for response in session.receive():
if response.server_content:
if response.server_content.input_transcription:
print(f"Input transcript: {response.server_content.input_transcription.text}")
if response.server_content.output_transcription:
print(f"Output transcript: {response.server_content.output_transcription.text}")
if response.server_content.model_turn:
for part in response.server_content.model_turn.parts:
if part.inline_data:
audio_data = part.inline_data.data
# Play or process the translated audio chunk
print(f"Received audio chunk ({len(audio_data)} bytes)")
if __name__ == "__main__":
asyncio.run(main())
JavaScript
import { GoogleGenAI, Modality } from '@google/genai';
const ai = new GoogleGenAI({});
const model = 'gemini-3.5-live-translate-preview';
const config = {
responseModalities: [Modality.AUDIO],
inputAudioTranscription: {},
outputAudioTranscription: {},
translationConfig: {
targetLanguageCode: 'pl',
echoTargetLanguage: true
}
};
async function main() {
const session = await ai.live.connect({
model: model,
config: config,
callbacks: {
onopen: () => console.debug('Opened'),
onmessage: (message) => {
const content = message.serverContent;
if (content?.inputTranscription) {
console.log('Input transcript:', content.inputTranscription.text);
}
if (content?.outputTranscription) {
console.log('Output transcript:', content.outputTranscription.text);
}
if (content?.modelTurn?.parts) {
for (const part of content.modelTurn.parts) {
if (part.inlineData) {
const audioData = part.inlineData.data;
// Play or process the translated audio chunk (base64 encoded)
console.debug(`Received audio chunk (${audioData.length} bytes)`);
}
}
}
},
onerror: (e) => console.debug('Error:', e.message),
onclose: (e) => console.debug('Close:', e.reason),
},
});
console.debug("Session started with translation");
}
main();
WebSockets
const API_KEY = "YOUR_API_KEY";
const MODEL_NAME = "gemini-3.5-live-translate-preview";
const WS_URL = `wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent?key=${API_KEY}`;
const websocket = new WebSocket(WS_URL);
websocket.onopen = () => {
console.log('WebSocket Connected');
const setupMessage = {
setup: {
model: `models/${MODEL_NAME}`,
generationConfig: {
responseModalities: ['AUDIO'],
inputAudioTranscription: {},
outputAudioTranscription: {},
translationConfig: {
targetLanguageCode: 'pl',
echoTargetLanguage: true
}
}
}
};
websocket.send(JSON.stringify(setupMessage));
};
websocket.onmessage = (event) => {
const response = JSON.parse(event.data);
if (response.serverContent) {
const content = response.serverContent;
if (content.inputTranscription) {
console.log('Input transcript:', content.inputTranscription.text, `(${content.inputTranscription.languageCode})`);
}
if (content.outputTranscription) {
console.log('Output transcript:', content.outputTranscription.text, `(${content.outputTranscription.languageCode})`);
}
if (content.modelTurn?.parts) {
for (const part of content.modelTurn.parts) {
if (part.inlineData) {
const audioData = part.inlineData.data;
// Play or process the translated audio chunk (base64 encoded)
console.debug(`Received audio chunk (${audioData.length} bytes)`);
}
}
}
}
};
إرسال الصوت
لبث الإدخالات الصوتية بغرض الترجمة، عليك إرسال صوت PCM أولي بتنسيق little-endian وبدقة 16 بت.
- تنسيق الصوت المُدخَل: تنسيق PCM الأولي بمعدّل 16 بت عند 16 كيلوهرتز (أحادي، little-endian).
- تنسيق الصوت الناتج: PCM خام بمعدل 16 بت عند 24 كيلوهرتز (أحادي، little-endian)
- حجم الأجزاء ووقت الاستجابة: إرسال الصوت في أجزاء تبلغ مدتها 100 ملي ثانية
توضّح الأمثلة التالية كيفية إرسال أجزاء من الصوت إلى الجلسة.
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'
}
});
WebSockets
// Assuming 'chunk' is a Buffer of raw PCM audio
function sendAudioChunk(chunk) {
if (websocket.readyState === WebSocket.OPEN) {
const audioMessage = {
realtimeInput: {
audio: {
data: chunk.toString('base64'),
mimeType: 'audio/pcm;rate=16000'
}
}
};
websocket.send(JSON.stringify(audioMessage));
}
}
التهيئة
لتفعيل الترجمة، يجب تحديد translationConfig ضمن generationConfig أثناء إعداد الجلسة.
إعدادات رسائل الإعداد
يتيح generationConfig الحقول التالية لتفعيل النصوص:
-
inputAudioTranscription: عنصر يتيح للنموذج، عند توفّره، إرسال نصوص صوتية للمحتوى الصوتي المُدخَل. outputAudioTranscription: عنصر يتيح للنموذج، عند توفّره، إرسال نصوص صوتية (مترجمة) للمحتوى الصوتي الناتج.
تتيح translationConfig استخدام الحقول التالية:
- استبدِل
targetLanguageCodeبرمز اللغة BCP-47 الذي تريد أن يترجم النموذج إليه (مثل"pl"للغة البولندية أو"es"للغة الإسبانية). القيمة التلقائية هي"en". echoTargetLanguage: قيمة منطقية تشير إلى كيفية التعامل مع الصوت الذي تم إدخاله والموجود أصلاً باللغة المستهدَفة. إذا تم ضبطها علىtrue، سيعيد النموذج صدى (محاكاة) الصوت المُدخَل الذي يكون باللغة المستهدَفة. إذا تم ضبطها علىfalse، سيظل النموذج صامتًا عندما يكون الكلام المُدخَل باللغة المستهدَفة. القيمة التلقائية هيfalse.
في ما يلي مثال على بنية رسالة الإعداد:
"setup": {
"model": "models/gemini-3.5-live-translate-preview",
"generationConfig": {
"responseModalities": [
"AUDIO"
],
"inputAudioTranscription": {},
"outputAudioTranscription": {},
"translationConfig": {
"targetLanguageCode": "pl",
"echoTargetLanguage": true
}
}
}
استخدام الرموز المميزة المؤقتة في التطبيقات من جهة العميل
بالنسبة إلى التطبيقات التي تتواصل بين العميل والخادم، يمكنك استخدام الرموز المميزة المؤقتة (المتوفّرة حاليًا في v1beta) لتجنُّب الكشف عن مفتاح واجهة برمجة التطبيقات.
عند استخدام الرموز المميزة المؤقتة مع ميزة "الترجمة المباشرة":
- يجب استخدام نقطة النهاية
v1beta. - إعدادات القفل: بشكلٍ تلقائي، يجب تحديد
translationConfigفي قيود إنشاء الرمز المميّز على خادمك. يضمن ذلك أنّ إعدادات الترجمة مقفلة ولا يمكن للعميل التلاعب بها. - إعدادات إلغاء القفل: إذا كنت تريد أن تتمكّن من ضبط
translationConfigمن جهة العميل (على سبيل المثال، للسماح للمستخدم باختيار اللغة المستهدَفة)، عليك إغفالها من طلب إنشاء الرمز المميّز وضبط"lock_additional_fields": []بدلاً من ذلك. سيؤدي ذلك إلى إتاحة ضبطtranslationConfigمن جهة العميل.
إنشاء رمز مميّز مؤقت محدود
توضّح الأمثلة التالية كيفية إنشاء رمز مميز مؤقت مع قيود الترجمة.
Python
import datetime
from google import genai
now = datetime.datetime.now(tz=datetime.timezone.utc)
client = genai.Client()
token = client.auth_tokens.create(
config = {
'uses': 1,
'expire_time': now + datetime.timedelta(minutes=30),
'live_connect_constraints': {
'model': 'gemini-3.5-live-translate-preview',
'config': {
'translation_config': {
'target_language_code': 'pl',
'echo_target_language': True
}
}
},
}
)
JavaScript
import { GoogleGenAI } from "@google/genai";
const client = new GoogleGenAI({});
const expireTime = new Date(Date.now() + 30 * 60 * 1000).toISOString();
const token = await client.authTokens.create({
config: {
uses: 1,
expireTime: expireTime,
liveConnectConstraints: {
model: 'gemini-3.5-live-translate-preview',
config: {
responseModalities: ['AUDIO'],
inputAudioTranscription: {},
outputAudioTranscription: {},
translationConfig: {
targetLanguageCode: 'pl',
echoTargetLanguage: true
}
}
},
},
});
REST
curl -X POST "https://generativelanguage.googleapis.com/v1beta/auth_tokens" \
-H "x-goog-api-key: ${GEMINI_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"uses": 1,
"expireTime": "YYYY-MM-DDTHH:MM:SSZ",
"liveConnectConstraints": {
"model": "models/gemini-3.5-live-translate-preview",
"config": {
"responseModalities": ["AUDIO"],
"inputAudioTranscription": {},
"outputAudioTranscription": {},
"translationConfig": {
"targetLanguageCode": "pl",
"echoTargetLanguage": true
}
}
}
}'
القيود
- طُرق الإدخال: لا تتوفّر الترجمة إلا من خلال إدخال الصوت. لا يمكن إدخال نص.
- تقليد الصوت: قد يكون تقليد الصوت غير متسق. قد تتغير الأصوات بعد فترات توقّف طويلة، أو يتم تحديد الجنس بشكل خاطئ استنادًا إلى طريقة بدء الكلام، أو قد يتم استخدام صوت واحد فقط أثناء المحادثات السريعة التي يشارك فيها عدة متحدثين.
- اكتشاف اللغة: يواجه نظام اكتشاف اللغة صعوبة في التعرّف على اللهجات الثقيلة أو اللغات المتشابهة (مثل الإسبانية والبرتغالية) أو التبديل السريع بين اللغات. ملاحظة: من المفترض أن يؤثر ذلك في نص الإدخال فقط. يجب أن تظل رموز اللغة والترجمة النهائية دقيقة.
- الصوت في الخلفية: تم تصميم النموذج لفلترة الضوضاء والموسيقى لإنتاج كلام واضح، ولكن قد لا يتم تجاهل كل الصوت في الخلفية.
- لغة الاستهداف Echo: عند تفعيل
echoTargetLanguage: true، قد تؤدي الضوضاء في الخلفية أو الموسيقى إلى حدوث تشوّش في الصوت المترجَم عندما يكون الصوت المُدخَل باللغة المستهدَفة.
اللغات المتاحة
تتوفّر ميزة "الترجمة المباشرة" باللغات التالية.
| اللغة | رمز BCP-47 | اللغة | رمز BCP-47 |
|---|---|---|---|
| الأفريقانية | af | الكازاخية | kk |
| الأكانية | ak | الخميرية | كلم |
| الألبانية | sq | الكينيارواندا | rw |
| الأمهرية | am | الكورية | ko |
| العربية | ar | لاو | lo |
| الأرمينية | hy | اللاتفية | lv |
| أذربيجان | az | الليتوانية | lt |
| الباسك | eu | المقدونية | mk |
| البيلاروسية | be | الماليزية | مللي ثانية |
| البنغالية | bn | المالايالامية | ml |
| البلغارية | bg | المراثية | mr |
| البورمية (ميانمار) | my | المنغولية | mn |
| الكتالانية | ca | النيبالية | ne |
| الصينية (المبسطة) | zh-Hans | النرويجية | no, nb |
| الصينية (التقليدية) | zh-Hant | الفارسية | fa |
| الكرواتية | ساعة | البولندية | pl |
| التشيكية | cs | البرتغالية (البرازيل) | pt-BR |
| الدانماركية | da | برتغالي (البرتغال) | pt-PT |
| الهولندية | nl | البنجابية | pa |
| الإنجليزية | en | الرومانية | ro |
| الإستونية | et | الروسية | ru |
| الفلبينية | fil | الصربية | sr |
| الفنلندية | fi | السندية | دقة عادية |
| الفرنسية | fr | السنهالية | si |
| الغليشيانية | gl | السلوفاكية | sk |
| الجورجية | ka | السلوفينية | sl |
| الألمانية | de | الإسبانية | es |
| اليونانية | el | السندانية | su |
| الغوجاراتية | gu | السواحيلية | sw |
| الهوسا | هكتار | السويدية | sv |
| العبرية | هو | التاميلية | ta |
| الهندية | hi | التيلوغوية | te |
| الهنغارية | hu | التايلاندية | th |
| الأيسلندية | هو | التركية | tr |
| الإندونيسية | id | الأوكرانية | uk |
| الإيطالية | it | الأوردية | ur |
| اليابانية | ja | الأوزبكية | uz |
| الجافانية | jv | الفيتنامية | vi |
| الكانادا | kn | الزولو | zu |
الخطوات التالية
- يمكنك الاطّلاع على دليل الإمكانات الكامل لواجهة برمجة التطبيقات Live API.
- اطّلِع على دليل بدء استخدام حزمة تطوير البرامج (SDK).
- اطّلِع على دليل بدء استخدام WebSockets.
- اطّلِع على دليل الرموز المميزة المؤقتة لإجراء مصادقة آمنة في التطبيقات التي تتواصل بين العميل والخادم.
- استنسِخ أمثلة Live API من GitHub.