Multimodal Live API

L'API Multimodal Live consente interazioni vocali e video bidirezionali a bassa latenza con Gemini. Con l'API Multimodal Live, puoi offrire agli utenti finali l'esperienza di conversazioni vocali naturali e simili a quelle umane, nonché la possibilità di interrompere le risposte del modello utilizzando i comandi vocali. Il modello può elaborare input di testo, audio e video e fornire output di testo e audio.

Puoi provare l'API Multimodal Live in Google AI Studio.

Utilizzare l'API Multimodal Live

Questa sezione descrive come utilizzare l'API Multimodal Live con uno dei nostri SDK. Per saperne di più sull'API WebSockets sottostante, consulta il riferimento all'API WebSockets di seguito.

Inviare e ricevere messaggi

import asyncio
from google import genai

client = genai.Client(api_key="GEMINI_API_KEY", http_options={'api_version': 'v1alpha'})
model = "gemini-2.0-flash-exp"

config = {"response_modalities": ["TEXT"]}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        while True:
            message = input("User> ")
            if message.lower() == "exit":
                break
            await session.send(input=message, end_of_turn=True)

            async for response in session.receive():
                if response.text is not None:
                    print(response.text, end="")

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

Ricevere audio

L'esempio seguente mostra come ricevere i dati audio e scriverli in un file .wav.

import asyncio
import wave
from google import genai

client = genai.Client(api_key="GEMINI_API_KEY", http_options={'api_version': 'v1alpha'})
model = "gemini-2.0-flash-exp"

config = {"response_modalities": ["AUDIO"]}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        wf = wave.open("audio.wav", "wb")
        wf.setnchannels(1)
        wf.setsampwidth(2)
        wf.setframerate(24000)

        message = "Hello? Gemini are you there?"
        await session.send(input=message, end_of_turn=True)

        async for idx,response in async_enumerate(session.receive()):
            if response.data is not None:
                wf.writeframes(response.data)

            # Comment this out to print audio data info
            # if response.server_content.model_turn is not None:
            #      print(response.server_content.model_turn.parts[0].inline_data.mime_type)

        wf.close()

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

Formati audio

L'API Multimodal Live supporta i seguenti formati audio:

• Formato audio di input: audio PCM non compresso a 16 bit a 16 kHz little-endian
• Formato audio di output: audio PCM non compresso a 16 bit a 24 kHz little-endian

Riprodurre audio e video in streaming

Istruzioni di sistema

Le istruzioni di sistema ti consentono di indirizzare il comportamento di un modello in base alle tue esigenze e ai tuoi casi d'uso specifici. Le istruzioni di sistema possono essere impostate nella configurazione della configurazione e rimarranno in vigore per l'intera sessione.

from google.genai import types

config = {
    "system_instruction": types.Content(
        parts=[
            types.Part(
                text="You are a helpful assistant and answer in a friendly tone."
            )
        ]
    ),
    "response_modalities": ["TEXT"],
}

Aggiornamenti incrementali dei contenuti

Utilizza gli aggiornamenti incrementali per inviare input di testo, stabilire il contesto della sessione o ripristinare il contesto della sessione. Per contesti brevi, puoi inviare interazioni passo passo per rappresentare la sequenza esatta di eventi:

from google.genai import types

turns = [
    types.Content(parts=[types.Part(text="What is the capital of France?")], role="user"),
    types.Content(parts=[types.Part(text="Paris")], role="model")
]
await session.send(input=types.LiveClientContent(turns=turns))

turns = [types.Content(parts=[types.Part(text="What is the capital of Germany?")], role="user")]
await session.send(input=types.LiveClientContent(turns=turns, turn_complete=True))

{
  "clientContent": {
    "turns": [
      {
        "parts":[
          {
            "text": ""
          }
        ],
        "role":"user"
      },
      {
        "parts":[
          {
            "text": ""
          }
        ],
        "role":"model"
      }
    ],
    "turnComplete": true
  }
}

Per contesti più lunghi, ti consigliamo di fornire un riepilogo di un singolo messaggio per liberare la finestra del contesto per le interazioni successive.

Cambiare le voci

L'API Multimodal Live supporta le seguenti voci: Aoede, Charon, Fenrir, Kore e Puck.

Per specificare una voce, imposta il nome della voce all'interno dell'oggetto speechConfig come parte della configurazione della sessione:

from google.genai import types

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    speech_config=types.SpeechConfig(
        voice_config=types.VoiceConfig(
            prebuilt_voice_config=types.PrebuiltVoiceConfig(voice_name="Kore")
        )
    )
)

{
  "voiceConfig": {
    "prebuiltVoiceConfig": {
      "voiceName": "Kore"
    }
  }
}

Utilizzare le chiamate di funzione

Puoi definire gli strumenti con l'API Multimodal Live. Consulta il tutorial sulle chiamate di funzione per scoprire di più sulle chiamate di funzione.

Gli strumenti devono essere definiti come parte della configurazione della sessione:

config = types.LiveConnectConfig(
    response_modalities=["TEXT"],
    tools=[set_light_values]
)

async with client.aio.live.connect(model=model, config=config) as session:
    await session.send(input="Turn the lights down to a romantic level", end_of_turn=True)

    async for response in session.receive():
        print(response.tool_call)

