Gérer les sessions pour l'API Live

Le Gemini Live API traite des flux continus d'audio ou de texte appelés sessions. Vous pouvez gérer le cycle de vie des sessions, de la prise de contact initiale à l'arrêt progressif.

Limites concernant les sessions

Pour le Live API, une session fait référence à une connexion persistante dans laquelle les entrées et les sorties sont diffusées en continu sur une connexion.

Si la session dépasse l'une des limites suivantes, la connexion est interrompue. Toutefois, notez que le Live API fournit certaines options (voir ci-dessous) pour gérer ces limites liées aux sessions.

  • La fenêtre de contexte de la session est limitée à 128 000 jetons.

    En raison de cette limite de la fenêtre de contexte, voici les durées maximales approximatives des sessions en fonction des modalités d'entrée :

    • Les sessions d'entrée audio uniquement sont limitées à 15 minutes.
    • Les entrées vidéo et audio sont limitées à 2 minutes.
  • La durée de la connexion est limitée à environ 10 minutes.

    Vous recevrez une notification d'arrêt environ 60 secondes avant la fin de la connexion.

Voici quelques options pour gérer les limites liées aux sessions :

Démarrer une session

Consultez le guide de démarrage pour Live API pour obtenir un extrait complet montrant comment démarrer une session.

Mettre à jour en cours de session

Les modèles Live API sont compatibles avec les fonctionnalités avancées suivantes pour les mises à jour en cours de session :

Ajouter des mises à jour incrémentielles du contenu

Vous pouvez ajouter des mises à jour incrémentielles pendant une session active. Utilisez cette option pour envoyer une entrée textuelle, ou établir ou restaurer le contexte de la session.

  • Pour les contextes plus longs, nous vous recommandons de fournir un seul résumé des messages afin de libérer la fenêtre de contexte pour les interactions suivantes.

  • Pour les contextes courts, vous pouvez envoyer des interactions au fur et à mesure pour représenter la séquence exacte des événements, comme dans l'extrait ci-dessous.

Swift

// Define initial turns (history/context).
let turns: [ModelContent] = [
  ModelContent(role: "user", parts: [TextPart("What is the capital of France?")]),
  ModelContent(role: "model", parts: [TextPart("Paris")]),
]

// Send history, keeping the conversational turn OPEN (false).
await session.sendContent(turns, turnComplete: false)

// Define the new user query.
let newTurn: [ModelContent] = [
  ModelContent(role: "user", parts: [TextPart("What is the capital of Germany?")]),
]

// Send the final query, CLOSING the turn (true) to trigger the model response.
await session.sendContent(newTurn, turnComplete: true)

Kotlin

Not yet supported for Android apps - check back soon!

Java

Not yet supported for Android apps - check back soon!

Web

const turns = [{ text: "Hello from the user!" }];

await session.send(
  turns,
  false // turnComplete: false
);

console.log("Sent history. Waiting for next input...");

// Define the new user query.
const newTurn [{ text: "And what is the capital of Germany?" }];

// Send the final query, CLOSING the turn (true) to trigger the model response.
await session.send(
    newTurn,
    true // turnComplete: true
);
console.log("Sent final query. Model response expected now.");

Dart

// Define initial turns (history/context).
final List turns = [
  Content(
    "user",
    [Part.text("What is the capital of France?")],
  ),
  Content(
    "model",
    [Part.text("Paris")],
  ),
];

// Send history, keeping the conversational turn OPEN (false).
await session.send(
  input: turns,
  turnComplete: false,
);

// Define the new user query.
final List newTurn = [
  Content(
    "user",
    [Part.text("What is the capital of Germany?")],
  ),
];

// Send the final query, CLOSING the turn (true) to trigger the model response.
await session.send(
  input: newTurn,
  turnComplete: true,
);

Unity

// Define initial turns (history/context).
List turns = new List {
    new ModelContent("user", new ModelContent.TextPart("What is the capital of France?") ),
    new ModelContent("model", new ModelContent.TextPart("Paris") ),
};

// Send history, keeping the conversational turn OPEN (false).
foreach (ModelContent turn in turns)
{
    await session.SendAsync(
        content: turn,
        turnComplete: false
    );
}

// Define the new user query.
ModelContent newTurn = ModelContent.Text("What is the capital of Germany?");

