با استفاده از WebSockets، کار با Gemini Live API را شروع کنید

رابط برنامه‌نویسی نرم‌افزار Gemini Live امکان تعامل دوطرفه و بلادرنگ با مدل‌های Gemini را فراهم می‌کند و از ورودی‌های صوتی، تصویری و متنی و خروجی‌های صوتی بومی پشتیبانی می‌کند. این راهنما نحوه ادغام مستقیم با API را با استفاده از WebSockets خام توضیح می‌دهد.

نمای کلی

رابط برنامه‌نویسی Gemini Live از WebSockets برای ارتباط بلادرنگ استفاده می‌کند. برخلاف استفاده از SDK، این رویکرد شامل مدیریت مستقیم اتصال WebSocket و ارسال/دریافت پیام‌ها در قالب JSON خاصی است که توسط API تعریف شده است.

مفاهیم کلیدی:

• WebSocket Endpoint : آدرس اینترنتی (URL) مشخصی که باید به آن متصل شوید.
• قالب پیام : تمام ارتباطات از طریق پیام‌های JSON مطابق با ساختارهای BidiGenerateContentClientMessage و BidiGenerateContentServerMessage انجام می‌شود.
• مدیریت جلسه : شما مسئول حفظ اتصال WebSocket هستید.

احراز هویت

احراز هویت با وارد کردن کلید API شما به عنوان یک پارامتر پرس و جو در URL وب‌ساکت انجام می‌شود.

قالب نقطه پایانی به صورت زیر است:

کپی کدwss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent?key=YOUR_API_KEY

به جای YOUR_API_KEY ، کلید API واقعی خود را قرار دهید.

احراز هویت با توکن‌های موقت

اگر از توکن‌های موقت استفاده می‌کنید، باید به نقطه پایانی v1beta متصل شوید. توکن موقت باید به عنوان پارامتر پرس‌وجوی access_token ارسال شود.

قالب نقطه پایانی برای کلیدهای موقت به صورت زیر است:

کپی کدwss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContentConstrained?access_token={short-lived-token}

{short-lived-token} را با توکن موقت واقعی جایگزین کنید.

اتصال به API زنده

برای شروع یک جلسه زنده، یک اتصال WebSocket به نقطه پایانی احراز هویت شده برقرار کنید. اولین پیام ارسال شده از طریق WebSocket باید یک BidiGenerateContentSetup حاوی config باشد. برای گزینه‌های کامل پیکربندی، به مرجع Live API - WebSockets API مراجعه کنید.

کپی کدimport asyncio
import websockets
import json

API_KEY = "YOUR_API_KEY"
MODEL_NAME = "gemini-3.8-live"
WS_URL = f"wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent?key={API_KEY}"

async def connect_and_configure():
    async with websockets.connect(WS_URL) as websocket:
        print("WebSocket Connected")

        # 1. Send the initial configuration
        setup_message = {
            "setup": {
                "model": f"models/{MODEL_NAME}",
                "responseModalities": ["AUDIO"],
                "systemInstruction": {
                    "parts": [{"text": "You are a helpful assistant."}]
                }
            }
        }
        await websocket.send(json.dumps(setup_message))
        print("Configuration sent")

        # Keep the session alive for further interactions
        await asyncio.sleep(3600) # Example: keep open for an hour

async def main():
    await connect_and_configure()

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

کپی کدconst API_KEY = "YOUR_API_KEY";
const MODEL_NAME = "gemini-3.8-live";
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');

  // 1. Send the initial configuration
  const setupMessage = {
    setup: {
      model: `models/${MODEL_NAME}`,
      responseModalities: ['AUDIO'],
      systemInstruction: {
        parts: [{ text: 'You are a helpful assistant.' }]
      }
    }
  };
  websocket.send(JSON.stringify(setupMessage));
  console.log('Configuration sent');
};

websocket.onmessage = (event) => {
  const response = JSON.parse(event.data);
  console.log('Received:', response);
  // Handle different types of responses here
};

websocket.onerror = (error) => {
  console.error('WebSocket Error:', error);
};

websocket.onclose = () => {
  console.log('WebSocket Closed');
};

ارسال متن

برای ارسال ورودی متن، یک پیام BidiGenerateContentRealtimeInput با فیلد text بسازید.

کپی کد# Inside the websocket context
async def send_text(websocket, text):
    text_message = {
        "realtimeInput": {
            "text": text
        }
    }
    await websocket.send(json.dumps(text_message))
    print(f"Sent text: {text}")

# Example usage: await send_text(websocket, "Hello, how are you?")

کپی کدfunction sendTextMessage(text) {
  if (websocket.readyState === WebSocket.OPEN) {
    const textMessage = {
      realtimeInput: {
        text: text
      }
    };
    websocket.send(JSON.stringify(textMessage));
    console.log('Text message sent:', text);
  } else {
    console.warn('WebSocket not open.');
  }
}

// Example usage:
sendTextMessage("Hello, how are you?");

ارسال صدا

صدا باید به صورت داده‌های خام PCM (صدای خام PCM شانزده بیتی، ۱۶ کیلوهرتز، little-endian) ارسال شود. یک پیام BidiGenerateContentRealtimeInput با داده‌های صوتی بسازید. mimeType بسیار مهم است.

کپی کد# Inside the websocket context
async def send_audio_chunk(websocket, chunk_bytes):
    import base64
    encoded_data = base64.b64encode(chunk_bytes).decode('utf-8')
    audio_message = {
        "realtimeInput": {
            "audio": {
                "data": encoded_data,
                "mimeType": "audio/pcm;rate=16000"
            }
        }
    }
    await websocket.send(json.dumps(audio_message))
    # print("Sent audio chunk") # Avoid excessive logging

# Assuming 'chunk' is your raw PCM audio bytes
# await send_audio_chunk(websocket, chunk)

کپی کد// 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));
    // console.log('Sent audio chunk');
  }
}
// Example usage: sendAudioChunk(audioBuffer);

برای مثالی از نحوه دریافت صدا از دستگاه کلاینت (مثلاً مرورگر)، به مثال سرتاسری در GitHub مراجعه کنید.

ارسال ویدیو

فریم‌های ویدیویی به صورت تصاویر مجزا (مثلاً JPEG یا PNG) ارسال می‌شوند. مشابه صدا، از realtimeInput با یک Blob استفاده کنید و mimeType صحیح را مشخص کنید.