Da un singolo prompt, il modello può generare più chiamate di funzione e il codice necessario per collegarne gli output. Questo codice viene eseguito in un ambiente sandbox, generando messaggi BidiGenerateContentToolCall successivi. L'esecuzione viene messa in pausa finché non sono disponibili i risultati di ogni chiamata di funzione, il che garantisce l'elaborazione sequenziale.

Il cliente deve rispondere con BidiGenerateContentToolResponse.

Gli input e gli output audio influiscono negativamente sulla capacità del modello di utilizzare la chiamata di funzioni.

Gestire le interruzioni

Gli utenti possono interrompere l'output del modello in qualsiasi momento. Quando il rilevamento dell'attività vocale (VAD) rileva un'interruzione, la generazione in corso viene annullata e ignorata. Nella cronologia della sessione vengono conservate solo le informazioni già inviate al client. Il server invia quindi un messaggio BidiGenerateContentServerContent per segnalare l'interruzione.

Inoltre, il server Gemini ignora le chiamate di funzione in attesa e invia un messaggio BidiGenerateContentServerContent con gli ID delle chiamate annullate.

async for response in session.receive():
    if response.server_content.interrupted is not None:
        # The generation was interrupted

Limitazioni

Tieni presente i seguenti limiti dell'API Multimodal Live e di Gemini 2.0 quando pianifichi il tuo progetto.

Autenticazione client

L'API Multimodal Live fornisce solo l'autenticazione server-to-server e non è consigliata per l'utilizzo diretto del client. L'input del client deve essere instradato tramite un server di applicazioni intermedio per l'autenticazione sicura con l'API Multimodal Live.

Cronologia conversazione

Sebbene il modello tenga traccia delle interazioni all'interno della sessione, la cronologia delle conversazioni non viene archiviata. Al termine di una sessione, il contesto corrispondente viene cancellato.

Per ripristinare una sessione precedente o fornire al modello il contesto storico delle interazioni utente, l'applicazione deve gestire il proprio log di conversazione e utilizzare un messaggio BidiGenerateContentClientContent per inviare queste informazioni all'inizio di una nuova sessione.

Durata massima della sessione

La durata della sessione è limitata a 15 minuti per l'audio o a 2 minuti per audio e video. Quando la durata della sessione supera il limite, la connessione viene interrotta.

Il modello è limitato anche dalle dimensioni del contesto. L'invio di grandi blocchi di contenuti insieme agli stream video e audio potrebbe comportare l'interruzione anticipata della sessione.

Rilevamento attività vocale (VAD)

Il modello esegue automaticamente il rilevamento dell'attività vocale (VAD) su un stream di input audio continuo. La funzionalità VAD è sempre attivata e i relativi parametri non sono configurabili.

Conteggio token

Il conteggio dei token non è supportato.

Limiti di frequenza

Si applicano i seguenti limiti di frequenza:

• 3 sessioni simultanee per chiave API
• 4 milioni di token al minuto

Riferimento all'API WebSockets

L'API Multimodal Live è un'API con stato che utilizza WebSockets. In questa sezione troverai ulteriori dettagli sull'API WebSockets.

Sessioni

Una connessione WebSocket stabilisce una sessione tra il client e il server Gemini. Dopo che un client ha avviato una nuova connessione, la sessione può scambiare messaggi con il server per:

• Invia testo, audio o video al server Gemini.
• Ricevere richieste di chiamate audio, di testo o di funzione dal server Gemini.

Il messaggio iniziale dopo la connessione imposta la configurazione della sessione, che include il modello, i parametri di generazione, le istruzioni di sistema e gli strumenti.

Consulta la seguente configurazione di esempio. Tieni presente che la modalità maiuscole/minuscole dei nomi negli SDK può variare. Puoi trovare le opzioni di configurazione dell'SDK Python qui.

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

Inviare messaggi

Per scambiare messaggi tramite la connessione WebSocket, il client deve inviare un oggetto JSON tramite una connessione WebSocket aperta. L'oggetto JSON deve avere esattamente uno dei campi del seguente insieme di oggetti:

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

Messaggi client supportati

Consulta i messaggi client supportati nella tabella seguente:

Ricevere messaggi

Per ricevere messaggi da Gemini, ascolta l'evento "message" di WebSocket, quindi analizza il risultato in base alla definizione dei messaggi del server supportati.

Consulta quanto segue:

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)

I messaggi del server avranno esattamente uno dei campi del seguente insieme di oggetti:

{
  "setupComplete": BidiGenerateContentSetupComplete,
  "serverContent": BidiGenerateContentServerContent,
  "toolCall": BidiGenerateContentToolCall,
  "toolCallCancellation": BidiGenerateContentToolCallCancellation
}

Messaggi del server supportati

Consulta i messaggi del server supportati nella tabella seguente:

Messaggi ed eventi

Ulteriori informazioni sui tipi comuni

Per saperne di più sui tipi di risorse API di uso comune Blob, Content, FunctionCall, FunctionResponse, GenerationConfig, GroundingMetadata e Tool, consulta Generare contenuti.

Integrazioni di terze parti

Per i deployment di app web e mobile, puoi esplorare le opzioni disponibili in:

• Ogni giorno
• Livekit