// Send the final query, CLOSING the turn (true) to trigger the model response.
await session.SendAsync(
    content: newTurn,
    turnComplete: true
);

Mettre à jour les instructions système en cours de session

Disponible uniquement lorsque vous utilisez Vertex AI Gemini API comme fournisseur d'API.

Vous pouvez mettre à jour les instructions système pendant une session active. Utilisez cette option pour adapter les réponses du modèle, par exemple pour modifier la langue de la réponse ou le ton.

Pour mettre à jour les instructions système en cours de session, vous pouvez envoyer du contenu textuel avec le rôle system. Les instructions système mises à jour resteront en vigueur pour le reste de la session.

Swift

await session.sendContent(
  [ModelContent(
    role: "system",
    parts: [TextPart("new system instruction")]
  )],
  turnComplete: false
)

Kotlin

Not yet supported for Android apps - check back soon!

Java

Not yet supported for Android apps - check back soon!

Web

Not yet supported for Web apps - check back soon!

Dart

try {
  await _session.send(
    input: Content(
      'system',
      [Part.text('new system instruction')],
    ),
    turnComplete: false,
  );
} catch (e) {
  print('Failed to update system instructions: $e');
}

Unity

try
{
    await session.SendAsync(
        content: new ModelContent(
            "system",
            new ModelContent.TextPart("new system instruction")
        ),
        turnComplete: false
    );
}
catch (Exception e)
{
    Debug.LogError($"Failed to update system instructions: {e.Message}");
}

Compresser la fenêtre de contexte

Cliquez sur votre fournisseur Gemini API pour afficher le contenu spécifique au fournisseur et le code sur cette page.