کپی کد# Inside the websocket context
async def send_video_frame(websocket, frame_bytes, mime_type="image/jpeg"):
    import base64
    encoded_data = base64.b64encode(frame_bytes).decode('utf-8')
    video_message = {
        "realtimeInput": {
            "video": {
                "data": encoded_data,
                "mimeType": mime_type
            }
        }
    }
    await websocket.send(json.dumps(video_message))
    # print("Sent video frame")

# Assuming 'frame' is your JPEG-encoded image bytes
# await send_video_frame(websocket, frame)

کپی کد// Assuming 'frame' is a Buffer of JPEG-encoded image data
function sendVideoFrame(frame, mimeType = 'image/jpeg') {
  if (websocket.readyState === WebSocket.OPEN) {
    const videoMessage = {
      realtimeInput: {
        video: {
          data: frame.toString('base64'),
          mimeType: mimeType
        }
      }
    };
    websocket.send(JSON.stringify(videoMessage));
    // console.log('Sent video frame');
  }
}
// Example usage: sendVideoFrame(jpegBuffer);

برای مثالی از نحوه دریافت ویدیو از دستگاه کلاینت (مثلاً مرورگر)، به مثال سرتاسری در GitHub مراجعه کنید.

دریافت پاسخ‌ها

WebSocket پیام‌های BidiGenerateContentServerMessage را ارسال می‌کند. شما باید این پیام‌های JSON را تجزیه و تحلیل کرده و انواع مختلف محتوا را مدیریت کنید.

کپی کد# Inside the websocket context, in a receive loop
async def receive_loop(websocket):
    async for message in websocket:
        response = json.loads(message)
        print("Received:", response)

        if "serverContent" in response:
            server_content = response["serverContent"]
            # Receiving Audio
            if "modelTurn" in server_content and "parts" in server_content["modelTurn"]:
                for part in server_content["modelTurn"]["parts"]:
                    if "inlineData" in part:
                        audio_data_b64 = part["inlineData"]["data"]
                        # Process or play the base64 encoded audio data
                        # audio_data = base64.b64decode(audio_data_b64)
                        print(f"Received audio data (base64 len: {len(audio_data_b64)})")

            # Receiving Text Transcriptions
            if "inputTranscription" in server_content:
                print(f"User: {server_content['inputTranscription']['text']}")
            if "outputTranscription" in server_content:
                print(f"Gemini: {server_content['outputTranscription']['text']}")

        # Handling Tool Calls
        if "toolCall" in response:
            await handle_tool_call(websocket, response["toolCall"])

# Example usage: await receive_loop(websocket)

کپی کدwebsocket.onmessage = (event) => {
  const response = JSON.parse(event.data);
  console.log('Received:', response);

  if (response.serverContent) {
    const serverContent = response.serverContent;
    // Receiving Audio
    if (serverContent.modelTurn?.parts) {
      for (const part of serverContent.modelTurn.parts) {
        if (part.inlineData) {
          const audioData = part.inlineData.data; // Base64 encoded string
          // Process or play audioData
          console.log(`Received audio data (base64 len: ${audioData.length})`);
        }
      }
    }

    // Receiving Text Transcriptions
    if (serverContent.inputTranscription) {
      console.log('User:', serverContent.inputTranscription.text);
    }
    if (serverContent.outputTranscription) {
      console.log('Gemini:', serverContent.outputTranscription.text);
    }
  }

  // Handling Tool Calls
  if (response.toolCall) {
    handleToolCall(response.toolCall);
  }
};

برای مثالی از نحوه مدیریت پاسخ، به مثال سرتاسری در GitHub مراجعه کنید.

مدیریت فراخوانی‌های ابزار

وقتی مدل درخواست فراخوانی ابزار را می‌دهد، BidiGenerateContentServerMessage شامل یک فیلد toolCall خواهد بود. شما باید تابع را به صورت محلی اجرا کنید و نتیجه را با استفاده از یک پیام BidiGenerateContentToolResponse به WebSocket ارسال کنید.

کپی کد# Placeholder for your tool function
def my_tool_function(args):
    print(f"Executing tool with args: {args}")
    # Implement your tool logic here
    return {"status": "success", "data": "some result"}

async def handle_tool_call(websocket, tool_call):
    function_responses = []
    for fc in tool_call["functionCalls"]:
        # 1. Execute the function locally
        try:
            result = my_tool_function(fc.get("args", {}))
            response_data = {"result": result}
        except Exception as e:
            print(f"Error executing tool {fc['name']}: {e}")
            response_data = {"error": str(e)}

        # 2. Prepare the response
        function_responses.append({
            "name": fc["name"],
            "id": fc["id"],
            "response": response_data
        })

    # 3. Send the tool response back to the session
    tool_response_message = {
        "toolResponse": {
            "functionResponses": function_responses
        }
    }
    await websocket.send(json.dumps(tool_response_message))
    print("Sent tool response")

# This function is called within the receive_loop when a toolCall is detected.

کپی کد// Placeholder for your tool function
function myToolFunction(args) {
  console.log(`Executing tool with args:`, args);
  // Implement your tool logic here
  return { status: 'success', data: 'some result' };
}

function handleToolCall(toolCall) {
  const functionResponses = [];
  for (const fc of toolCall.functionCalls) {
    // 1. Execute the function locally
    let result;
    try {
      result = myToolFunction(fc.args || {});
    } catch (e) {
      console.error(`Error executing tool ${fc.name}:`, e);
      result = { error: e.message };
    }

    // 2. Prepare the response
    functionResponses.push({
      name: fc.name,
      id: fc.id,
      response: { result }
    });
  }

  // 3. Send the tool response back to the session
  if (websocket.readyState === WebSocket.OPEN) {
    const toolResponseMessage = {
      toolResponse: {
        functionResponses: functionResponses
      }
    };
    websocket.send(JSON.stringify(toolResponseMessage));
    console.log('Sent tool response');
  } else {
    console.warn('WebSocket not open to send tool response.');
  }
}
// This function is called within websocket.onmessage when a toolCall is detected.

قدم بعدی چیست؟

• برای آشنایی با قابلیت‌ها و پیکربندی‌های کلیدی، راهنمای کامل قابلیت‌های Live API را مطالعه کنید؛ از جمله تشخیص فعالیت صوتی و ویژگی‌های صوتی بومی.
• برای یادگیری نحوه ادغام Live API با ابزارها و فراخوانی توابع، راهنمای استفاده از ابزار را مطالعه کنید.
• برای مدیریت مکالمات طولانی مدت، راهنمای مدیریت جلسه را مطالعه کنید.
• برای احراز هویت امن در برنامه‌های کلاینت به سرور، راهنمای توکن‌های زودگذر را مطالعه کنید.
• برای اطلاعات بیشتر در مورد API مربوط به WebSockets، به مرجع API مربوط به WebSockets مراجعه کنید.

