تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

Live API capabilities guide

هذا دليل شامل يتناول الإمكانات والإعدادات المتاحة من خلال Live API. راجِع صفحة بدء استخدام Live API للحصول على نظرة عامة ورمز نموذجي لحالات الاستخدام الشائعة.

قبل البدء

التعرّف على المفاهيم الأساسية: إذا لم يسبق لك ذلك، ننصحك بقراءة صفحة البدء باستخدام Live API أولاً. سنتعرّف في هذا القسم على المبادئ الأساسية لواجهة برمجة التطبيقات Live API وطريقة عملها ومختلف طرق التنفيذ.
تجربة Live API في AI Studio: قد يكون من المفيد تجربة Live API في Google AI Studio قبل البدء في إنشاء التطبيقات. لاستخدام Live API في Google AI Studio، انقر على بث (Stream).

إنشاء اتصال

يوضّح المثال التالي كيفية إنشاء اتصال باستخدام مفتاح واجهة برمجة التطبيقات:

Python

import asyncio
from google import genai

client = genai.Client()

model = "gemini-2.5-flash-native-audio-preview-09-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({});
const model = 'gemini-2.5-flash-native-audio-preview-09-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();

طُرق التفاعل

تقدّم الأقسام التالية أمثلة وسياقًا داعمًا لمختلف أساليب الإدخال والإخراج المتاحة في Live API.

إرسال الصوت واستلامه

يتم تناول المثال الأكثر شيوعًا على الصوت، وهو الصوت إلى الصوت، في دليل البدء.

تنسيقات الصوت

تكون البيانات الصوتية في Live API دائمًا بتنسيق PCM غير مضغوط وبترتيب وحدات البايت الأصغر أولاً وبدقة 16 بت. يستخدم إخراج الصوت دائمًا معدّل بيانات يبلغ 24 كيلوهرتز. يكون معدّل البيانات في الملف الصوتي 16 كيلو هرتز بشكل تلقائي، ولكن ستعيد Live API أخذ عينات إذا لزم الأمر، ما يتيح إرسال أي معدّل بيانات في الملف الصوتي. لتحديد معدّل عيّنات الصوت المُدخَل، اضبط نوع MIME لكل Blob يحتوي على صوت على قيمة مثل audio/pcm;rate=16000.

جارٍ إرسال الرسالة النصية

إليك كيفية إرسال نص:

Python

message = "Hello, how are you?"
await session.send_client_content(turns=message, turn_complete=True)

JavaScript

const message = 'Hello, how are you?';
session.sendClientContent({ turns: message, turnComplete: true });

تعديلات المحتوى التدريجية

استخدِم التحديثات التزايدية لإرسال النص المُدخَل أو إنشاء سياق الجلسة أو استعادة سياق الجلسة. بالنسبة إلى السياقات القصيرة، يمكنك إرسال تفاعلات خطوة بخطوة لتمثيل التسلسل الدقيق للأحداث:

Python

turns = [
    {"role": "user", "parts": [{"text": "What is the capital of France?"}]},
    {"role": "model", "parts": [{"text": "Paris"}]},
]

await session.send_client_content(turns=turns, turn_complete=False)

turns = [{"role": "user", "parts": [{"text": "What is the capital of Germany?"}]}]

await session.send_client_content(turns=turns, turn_complete=True)

JavaScript

let inputTurns = [
  { "role": "user", "parts": [{ "text": "What is the capital of France?" }] },
  { "role": "model", "parts": [{ "text": "Paris" }] },
]

session.sendClientContent({ turns: inputTurns, turnComplete: false })

inputTurns = [{ "role": "user", "parts": [{ "text": "What is the capital of Germany?" }] }]

session.sendClientContent({ turns: inputTurns, turnComplete: true })

بالنسبة إلى السياقات الأطول، ننصحك بتقديم ملخّص لرسالة واحدة لإتاحة مساحة أكبر في قدرة الاستيعاب للتفاعلات اللاحقة. راجِع استئناف الجلسة للتعرّف على طريقة أخرى لتحميل سياق الجلسة.

النصوص المُحوَّلة من مقاطع صوتية