La Live API fenêtre de contexte de session stocke les données diffusées en temps réel (25 jetons par seconde (TPS) pour l'audio et 258 TPS pour la vidéo), ainsi que d'autres contenus, y compris les entrées textuelles et les sorties de modèle. Tous les modèles Live API ont une limite de fenêtre de contexte de session de 128 000 jetons.

Par défaut, en raison de cette limite de la fenêtre de contexte, voici les durées maximales approximatives des sessions en fonction des modalités d'entrée :

  • Les sessions d'entrée audio uniquement sont limitées à 15 minutes.
  • Les entrées vidéo et audio sont limitées à 2 minutes.

Dans les sessions de longue durée, à mesure que la conversation progresse, l'historique des jetons audio et/ou vidéo s'accumule. Si cet historique dépasse la limite du modèle, le modèle peut halluciner, ralentir ou la session peut être interrompue de force.

Pour autoriser des sessions plus longues, vous pouvez activer la compression de la fenêtre de contexte en définissant le champ contextWindowCompression dans le cadre de LiveGenerationConfig. Lorsqu'elle est activée, le serveur utilise un mécanisme de fenêtre glissante pour ignorer automatiquement les tours les plus anciens ou les résumer afin de maintenir la taille du contexte dans les limites par défaut ou spécifiées. Les instructions système ne sont pas ignorées et resteront toujours au début de la fenêtre de contexte.

Du point de vue de l'utilisateur, cela permet des durées de session théoriquement infinies, car la "mémoire" est constamment gérée.

Vous pouvez configurer le mécanisme de fenêtre glissante, ainsi que éventuellement le nombre de jetons qui déclenche la compression (voir les paramètres et valeurs disponibles ci-dessous). Voici quelques considérations générales concernant l'utilisation de ces paramètres :

  • Si vous définissez targetTokens sur une valeur très faible, vous libérerez plus d'espace de contexte pour les flux continus, mais le modèle "oubliera" rapidement les tours les plus anciens de la conversation.

  • Si vous définissez targetTokens sur une valeur plus proche de triggerTokens, vous préserverez plus de mémoire, mais vous déclencherez des routines de compression beaucoup plus fréquemment.

Paramètre Valeur par défaut pour la fenêtre glissante si elle n'est pas définie dans la configuration Valeur minimale Valeur maximale
triggerTokens
Longueur de contexte avant le déclenchement de la compression
80% de la limite de la fenêtre de contexte du modèle 5 000 128 000
targetTokens
Nombre cible de jetons à conserver
50% de la valeur triggerTokens
  • Si triggerTokens n'est pas explicitement défini, alors targetTokens est défini par défaut sur 50% de la valeur par défaut triggerTokens.
  • La valeur targetTokens doit être inférieure à la valeur triggerTokens
0 128 000

Swift


// Initialize the Gemini Developer API backend service
let liveModel = FirebaseAI.firebaseAI(backend: .googleAI()).liveModel(
  modelName: "gemini-2.5-flash-native-audio-preview-12-2025",
  // Enable context window compression.
  // (Optional) Configure the number of tokens in the context window that triggers the compression.
  generationConfig: LiveGenerationConfig(
    responseModalities: [.audio],
    contextWindowCompression: ContextWindowCompressionConfig(
      triggerTokens: 10000,
      slidingWindow: SlidingWindow(
        targetTokens: 2000,
      )
    )
  )
)

Kotlin


// Initialize the Gemini Developer API backend service
val liveModel = Firebase.ai(backend = GenerativeBackend.googleAI()).liveModel(
    modelName = "gemini-2.5-flash-native-audio-preview-12-2025",
    // Enable context window compression.
    // (Optional) Configure the number of tokens in the context window that triggers the compression.
    generationConfig = liveGenerationConfig {
        responseModality = ResponseModality.AUDIO,
        contextWindowCompression = ContextWindowCompressionConfig(
            triggerTokens = 10000,
            slidingWindow = SlidingWindow(targetTokens = 2000)
        )
    }
)

Java


// Initialize the Gemini Developer API backend service
LiveGenerativeModel lm = FirebaseAI.getInstance(GenerativeBackend.googleAI()).liveModel(
        "gemini-2.5-flash-native-audio-preview-12-2025",
        // Enable context window compression.
        // (Optional) Configure the number of tokens in the context window that triggers the compression.
        new LiveGenerationConfig.Builder()
                .setResponseModality(ResponseModality.AUDIO)
                .setContextWindowCompression(
                        new ContextWindowCompressionConfig(10000, new SlidingWindow(2000))
                )
                .build()
);

Web


const ai = getAI(firebaseApp, { backend: new GoogleAIBackend() });

const liveModel = getLiveGenerativeModel(ai, {
  model: "gemini-2.5-flash-native-audio-preview-12-2025",
  // Enable context window compression.
  // (Optional) Configure the number of tokens in the context window that triggers the compression.
  generationConfig: {
    responseModalities: [ResponseModality.AUDIO],
    contextWindowCompression: {
      triggerTokens: 10000,
      slidingWindow: {
        targetTokens: 2000,
      },
    },
  },
});

Dart


final _liveModel = FirebaseAI.googleAI().liveGenerativeModel(
  model: 'gemini-2.5-flash-native-audio-preview-12-2025',
  // Enable context window compression.
  // (Optional) Configure the number of tokens in the context window that triggers the compression.
  liveGenerationConfig: LiveGenerationConfig(
    responseModalities: [ResponseModalities.audio],
    contextWindowCompression: ContextWindowCompressionConfig(
      triggerTokens: 10000,
      slidingWindow: SlidingWindow(targetTokens: 2000),
    ),
  ),
);

Unity


var liveModel = FirebaseAI.GetInstance(FirebaseAI.Backend.GoogleAI()).GetLiveModel(
    modelName: "gemini-2.5-flash-native-audio-preview-12-2025",
    // Enable context window compression.
    // (Optional) Configure the number of tokens in the context window that triggers the compression.
    liveGenerationConfig: new LiveGenerationConfig(
        responseModalities: new[] { ResponseModality.Audio },
        contextWindowCompression: new ContextWindowCompressionConfig(
            triggerTokens: 10000,
            slidingWindow: new SlidingWindow(targetTokens: 2000)
        )
    )
);

Détecter la fin d'une session

La durée maximale d'une connexion WebSocket unique et continue est d'environ 10 minutes. Une notification d'arrêt est envoyée au client 60 secondes avant la fin de la connexion, ce qui peut vous aider à prendre d'autres mesures (par exemple, en reprenant une session).

L'exemple suivant montre comment détecter une interruption de connexion imminente en écoutant une notification d'arrêt :

Swift

for try await response in session.responses {
  switch response.payload {

  case .goingAwayNotice(let goingAwayNotice):
    // Prepare for the session to close soon
    if let timeLeft = goingAwayNotice.timeLeft {
        print("Server going away in \(timeLeft) seconds")
    }
  }
}

Kotlin

for (response in session.responses) {
    when (val message = response.payload) {
        is LiveServerGoAway -> {
            // Prepare for the session to close soon
            val remaining = message.timeLeft
            logger.info("Server going away in $remaining")
        }
    }
}

Java

session.getResponses().forEach(response -> {
    if (response.getPayload() instanceof LiveServerResponse.GoingAwayNotice) {
        LiveServerResponse.GoingAwayNotice notice = (LiveServerResponse.GoingAwayNotice) response.getPayload();
        // Prepare for the session to close soon
        Duration timeLeft = notice.getTimeLeft();
    }
});

Web

for await (const message of session.receive()) {
  switch (message.type) {

  ...
  case "goingAwayNotice":
    console.log("Server going away. Time left:", message.timeLeft);
    break;
  }
}

Dart

Future _handleLiveServerMessage(LiveServerResponse response) async {
  final message = response.message;
  if (message is GoingAwayNotice) {
     // Prepare for the session to close soon
     developer.log('Server going away. Time left: ${message.timeLeft}');
  }
}

Unity

foreach (var response in session.Responses) {
    if (response.Payload is LiveSessionGoingAway notice) {
        // Prepare for the session to close soon
        TimeSpan timeLeft = notice.TimeLeft;
        Debug.Log($"Server going away notice received. Remaining: {timeLeft}");
    }
}

Reprendre une session

Le Live API est compatible avec la reprise de session pour éviter de perdre le contexte de la conversation. Chaque session possède un handle, qui peut être utilisé de différentes manières :

  • Maintenir une session avant d'atteindre la limite de temps de connexion

    La durée maximale d'une connexion WebSocket unique et continue est d'environ 10 minutes. Vous pouvez détecter la fin d'une connexion en écoutant une notification d'arrêt, puis en prolongeant la session en établissant une nouvelle connexion à l'aide du handle de session.

  • Reprendre une session juste après une interruption de connexion

    Si une connexion s'arrête ou est interrompue avant la limite de temps de connexion maximale (par exemple, en passant du Wi-Fi à la 5G), le serveur conserve l'état de la session pendant environ 10 minutes. Pendant cette période, vous pouvez reprendre la session en établissant une nouvelle connexion à l'aide du handle de session.

  • Reprendre une session après une période prolongée

    Une fois la connexion terminée, le serveur conserve l'état de la session pendant quelques heures. Pendant cette période, vous pouvez reprendre la session en établissant une nouvelle connexion à l'aide du handle de session. Notez que cette période est différente pour les deux Gemini API fournisseurs : Gemini Developer API est de 2 heures | Vertex AI Gemini API est de 24 heures.

Par défaut, la reprise de session est désactivée. Pour activer la reprise de session, transmettez une configuration de reprise vide lorsque vous établissez une nouvelle connexion. Lorsqu'elle est activée, le serveur envoie régulièrement des mises à jour contenant un handle de reprise de session. Si la session est déconnectée, vous pouvez vous reconnecter et transmettre ce handle pour reprendre la session avec son contexte intact.

Les exemples suivants présentent deux options pour reprendre la session :

Swift

// Local variable to save the active session handle
var activeSessionHandle: String?

// Initialize the session. Passing an empty config requests the server to send SessionResumptionUpdate
var session = try await liveModel.connect(
  sessionResumption: SessionResumptionConfig()
)

// Start receiving responses
for try await message in session.responses {
  // Check for new session handles inside your message handling loop
  switch message.payload {
  case let .sessionResumptionUpdate(updateMessage):
    guard let newHandle = updateMessage.newHandle, updateMessage.resumable else {
      continue
    }
    activeSessionHandle = newHandle
    print("SessionResumptionUpdate: handle \(newHandle)")
  // ... handle other LiveServerMessage types ...
  default:
    break
  }
}

// The following are alternative options to resume a session. Choose only one.

// Option 1: Create and connect a session to resume with the saved handle
if let handle = activeSessionHandle {
  session = try await liveModel.connect(
    sessionResumption: SessionResumptionConfig(handle: handle)
  )
}

// Option 2: Resume the session directly on an existing session object
if let handle = activeSessionHandle {
  try await session.resumeSession(
    sessionResumption: SessionResumptionConfig(handle: handle)
  )
}

Kotlin

// Local variable to save the active session handle
var activeSessionHandle: String? = null

// Initialize the session. Passing an empty config requests the server to send SessionResumptionUpdate
var session = liveModel.connect(
    sessionResumption = SessionResumptionConfig()
)

// Start receiving responses
session.receive().collect { message ->
    // Process other received response types...

    // Check for new session handles inside your message handling loop
    if (message is LiveSessionResumptionUpdate) {
        if (message.resumable == true && message.newHandle != null) {
            activeSessionHandle = message.newHandle
            Log.d("TAG", "SessionResumptionUpdate: handle ${message.newHandle}")
        }
    }
}

// The following are alternative options to resume a session. Choose only one.

// Option 1: Create and connect a session to resume with the saved handle
activeSessionHandle?.let { handle ->
    session = liveModel.connect(
        sessionResumption = SessionResumptionConfig(handle = handle)
    )
}

// Option 2: Resume the session directly on an existing session object
activeSessionHandle?.let { handle ->
    session.resumeSession(
        sessionResumption = SessionResumptionConfig(handle = handle)
    )
}

Java

For Java, session resumption is not yet supported. Check back soon!

Web

// Local variable to save the active session handle
let activeSessionHandle = null;

// Initialize the session. Passing an empty object requests the server to send SessionResumptionUpdate
let session = await liveModel.connect({});

// Start receiving responses
for await (const message of session.receive()) {
  // Process other received response types...

  // Check for new session handles inside your message handling loop
  if (message.type === 'sessionResumptionUpdate') {
    if (message.resumable && message.newHandle) {
      activeSessionHandle = message.newHandle;
      console.log(`SessionResumptionUpdate: handle ${activeSessionHandle}`);
    }
  }
}

// The following are alternative options to resume a session. Choose only one.

// Option 1: Create and connect a session to resume with the saved handle
if (activeSessionHandle) {
  session = await liveModel.connect({
    handle: activeSessionHandle
  });
}

// Option 2: Resume the session directly on an existing session object
if (activeSessionHandle) {
  await session.resumeSession({
    handle: activeSessionHandle
  });
}

Dart

// Local variable to save the active session handle
String? _activeSessionHandle;

// Initialize the session. Passing an empty config requests the server to send SessionResumptionUpdate
var _session = await _liveModel.connect(
  sessionResumption: SessionResumptionConfig(),
);

// Start receiving responses
await for (final message in _session.receive()) {
  // Process other received response types...

  // Check for new session handles inside your message handling loop
  if (message is SessionResumptionUpdate &&
      message.resumable != null &&
      message.resumable!) {
    _activeSessionHandle = message.newHandle;
    log('SessionResumptionUpdate: handle ${message.newHandle}');
  }
}

// The following are alternative options to resume a session. Choose only one.

// Option 1: Create and connect a session to resume with the saved handle
if (_activeSessionHandle != null) {
  _session = await _liveModel.connect(
    sessionResumption: SessionResumptionConfig.resume(_activeSessionHandle!),
  );
}

// Option 2: Alternatively, resume the session directly on an existing session object
if (_activeSessionHandle != null) {
  await _session.resumeSession(
    sessionResumption: SessionResumptionConfig.resume(_activeSessionHandle!),
  );
}

Unity

// Local variable to save the active session handle
string activeSessionHandle = null;

// Initialize the session. Passing an empty config requests the server to send SessionResumptionUpdate
var session = await liveModel.ConnectAsync(
    sessionResumption: new SessionResumptionConfig()
);

// Start receiving responses
await foreach (var response in session.ReceiveAsync())
{
  // Process other received response types...

  // Check for new session handles inside your message handling loop
  if (response.Message is LiveSessionResumptionUpdate updateMessage)
  {
    if (updateMessage.Resumable == true && !string.IsNullOrEmpty(updateMessage.NewHandle))
    {
      activeSessionHandle = updateMessage.NewHandle;
      Debug.Log($"SessionResumptionUpdate: handle {activeSessionHandle}");
    }
  }
}

// The following are alternative options to resume a session. Choose only one.

// Option 1: Create and connect a session to resume with the saved handle
if (!string.IsNullOrEmpty(activeSessionHandle)) {
  session = await liveModel.ConnectAsync(
      sessionResumption: new SessionResumptionConfig(activeSessionHandle)
  );
}

// Option 2: Resume the session directly on an existing session object
if (!string.IsNullOrEmpty(activeSessionHandle)) {
  await session.ResumeSessionAsync(
      sessionResumption: new SessionResumptionConfig(activeSessionHandle)
  );
}