رابط برنامه‌نویسی نرم‌افزار Gemini Live امکان تعامل دوطرفه و بلادرنگ با مدل‌های Gemini را فراهم می‌کند و از ورودی‌های صوتی، تصویری و متنی و خروجی‌های صوتی بومی پشتیبانی می‌کند. این راهنما نحوه ادغام مستقیم با API را با استفاده از WebSockets خام توضیح می‌دهد.

نمای کلی

رابط برنامه‌نویسی Gemini Live از WebSockets برای ارتباط بلادرنگ استفاده می‌کند. برخلاف استفاده از SDK، این رویکرد شامل مدیریت مستقیم اتصال WebSocket و ارسال/دریافت پیام‌ها در قالب JSON خاصی است که توسط API تعریف شده است.

مفاهیم کلیدی:

• WebSocket Endpoint : آدرس اینترنتی (URL) مشخصی که باید به آن متصل شوید.
• قالب پیام : تمام ارتباطات از طریق پیام‌های JSON مطابق با ساختارهای BidiGenerateContentClientMessage و BidiGenerateContentServerMessage انجام می‌شود.
• مدیریت جلسه : شما مسئول حفظ اتصال WebSocket هستید.

احراز هویت

احراز هویت با وارد کردن کلید API شما به عنوان یک پارامتر پرس و جو در URL وب‌ساکت انجام می‌شود.

قالب نقطه پایانی به صورت زیر است:

کپی کدwss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent?key=YOUR_API_KEY

به جای YOUR_API_KEY ، کلید API واقعی خود را قرار دهید.

احراز هویت با توکن‌های موقت

اگر از توکن‌های موقت استفاده می‌کنید، باید به نقطه پایانی v1beta متصل شوید. توکن موقت باید به عنوان پارامتر پرس‌وجوی access_token ارسال شود.

قالب نقطه پایانی برای کلیدهای موقت به صورت زیر است:

کپی کدwss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContentConstrained?access_token={short-lived-token}

{short-lived-token} را با توکن موقت واقعی جایگزین کنید.

اتصال به API زنده

برای شروع یک جلسه زنده، یک اتصال WebSocket به نقطه پایانی احراز هویت شده برقرار کنید. اولین پیام ارسال شده از طریق WebSocket باید یک BidiGenerateContentSetup حاوی config باشد. برای گزینه‌های کامل پیکربندی، به مرجع Live API - WebSockets API مراجعه کنید.

کپی کدimport asyncio
import websockets
import json

API_KEY = "YOUR_API_KEY"
MODEL_NAME = "gemini-3.8-live"
WS_URL = f"wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent?key={API_KEY}"

async def connect_and_configure():
    async with websockets.connect(WS_URL) as websocket:
        print("WebSocket Connected")

        # 1. Send the initial configuration
        setup_message = {
            "setup": {
                "model": f"models/{MODEL_NAME}",
                "responseModalities": ["AUDIO"],
                "systemInstruction": {
                    "parts": [{"text": "You are a helpful assistant."}]
                }
            }
        }
        await websocket.send(json.dumps(setup_message))
        print("Configuration sent")

        # Keep the session alive for further interactions
        await asyncio.sleep(3600) # Example: keep open for an hour

async def main():
    await connect_and_configure()

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

کپی کدconst API_KEY = "YOUR_API_KEY";
const MODEL_NAME = "gemini-3.8-live";
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');

  // 1. Send the initial configuration
  const setupMessage = {
    setup: {
      model: `models/${MODEL_NAME}`,
      responseModalities: ['AUDIO'],
      systemInstruction: {
        parts: [{ text: 'You are a helpful assistant.' }]
      }
    }
  };
  websocket.send(JSON.stringify(setupMessage));
  console.log('Configuration sent');
};

websocket.onmessage = (event) => {
  const response = JSON.parse(event.data);
  console.log('Received:', response);
  // Handle different types of responses here
};

websocket.onerror = (error) => {
  console.error('WebSocket Error:', error);
};

websocket.onclose = () => {
  console.log('WebSocket Closed');
};

ارسال متن

برای ارسال ورودی متن، یک پیام BidiGenerateContentRealtimeInput با فیلد text بسازید.

کپی کد# Inside the websocket context
async def send_text(websocket, text):
    text_message = {
        "realtimeInput": {
            "text": text
        }
    }
    await websocket.send(json.dumps(text_message))
    print(f"Sent text: {text}")

# Example usage: await send_text(websocket, "Hello, how are you?")

کپی کدfunction sendTextMessage(text) {
  if (websocket.readyState === WebSocket.OPEN) {
    const textMessage = {
      realtimeInput: {
        text: text
      }
    };
    websocket.send(JSON.stringify(textMessage));
    console.log('Text message sent:', text);
  } else {
    console.warn('WebSocket not open.');
  }
}

// Example usage:
sendTextMessage("Hello, how are you?");

ارسال صدا

صدا باید به صورت داده‌های خام PCM (صدای خام PCM شانزده بیتی، ۱۶ کیلوهرتز، little-endian) ارسال شود. یک پیام BidiGenerateContentRealtimeInput با داده‌های صوتی بسازید. mimeType بسیار مهم است.

کپی کد# Inside the websocket context
async def send_audio_chunk(websocket, chunk_bytes):
    import base64
    encoded_data = base64.b64encode(chunk_bytes).decode('utf-8')
    audio_message = {
        "realtimeInput": {
            "audio": {
                "data": encoded_data,
                "mimeType": "audio/pcm;rate=16000"
            }
        }
    }
    await websocket.send(json.dumps(audio_message))
    # print("Sent audio chunk") # Avoid excessive logging

# Assuming 'chunk' is your raw PCM audio bytes
# await send_audio_chunk(websocket, chunk)

کپی کد// 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));
    // console.log('Sent audio chunk');
  }
}
// Example usage: sendAudioChunk(audioBuffer);

برای مثالی از نحوه دریافت صدا از دستگاه کلاینت (مثلاً مرورگر)، به مثال سرتاسری در GitHub مراجعه کنید.

ارسال ویدیو

فریم‌های ویدیویی به صورت تصاویر مجزا (مثلاً JPEG یا PNG) ارسال می‌شوند. مشابه صدا، از realtimeInput با یک Blob استفاده کنید و mimeType صحیح را مشخص کنید.

کپی کد# Inside the websocket context
async def send_video_frame(websocket, frame_bytes, mime_type="image/jpeg"):
    import base64
    encoded_data = base64.b64encode(frame_bytes).decode('utf-8')
    video_message = {
        "realtimeInput": {
            "video": {
                "data": encoded_data,
                "mimeType": mime_type
            }
        }
    }
    await websocket.send(json.dumps(video_message))
    # print("Sent video frame")

