Configurare gli avatar live

Questo documento descrive come configurare gli avatar live nell'API Gemini Live. Gli avatar live ti consentono di generare video in tempo reale di un avatar che parla sincronizzato con le risposte vocali sintetizzate del modello gemini-3.8-live. Puoi scegliere tra una serie di avatar integrati e abbinarli a voci predefinite supportate sia nella console Google Cloud che nell'API Gemini Live.

Configura gli avatar live nella console Google Cloud

Segui questi passaggi:

  1. Nella console Google Cloud , vai alla pagina Agent Platform > Studio > Stream in tempo reale.

    Vai a Stream in tempo reale

  2. Fai clic su Cambia modello.

  3. Dall'elenco dei modelli, seleziona gemini-3.8-live.

  4. Nel riquadro principale, seleziona Avatar live.

  5. Seleziona un avatar dall'elenco Avatar.

  6. Seleziona una voce dall'elenco Voce.

  7. (Facoltativo) Aggiungi istruzioni di sistema per guidare il comportamento e l'output.

  8. (Facoltativo) Attiva l'input della videocamera per condividere video con l'API Gemini Live.

  9. Nel riquadro principale, fai clic su Avvia sessione.

Configurare gli avatar live utilizzando l'API

Segui questi passaggi:

  1. Nel set generation_config, imposta "response_modalities": ["VIDEO"].

  2. Nell'oggetto avatar_config, specifica il nome dell'avatar predefinito.

  3. Nell'oggetto speech_config, specifica la voce predefinita.

Configurazione WebSocket

Le connessioni WebSocket vengono stabilite con un handshake WebSocket standard. L'endpoint è regionale e utilizza token di connessione (bearer) OAuth 2.0 per l'autenticazione. Il token di autenticazione viene in genere passato nelle intestazioni WebSocket, ad esempio Authorization: Bearer [TOKEN].

Di seguito è riportata una configurazione WebSocket di esempio:

import asyncio
import json
import websockets

# Replace PROJECT_ID and LOCATION with your Project ID and location.
PROJECT_ID = "PROJECT_ID"
LOCATION = "LOCATION"

# Authentication
token_list = !gcloud auth application-default print-access-token
ACCESS_TOKEN = token_list[0]

# Configuration
MODEL_ID = "gemini-3.8-live"
MODEL = f"projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}"

config = {
    "response_modalities": ["VIDEO"],
    "speech_config": {
        "voice_config": {
            "prebuilt_voice_config": {
                "voice_name": "Puck",
            }
        }
    },
}

avatar_config = {
    "avatar_name": "Ben",
}

# Construct the WSS URL
HOST = f"{LOCATION}-aiplatform.googleapis.com"
URI = f"wss://{HOST}/ws/google.cloud.aiplatform.v1.LlmBidiService/BidiGenerateContent"

async def main():
    headers = {"Authorization": f"Bearer {ACCESS_TOKEN}"}

    async with websockets.connect(URI, additional_headers=headers) as ws:
        print("Session established.")

        # Send Setup (Handshake)
        await ws.send(json.dumps({
            "setup": {
                "model": MODEL,
                "generation_config": config,
                "avatar_config": avatar_config,
            }
        }))
        # Send and receive audio/video streams...

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

Configurazione dell'SDK Python

Il seguente esempio mostra come configurare gli avatar live utilizzando l'SDK Google Gen AI:

from google import genai
from google.genai import types

client = genai.Client()

config = types.LiveConnectConfig(
    response_modalities=["VIDEO"],
    speech_config=types.SpeechConfig(
        voice_config=types.VoiceConfig(
            prebuilt_voice_config=types.PrebuiltVoiceConfig(
                voice_name="Puck",
            )
        )
    ),
    avatar_config=types.AvatarConfig(
        avatar_name="Ben",
    ),
    system_instruction=types.Content(
        parts=[types.Part.from_text(text="You are a helpful customer service assistant.")]
    ),
)

async with client.aio.live.connect(model="gemini-3.8-live", config=config) as session:
    # Interact with the live session...
    pass

Utilizzare un avatar personalizzato

