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 usando el SDK de GenAI de Google 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.
- Config: Configuración de modalidades (audio/texto), voz y las instrucciones del sistema.
- Entrada en tiempo real: Envío de fotogramas de audio y video como BLOBs
Cómo conectarse a la API de Live
Para iniciar una sesión de la API en vivo con una clave de API, haz lo siguiente:
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();
Enviando mensaje de 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.
Enviando 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 aprender a recibir el audio en tu servidor y reproducirlo en el navegador.
Recibiendo mensaje de 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 solicite 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 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 aprender a integrar la API en vivo 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 sobre tokens efímeros para obtener información sobre la autenticación segura en aplicaciones cliente-servidor.
- Para obtener más información sobre la API de WebSockets subyacente, consulta la referencia de la API de WebSockets.