Gemini Live API cho phép tương tác hai chiều theo thời gian thực với các mô hình Gemini, hỗ trợ đầu vào bằng âm thanh, video và văn bản cũng như đầu ra âm thanh gốc. Hướng dẫn này giải thích cách tích hợp với API bằng SDK Google GenAI trên máy chủ của bạn.
Tổng quan
Gemini Live API sử dụng WebSocket để giao tiếp theo thời gian thực. SDK google-genai cung cấp một giao diện không đồng bộ cấp cao để quản lý các kết nối này.
Các khái niệm chính:
- Phiên: Kết nối liên tục với mô hình.
- Cấu hình: Thiết lập phương thức (âm thanh/văn bản), giọng nói và hướng dẫn hệ thống.
- Đầu vào theo thời gian thực: Gửi khung âm thanh và video dưới dạng blob.
Kết nối với Live API
Bắt đầu phiên Live API bằng khoá 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();
Đang gửi tin nhắn
Bạn có thể gửi văn bản bằng send_realtime_input (Python) hoặc sendRealtimeInput (JavaScript).
Python
await session.send_realtime_input(text="Hello, how are you?")
JavaScript
session.sendRealtimeInput({
text: 'Hello, how are you?'
});
Đang gửi âm thanh
Bạn cần gửi âm thanh dưới dạng dữ liệu PCM thô (âm thanh PCM 16 bit thô, 16 kHz, little-endian).
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'
}
});
Để xem ví dụ về cách lấy âm thanh từ thiết bị của ứng dụng (ví dụ: trình duyệt) hãy xem ví dụ toàn diện trên GitHub.
Đang gửi video
Khung video được gửi dưới dạng hình ảnh riêng lẻ (ví dụ: JPEG hoặc PNG) ở một tốc độ khung hình cụ thể (tối đa 1 khung hình mỗi giây).
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'
}
});
Để xem ví dụ về cách lấy video từ thiết bị của ứng dụng (ví dụ: trình duyệt) hãy xem ví dụ toàn diện trên GitHub.
Đang nhận âm thanh
Phản hồi âm thanh của mô hình được nhận dưới dạng các khối dữ liệu.
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)
}
}
}
Hãy xem ứng dụng mẫu trên GitHub để tìm hiểu cách nhận âm thanh trên máy chủ và phát âm thanh đó trong trình duyệt.
Đang nhận tin nhắn
Bản chép lời cho cả hoạt động đầu vào của người dùng và đầu ra của mô hình đều có trong nội dung máy chủ.
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);
}
Xử lý lệnh gọi công cụ
API này hỗ trợ lệnh gọi công cụ (lệnh gọi hàm). Khi mô hình yêu cầu lệnh gọi công cụ, bạn phải thực thi hàm và gửi phản hồi.
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 });
}
Bước tiếp theo
- Đọc hướng dẫn đầy đủ về Các tính năng của Live API Capabilities để biết các tính năng và cấu hình chính, bao gồm cả tính năng Phát hiện hoạt động bằng giọng nói và các tính năng âm thanh gốc.
- Đọc hướng dẫn Sử dụng công cụ để tìm hiểu cách tích hợp Live API với các công cụ và lệnh gọi hàm.
- Đọc hướng dẫn Quản lý phiên để quản lý các cuộc trò chuyện chạy trong thời gian dài.
- Đọc hướng dẫn Mã thông báo tạm thời để xác thực an toàn trong các ứng dụng ứng dụng-đến-máy chủ.
- Để biết thêm thông tin về WebSocket API cơ bản, hãy xem Tài liệu tham khảo API WebSocket.