بالإضافة إلى ردّ النموذج، يمكنك أيضًا تلقّي نصوص لكل من الناتج الصوتي والمدخل الصوتي.

لتفعيل تحويل الصوت الذي يخرجه النموذج إلى نص، أرسِل output_audio_transcription في إعدادات الضبط. يتم استنتاج لغة تحويل الصوت إلى نص من ردّ النموذج.

Python

import asyncio
from google import genai
from google.genai import types

client = genai.Client()
model = "gemini-2.5-flash-native-audio-preview-09-2025"

config = {
    "response_modalities": ["AUDIO"],
    "output_audio_transcription": {}
}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        message = "Hello? Gemini are you there?"

        await session.send_client_content(
            turns={"role": "user", "parts": [{"text": message}]}, turn_complete=True
        )

        async for response in session.receive():
            if response.server_content.model_turn:
                print("Model turn:", response.server_content.model_turn)
            if response.server_content.output_transcription:
                print("Transcript:", response.server_content.output_transcription.text)

if __name__ == "__main__":
    asyncio.run(main())

JavaScript

import { GoogleGenAI, Modality } from '@google/genai';

const ai = new GoogleGenAI({});
const model = 'gemini-2.5-flash-native-audio-preview-09-2025';

const config = {
  responseModalities: [Modality.AUDIO],
  outputAudioTranscription: {}
};

async function live() {
  const responseQueue = [];

  async function waitMessage() {
    let done = false;
    let message = undefined;
    while (!done) {
      message = responseQueue.shift();
      if (message) {
        done = true;
      } else {
        await new Promise((resolve) => setTimeout(resolve, 100));
      }
    }
    return message;
  }

  async function handleTurn() {
    const turns = [];
    let done = false;
    while (!done) {
      const message = await waitMessage();
      turns.push(message);
      if (message.serverContent && message.serverContent.turnComplete) {
        done = true;
      }
    }
    return turns;
  }

  const session = await ai.live.connect({
    model: model,
    callbacks: {
      onopen: function () {
        console.debug('Opened');
      },
      onmessage: function (message) {
        responseQueue.push(message);
      },
      onerror: function (e) {
        console.debug('Error:', e.message);
      },
      onclose: function (e) {
        console.debug('Close:', e.reason);
      },
    },
    config: config,
  });

  const inputTurns = 'Hello how are you?';
  session.sendClientContent({ turns: inputTurns });

  const turns = await handleTurn();

  for (const turn of turns) {
    if (turn.serverContent && turn.serverContent.outputTranscription) {
      console.debug('Received output transcription: %s\n', turn.serverContent.outputTranscription.text);
    }
  }

  session.close();
}

async function main() {
  await live().catch((e) => console.error('got error', e));
}

main();

لتفعيل تحويل الصوت إلى نص، أرسِل input_audio_transcription في إعدادات الضبط.

Python

import asyncio
from pathlib import Path
from google import genai
from google.genai import types

client = genai.Client()
model = "gemini-2.5-flash-native-audio-preview-09-2025"

config = {
    "response_modalities": ["AUDIO"],
    "input_audio_transcription": {},
}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        audio_data = Path("16000.pcm").read_bytes()

        await session.send_realtime_input(
            audio=types.Blob(data=audio_data, mime_type='audio/pcm;rate=16000')
        )

        async for msg in session.receive():
            if msg.server_content.input_transcription:
                print('Transcript:', msg.server_content.input_transcription.text)

if __name__ == "__main__":
    asyncio.run(main())

JavaScript

import { GoogleGenAI, Modality } from '@google/genai';
import * as fs from "node:fs";
import pkg from 'wavefile';
const { WaveFile } = pkg;

const ai = new GoogleGenAI({});
const model = 'gemini-2.5-flash-native-audio-preview-09-2025';

const config = {
  responseModalities: [Modality.AUDIO],
  inputAudioTranscription: {}
};

