Inferência flex

A API Gemini Flex é um nível de inferência que oferece uma redução de custos de 50% em comparação com as taxas padrão, em troca de latência variável e disponibilidade de melhor esforço. Ela foi projetada para cargas de trabalho tolerantes à latência que exigem processamento síncrono, mas não precisam da performance em tempo real da API padrão.

Como usar o Flex

Para usar o nível Flex, especifique service_tier como flex na solicitação. Por padrão, as solicitações usam o nível padrão se esse campo for omitido.

Python

from google import genai

client = genai.Client()

try:
    interaction = client.interactions.create(
        model="gemini-3.5-flash",
        input="Analyze this dataset for trends...",
        service_tier='flex'
    )
    print(interaction.output_text)
except Exception as e:
    print(f"Flex request failed: {e}")

JavaScript

import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({});

async function main() {
    try {
        const interaction = await client.interactions.create({
            model: 'gemini-3.5-flash',
            input: 'Analyze this dataset for trends...',
            service_tier: 'flex'
        });
        console.log(interaction.output_text);
    } catch (e) {
        console.log(`Flex request failed: ${e}`);
    }
}
await main();

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
      "model": "gemini-3.5-flash",
      "input": "Analyze this dataset for trends...",
      "service_tier": "flex"
  }'

Como funciona a inferência flex

A inferência flex do Gemini preenche a lacuna entre a API padrão e o tempo de resposta de 24 horas da API Batch. Ela usa capacidade de computação fora do horário de pico e "descartável" para oferecer uma solução econômica para tarefas em segundo plano e fluxos de trabalho sequenciais.

Recurso Flex Prioridade Padrão Lote
Preços 50% de desconto 75 a 100% a mais que o padrão Preço total 50% de desconto
Latência Minutos (1 a 15 min de destino) Baixa (segundos) Segundos a minutos Até 24 horas
Confiabilidade Melhor esforço (descartável) Alta (não descartável) Alta / média-alta Alta (para capacidade de processamento)
Interface Síncrona Síncrona Síncrona Assíncrona

Principais benefícios

  • Eficiência de custos: economia substancial para avaliações de não produção, agentes em segundo plano e aprimoramento de dados.
  • Baixa fricção: basta adicionar um único parâmetro às solicitações atuais.
  • Fluxos de trabalho síncronos: ideal para cadeias de API sequenciais em que a próxima solicitação depende da saída da anterior, tornando-a mais flexível do que o lote para fluxos de trabalho de agentes.

Casos de uso

  • Avaliações off-line: execução de testes de regressão ou placares de "LLM como um juiz".
  • Agentes em segundo plano: tarefas sequenciais, como atualizações de CRM, criação de perfis ou moderação de conteúdo, em que minutos de atraso são aceitáveis.
  • Pesquisa limitada pelo orçamento: experimentos acadêmicos que exigem alto volume de tokens em um orçamento limitado.

Limites de taxas

O tráfego de inferência flex é contabilizado nos seus limites de taxa gerais. Ele não oferece limites de taxa estendidos, como a API Batch.

Capacidade descartável

O tráfego flex é tratado com menor prioridade. Se houver um pico no tráfego padrão, as solicitações flex poderão ser substituídas ou removidas para garantir a capacidade de usuários de alta prioridade. Se você estiver procurando inferência de alta prioridade, confira Inferência de prioridade

Códigos de erro

Quando a capacidade flex não estiver disponível ou o sistema estiver congestionado, a API vai retornar códigos de erro padrão:

  • 503 Serviço indisponível: o sistema está no limite da capacidade.
  • 429 Há muitas solicitações: limites de taxa ou esgotamento de recursos.

Responsabilidade do cliente

  • Nenhum fallback do lado do servidor: para evitar cobranças inesperadas, o sistema não vai fazer upgrade automático de uma solicitação flex para o nível padrão se a capacidade flex estiver cheia.
  • Novas tentativas: você precisa implementar sua própria lógica de nova tentativa do lado do cliente com espera exponencial.
  • Tempos limite: como as solicitações Flex podem ficar em uma fila, recomendamos aumentar os tempos limite do lado do cliente para 10 minutos ou mais para evitar o fechamento prematuro da conexão.

Ajustar janelas de tempo limite

É possível configurar tempos limite por solicitação para a API REST e bibliotecas de cliente. Sempre verifique se o tempo limite do lado do cliente abrange a janela de paciência do servidor pretendida (por exemplo, 600 segundos ou mais para filas de espera flex). Os SDKs esperam valores de tempo limite em milissegundos.

Tempos limite por solicitação

Python

from google import genai

client = genai.Client(http_options={"timeout": 900000})

try:
    interaction = client.interactions.create(
        model="gemini-3.5-flash",
        input="why is the sky blue?",
        service_tier="flex",
    )
except Exception as e:
    print(f"Flex request failed: {e}")

JavaScript

import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({});

async function main() {
    try {
        const interaction = await client.interactions.create({
            model: "gemini-3.5-flash",
            input: "why is the sky blue?",
            service_tier: "flex",
        }, {timeout: 900000});
    } catch (e) {
        console.log(`Flex request failed: ${e}`);
    }
}

await main();

Implementar novas tentativas

Como o Flex é descartável e falha com erros 503, confira um exemplo de implementação opcional da lógica de nova tentativa para continuar com solicitações com falha:

Python

import time
from google import genai

client = genai.Client()

def call_with_retry(max_retries=3, base_delay=5):
    for attempt in range(max_retries):
        try:
            return client.interactions.create(
                model="gemini-3.5-flash",
                input="Analyze this batch statement.",
                service_tier="flex",
            )
        except Exception as e:
            if attempt < max_retries - 1:
                delay = base_delay * (2 ** attempt) # Exponential Backoff
                print(f"Flex busy, retrying in {delay}s...")
                time.sleep(delay)
            else:
                print("Flex exhausted, falling back to Standard...")
                return client.interactions.create(
                    model="gemini-3.5-flash",
                    input="Analyze this batch statement."
                )

interaction = call_with_retry()
print(interaction.output_text)

JavaScript

import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI({});

async function sleep(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

async function callWithRetry(maxRetries = 3, baseDelay = 5) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      console.log(`Attempt ${attempt + 1}: Calling Flex tier...`);
      const interaction = await ai.interactions.create({
        model: "gemini-3.5-flash",
        input: "Analyze this batch statement.",
        service_tier: 'flex',
      });
      return interaction;
    } catch (e) {
      if (attempt < maxRetries - 1) {
        const delay = baseDelay * (2 ** attempt);
        console.log(`Flex busy, retrying in ${delay}s...`);
        await sleep(delay * 1000);
      } else {
        console.log("Flex exhausted, falling back to Standard...");
        return await ai.interactions.create({
          model: "gemini-3.5-flash",
          input: "Analyze this batch statement.",
        });
      }
    }
  }
}

async function main() {
    const interaction = await callWithRetry();
    console.log(interaction.output_text);
}

await main();

Preços

A inferência flex tem preço de 50% da API padrão e é faturada por token.

Modelos compatíveis

Os seguintes modelos oferecem suporte à inferência flex:

Modelo Inferência flex
Gemini 3.5 Flash ✔️
Gemini 3.1 Flash-Lite ✔️
Pré-lançamento do Gemini 3.1 Flash-Lite ✔️
Pré-lançamento do Gemini 3.1 Pro ✔️
Pré-lançamento do Gemini 3 Flash ✔️
Gemini 2.5 Pro ✔️
Gemini 2.5 Flash ✔️
Gemini 2.5 Flash-Lite ✔️

A seguir