L'API Live consente interazioni vocali e video bidirezionali a bassa latenza con Gemini. Utilizza l'API Live per fornire agli utenti finali conversazioni vocali naturali e simili a quelle umane, inclusa la possibilità di interrompere le risposte del modello con i comandi vocali.
Questo documento illustra le nozioni di base sull'utilizzo dell'API Live, incluse le sue funzionalità, esempi iniziali ed esempi di codice per casi d'uso di base. Se stai cercando informazioni su come avviare una conversazione interattiva utilizzando l'API Live, consulta Conversazioni interattive con l'API Live. Se stai cercando informazioni sugli strumenti che l'API Live può utilizzare, consulta la sezione Strumenti integrati.
Modelli supportati
L'API Live è supportata per l'utilizzo sia nell'SDK Google Gen AI sia in Vertex AI Studio. Alcune funzionalità (come l'input e l'output di testo) sono disponibili solo utilizzando Gen AI SDK.
Puoi utilizzare l'API Live con i seguenti modelli:
Versione del modello | Livello di disponibilità |
---|---|
gemini-live-2.5-flash |
GA privato* |
gemini-live-2.5-flash-preview-native-audio-09-2025 |
Anteprima pubblica |
gemini-live-2.5-flash-preview-native-audio |
Anteprima pubblica; data di ritiro: 18 ottobre 2025 |
* Contatta il rappresentante del team dedicato al tuo Account Google per richiedere l'accesso.
Per ulteriori informazioni, incluse specifiche tecniche e limitazioni, consulta la guida di riferimento dell'API Live.
Funzionalità dell'API Live
- Comprensione multimodale in tempo reale: conversa con Gemini su ciò che vede in un feed video o tramite la condivisione dello schermo, utilizzando il supporto integrato per lo streaming audio e video.
- Utilizzo di strumenti integrati: integra perfettamente strumenti come chiamata di funzioni e Grounding con la Ricerca Google nelle tue conversazioni per interazioni più pratiche e dinamiche.
- Interazioni a bassa latenza: interagisci con Gemini con una latenza ridotta e in modo simile a un essere umano.
- Supporto multilingue: Conversa in 24 lingue supportate.
- (Solo versioni GA) Supporto del throughput sottoposto a provisioning: utilizza un abbonamento a costo fisso e durata fissa disponibile in diverse durate che riserva il throughput per i modelli di AI generativa supportati su Vertex AI, inclusa l'API Live.
- Trascrizione di alta qualità:l'API Live supporta la trascrizione del testo per l'audio di input e output.
Gemini 2.5 Flash con l'API Live include anche l'audio nativo come offerta di anteprima pubblica. L'audio nativo introduce:
- Dialogo affettivo: l'API Live comprende e risponde al tono di voce dell'utente. Le stesse parole pronunciate in modi diversi possono portare a conversazioni molto diverse e più sfumate.
- Audio proattivo e consapevolezza del contesto: l'API Live ignora in modo intelligente le conversazioni ambientali e altri audio irrilevanti, comprendendo quando ascoltare e quando rimanere in silenzio.
Per ulteriori informazioni sull'audio nativo, consulta Strumenti integrati.
Formati audio supportati
L'API Live supporta i seguenti formati audio:
- Audio di input:audio PCM a 16 bit non elaborato a 16 kHz, little-endian
- Audio di output:audio PCM a 16 bit non elaborato a 24 kHz, little-endian
Formati video supportati
L'API Live supporta l'input di frame video a 1 FPS. Per risultati ottimali, utilizza la risoluzione nativa 768x768 a 1 FPS.
Esempi di comandi iniziali
Puoi iniziare a utilizzare l'API Live con uno dei seguenti tutorial sui notebook, applicazioni demo o guide.
Tutorial su Notebook
Scarica questi tutorial sui notebook da GitHub o aprili nell'ambiente che preferisci.
Utilizzare WebSocket con l'API Live
Streaming di audio e video
App e guide dimostrative
Altri esempi
Per ottenere ancora più utilità dall'API Live, prova questi esempi che utilizzano le funzionalità di elaborazione audio, trascrizione e risposta vocale dell'API Live.
Ricevere risposte di testo dall'input audio
Puoi inviare audio e ricevere risposte di testo convertendo l'audio in un formato PCM a 16 bit, 16 kHz, mono. Il seguente esempio legge un file WAV e lo invia nel formato corretto:
Python
# Test file: https://storage.googleapis.com/generativeai-downloads/data/16000.wav # Install helpers for converting files: pip install librosa soundfile import asyncio import io from pathlib import Path from google import genai from google.genai import types import soundfile as sf import librosa client = genai.Client( vertexai=True, project=GOOGLE_CLOUD_PROJECT, location=GOOGLE_CLOUD_LOCATION, ) model = "gemini-live-2.5-flash" config = {"response_modalities": ["TEXT"]} async def main(): async with client.aio.live.connect(model=model, config=config) as session: buffer = io.BytesIO() y, sr = librosa.load("sample.wav", sr=16000) sf.write(buffer, y, sr, format="RAW", subtype="PCM_16") buffer.seek(0) audio_bytes = buffer.read() # If already in correct format, you can use this: # audio_bytes = Path("sample.pcm").read_bytes() await session.send_realtime_input( audio=types.Blob(data=audio_bytes, mime_type="audio/pcm;rate=16000") ) async for response in session.receive(): if response.text is not None: print(response.text) if __name__ == "__main__": asyncio.run(main())
Ricevere risposte vocali dall'input di testo
Utilizza questo esempio per inviare l'input di testo e ricevere risposte vocali sintetizzate:
Python
import asyncio import numpy as np from IPython.display import Audio, Markdown, display from google import genai from google.genai.types import ( Content, LiveConnectConfig, HttpOptions, Modality, Part, SpeechConfig, VoiceConfig, PrebuiltVoiceConfig, ) client = genai.Client( vertexai=True, project=GOOGLE_CLOUD_PROJECT, location=GOOGLE_CLOUD_LOCATION, ) voice_name = "Aoede" config = LiveConnectConfig( response_modalities=["AUDIO"], speech_config=SpeechConfig( voice_config=VoiceConfig( prebuilt_voice_config=PrebuiltVoiceConfig( voice_name=voice_name, ) ), ), ) async with client.aio.live.connect( model="gemini-live-2.5-flash", config=config, ) as session: text_input = "Hello? Gemini are you there?" display(Markdown(f"**Input:** {text_input}")) await session.send_client_content( turns=Content(role="user", parts=[Part(text=text_input)])) audio_data = [] async for message in session.receive(): if ( message.server_content.model_turn and message.server_content.model_turn.parts ): for part in message.server_content.model_turn.parts: if part.inline_data: audio_data.append( np.frombuffer(part.inline_data.data, dtype=np.int16) ) if audio_data: display(Audio(np.concatenate(audio_data), rate=24000, autoplay=True))
Per altri esempi di invio di testo, consulta la nostra Guida introduttiva.
Trascrivi audio
L'API Live può trascrivere l'audio di input e output. Utilizza il seguente esempio per attivare la trascrizione:
Python
import asyncio from google import genai from google.genai import types client = genai.Client( vertexai=True, project=GOOGLE_CLOUD_PROJECT, location=GOOGLE_CLOUD_LOCATION, ) model = "gemini-live-2.5-flash" config = { "response_modalities": ["AUDIO"], "input_audio_transcription": {}, "output_audio_transcription": {} } async def main(): async with client.aio.live.connect(model=model, config=config) as session: message = "Hello? Gemini are you there?" await session.send_client_content( turns={"role": "user", "parts": [{"text": message}]}, turn_complete=True ) async for response in session.receive(): if response.server_content.model_turn: print("Model turn:", response.server_content.model_turn) if response.server_content.input_transcription: print("Input transcript:", response.server_content.input_transcription.text) if response.server_content.output_transcription: print("Output transcript:", response.server_content.output_transcription.text) if __name__ == "__main__": asyncio.run(main())
WebSockets
# Set model generation_config CONFIG = { 'response_modalities': ['AUDIO'], } headers = { "Content-Type": "application/json", "Authorization": f"Bearer {bearer_token[0]}", } # Connect to the server async with connect(SERVICE_URL, additional_headers=headers) as ws: # Setup the session await ws.send( json.dumps( { "setup": { "model": "gemini-2.0-flash-live-preview-04-09", "generation_config": CONFIG, 'input_audio_transcription': {}, 'output_audio_transcription': {} } } ) ) # Receive setup response raw_response = await ws.recv(decode=False) setup_response = json.loads(raw_response.decode("ascii")) # Send text message text_input = "Hello? Gemini are you there?" display(Markdown(f"**Input:** {text_input}")) msg = { "client_content": { "turns": [{"role": "user", "parts": [{"text": text_input}]}], "turn_complete": True, } } await ws.send(json.dumps(msg)) responses = [] input_transcriptions = [] output_transcriptions = [] # Receive chucks of server response async for raw_response in ws: response = json.loads(raw_response.decode()) server_content = response.pop("serverContent", None) if server_content is None: break if (input_transcription := server_content.get("inputTranscription")) is not None: if (text := input_transcription.get("text")) is not None: input_transcriptions.append(text) if (output_transcription := server_content.get("outputTranscription")) is not None: if (text := output_transcription.get("text")) is not None: output_transcriptions.append(text) model_turn = server_content.pop("modelTurn", None) if model_turn is not None: parts = model_turn.pop("parts", None) if parts is not None: for part in parts: pcm_data = base64.b64decode(part["inlineData"]["data"]) responses.append(np.frombuffer(pcm_data, dtype=np.int16)) # End of turn turn_complete = server_content.pop("turnComplete", None) if turn_complete: break if input_transcriptions: display(Markdown(f"**Input transcription >** {''.join(input_transcriptions)}")) if responses: # Play the returned audio message display(Audio(np.concatenate(responses), rate=24000, autoplay=True)) if output_transcriptions: display(Markdown(f"**Output transcription >** {''.join(output_transcriptions)}"))
Il prezzo della trascrizione dell'API Live è determinato dal numero di token di output di testo. Per saperne di più, consulta la pagina dei prezzi di Vertex AI.
Ulteriori informazioni
Per ulteriori informazioni sull'utilizzo dell'API Live, consulta:
- Best practice per l'API Live
- Guida di riferimento all'API live
- Conversazioni interattive
- Strumenti integrati