Live API - WebSockets API reference

La API de Live es una API con estado que usa WebSockets. En esta sección, encontrarás detalles adicionales sobre la API de WebSockets.

Sesiones

Una conexión WebSocket establece una sesión entre el cliente y el servidor Gemini. Después de que un cliente inicia una conexión nueva, la sesión puede intercambiar mensajes con el servidor para realizar las siguientes acciones:

  • Enviar texto, audio o video al servidor de Gemini
  • Recibir solicitudes de llamadas de audio, texto o función del servidor de Gemini

Conexión de WebSocket

Para iniciar una sesión, conéctate a este extremo de websocket:

wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent

Configuración de la sesión

El mensaje inicial después de la conexión establece la configuración de la sesión, que incluye el modelo, los parámetros de generación, las instrucciones del sistema y las herramientas.

Puedes cambiar los parámetros de configuración, excepto el modelo, durante la sesión.

Consulta la siguiente configuración de ejemplo. Ten en cuenta que la mayúscula o minúscula de los nombres en los SDKs puede variar. Puedes buscar las opciones de configuración del SDK de Python aquí.


{
  "model": string,
  "generationConfig": {
    "candidateCount": integer,
    "maxOutputTokens": integer,
    "temperature": number,
    "topP": number,
    "topK": integer,
    "presencePenalty": number,
    "frequencyPenalty": number,
    "responseModalities": [string],
    "speechConfig": object,
    "mediaResolution": object
  },
  "systemInstruction": string,
  "tools": [object]
}

Para obtener más información sobre el campo de la API, consulta generationConfig.

Cómo enviar mensajes

Para intercambiar mensajes a través de la conexión WebSocket, el cliente debe enviar un objeto JSON a través de una conexión WebSocket abierta. El objeto JSON debe tener exactamente uno de los campos del siguiente conjunto de objetos:


{
  "setup": BidiGenerateContentSetup,
  "clientContent": BidiGenerateContentClientContent,
  "realtimeInput": BidiGenerateContentRealtimeInput,
  "toolResponse": BidiGenerateContentToolResponse
}

Mensajes de cliente compatibles

Consulta los mensajes de cliente admitidos en la siguiente tabla:

Mensaje Descripción
BidiGenerateContentSetup Configuración de la sesión que se enviará en el primer mensaje
BidiGenerateContentClientContent Actualización incremental del contenido de la conversación actual que se entrega desde el cliente
BidiGenerateContentRealtimeInput Entrada de audio, video o texto en tiempo real
BidiGenerateContentToolResponse Respuesta a un ToolCallMessage recibido del servidor

Recibir mensajes

Para recibir mensajes de Gemini, escucha el evento "message" de WebSocket y, luego, analiza el resultado según la definición de los mensajes del servidor compatibles.

Consulta lo siguiente:

async with client.aio.live.connect(model='...', config=config) as session:
    await session.send(input='Hello world!', end_of_turn=True)
    async for message in session.receive():
        print(message)

Los mensajes del servidor pueden tener un campo usageMetadata, pero, de lo contrario, incluirán exactamente uno de los otros campos del mensaje BidiGenerateContentServerMessage. (La unión messageType no se expresa en JSON, por lo que el campo aparecerá en el nivel superior del mensaje).

Mensajes y eventos

ActivityEnd

Este tipo no tiene campos.

Marca el final de la actividad del usuario.

ActivityHandling

Las diferentes formas de controlar la actividad del usuario

Enumeraciones
ACTIVITY_HANDLING_UNSPECIFIED Si no se especifica, el comportamiento predeterminado es START_OF_ACTIVITY_INTERRUPTS.
START_OF_ACTIVITY_INTERRUPTS Si es verdadero, el inicio de la actividad interrumpirá la respuesta del modelo (también llamada "interrupción"). La respuesta actual del modelo se cortará en el momento de la interrupción. Este es el comportamiento predeterminado.
NO_INTERRUPTION La respuesta del modelo no se interrumpirá.

ActivityStart

Este tipo no tiene campos.

Marca el inicio de la actividad del usuario.

AudioTranscriptionConfig

Este tipo no tiene campos.

La configuración de la transcripción de audio

AutomaticActivityDetection

Configura la detección automática de actividad.

Campos
disabled

bool

