La API de Gemini Live permite la interacción bidireccional en tiempo real con los modelos de Gemini, admite entradas de audio, video y texto, y salidas de audio nativas. En esta guía, se explica cómo realizar la integración con la API mediante el SDK de Google GenAI en tu servidor.
Descripción general
La API de Gemini Live usa WebSockets para la comunicación en tiempo real. El SDK de google-genai proporciona una interfaz asíncrona de alto nivel para administrar estas conexiones.
Conceptos clave:
- Sesión: Es una conexión persistente al modelo.
- Configuración: Es la configuración de modalidades (audio/texto), voz y las instrucciones del sistema.
- Entrada en tiempo real: Es el envío de fotogramas de audio y video como objetos binarios grandes.
Cómo conectarse a la API de Live
Inicia una sesión de la API de Live con una clave de API:
Python
import asyncio
from google import genai
client = genai.Client(api_key="YOUR_API_KEY")
model = "gemini-3.1-flash-live-preview"
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-3.1-flash-live-preview';
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();
Cómo enviar texto
El texto se puede enviar con send_realtime_input (Python) o sendRealtimeInput (JavaScript).
Python
await session.send_realtime_input(text="Hello, how are you?")
JavaScript
session.sendRealtimeInput({
text: 'Hello, how are you?'
});
Cómo enviar audio
El audio debe enviarse como datos PCM sin procesar (audio PCM sin procesar de 16 bits, 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'
}
});
Para ver un ejemplo de cómo obtener el audio del dispositivo cliente (p.ej., el navegador) consulta el ejemplo de extremo a extremo en GitHub.
Cómo enviar video
Los fotogramas de video se envían como imágenes individuales (p.ej., JPEG o PNG) a una velocidad de fotogramas específica (máximo 1 fotograma por segundo).
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'
}
});
Para ver un ejemplo de cómo obtener el video del dispositivo cliente (p.ej., el navegador) consulta el ejemplo de extremo a extremo en GitHub.
Cómo recibir audio
Las respuestas de audio del modelo se reciben como fragmentos de datos.
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)
}
}
}
Consulta la app de ejemplo en GitHub para obtener información sobre cómo recibir el audio en tu servidor y reproducirlo en el navegador.
Cómo recibir texto
Las transcripciones de la entrada del usuario y la salida del modelo están disponibles en el contenido del servidor.
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);
}
Cómo controlar las llamadas a herramientas
La API admite llamadas a herramientas (llamadas a funciones). Cuando el modelo solicita una llamada a herramienta, debes ejecutar la función y enviar la respuesta.
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 });
}
¿Qué sigue?
- Lee la guía completa de capacidades de la API de Live Capabilities para conocer las capacidades y configuraciones clave, incluidas la detección de actividad de voz y las funciones de audio nativas.
- Lee la guía de uso de herramientas para obtener información sobre cómo integrar la API de Live con herramientas y llamadas a funciones.
- Lee la guía de administración de sesiones para administrar conversaciones de larga duración.
- Lee la guía de tokens efímeros para obtener información sobre la autenticación segura en aplicaciones de cliente a servidor.
- Para obtener más información sobre la API de WebSockets subyacente, consulta la referencia de la API de WebSockets.