Gerenciar sessões da API Live 

O Gemini Live API processa fluxos contínuos de áudio ou texto chamados de sessões. É possível gerenciar o ciclo de vida da sessão, desde o handshake inicial até o encerramento normal.

Limites para sessões

Para o Live API, uma sessão se refere a uma conexão persistente em que a entrada e a saída são transmitidas continuamente por uma conexão.

Se a sessão exceder qualquer um dos seguintes limites, a conexão será encerrada. No entanto, o Live API oferece algumas opções (veja abaixo) para lidar com esses limites relacionados à sessão.

  • A janela de contexto da sessão é limitada a 128 mil tokens.

    Devido a esse limite de janela de contexto, confira as durações máximas aproximadas das sessões com base nas modalidades de entrada:

    • As sessões de entrada somente de áudio são limitadas a 15 minutos.
    • A entrada de vídeo e áudio é limitada a 2 minutos.

  • A duração da conexão é limitada a cerca de 10 minutos.

    Você vai receber uma notificação de encerramento cerca de 60 segundos antes do fim da conexão.

Confira algumas opções para lidar com limites relacionados à sessão:

Iniciar uma sessão

Consulte o guia de primeiros passos do Live API para ver um snippet completo mostrando como iniciar uma sessão.

Atualização no meio da sessão

Os modelos Live API oferecem suporte aos seguintes recursos avançados para atualizações no meio da sessão:

Adicionar atualizações incrementais de conteúdo

É possível adicionar atualizações incrementais durante uma sessão ativa. Use isso para enviar entrada de texto, estabelecer contexto de sessão ou restaurar contexto de sessão.

  • Para contextos mais longos, recomendamos fornecer um único resumo da mensagem para liberar a janela de contexto para interações subsequentes.

  • Para contextos curtos, você pode enviar interações de navegação guiada para representar a sequência exata de eventos, como o snippet abaixo.

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
);

Atualizar instruções do sistema no meio da sessão

Disponível apenas quando você usa o Vertex AI Gemini API como seu provedor de API.

Você pode atualizar as instruções do sistema durante uma sessão ativa. Use isso para adaptar as respostas do modelo, por exemplo, para mudar o idioma ou o tom.

Para atualizar as instruções do sistema no meio da sessão, envie conteúdo de texto com a função system. As instruções atualizadas do sistema vão permanecer em vigor durante o restante da sessão.

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}");
}

Comprimir a janela de contexto

Clique no seu provedor de Gemini API para conferir o conteúdo e o código específicos do provedor nesta página.

A Live API janela de contexto da sessão armazena dados transmitidos em tempo real (25 tokens por segundo [TPS] para áudio e 258 TPS para vídeo), além de outros conteúdos, incluindo entradas de texto e saídas do modelo. Todos os modelos Live API têm um limite de janela de contexto de sessão de 128 mil tokens.

Por padrão, devido a esse limite de janela de contexto, estas são as durações máximas aproximadas das sessões com base nas modalidades de entrada:

  • As sessões de entrada somente de áudio são limitadas a 15 minutos.
  • A entrada de vídeo e áudio é limitada a 2 minutos.

Em sessões longas, conforme a conversa avança, o histórico de tokens de áudio e/ou vídeo se acumula. Se esse histórico exceder o limite do modelo, ele poderá alucinar, ficar mais lento ou a sessão poderá ser encerrada à força.

Para ativar sessões mais longas, ative a compressão da janela de contexto definindo o campo contextWindowCompression como parte do LiveGenerationConfig. Quando ativado, o servidor usa um mecanismo de janela deslizante para descartar automaticamente as conversas mais antigas ou resumi-las para manter o tamanho do contexto dentro dos limites padrão ou especificados. As instruções do sistema não são descartadas e sempre ficam no início da janela de contexto.

Da perspectiva do usuário, isso permite durações de sessão teoricamente infinitas, já que a "memória" é gerenciada constantemente.

É possível configurar o mecanismo de janela deslizante e, opcionalmente, o número de tokens que aciona a compactação. Consulte as configurações e os valores disponíveis abaixo. Confira algumas considerações gerais sobre o uso dessas configurações:

  • Definir targetTokens como um valor muito baixo libera mais espaço de contexto para fluxos contínuos, mas o modelo "esquece" rapidamente as conversas mais antigas.

  • Definir targetTokens mais perto de triggerTokens preserva mais memória, mas aciona rotinas de compactação com muito mais frequência.

Configuração Padrão para janela deslizante se não estiver definido na configuração Valor mínimo Valor máximo
triggerTokens
o tamanho do contexto antes que a compactação seja acionada 		80% do limite da janela de contexto do modelo 5.000 128.000
targetTokens
o número de tokens de destino a serem mantidos 		50% do valor triggerTokens
  • Se triggerTokens não for definido explicitamente, targetTokens será 50% do valor triggerTokens padrão.
  • O valor de targetTokens precisa ser menor que o de 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)
        )
    )
);

Detectar quando uma sessão vai terminar

A duração máxima de uma única conexão WebSocket contínua é de aproximadamente 10 minutos. Uma notificação de descontinuação é enviada ao cliente 60 segundos antes do fim da conexão, o que pode ajudar você a tomar outras medidas, por exemplo, retomar uma sessão.

O exemplo a seguir mostra como detectar um encerramento de conexão iminente ao ouvir uma notificação de going away:

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}");
    }
}

Retomar uma sessão

O Live API oferece suporte à retomada de sessão para evitar a perda do contexto da conversa. Cada sessão tem um identificador que pode ser usado das seguintes maneiras:

  • Manter uma sessão antes de atingir o limite de tempo de conexão

    A duração máxima de uma única conexão WebSocket contínua é de aproximadamente 10 minutos. É possível detectar quando uma conexão está prestes a terminar ouvindo uma notificação de going away e estendendo a sessão ao estabelecer uma nova conexão usando o identificador da sessão.

  • Retomar uma sessão logo após uma queda de conexão

    Se uma conexão for encerrada ou interrompida antes do tempo máximo de conexão (por exemplo, ao mudar do Wi-Fi para o 5G), o servidor manterá o estado da sessão por cerca de 10 minutos. Durante esse período, você pode retomar a sessão estabelecendo uma nova conexão usando o identificador de sessão.

  • Retomar uma sessão após um longo período

    Depois que uma conexão termina, o servidor mantém o estado da sessão por algumas horas. Durante esse período, você pode retomar a sessão estabelecendo uma nova conexão usando o identificador de sessão. Essa janela é diferente para os dois provedores de Gemini API: Gemini Developer API é de 2 horas e Vertex AI Gemini API é de 24 horas.

Por padrão, a retomada de sessão está desativada. Para ativar a retomada da sessão, transmita uma configuração de retomada vazia ao estabelecer uma nova conexão. Quando ativado, o servidor envia atualizações periodicamente com um identificador de retomada de sessão. Se a sessão for desconectada, você poderá se reconectar e transmitir esse identificador para retomar a sessão com o contexto intacto.

Os exemplos a seguir mostram duas opções para retomar a sessão:

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)
  );
}