Opcional. Si está habilitada (configuración predeterminada), la entrada de voz y texto detectada se registra como actividad. Si está inhabilitado, el cliente debe enviar indicadores de actividad.

startOfSpeechSensitivity

StartSensitivity

Opcional. Determina la probabilidad de que se detecte la voz.

prefixPaddingMs

int32

Opcional. Es la duración requerida de la voz detectada antes de que se confirme el inicio de la voz. Cuanto más bajo sea este valor, más sensible será la detección del inicio de la voz y se podrá reconocer una voz más corta. Sin embargo, esto también aumenta la probabilidad de falsos positivos.

endOfSpeechSensitivity

EndSensitivity

Opcional. Determina la probabilidad de que haya finalizado la voz detectada.

silenceDurationMs

int32

Opcional. Es la duración requerida de la detección de audio sin voz (p.ej., silencio) antes de que se confirme el final de la voz. Cuanto mayor sea este valor, más largas pueden ser las pausas de voz sin interrumpir la actividad del usuario, pero esto aumentará la latencia del modelo.

BidiGenerateContentClientContent

Es la actualización incremental de la conversación actual que se entrega desde el cliente. Todo el contenido aquí se agrega sin condiciones al historial de conversaciones y se usa como parte de la instrucción para que el modelo genere contenido.

Un mensaje aquí interrumpirá cualquier generación de modelos actual.

Campos
turns[]

Content

Opcional. Es el contenido que se adjunta a la conversación actual con el modelo.

Para consultas de un solo turno, esta es una instancia única. Para las consultas de varios turnos, este es un campo repetido que contiene el historial de conversaciones y la solicitud más reciente.

turnComplete

bool

Opcional. Si es verdadero, indica que la generación de contenido del servidor debe comenzar con la instrucción acumulada actualmente. De lo contrario, el servidor espera mensajes adicionales antes de iniciar la generación.

BidiGenerateContentRealtimeInput

Entrada del usuario que se envía en tiempo real.

Las diferentes modalidades (audio, video y texto) se controlan como transmisiones simultáneas. No se garantiza el orden de estas transmisiones.

Esto es diferente de BidiGenerateContentClientContent en algunos aspectos:

  • Se pueden enviar de forma continua sin interrupciones a la generación de modelos.
  • Si es necesario mezclar datos intercalados entre BidiGenerateContentClientContent y BidiGenerateContentRealtimeInput, el servidor intenta realizar optimizaciones para obtener la mejor respuesta, pero no hay garantías.
  • El final de la toma de turno no se especifica de forma explícita, sino que se deriva de la actividad del usuario (por ejemplo, el final de la voz).
  • Incluso antes de que finalice el turno, los datos se procesan de forma incremental para optimizar un inicio rápido de la respuesta del modelo.
Campos
mediaChunks[]

Blob

Opcional. Datos de bytes intercalados para la entrada de contenido multimedia. No se admiten varios mediaChunks, se ignorarán todos menos el primero.

OBSOLETO: En su lugar, usa uno de audio, video o text.

audio

Blob

Opcional. Estos forman la transmisión de entrada de audio en tiempo real.

video

Blob

Opcional. Estos forman el flujo de entrada de video en tiempo real.

activityStart

ActivityStart

Opcional. Marca el inicio de la actividad del usuario. Solo se puede enviar si la detección automática de actividad (es decir, del servidor) está inhabilitada.

activityEnd

ActivityEnd

Opcional. Marca el final de la actividad del usuario. Solo se puede enviar si la detección automática de actividad (es decir, del servidor) está inhabilitada.

audioStreamEnd

bool

Opcional. Indica que finalizó la transmisión de audio, p.ej., porque se apagó el micrófono.

Solo se debe enviar cuando la detección automática de actividades está habilitada (que es la configuración predeterminada).

El cliente puede volver a abrir la transmisión enviando un mensaje de audio.

text

string

Opcional. Estos forman el flujo de entrada de texto en tiempo real.

BidiGenerateContentServerContent

Actualización incremental del servidor que genera el modelo en respuesta a los mensajes del cliente.

El contenido se genera lo más rápido posible, no en tiempo real. Los clientes pueden optar por almacenar en búfer y reproducirlo en tiempo real.

Campos
generationComplete

bool

Solo salida. Si es verdadero, indica que el modelo terminó de generarse.