async function live() {
  const responseQueue = [];

  async function waitMessage() {
    let done = false;
    let message = undefined;
    while (!done) {
      message = responseQueue.shift();
      if (message) {
        done = true;
      } else {
        await new Promise((resolve) => setTimeout(resolve, 100));
      }
    }
    return message;
  }

  async function handleTurn() {
    const turns = [];
    let done = false;
    while (!done) {
      const message = await waitMessage();
      turns.push(message);
      if (message.serverContent && message.serverContent.turnComplete) {
        done = true;
      }
    }
    return turns;
  }

  const session = await ai.live.connect({
    model: model,
    callbacks: {
      onopen: function () {
        console.debug('Opened');
      },
      onmessage: function (message) {
        responseQueue.push(message);
      },
      onerror: function (e) {
        console.debug('Error:', e.message);
      },
      onclose: function (e) {
        console.debug('Close:', e.reason);
      },
    },
    config: config,
  });

  // Send Audio Chunk
  const fileBuffer = fs.readFileSync("16000.wav");

  // Ensure audio conforms to API requirements (16-bit PCM, 16kHz, mono)
  const wav = new WaveFile();
  wav.fromBuffer(fileBuffer);
  wav.toSampleRate(16000);
  wav.toBitDepth("16");
  const base64Audio = wav.toBase64();

  // If already in correct format, you can use this:
  // const fileBuffer = fs.readFileSync("sample.pcm");
  // const base64Audio = Buffer.from(fileBuffer).toString('base64');

  session.sendRealtimeInput(
    {
      audio: {
        data: base64Audio,
        mimeType: "audio/pcm;rate=16000"
      }
    }
  );

  const turns = await handleTurn();
  for (const turn of turns) {
    if (turn.text) {
      console.debug('Received text: %s\n', turn.text);
    }
    else if (turn.data) {
      console.debug('Received inline data: %s\n', turn.data);
    }
    else if (turn.serverContent && turn.serverContent.inputTranscription) {
      console.debug('Received input transcription: %s\n', turn.serverContent.inputTranscription.text);
    }
  }

  session.close();
}

async function main() {
  await live().catch((e) => console.error('got error', e));
}

main();

بث الصوت والفيديو

تغيير الصوت واللغة

تتيح نماذج إخراج الصوت الأصلي استخدام أي من الأصوات المتاحة لنماذج تحويل النص إلى كلام (TTS). يمكنك الاستماع إلى جميع الأصوات في AI Studio.

لتحديد صوت، اضبط اسم الصوت ضمن الكائن speechConfig كجزء من إعدادات الجلسة:

Python

config = {
    "response_modalities": ["AUDIO"],
    "speech_config": {
        "voice_config": {"prebuilt_voice_config": {"voice_name": "Kore"}}
    },
}

JavaScript

const config = {
  responseModalities: [Modality.AUDIO],
  speechConfig: { voiceConfig: { prebuiltVoiceConfig: { voiceName: "Kore" } } }
};

تتيح Live API لغات متعددة. تختار نماذج إخراج الصوت الأصلي اللغة المناسبة تلقائيًا، ولا تتيح ضبط رمز اللغة بشكل صريح.

إمكانات الصوت المضمَّنة

تتضمّن أحدث نماذجنا إخراجًا صوتيًا مدمجًا، ما يتيح تقديم كلام طبيعي وواقعي وتحسين الأداء بلغات متعددة. يتيح الصوت الأصلي أيضًا ميزات متقدّمة، مثل الحوار العاطفي والصوت الاستباقي (حيث يقرّر النموذج بذكاء متى يردّ على الإدخال) و"التفكير".

حوار تفاعلي تعاطفي

تتيح هذه الميزة لـ Gemini تعديل أسلوب الردّ بما يتناسب مع التعبير والنبرة في الطلب.

لاستخدام الحوار العاطفي، اضبط إصدار واجهة برمجة التطبيقات على v1alpha واضبط enable_affective_dialog على true في رسالة الإعداد:

Python

client = genai.Client(http_options={"api_version": "v1alpha"})

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    enable_affective_dialog=True
)

JavaScript

const ai = new GoogleGenAI({ httpOptions: {"apiVersion": "v1alpha"} });

const config = {
  responseModalities: [Modality.AUDIO],
  enableAffectiveDialog: true
};

التحكّم التلقائي بالصوت