# Assuming 'frame' is your JPEG-encoded image bytes
# await send_video_frame(websocket, frame)

کپی کد// Assuming 'frame' is a Buffer of JPEG-encoded image data
function sendVideoFrame(frame, mimeType = 'image/jpeg') {
  if (websocket.readyState === WebSocket.OPEN) {
    const videoMessage = {
      realtimeInput: {
        video: {
          data: frame.toString('base64'),
          mimeType: mimeType
        }
      }
    };
    websocket.send(JSON.stringify(videoMessage));
    // console.log('Sent video frame');
  }
}
// Example usage: sendVideoFrame(jpegBuffer);

برای مثالی از نحوه دریافت ویدیو از دستگاه کلاینت (مثلاً مرورگر)، به مثال سرتاسری در GitHub مراجعه کنید.

دریافت پاسخ‌ها

WebSocket پیام‌های BidiGenerateContentServerMessage را ارسال می‌کند. شما باید این پیام‌های JSON را تجزیه و تحلیل کرده و انواع مختلف محتوا را مدیریت کنید.

کپی کد# Inside the websocket context, in a receive loop
async def receive_loop(websocket):
    async for message in websocket:
        response = json.loads(message)
        print("Received:", response)

        if "serverContent" in response:
            server_content = response["serverContent"]
            # Receiving Audio
            if "modelTurn" in server_content and "parts" in server_content["modelTurn"]:
                for part in server_content["modelTurn"]["parts"]:
                    if "inlineData" in part:
                        audio_data_b64 = part["inlineData"]["data"]
                        # Process or play the base64 encoded audio data
                        # audio_data = base64.b64decode(audio_data_b64)
                        print(f"Received audio data (base64 len: {len(audio_data_b64)})")

            # Receiving Text Transcriptions
            if "inputTranscription" in server_content:
                print(f"User: {server_content['inputTranscription']['text']}")
            if "outputTranscription" in server_content:
                print(f"Gemini: {server_content['outputTranscription']['text']}")

        # Handling Tool Calls
        if "toolCall" in response:
            await handle_tool_call(websocket, response["toolCall"])

# Example usage: await receive_loop(websocket)

کپی کدwebsocket.onmessage = (event) => {
  const response = JSON.parse(event.data);
  console.log('Received:', response);

  if (response.serverContent) {
    const serverContent = response.serverContent;
    // Receiving Audio
    if (serverContent.modelTurn?.parts) {
      for (const part of serverContent.modelTurn.parts) {
        if (part.inlineData) {
          const audioData = part.inlineData.data; // Base64 encoded string
          // Process or play audioData
          console.log(`Received audio data (base64 len: ${audioData.length})`);
        }
      }
    }

    // Receiving Text Transcriptions
    if (serverContent.inputTranscription) {
      console.log('User:', serverContent.inputTranscription.text);
    }
    if (serverContent.outputTranscription) {
      console.log('Gemini:', serverContent.outputTranscription.text);
    }
  }

  // Handling Tool Calls
  if (response.toolCall) {
    handleToolCall(response.toolCall);
  }
};

برای مثالی از نحوه مدیریت پاسخ، به مثال سرتاسری در GitHub مراجعه کنید.

مدیریت فراخوانی‌های ابزار

وقتی مدل درخواست فراخوانی ابزار را می‌دهد، BidiGenerateContentServerMessage شامل یک فیلد toolCall خواهد بود. شما باید تابع را به صورت محلی اجرا کنید و نتیجه را با استفاده از یک پیام BidiGenerateContentToolResponse به WebSocket ارسال کنید.

کپی کد# Placeholder for your tool function
def my_tool_function(args):
    print(f"Executing tool with args: {args}")
    # Implement your tool logic here
    return {"status": "success", "data": "some result"}

async def handle_tool_call(websocket, tool_call):
    function_responses = []
    for fc in tool_call["functionCalls"]:
        # 1. Execute the function locally
        try:
            result = my_tool_function(fc.get("args", {}))
            response_data = {"result": result}
        except Exception as e:
            print(f"Error executing tool {fc['name']}: {e}")
            response_data = {"error": str(e)}

        # 2. Prepare the response
        function_responses.append({
            "name": fc["name"],
            "id": fc["id"],
            "response": response_data
        })

    # 3. Send the tool response back to the session
    tool_response_message = {
        "toolResponse": {
            "functionResponses": function_responses
        }
    }
    await websocket.send(json.dumps(tool_response_message))
    print("Sent tool response")

# This function is called within the receive_loop when a toolCall is detected.

کپی کد// Placeholder for your tool function
function myToolFunction(args) {
  console.log(`Executing tool with args:`, args);
  // Implement your tool logic here
  return { status: 'success', data: 'some result' };
}

function handleToolCall(toolCall) {
  const functionResponses = [];
  for (const fc of toolCall.functionCalls) {
    // 1. Execute the function locally
    let result;
    try {
      result = myToolFunction(fc.args || {});
    } catch (e) {
      console.error(`Error executing tool ${fc.name}:`, e);
      result = { error: e.message };
    }

    // 2. Prepare the response
    functionResponses.push({
      name: fc.name,
      id: fc.id,
      response: { result }
    });
  }

  // 3. Send the tool response back to the session
  if (websocket.readyState === WebSocket.OPEN) {
    const toolResponseMessage = {
      toolResponse: {
        functionResponses: functionResponses
      }
    };
    websocket.send(JSON.stringify(toolResponseMessage));
    console.log('Sent tool response');
  } else {
    console.warn('WebSocket not open to send tool response.');
  }
}
// This function is called within websocket.onmessage when a toolCall is detected.

قدم بعدی چیست؟

• برای آشنایی با قابلیت‌ها و پیکربندی‌های کلیدی، راهنمای کامل قابلیت‌های Live API را مطالعه کنید؛ از جمله تشخیص فعالیت صوتی و ویژگی‌های صوتی بومی.
• برای یادگیری نحوه ادغام Live API با ابزارها و فراخوانی توابع، راهنمای استفاده از ابزار را مطالعه کنید.
• برای مدیریت مکالمات طولانی مدت، راهنمای مدیریت جلسه را مطالعه کنید.
• برای احراز هویت امن در برنامه‌های کلاینت به سرور، راهنمای توکن‌های زودگذر را مطالعه کنید.
• برای اطلاعات بیشتر در مورد API مربوط به WebSockets، به مرجع API مربوط به WebSockets مراجعه کنید.