Cuando el modelo se interrumpa durante la generación, no habrá un mensaje "generation_complete" en el turno interrumpido, sino que pasará por "interrupted > turn_complete".

Cuando el modelo asuma la reproducción en tiempo real, habrá una demora entre generation_complete y turn_complete, que se debe a que el modelo espera a que finalice la reproducción.

turnComplete

bool

Solo salida. Si es verdadero, indica que el modelo completó su turno. La generación solo comenzará en respuesta a mensajes adicionales del cliente.

interrupted

bool

Solo salida. Si es verdadero, indica que un mensaje del cliente interrumpió la generación de modelos actual. Si el cliente reproduce el contenido en tiempo real, esta es una buena señal para detener y vaciar la cola de reproducción actual.

groundingMetadata

GroundingMetadata

Solo salida. Metadatos de origen para el contenido generado

outputTranscription

BidiGenerateContentTranscription

Solo salida. Genera una transcripción de audio de salida. La transcripción se envía independientemente de los otros mensajes del servidor y no hay un orden garantizado, en particular, no entre serverContent y este outputTranscription.

modelTurn

Content

Solo salida. Es el contenido que el modelo generó como parte de la conversación actual con el usuario.

BidiGenerateContentServerMessage

Es el mensaje de respuesta para la llamada BidiGenerateContent.

Campos
usageMetadata

UsageMetadata

Solo salida. Son los metadatos de uso sobre las respuestas.

Campo de unión messageType. Es el tipo de mensaje. Las direcciones (messageType) solo pueden ser una de las siguientes opciones:
setupComplete

BidiGenerateContentSetupComplete

Solo salida. Se envía en respuesta a un mensaje BidiGenerateContentSetup del cliente cuando se completa la configuración.

serverContent

BidiGenerateContentServerContent

Solo salida. Es el contenido que genera el modelo en respuesta a los mensajes de los clientes.

toolCall

BidiGenerateContentToolCall

Solo salida. Solicita al cliente que ejecute el functionCalls y que devuelva las respuestas con los id coincidentes.

toolCallCancellation

BidiGenerateContentToolCallCancellation

Solo salida. Notificación para el cliente de que se debe cancelar un ToolCallMessage emitido anteriormente con los id especificados.

goAway

GoAway

Solo salida. Un aviso de que el servidor pronto se desconectará

sessionResumptionUpdate

SessionResumptionUpdate

Solo salida. Actualización del estado de reanudación de la sesión.

BidiGenerateContentSetup

Es el mensaje que se enviará en el primer (y solo en el primer) BidiGenerateContentClientMessage. Contiene la configuración que se aplicará durante la RPC de transmisión.

Los clientes deben esperar un mensaje BidiGenerateContentSetupComplete antes de enviar cualquier mensaje adicional.

Campos
model

string

Obligatorio. Es el nombre del recurso del modelo. Este ID sirve como ID para que lo use el modelo.

Formato: models/{model}

generationConfig

GenerationConfig

Opcional. Configuración de generación

No se admiten los siguientes campos:

  • responseLogprobs
  • responseMimeType
  • logprobs
  • responseSchema
  • stopSequence
  • routingConfig
  • audioTimestamp
systemInstruction

Content

Opcional. Las instrucciones del sistema que proporcionó el usuario para el modelo.

Nota: Solo se debe usar texto en las partes y el contenido en cada parte debe encontrarse en un párrafo separado.

tools[]

Tool

Opcional. Es una lista de Tools que el modelo puede usar para generar la siguiente respuesta.

Un Tool es un fragmento de código que permite que el sistema interactúe con sistemas externos para realizar una acción, o un conjunto de acciones, fuera del conocimiento y del alcance del modelo.

realtimeInputConfig

RealtimeInputConfig

Opcional. Configura el control de la entrada en tiempo real.

sessionResumption

SessionResumptionConfig

Opcional. Configura el mecanismo de reanudación de la sesión.

Si se incluye, el servidor enviará mensajes SessionResumptionUpdate.

contextWindowCompression

ContextWindowCompressionConfig

Opcional. Configura un mecanismo de compresión de ventana de contexto.

Si se incluye, el servidor reducirá automáticamente el tamaño del contexto cuando supere la longitud configurada.

outputAudioTranscription

AudioTranscriptionConfig

Opcional. Si se establece, habilita la transcripción de la salida de audio del modelo. La transcripción se alinea con el código de idioma especificado para el audio de salida, si está configurado.