عند تفعيل هذه الميزة، يمكن أن يقرّر Gemini بشكل استباقي عدم الردّ إذا كان المحتوى غير ذي صلة.

لاستخدامها، اضبط إصدار واجهة برمجة التطبيقات على v1alpha واضبط الحقل proactivity في رسالة الإعداد واضبط proactive_audio على true:

Python

client = genai.Client(http_options={"api_version": "v1alpha"})

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    proactivity={'proactive_audio': True}
)

JavaScript

const ai = new GoogleGenAI({ httpOptions: {"apiVersion": "v1alpha"} });

const config = {
  responseModalities: [Modality.AUDIO],
  proactivity: { proactiveAudio: true }
}

جارٍ التفكير

يتوافق أحدث نموذج لإخراج الصوت الأصلي gemini-2.5-flash-native-audio-preview-09-2025 مع إمكانات التفكير، ويتم تفعيل التفكير الديناميكي تلقائيًا.

توجّه المَعلمة thinkingBudget النموذج بشأن عدد الرموز المميزة الخاصة بالتفكير التي يجب استخدامها عند إنشاء ردّ. يمكنك إيقاف التفكير من خلال ضبط thinkingBudget على 0. لمزيد من المعلومات حول تفاصيل إعدادات thinkingBudget الخاصة بالنموذج، يُرجى الاطّلاع على مستندات ميزانيات التفكير.

Python

model = "gemini-2.5-flash-native-audio-preview-09-2025"

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"]
    thinking_config=types.ThinkingConfig(
        thinking_budget=1024,
    )
)

async with client.aio.live.connect(model=model, config=config) as session:
    # Send audio input and receive audio

JavaScript

const model = 'gemini-2.5-flash-native-audio-preview-09-2025';
const config = {
  responseModalities: [Modality.AUDIO],
  thinkingConfig: {
    thinkingBudget: 1024,
  },
};

async function main() {

  const session = await ai.live.connect({
    model: model,
    config: config,
    callbacks: ...,
  });

  // Send audio input and receive audio

  session.close();
}

main();

بالإضافة إلى ذلك، يمكنك تفعيل ملخّصات الأفكار من خلال ضبط includeThoughts على true في الإعدادات. يمكنك الاطّلاع على ملخّصات الأفكار لمزيد من المعلومات:

Python

model = "gemini-2.5-flash-native-audio-preview-09-2025"

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"]
    thinking_config=types.ThinkingConfig(
        thinking_budget=1024,
        include_thoughts=True
    )
)

JavaScript

const model = 'gemini-2.5-flash-native-audio-preview-09-2025';
const config = {
  responseModalities: [Modality.AUDIO],
  thinkingConfig: {
    thinkingBudget: 1024,
    includeThoughts: true,
  },
};

التعرّف على النشاط الصوتي (VAD)

تتيح ميزة "رصد النشاط الصوتي" (VAD) للنموذج التعرّف على وقت تحدث شخص ما. وهذا أمر ضروري لإنشاء محادثات طبيعية، لأنّه يتيح للمستخدم مقاطعة النموذج في أي وقت.

عندما ترصد ميزة "النشاط الصوتي" انقطاعًا، يتم إلغاء عملية الإنشاء الجارية والتخلص منها. يتم الاحتفاظ فقط بالمعلومات التي تم إرسالها إلى العميل في سجلّ الجلسة. بعد ذلك، يرسل الخادم رسالة BidiGenerateContentServerContent للإبلاغ عن الانقطاع.

بعد ذلك، يتجاهل خادم Gemini أي طلبات معلّقة لاستدعاء الدوال ويرسل رسالة BidiGenerateContentServerContent تتضمّن أرقام تعريف الطلبات التي تم إلغاؤها.

Python

async for response in session.receive():
    if response.server_content.interrupted is True:
        # The generation was interrupted

        # If realtime playback is implemented in your application,
        # you should stop playing audio and clear queued playback here.

JavaScript

const turns = await handleTurn();

for (const turn of turns) {
  if (turn.serverContent && turn.serverContent.interrupted) {
    // The generation was interrupted

    // If realtime playback is implemented in your application,
    // you should stop playing audio and clear queued playback here.
  }
}