رابط برنامه‌نویسی نرم‌افزار Gemini Live امکان تعامل دوطرفه و بلادرنگ با مدل‌های Gemini را فراهم می‌کند و از ورودی‌های صوتی، تصویری و متنی و خروجی‌های صوتی بومی پشتیبانی می‌کند. این راهنما نحوه ادغام مستقیم با API را با استفاده از WebSockets خام توضیح می‌دهد.

نمای کلی

رابط برنامه‌نویسی Gemini Live از WebSockets برای ارتباط بلادرنگ استفاده می‌کند. برخلاف استفاده از SDK، این رویکرد شامل مدیریت مستقیم اتصال WebSocket و ارسال/دریافت پیام‌ها در قالب JSON خاصی است که توسط API تعریف شده است.

مفاهیم کلیدی:

• WebSocket Endpoint : آدرس اینترنتی (URL) مشخصی که باید به آن متصل شوید.
• قالب پیام : تمام ارتباطات از طریق پیام‌های JSON مطابق با ساختارهای BidiGenerateContentClientMessage و BidiGenerateContentServerMessage انجام می‌شود.
• مدیریت جلسه : شما مسئول حفظ اتصال WebSocket هستید.

احراز هویت

احراز هویت با وارد کردن کلید API شما به عنوان یک پارامتر پرس و جو در URL وب‌ساکت انجام می‌شود.

قالب نقطه پایانی به صورت زیر است:

کپی کدwss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent?key=YOUR_API_KEY

به جای YOUR_API_KEY ، کلید API واقعی خود را قرار دهید.

احراز هویت با توکن‌های موقت

اگر از توکن‌های موقت استفاده می‌کنید، باید به نقطه پایانی v1beta متصل شوید. توکن موقت باید به عنوان پارامتر پرس‌وجوی access_token ارسال شود.

قالب نقطه پایانی برای کلیدهای موقت به صورت زیر است:

کپی کدwss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContentConstrained?access_token={short-lived-token}

{short-lived-token} را با توکن موقت واقعی جایگزین کنید.

اتصال به API زنده

برای شروع یک جلسه زنده، یک اتصال WebSocket به نقطه پایانی احراز هویت شده برقرار کنید. اولین پیام ارسال شده از طریق WebSocket باید یک BidiGenerateContentSetup حاوی config باشد. برای گزینه‌های کامل پیکربندی، به مرجع Live API - WebSockets API مراجعه کنید.

کپی کدimport asyncio
import websockets
import json

API_KEY = "YOUR_API_KEY"
MODEL_NAME = "gemini-3.8-live"
WS_URL = f"wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent?key={API_KEY}"

async def connect_and_configure():
    async with websockets.connect(WS_URL) as websocket:
        print("WebSocket Connected")

        # 1. Send the initial configuration
        setup_message = {
            "setup": {
                "model": f"models/{MODEL_NAME}",
                "responseModalities": ["AUDIO"],
                "systemInstruction": {
                    "parts": [{"text": "You are a helpful assistant."}]
                }
            }
        }
        await websocket.send(json.dumps(setup_message))
        print("Configuration sent")

        # Keep the session alive for further interactions
        await asyncio.sleep(3600) # Example: keep open for an hour

async def main():
    await connect_and_configure()

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

کپی کدconst API_KEY = "YOUR_API_KEY";
const MODEL_NAME = "gemini-3.8-live";
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');

  // 1. Send the initial configuration
  const setupMessage = {
    setup: {
      model: `models/${MODEL_NAME}`,
      responseModalities: ['AUDIO'],
      systemInstruction: {
        parts: [{ text: 'You are a helpful assistant.' }]
      }
    }
  };
  websocket.send(JSON.stringify(setupMessage));
  console.log('Configuration sent');
};

websocket.onmessage = (event) => {
  const response = JSON.parse(event.data);
  console.log('Received:', response);
  // Handle different types of responses here
};

websocket.onerror = (error) => {
  console.error('WebSocket Error:', error);
};

websocket.onclose = () => {
  console.log('WebSocket Closed');
};

ارسال متن

برای ارسال ورودی متن، یک پیام BidiGenerateContentRealtimeInput با فیلد text بسازید.

کپی کد# Inside the websocket context
async def send_text(websocket, text):
    text_message = {
        "realtimeInput": {
            "text": text
        }
    }
    await websocket.send(json.dumps(text_message))
    print(f"Sent text: {text}")

# Example usage: await send_text(websocket, "Hello, how are you?")

کپی کدfunction sendTextMessage(text) {
  if (websocket.readyState === WebSocket.OPEN) {
    const textMessage = {
      realtimeInput: {
        text: text
      }
    };
    websocket.send(JSON.stringify(textMessage));
    console.log('Text message sent:', text);
  } else {
    console.warn('WebSocket not open.');
  }
}

// Example usage:
sendTextMessage("Hello, how are you?");

ارسال صدا

صدا باید به صورت داده‌های خام PCM (صدای خام PCM شانزده بیتی، ۱۶ کیلوهرتز، little-endian) ارسال شود. یک پیام BidiGenerateContentRealtimeInput با داده‌های صوتی بسازید. mimeType بسیار مهم است.

کپی کد# Inside the websocket context
async def send_audio_chunk(websocket, chunk_bytes):
    import base64
    encoded_data = base64.b64encode(chunk_bytes).decode('utf-8')
    audio_message = {
        "realtimeInput": {
            "audio": {
                "data": encoded_data,
                "mimeType": "audio/pcm;rate=16000"
            }
        }
    }
    await websocket.send(json.dumps(audio_message))
    # print("Sent audio chunk") # Avoid excessive logging

# Assuming 'chunk' is your raw PCM audio bytes
# await send_audio_chunk(websocket, chunk)

کپی کد// 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));
    // console.log('Sent audio chunk');
  }
}
// Example usage: sendAudioChunk(audioBuffer);

برای مثالی از نحوه دریافت صدا از دستگاه کلاینت (مثلاً مرورگر)، به مثال سرتاسری در GitHub مراجعه کنید.

ارسال ویدیو

فریم‌های ویدیویی به صورت تصاویر مجزا (مثلاً JPEG یا PNG) ارسال می‌شوند. مشابه صدا، از realtimeInput با یک Blob استفاده کنید و mimeType صحیح را مشخص کنید.

کپی کد# Inside the websocket context
async def send_video_frame(websocket, frame_bytes, mime_type="image/jpeg"):
    import base64
    encoded_data = base64.b64encode(frame_bytes).decode('utf-8')
    video_message = {
        "realtimeInput": {
            "video": {
                "data": encoded_data,
                "mimeType": mime_type
            }
        }
    }
    await websocket.send(json.dumps(video_message))
    # print("Sent video frame")