BidiGenerateContentSetupComplete

Este tipo no tiene campos.

Se envía en respuesta a un mensaje BidiGenerateContentSetup del cliente.

BidiGenerateContentToolCall

Solicita al cliente que ejecute el functionCalls y que devuelva las respuestas con los id coincidentes.

Campos
functionCalls[]

FunctionCall

Solo salida. La llamada a función que se ejecutará.

BidiGenerateContentToolCallCancellation

Notificación para el cliente de que un ToolCallMessage emitido anteriormente con los id especificados no debería haberse ejecutado y debe cancelarse. Si hubo efectos secundarios en esas llamadas a la herramienta, los clientes pueden intentar deshacerlas. Este mensaje solo ocurre en los casos en que los clientes interrumpen los turnos del servidor.

Campos
ids[]

string

Solo salida. Los IDs de las llamadas a la herramienta que se cancelarán.

BidiGenerateContentToolResponse

Respuesta generada por el cliente a un ToolCall recibido del servidor. Los objetos FunctionResponse individuales se corresponden con los objetos FunctionCall respectivos mediante el campo id.

Ten en cuenta que, en las APIs de GenerateContent uniaria y de transmisión del servidor, las llamadas a función se realizan intercambiando las partes Content, mientras que, en las APIs de GenerateContent de transmisión bidireccional, las llamadas a función se realizan a través de este conjunto dedicado de mensajes.

Campos
functionResponses[]

FunctionResponse

Opcional. La respuesta a las llamadas a la función.

BidiGenerateContentTranscription

Transcripción de audio (entrada o salida).

Campos
text

string

Texto de la transcripción.

ContextWindowCompressionConfig

Habilita la compresión de la ventana de contexto, un mecanismo para administrar la ventana de contexto del modelo de modo que no exceda una longitud determinada.

Campos
Campo de unión compressionMechanism. Es el mecanismo de compresión de la ventana de contexto que se usa. Las direcciones (compressionMechanism) solo pueden ser una de las siguientes opciones:
slidingWindow

SlidingWindow

Un mecanismo de ventana deslizante

triggerTokens

int64

Es la cantidad de tokens (antes de ejecutar un turno) necesarios para activar una compresión de ventana de contexto.

Esto se puede usar para equilibrar la calidad con la latencia, ya que las ventanas de contexto más cortas pueden generar respuestas del modelo más rápidas. Sin embargo, cualquier operación de compresión provocará un aumento temporal de la latencia, por lo que no se deben activar con frecuencia.

Si no se establece, el valor predeterminado es el 80% del límite de la ventana de contexto del modelo. Esto deja un 20% para la próxima solicitud del usuario o respuesta del modelo.

EndSensitivity

Determina cómo se detecta el final de la voz.

Enumeraciones
END_SENSITIVITY_UNSPECIFIED El valor predeterminado es END_SENSITIVITY_HIGH.
END_SENSITIVITY_HIGH La detección automática finaliza la voz con más frecuencia.
END_SENSITIVITY_LOW La detección automática finaliza la voz con menos frecuencia.

GoAway

Un aviso de que el servidor pronto se desconectará

Campos
timeLeft

Duration

El tiempo restante antes de que se cierre la conexión se mostrará como ABORTED.

Esta duración nunca será inferior a un mínimo específico del modelo, que se especificará junto con los límites de frecuencia del modelo.

RealtimeInputConfig

Configura el comportamiento de entrada en tiempo real en BidiGenerateContent.

Campos
automaticActivityDetection

AutomaticActivityDetection

Opcional. Si no se establece, la detección automática de actividades está habilitada de forma predeterminada. Si la detección de voz automática está inhabilitada, el cliente debe enviar indicadores de actividad.

activityHandling

ActivityHandling

Opcional. Define qué efecto tiene la actividad.

turnCoverage

TurnCoverage

Opcional. Define qué entrada se incluye en el turno del usuario.

SessionResumptionConfig

Configuración de la reanudación de la sesión.

Este mensaje se incluye en la configuración de la sesión como BidiGenerateContentSetup.sessionResumption. Si se configura, el servidor enviará mensajes SessionResumptionUpdate.

Campos
handle

string

Es el identificador de una sesión anterior. Si no está presente, se crea una sesión nueva.