الكشف التلقائي عن النشاط الصوتي

بشكل تلقائي، ينفّذ النموذج ميزة "التعرّف على النشاط الصوتي" تلقائيًا على دفق مستمر من إدخال الصوت. يمكن ضبط VAD باستخدام الحقل realtimeInputConfig.automaticActivityDetection في إعدادات الضبط.

عند إيقاف بث الصوت مؤقتًا لأكثر من ثانية واحدة (على سبيل المثال، لأنّ المستخدم أوقف الميكروفون)، يجب إرسال حدث audioStreamEnd لمحو أي صوت مخزّن مؤقتًا. يمكن للعميل استئناف إرسال البيانات الصوتية في أي وقت.

Python

# example audio file to try:
# URL = "https://storage.googleapis.com/generativeai-downloads/data/hello_are_you_there.pcm"
# !wget -q $URL -O sample.pcm
import asyncio
from pathlib import Path
from google import genai
from google.genai import types

client = genai.Client()
model = "gemini-live-2.5-flash-preview"

config = {"response_modalities": ["TEXT"]}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        audio_bytes = Path("sample.pcm").read_bytes()

        await session.send_realtime_input(
            audio=types.Blob(data=audio_bytes, mime_type="audio/pcm;rate=16000")
        )

        # if stream gets paused, send:
        # await session.send_realtime_input(audio_stream_end=True)

        async for response in session.receive():
            if response.text is not None:
                print(response.text)

if __name__ == "__main__":
    asyncio.run(main())

JavaScript

// example audio file to try:
// URL = "https://storage.googleapis.com/generativeai-downloads/data/hello_are_you_there.pcm"
// !wget -q $URL -O sample.pcm
import { GoogleGenAI, Modality } from '@google/genai';
import * as fs from "node:fs";

const ai = new GoogleGenAI({});
const model = 'gemini-live-2.5-flash-preview';
const config = { responseModalities: [Modality.TEXT] };

async function live() {
  const responseQueue = [];

  async function waitMessage() {
    let done = false;
    let message = undefined;
    while (!done) {
      message = responseQueue.shift();
      if (message) {
        done = true;
      } else {
        await new Promise((resolve) => setTimeout(resolve, 100));
      }
    }
    return message;
  }

  async function handleTurn() {
    const turns = [];
    let done = false;
    while (!done) {
      const message = await waitMessage();
      turns.push(message);
      if (message.serverContent && message.serverContent.turnComplete) {
        done = true;
      }
    }
    return turns;
  }

  const session = await ai.live.connect({
    model: model,
    callbacks: {
      onopen: function () {
        console.debug('Opened');
      },
      onmessage: function (message) {
        responseQueue.push(message);
      },
      onerror: function (e) {
        console.debug('Error:', e.message);
      },
      onclose: function (e) {
        console.debug('Close:', e.reason);
      },
    },
    config: config,
  });

  // Send Audio Chunk
  const fileBuffer = fs.readFileSync("sample.pcm");
  const base64Audio = Buffer.from(fileBuffer).toString('base64');

  session.sendRealtimeInput(
    {
      audio: {
        data: base64Audio,
        mimeType: "audio/pcm;rate=16000"
      }
    }

  );

  // if stream gets paused, send:
  // session.sendRealtimeInput({ audioStreamEnd: true })

  const turns = await handleTurn();
  for (const turn of turns) {
    if (turn.text) {
      console.debug('Received text: %s\n', turn.text);
    }
    else if (turn.data) {
      console.debug('Received inline data: %s\n', turn.data);
    }
  }

  session.close();
}

async function main() {
  await live().catch((e) => console.error('got error', e));
}

main();

باستخدام send_realtime_input، ستستجيب واجهة برمجة التطبيقات تلقائيًا للصوت استنادًا إلى VAD. في حين أنّ send_client_content يضيف الرسائل إلى سياق النموذج بالترتيب، تم تحسين send_realtime_input لتحقيق سرعة الاستجابة على حساب الترتيب الحتمي.

إعدادات VAD التلقائية