Anziché scegliere un avatar predefinito, puoi fornire un'immagine di riferimento di un volto e l'API Gemini Live genera il video dell'avatar a partire da questa somiglianza. Gli avatar personalizzati vengono configurati per sessione nel campo customized_avatar di avatar_config.

Requisiti per le immagini di riferimento

L'immagine di riferimento deve soddisfare le seguenti specifiche:

  • Formato immagine: PNG consigliato. Il formato PNG utilizza la compressione lossless e la trasparenza alfa impedisce la visualizzazione di un riquadro visibile intorno all'avatar nelle modalità Chiaro e Buio.
  • Modalità colore: RGB.
  • Dimensioni dell'immagine: minimo 704 x 1280 pixel (verticale), minimo 1280 x 704 pixel (orizzontale).
  • Risoluzione: 720p o superiore.
  • Proporzioni: 9:16 (verticale) e 16:9 (orizzontale) sono standard.
  • Dimensioni file: inferiori a 5 MB
  • Qualità: nessuna sfocatura o artefatto di compressione.

Per risultati ottimali, segui anche queste linee guida per la composizione:

  • Inquadratura: utilizza un primo piano, in cui la testa e le spalle occupano più del 60% dell'inquadratura. Ritaglia la parte inferiore del corpo, le braccia, le mani e qualsiasi oggetto tenuto in mano, come microfoni o smartphone.

  • Sfondo:utilizza uno sfondo semplice e ordinato, senza altre persone o oggetti distinti.

  • Prospettiva: guarda direttamente la fotocamera, con la testa dritta e gli occhi che guardano nell'obiettivo.

  • Espressione:mantieni un'espressione neutra e a riposo, senza sorridere, stringere gli occhi o mostrare i denti.

  • Sicurezza:non utilizzare immagini di minorenni, celebrità o contenuti offensivi.

Configurare un avatar personalizzato nella Google Cloud console

Segui questi passaggi:

  1. Nella console Google Cloud , vai alla pagina Agent Platform > Studio > Stream in tempo reale.

    Stream realtime

  2. Dall'elenco dei modelli, seleziona gemini-3.8-live.

  3. Nel riquadro principale, fai clic su Avatar live.

  4. Seleziona Carica tra le opzioni dell'avatar e carica un'immagine dell'avatar.

  5. Fai clic su Avvia sessione, quindi su Avvia conversazione.

Configurare un avatar personalizzato utilizzando l'API

Configura l'avatar personalizzato nel payload setup iniziale che invii tramite la connessione WebSocket:

import base64
import json
import websockets

# Load custom avatar image (PNG format, 704x1280 min)
with open("/path/to/your/sample_avatar.png", "rb") as f:
    avatar_b64 = base64.b64encode(f.read()).decode("utf-8")

GENERATION_CONFIG = {
    "response_modalities": ["VIDEO"],
}

# Setup avatar config with custom face image
AVATAR_CONFIG = {
    "customized_avatar": {
        "image_data": avatar_b64,
        "image_mime_type": "png",
    }
}

# Session setup message
SETUP_MESSAGE = {
    "setup": {
        "model": "gemini-3.8-live",
        "generation_config": GENERATION_CONFIG,
        "avatar_config": AVATAR_CONFIG,
        "system_instruction": {
            "parts": [{"text": "Your system instruction here"}]
        },
        "input_audio_transcription": {},
        "output_audio_transcription": {},
    }
}

L'esempio precedente utilizza i seguenti campi:

Percorso campo Tipo Descrizione
generation_config.response_modalities list[string] Deve essere impostato su ["VIDEO"] per attivare l'output video dell'avatar.
avatar_config.customized_avatar.image_data string Stringa dell'immagine con codifica base64.
avatar_config.customized_avatar.image_mime_type string Formato MIME immagine ("png").

Puoi abbinare un avatar personalizzato a una voce predefinita o a una voce personalizzata.

Voci predefinite disponibili

Puoi abbinare avatar predefiniti a una qualsiasi delle voci HD predefinite nell'API Gemini Live. Per ulteriori informazioni sulle voci predefinite, consulta Voci predefinite.

Passaggi successivi