Los identificadores de sesión provienen de los valores de SessionResumptionUpdate.token en conexiones anteriores.

SessionResumptionUpdate

Actualización del estado de reanudación de la sesión.

Solo se envía si se configuró BidiGenerateContentSetup.sessionResumption.

Campos
newHandle

string

Es un identificador nuevo que representa un estado que se puede reanudar. Está vacío si resumable=false.

resumable

bool

Es verdadero si la sesión actual se puede reanudar en este momento.

No es posible reanudar la sesión en algunos puntos. Por ejemplo, cuando el modelo ejecuta llamadas a funciones o genera. Si se reanuda la sesión (con un token de sesión anterior) en ese estado, se perderán algunos datos. En estos casos, newHandle estará vacío y resumable será falso.

SlidingWindow

El método SlidingWindow funciona descartando el contenido al comienzo de la ventana de contexto. El contexto resultante siempre comenzará al comienzo de un turno de rol de USUARIO. Las instrucciones del sistema y cualquier BidiGenerateContentSetup.prefixTurns siempre permanecerán al principio del resultado.

Campos
targetTokens

int64

Es la cantidad objetivo de tokens que se deben conservar. El valor predeterminado es trigger_tokens/2.

Si se descartan partes de la ventana de contexto, se produce un aumento temporal de latencia, por lo que este valor se debe calibrar para evitar operaciones de compresión frecuentes.

StartSensitivity

Determina cómo se detecta el inicio de la voz.

Enumeraciones
START_SENSITIVITY_UNSPECIFIED El valor predeterminado es START_SENSITIVITY_HIGH.
START_SENSITIVITY_HIGH La detección automática detectará el inicio de la voz con mayor frecuencia.
START_SENSITIVITY_LOW La detección automática detectará el inicio de la voz con menos frecuencia.

TurnCoverage

Son opciones sobre qué entrada se incluye en el turno del usuario.

Enumeraciones
TURN_COVERAGE_UNSPECIFIED Si no se especifica, el comportamiento predeterminado es TURN_INCLUDES_ONLY_ACTIVITY.
TURN_INCLUDES_ONLY_ACTIVITY El turno del usuario solo incluye la actividad desde el último turno, sin incluir la inactividad (p.ej., silencio en la transmisión de audio). Este es el comportamiento predeterminado.
TURN_INCLUDES_ALL_INPUT El turno del usuario incluye todas las entradas en tiempo real desde el último turno, incluida la inactividad (p.ej., silencio en la transmisión de audio).

UsageMetadata

Son los metadatos de uso sobre las respuestas.

Campos
promptTokenCount

int32

Solo salida. Cantidad de tokens en la instrucción. Cuando se establece cachedContent, este sigue siendo el tamaño total de la instrucción efectiva, lo que significa que incluye la cantidad de tokens en el contenido almacenado en caché.

cachedContentTokenCount

int32

Cantidad de tokens en la parte almacenada en caché de la instrucción (el contenido almacenado en caché)

responseTokenCount

int32

Solo salida. Es la cantidad total de tokens de todos los candidatos de respuesta generados.

toolUsePromptTokenCount

int32

Solo salida. Cantidad de tokens presentes en las instrucciones de uso de herramientas.

thoughtsTokenCount

int32

Solo salida. Cantidad de tokens de pensamientos para los modelos de pensamiento.

totalTokenCount

int32

Solo salida. Es el recuento total de tokens para la solicitud de generación (instrucción + candidatos de respuesta).

promptTokensDetails[]

ModalityTokenCount

Solo salida. Es la lista de modalidades que se procesaron en la entrada de la solicitud.

cacheTokensDetails[]

ModalityTokenCount

Solo salida. Es la lista de modalidades del contenido almacenado en caché en la entrada de la solicitud.

responseTokensDetails[]

ModalityTokenCount

Solo salida. Es la lista de modalidades que se mostraron en la respuesta.

toolUsePromptTokensDetails[]

ModalityTokenCount

Solo salida. Es la lista de modalidades que se procesaron para las entradas de solicitudes de uso de herramientas.

Más información sobre los tipos comunes

Para obtener más información sobre los tipos de recursos de API de uso general Blob, Content, FunctionCall, FunctionResponse, GenerationConfig, GroundingMetadata, ModalityTokenCount y Tool, consulta Cómo generar contenido.