لمزيد من التحكّم في نشاط "التعرّف التلقائي على الصوت"، يمكنك ضبط المَعلمات التالية. يمكنك الاطّلاع على مرجع واجهة برمجة التطبيقات للحصول على مزيد من المعلومات.

Python

from google.genai import types

config = {
    "response_modalities": ["TEXT"],
    "realtime_input_config": {
        "automatic_activity_detection": {
            "disabled": False, # default
            "start_of_speech_sensitivity": types.StartSensitivity.START_SENSITIVITY_LOW,
            "end_of_speech_sensitivity": types.EndSensitivity.END_SENSITIVITY_LOW,
            "prefix_padding_ms": 20,
            "silence_duration_ms": 100,
        }
    }
}

JavaScript

import { GoogleGenAI, Modality, StartSensitivity, EndSensitivity } from '@google/genai';

const config = {
  responseModalities: [Modality.TEXT],
  realtimeInputConfig: {
    automaticActivityDetection: {
      disabled: false, // default
      startOfSpeechSensitivity: StartSensitivity.START_SENSITIVITY_LOW,
      endOfSpeechSensitivity: EndSensitivity.END_SENSITIVITY_LOW,
      prefixPaddingMs: 20,
      silenceDurationMs: 100,
    }
  }
};

إيقاف ميزة "التعرّف التلقائي على النشاط الصوتي"

بدلاً من ذلك، يمكن إيقاف ميزة VAD التلقائية من خلال ضبط realtimeInputConfig.automaticActivityDetection.disabled على true في رسالة الإعداد. في هذا الإعداد، يكون العميل مسؤولاً عن رصد كلام المستخدم وإرسال رسالتَي activityStart وactivityEnd في الأوقات المناسبة. لا يتم إرسال audioStreamEnd في هذا الإعداد. بدلاً من ذلك، يتم تمييز أي انقطاع في البث برسالة activityEnd.

Python

config = {
    "response_modalities": ["TEXT"],
    "realtime_input_config": {"automatic_activity_detection": {"disabled": True}},
}

async with client.aio.live.connect(model=model, config=config) as session:
    # ...
    await session.send_realtime_input(activity_start=types.ActivityStart())
    await session.send_realtime_input(
        audio=types.Blob(data=audio_bytes, mime_type="audio/pcm;rate=16000")
    )
    await session.send_realtime_input(activity_end=types.ActivityEnd())
    # ...

JavaScript

const config = {
  responseModalities: [Modality.TEXT],
  realtimeInputConfig: {
    automaticActivityDetection: {
      disabled: true,
    }
  }
};

session.sendRealtimeInput({ activityStart: {} })

session.sendRealtimeInput(
  {
    audio: {
      data: base64Audio,
      mimeType: "audio/pcm;rate=16000"
    }
  }

);

session.sendRealtimeInput({ activityEnd: {} })

عدد الرموز المميّزة

يمكنك العثور على إجمالي عدد الرموز المميزة المستهلكة في الحقل usageMetadata ضمن رسالة الخادم التي تم إرجاعها.

Python

async for message in session.receive():
    # The server will periodically send messages that include UsageMetadata.
    if message.usage_metadata:
        usage = message.usage_metadata
        print(
            f"Used {usage.total_token_count} tokens in total. Response token breakdown:"
        )
        for detail in usage.response_tokens_details:
            match detail:
                case types.ModalityTokenCount(modality=modality, token_count=count):
                    print(f"{modality}: {count}")

JavaScript

const turns = await handleTurn();

for (const turn of turns) {
  if (turn.usageMetadata) {
    console.debug('Used %s tokens in total. Response token breakdown:\n', turn.usageMetadata.totalTokenCount);

    for (const detail of turn.usageMetadata.responseTokensDetails) {
      console.debug('%s\n', detail);
    }
  }
}

درجة دقة الوسائط

يمكنك تحديد دقة الوسائط للإدخال عن طريق ضبط الحقل mediaResolution كجزء من إعدادات الجلسة:

Python

from google.genai import types

config = {
    "response_modalities": ["AUDIO"],
    "media_resolution": types.MediaResolution.MEDIA_RESOLUTION_LOW,
}