# Assuming 'frame' is your JPEG-encoded image bytes
# await send_video_frame(websocket, frame)

کپی کد// Assuming 'frame' is a Buffer of JPEG-encoded image data
function sendVideoFrame(frame, mimeType = 'image/jpeg') {
  if (websocket.readyState === WebSocket.OPEN) {
    const videoMessage = {
      realtimeInput: {
        video: {
          data: frame.toString('base64'),
          mimeType: mimeType
        }
      }
    };
    websocket.send(JSON.stringify(videoMessage));
    // console.log('Sent video frame');
  }
}
// Example usage: sendVideoFrame(jpegBuffer);

برای مثالی از نحوه دریافت ویدیو از دستگاه کلاینت (مثلاً مرورگر)، به مثال سرتاسری در GitHub مراجعه کنید.

دریافت پاسخ‌ها

WebSocket پیام‌های BidiGenerateContentServerMessage را ارسال می‌کند. شما باید این پیام‌های JSON را تجزیه و تحلیل کرده و انواع مختلف محتوا را مدیریت کنید.

کپی کد# Inside the websocket context, in a receive loop
async def receive_loop(websocket):
    async for message in websocket:
        response = json.loads(message)
        print("Received:", response)

        if "serverContent" in response:
            server_content = response["serverContent"]
            # Receiving Audio
            if "modelTurn" in server_content and "parts" in server_content["modelTurn"]:
                for part in server_content["modelTurn"]["parts"]:
                    if "inlineData" in part:
                        audio_data_b64 = part["inlineData"]["data"]
                        # Process or play the base64 encoded audio data
                        # audio_data = base64.b64decode(audio_data_b64)
                        print(f"Received audio data (base64 len: {len(audio_data_b64)})")

            # Receiving Text Transcriptions
            if "inputTranscription" in server_content:
                print(f"User: {server_content['inputTranscription']['text']}")
            if "outputTranscription" in server_content:
                print(f"Gemini: {server_content['outputTranscription']['text']}")

        # Handling Tool Calls
        if "toolCall" in response:
            await handle_tool_call(websocket, response["toolCall"])

# Example usage: await receive_loop(websocket)

کپی کدwebsocket.onmessage = (event) => {
  const response = JSON.parse(event.data);
  console.log('Received:', response);

  if (response.serverContent) {
    const serverContent = response.serverContent;
    // Receiving Audio
    if (serverContent.modelTurn?.parts) {
      for (const part of serverContent.modelTurn.parts) {
        if (part.inlineData) {
          const audioData = part.inlineData.data; // Base64 encoded string
          // Process or play audioData
          console.log(`Received audio data (base64 len: ${audioData.length})`);
        }
      }
    }

    // Receiving Text Transcriptions
    if (serverContent.inputTranscription) {
      console.log('User:', serverContent.inputTranscription.text);
    }
    if (serverContent.outputTranscription) {
      console.log('Gemini:', serverContent.outputTranscription.text);
    }
  }

  // Handling Tool Calls
  if (response.toolCall) {
    handleToolCall(response.toolCall);
  }
};

برای مثالی از نحوه مدیریت پاسخ، به مثال سرتاسری در GitHub مراجعه کنید.

مدیریت فراخوانی‌های ابزار

وقتی مدل درخواست فراخوانی ابزار را می‌دهد، BidiGenerateContentServerMessage شامل یک فیلد toolCall خواهد بود. شما باید تابع را به صورت محلی اجرا کنید و نتیجه را با استفاده از یک پیام BidiGenerateContentToolResponse به WebSocket ارسال کنید.

کپی کد# Placeholder for your tool function
def my_tool_function(args):
    print(f"Executing tool with args: {args}")
    # Implement your tool logic here
    return {"status": "success", "data": "some result"}

async def handle_tool_call(websocket, tool_call):
    function_responses = []
    for fc in tool_call["functionCalls"]:
        # 1. Execute the function locally
        try:
            result = my_tool_function(fc.get("args", {}))
            response_data = {"result": result}
        except Exception as e:
            print(f"Error executing tool {fc['name']}: {e}")
            response_data = {"error": str(e)}

        # 2. Prepare the response
        function_responses.append({
            "name": fc["name"],
            "id": fc["id"],
            "response": response_data
        })

    # 3. Send the tool response back to the session
    tool_response_message = {
        "toolResponse": {
            "functionResponses": function_responses
        }
    }
    await websocket.send(json.dumps(tool_response_message))
    print("Sent tool response")

# This function is called within the receive_loop when a toolCall is detected.

کپی کد// Placeholder for your tool function
function myToolFunction(args) {
  console.log(`Executing tool with args:`, args);
  // Implement your tool logic here
  return { status: 'success', data: 'some result' };
}

function handleToolCall(toolCall) {
  const functionResponses = [];
  for (const fc of toolCall.functionCalls) {
    // 1. Execute the function locally
    let result;
    try {
      result = myToolFunction(fc.args || {});
    } catch (e) {
      console.error(`Error executing tool ${fc.name}:`, e);
      result = { error: e.message };
    }

    // 2. Prepare the response
    functionResponses.push({
      name: fc.name,
      id: fc.id,
      response: { result }
    });
  }

  // 3. Send the tool response back to the session
  if (websocket.readyState === WebSocket.OPEN) {
    const toolResponseMessage = {
      toolResponse: {
        functionResponses: functionResponses
      }
    };
    websocket.send(JSON.stringify(toolResponseMessage));
    console.log('Sent tool response');
  } else {
    console.warn('WebSocket not open to send tool response.');
  }
}
// This function is called within websocket.onmessage when a toolCall is detected.

قدم بعدی چیست؟

• برای آشنایی با قابلیت‌ها و پیکربندی‌های کلیدی، راهنمای کامل قابلیت‌های Live API را مطالعه کنید؛ از جمله تشخیص فعالیت صوتی و ویژگی‌های صوتی بومی.
• برای یادگیری نحوه ادغام Live API با ابزارها و فراخوانی توابع، راهنمای استفاده از ابزار را مطالعه کنید.
• برای مدیریت مکالمات طولانی مدت، راهنمای مدیریت جلسه را مطالعه کنید.
• برای احراز هویت امن در برنامه‌های کلاینت به سرور، راهنمای توکن‌های زودگذر را مطالعه کنید.
• برای اطلاعات بیشتر در مورد API مربوط به WebSockets، به مرجع API مربوط به WebSockets مراجعه کنید.

رابط برنامه‌نویسی نرم‌افزار Gemini Live امکان تعامل دوطرفه و بلادرنگ با مدل‌های Gemini را فراهم می‌کند و از ورودی‌های صوتی، تصویری و متنی و خروجی‌های صوتی بومی پشتیبانی می‌کند. این راهنما نحوه ادغام مستقیم با API را با استفاده از WebSockets خام توضیح می‌دهد.

نمای کلی

رابط برنامه‌نویسی Gemini Live از WebSockets برای ارتباط بلادرنگ استفاده می‌کند. برخلاف استفاده از SDK، این رویکرد شامل مدیریت مستقیم اتصال WebSocket و ارسال/دریافت پیام‌ها در قالب JSON خاصی است که توسط API تعریف شده است.

مفاهیم کلیدی:

• WebSocket Endpoint : آدرس اینترنتی (URL) مشخصی که باید به آن متصل شوید.
• قالب پیام : تمام ارتباطات از طریق پیام‌های JSON مطابق با ساختارهای BidiGenerateContentClientMessage و BidiGenerateContentServerMessage انجام می‌شود.
• مدیریت جلسه : شما مسئول حفظ اتصال WebSocket هستید.

احراز هویت

احراز هویت با وارد کردن کلید API شما به عنوان یک پارامتر پرس و جو در URL وب‌ساکت انجام می‌شود.

قالب نقطه پایانی به صورت زیر است:

کپی کدwss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent?key=YOUR_API_KEY

به جای YOUR_API_KEY ، کلید API واقعی خود را قرار دهید.

احراز هویت با توکن‌های موقت

اگر از توکن‌های موقت استفاده می‌کنید، باید به نقطه پایانی v1beta متصل شوید. توکن موقت باید به عنوان پارامتر پرس‌وجوی access_token ارسال شود.

قالب نقطه پایانی برای کلیدهای موقت به صورت زیر است:

کپی کدwss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContentConstrained?access_token={short-lived-token}

{short-lived-token} را با توکن موقت واقعی جایگزین کنید.

اتصال به API زنده

برای شروع یک جلسه زنده، یک اتصال WebSocket به نقطه پایانی احراز هویت شده برقرار کنید. اولین پیام ارسال شده از طریق WebSocket باید یک BidiGenerateContentSetup حاوی config باشد. برای گزینه‌های کامل پیکربندی، به مرجع Live API - WebSockets API مراجعه کنید.

کپی کدimport asyncio
import websockets
import json

API_KEY = "YOUR_API_KEY"
MODEL_NAME = "gemini-3.8-live"
WS_URL = f"wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent?key={API_KEY}"

async def connect_and_configure():
    async with websockets.connect(WS_URL) as websocket:
        print("WebSocket Connected")

        # 1. Send the initial configuration
        setup_message = {
            "setup": {
                "model": f"models/{MODEL_NAME}",
                "responseModalities": ["AUDIO"],
                "systemInstruction": {
                    "parts": [{"text": "You are a helpful assistant."}]
                }
            }
        }
        await websocket.send(json.dumps(setup_message))
        print("Configuration sent")

        # Keep the session alive for further interactions
        await asyncio.sleep(3600) # Example: keep open for an hour

async def main():
    await connect_and_configure()

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

کپی کدconst API_KEY = "YOUR_API_KEY";
const MODEL_NAME = "gemini-3.8-live";
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');

  // 1. Send the initial configuration
  const setupMessage = {
    setup: {
      model: `models/${MODEL_NAME}`,
      responseModalities: ['AUDIO'],
      systemInstruction: {
        parts: [{ text: 'You are a helpful assistant.' }]
      }
    }
  };
  websocket.send(JSON.stringify(setupMessage));
  console.log('Configuration sent');
};

websocket.onmessage = (event) => {
  const response = JSON.parse(event.data);
  console.log('Received:', response);
  // Handle different types of responses here
};

websocket.onerror = (error) => {
  console.error('WebSocket Error:', error);
};

websocket.onclose = () => {
  console.log('WebSocket Closed');
};

ارسال متن

برای ارسال ورودی متن، یک پیام BidiGenerateContentRealtimeInput با فیلد text بسازید.

کپی کد# Inside the websocket context
async def send_text(websocket, text):
    text_message = {
        "realtimeInput": {
            "text": text
        }
    }
    await websocket.send(json.dumps(text_message))
    print(f"Sent text: {text}")

# Example usage: await send_text(websocket, "Hello, how are you?")

کپی کدfunction sendTextMessage(text) {
  if (websocket.readyState === WebSocket.OPEN) {
    const textMessage = {
      realtimeInput: {
        text: text
      }
    };
    websocket.send(JSON.stringify(textMessage));
    console.log('Text message sent:', text);
  } else {
    console.warn('WebSocket not open.');
  }
}

// Example usage:
sendTextMessage("Hello, how are you?");

ارسال صدا

صدا باید به صورت داده‌های خام PCM (صدای خام PCM شانزده بیتی، ۱۶ کیلوهرتز، little-endian) ارسال شود. یک پیام BidiGenerateContentRealtimeInput با داده‌های صوتی بسازید. mimeType بسیار مهم است.

کپی کد# Inside the websocket context
async def send_audio_chunk(websocket, chunk_bytes):
    import base64
    encoded_data = base64.b64encode(chunk_bytes).decode('utf-8')
    audio_message = {
        "realtimeInput": {
            "audio": {
                "data": encoded_data,
                "mimeType": "audio/pcm;rate=16000"
            }
        }
    }
    await websocket.send(json.dumps(audio_message))
    # print("Sent audio chunk") # Avoid excessive logging

# Assuming 'chunk' is your raw PCM audio bytes
# await send_audio_chunk(websocket, chunk)

کپی کد// 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));
    // console.log('Sent audio chunk');
  }
}
// Example usage: sendAudioChunk(audioBuffer);

برای مثالی از نحوه دریافت صدا از دستگاه کلاینت (مثلاً مرورگر)، به مثال سرتاسری در GitHub مراجعه کنید.

ارسال ویدیو

فریم‌های ویدیویی به صورت تصاویر مجزا (مثلاً JPEG یا PNG) ارسال می‌شوند. مشابه صدا، از realtimeInput با یک Blob استفاده کنید و mimeType صحیح را مشخص کنید.

کپی کد# Inside the websocket context
async def send_video_frame(websocket, frame_bytes, mime_type="image/jpeg"):
    import base64
    encoded_data = base64.b64encode(frame_bytes).decode('utf-8')
    video_message = {
        "realtimeInput": {
            "video": {
                "data": encoded_data,
                "mimeType": mime_type
            }
        }
    }
    await websocket.send(json.dumps(video_message))
    # print("Sent video frame")