JavaScript

import { GoogleGenAI, Modality, MediaResolution } from '@google/genai';

const config = {
    responseModalities: [Modality.TEXT],
    mediaResolution: MediaResolution.MEDIA_RESOLUTION_LOW,
};

القيود

يُرجى مراعاة القيود التالية في Live API عند التخطيط لمشروعك.

طُرق الاستجابة

يمكنك ضبط طريقة رد واحدة فقط (TEXT أو AUDIO) لكل جلسة في إعدادات الجلسة. سيؤدي ضبط كليهما إلى ظهور رسالة خطأ في الإعدادات. وهذا يعني أنّه يمكنك ضبط النموذج للردّ إما بالنص أو بالصوت، ولكن ليس بكليهما في الجلسة نفسها.

مصادقة البرنامج

لا توفّر Live API تلقائيًا سوى مصادقة الخادم إلى الخادم. إذا كنت تنفّذ تطبيق Live API باستخدام أسلوب من العميل إلى الخادم، عليك استخدام رموز مميزة مؤقتة للحدّ من المخاطر الأمنية.

مدة الجلسة

تقتصر مدة الجلسات الصوتية فقط على 15 دقيقة، بينما تقتصر مدة الجلسات الصوتية والمرئية على دقيقتَين. ومع ذلك، يمكنك ضبط تقنيات مختلفة لإدارة الجلسات من أجل إضافات غير محدودة بشأن مدة الجلسة.

قدرة الاستيعاب

يبلغ الحدّ الأقصى لقدرة الاستيعاب في الجلسة:

‫128 ألف رمز مميز لنماذج إخراج الصوت الأصلي
‫32 ألف رمز مميز لطُرز Live API الأخرى

اللغات المتاحة

تتوفّر Live API باللغات التالية.

اللغة	رمز BCP-47	اللغة	رمز BCP-47
الألمانية (ألمانيا)	`de-DE`	الإنجليزية (أستراليا)*	`en-AU`
الإنجليزية (المملكة المتحدة)*	`en-GB`	الإنجليزية (الهند)	`en-IN`
الإنجليزية (الولايات المتحدة)	`en-US`	الإسبانية (الولايات المتحدة)	`es-US`
الفرنسية (فرنسا)	`fr-FR`	الهندية (الهند)	`hi-IN`
البرتغالية (البرازيل)	`pt-BR`	العربية (عامة)	`ar-XA`
الإسبانية (إسبانيا)*	`es-ES`	الفرنسية (كندا)*	`fr-CA`
الإندونيسية (إندونيسيا)	`id-ID`	الإيطالية (إيطاليا)	`it-IT`
اليابانية (اليابان)	`ja-JP`	التركية (تركيا)	`tr-TR`
الفيتنامية (فيتنام)	`vi-VN`	البنغالية (الهند)	`bn-IN`
الغوجاراتية (الهند)*	`gu-IN`	الكانادا (الهند)*	`kn-IN`
الماراثية (الهند)	`mr-IN`	المالايالامية (الهند)*	`ml-IN`
التاميلية (الهند)	`ta-IN`	التيلوغوية (الهند)	`te-IN`
الهولندية (هولندا)	`nl-NL`	الكورية (كوريا الجنوبية)	`ko-KR`
الصينية (الماندرين) (الصين)*	`cmn-CN`	البولندية (بولندا)	`pl-PL`
الروسية (روسيا)	`ru-RU`	التايلاندية (تايلاند)	`th-TH`

اللغات التي تحمل علامة نجمة (*) غير متاحة في الصوت الأصلي.

الخطوات التالية

يمكنك الاطّلاع على دليلَي استخدام الأدوات وإدارة الجلسات للحصول على معلومات أساسية حول استخدام Live API بفعالية.
جرِّب Live API في Google AI Studio.
لمزيد من المعلومات حول نماذج Live API، يُرجى الاطّلاع على Gemini 2.5 Flash Native Audio في صفحة "النماذج".
يمكنك الاطّلاع على المزيد من الأمثلة في كتاب وصفات Live API وكتاب وصفات أدوات Live API ونص Live API Get Started البرمجي.