# Assuming 'frame' is your JPEG-encoded image bytes
# await send_video_frame(websocket, frame)

کپی کد// Assuming 'frame' is a Buffer of JPEG-encoded image data
function sendVideoFrame(frame, mimeType = 'image/jpeg') {
  if (websocket.readyState === WebSocket.OPEN) {
    const videoMessage = {
      realtimeInput: {
        video: {
          data: frame.toString('base64'),
          mimeType: mimeType
        }
      }
    };
    websocket.send(JSON.stringify(videoMessage));
    // console.log('Sent video frame');
  }
}
// Example usage: sendVideoFrame(jpegBuffer);

برای مثالی از نحوه دریافت ویدیو از دستگاه کلاینت (مثلاً مرورگر)، به مثال سرتاسری در GitHub مراجعه کنید.

دریافت پاسخ‌ها

WebSocket پیام‌های BidiGenerateContentServerMessage را ارسال می‌کند. شما باید این پیام‌های JSON را تجزیه و تحلیل کرده و انواع مختلف محتوا را مدیریت کنید.

کپی کد# Inside the websocket context, in a receive loop
async def receive_loop(websocket):
    async for message in websocket:
        response = json.loads(message)
        print("Received:", response)

        if "serverContent" in response:
            server_content = response["serverContent"]
            # Receiving Audio
            if "modelTurn" in server_content and "parts" in server_content["modelTurn"]:
                for part in server_content["modelTurn"]["parts"]:
                    if "inlineData" in part:
                        audio_data_b64 = part["inlineData"]["data"]
                        # Process or play the base64 encoded audio data
                        # audio_data = base64.b64decode(audio_data_b64)
                        print(f"Received audio data (base64 len: {len(audio_data_b64)})")

            # Receiving Text Transcriptions
            if "inputTranscription" in server_content:
                print(f"User: {server_content['inputTranscription']['text']}")
            if "outputTranscription" in server_content:
                print(f"Gemini: {server_content['outputTranscription']['text']}")

        # Handling Tool Calls
        if "toolCall" in response:
            await handle_tool_call(websocket, response["toolCall"])

# Example usage: await receive_loop(websocket)

کپی کدwebsocket.onmessage = (event) => {
  const response = JSON.parse(event.data);
  console.log('Received:', response);

  if (response.serverContent) {
    const serverContent = response.serverContent;
    // Receiving Audio
    if (serverContent.modelTurn?.parts) {
      for (const part of serverContent.modelTurn.parts) {
        if (part.inlineData) {
          const audioData = part.inlineData.data; // Base64 encoded string
          // Process or play audioData
          console.log(`Received audio data (base64 len: ${audioData.length})`);
        }
      }
    }

    // Receiving Text Transcriptions
    if (serverContent.inputTranscription) {
      console.log('User:', serverContent.inputTranscription.text);
    }
    if (serverContent.outputTranscription) {
      console.log('Gemini:', serverContent.outputTranscription.text);
    }
  }

  // Handling Tool Calls
  if (response.toolCall) {
    handleToolCall(response.toolCall);
  }
};

برای مثالی از نحوه مدیریت پاسخ، به مثال سرتاسری در GitHub مراجعه کنید.

مدیریت فراخوانی‌های ابزار

وقتی مدل درخواست فراخوانی ابزار را می‌دهد، BidiGenerateContentServerMessage شامل یک فیلد toolCall خواهد بود. شما باید تابع را به صورت محلی اجرا کنید و نتیجه را با استفاده از یک پیام BidiGenerateContentToolResponse به WebSocket ارسال کنید.

کپی کد# Placeholder for your tool function
def my_tool_function(args):
    print(f"Executing tool with args: {args}")
    # Implement your tool logic here
    return {"status": "success", "data": "some result"}

async def handle_tool_call(websocket, tool_call):
    function_responses = []
    for fc in tool_call["functionCalls"]:
        # 1. Execute the function locally
        try:
            result = my_tool_function(fc.get("args", {}))
            response_data = {"result": result}
        except Exception as e:
            print(f"Error executing tool {fc['name']}: {e}")
            response_data = {"error": str(e)}

        # 2. Prepare the response
        function_responses.append({
            "name": fc["name"],
            "id": fc["id"],
            "response": response_data
        })

    # 3. Send the tool response back to the session
    tool_response_message = {
        "toolResponse": {
            "functionResponses": function_responses
        }
    }
    await websocket.send(json.dumps(tool_response_message))
    print("Sent tool response")

# This function is called within the receive_loop when a toolCall is detected.

کپی کد// Placeholder for your tool function
function myToolFunction(args) {
  console.log(`Executing tool with args:`, args);
  // Implement your tool logic here
  return { status: 'success', data: 'some result' };
}

function handleToolCall(toolCall) {
  const functionResponses = [];
  for (const fc of toolCall.functionCalls) {
    // 1. Execute the function locally
    let result;
    try {
      result = myToolFunction(fc.args || {});
    } catch (e) {
      console.error(`Error executing tool ${fc.name}:`, e);
      result = { error: e.message };
    }

    // 2. Prepare the response
    functionResponses.push({
      name: fc.name,
      id: fc.id,
      response: { result }
    });
  }

  // 3. Send the tool response back to the session
  if (websocket.readyState === WebSocket.OPEN) {
    const toolResponseMessage = {
      toolResponse: {
        functionResponses: functionResponses
      }
    };
    websocket.send(JSON.stringify(toolResponseMessage));
    console.log('Sent tool response');
  } else {
    console.warn('WebSocket not open to send tool response.');
  }
}
// This function is called within websocket.onmessage when a toolCall is detected.

قدم بعدی چیست؟

• برای آشنایی با قابلیت‌ها و پیکربندی‌های کلیدی، راهنمای کامل قابلیت‌های Live API را مطالعه کنید؛ از جمله تشخیص فعالیت صوتی و ویژگی‌های صوتی بومی.
• برای یادگیری نحوه ادغام Live API با ابزارها و فراخوانی توابع، راهنمای استفاده از ابزار را مطالعه کنید.
• برای مدیریت مکالمات طولانی مدت، راهنمای مدیریت جلسه را مطالعه کنید.
• برای احراز هویت امن در برنامه‌های کلاینت به سرور، راهنمای توکن‌های زودگذر را مطالعه کنید.
• برای اطلاعات بیشتر در مورد API مربوط به WebSockets، به مرجع API مربوط به WebSockets مراجعه کنید.