Inferencia flexible

La API de Gemini Flex es un nivel de inferencia que ofrece una reducción de costos del 50% en comparación con las tarifas estándar, a cambio de una latencia variable y una disponibilidad de mejor esfuerzo. Está diseñada para cargas de trabajo tolerantes a la latencia que requieren procesamiento síncrono, pero no necesitan el rendimiento en tiempo real de la API estándar.

Cómo usar Flex

Para usar el nivel Flex, especifica service_tier como flex en tu solicitud. De forma predeterminada, las solicitudes usan el nivel estándar si se omite este campo.

Python

from google import genai

client = genai.Client()

try:
    interaction = client.interactions.create(
        model="gemini-3-flash-preview",
        input="Analyze this dataset for trends...",
        service_tier='flex'
    )
    print(interaction.steps[-1].content[0].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-flash-preview',
            input: 'Analyze this dataset for trends...',
            serviceTier: 'flex'
        });
        console.log(interaction.steps.at(-1).content[0].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" \
  -d '{
      "model": "gemini-3-flash-preview",
      "input": "Analyze this dataset for trends...",
      "service_tier": "flex"
  }'

Cómo funciona la inferencia flexible

La inferencia de Gemini Flex une la brecha entre la API estándar y el tiempo de respuesta de las 24 horas de la API de Batch. Utiliza capacidad de procesamiento fuera de las horas pico y "desechable" para proporcionar una solución rentable para tareas en segundo plano y flujos de trabajo secuenciales.

Función Flexible Prioridad Estándar Lote
Precios 50% de descuento Entre un 75% y un 100% más que el estándar Precio completo 50% de descuento
Latencia Minutos (objetivo de 1 a 15 min) Baja (segundos) De segundos a minutos Hasta 24 horas
Confiabilidad Mejor esfuerzo (desechable) Alta (no desechable) Alta / media alta Alta (para la capacidad de procesamiento)
Interfaz Síncrona Síncrona Síncrona Asíncrona

Ventajas clave

  • Rentabilidad: Ahorros significativos para evaluaciones que no son de producción, agentes en segundo plano y enriquecimiento de datos
  • Baja fricción: Simplemente agrega un solo parámetro a tus solicitudes existentes.
  • Flujos de trabajo síncronos: Ideal para cadenas de API secuenciales en las que la siguiente solicitud depende del resultado de la anterior, lo que la hace más flexible que Batch para los flujos de trabajo de agentes.

Casos de uso

  • Evaluaciones sin conexión: Ejecución de pruebas de regresión o clasificaciones de "LLM como juez".
  • Agentes en segundo plano: Tareas secuenciales como actualizaciones de CRM, creación de perfiles o moderación de contenido en las que se aceptan minutos de demora.
  • Investigación con presupuesto limitado: Experimentos académicos que requieren un gran volumen de tokens con un presupuesto limitado.

Límites de frecuencia

El tráfico de inferencia flexible se incluye en los límites de frecuencia generales; no ofrece límites de frecuencia extendidos como la API de Batch.

Capacidad desechable

El tráfico flexible se trata con menor prioridad. Si hay un aumento repentino en el tráfico estándar, es posible que se interrumpan o se expulsen las solicitudes Flex para garantizar la capacidad de los usuarios de alta prioridad. Si buscas inferencia de alta prioridad, consulta Inferencia de prioridad

Códigos de error

Cuando la capacidad flexible no esté disponible o el sistema esté congestionado, la API mostrará códigos de error estándar:

  • 503 Service Unavailable: El sistema está actualmente al máximo de su capacidad.
  • 429 Too Many Requests: Límites de frecuencia o agotamiento de recursos.

Responsabilidad del cliente

  • Sin fallback del servidor: Para evitar cargos inesperados, el sistema no actualizará automáticamente una solicitud flexible al nivel estándar si la capacidad flexible está llena.
  • Reintentos: Debes implementar tu propia lógica de reintento del cliente con retirada exponencial.
  • Tiempos de espera: Debido a que las solicitudes flexibles pueden permanecer en una cola, te recomendamos que aumentes los tiempos de espera del cliente a 10 minutos o más para evitar el cierre prematuro de la conexión.

Ajusta los períodos de tiempo de espera

Puedes configurar tiempos de espera por solicitud para la API de REST y las bibliotecas cliente. Asegúrate siempre de que el tiempo de espera del cliente cubra el período de paciencia del servidor deseado (p.ej., 600 s o más para las colas de espera flexibles). Los SDK esperan valores de tiempo de espera en milisegundos.

Tiempos de espera por solicitud

Python

from google import genai

client = genai.Client()

try:
    interaction = client.interactions.create(
        model="gemini-3-flash-preview",
        input="why is the sky blue?",
        service_tier="flex",
        http_options={"timeout": 900000}
    )
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-flash-preview",
            input: "why is the sky blue?",
            serviceTier: "flex",
            httpOptions: {timeout: 900000}
        });
    } catch (e) {
        console.log(`Flex request failed: ${e}`);
    }
}

await main();

Implementa reintentos

Debido a que Flex es desechable y falla con errores 503, aquí tienes un ejemplo de cómo implementar de forma opcional la lógica de reintento para continuar con las solicitudes fallidas:

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-flash-preview",
                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:
                # Fallback to standard on last strike (Optional)
                print("Flex exhausted, falling back to Standard...")
                return client.interactions.create(
                    model="gemini-3-flash-preview",
                    input="Analyze this batch statement."
                )

# Usage
interaction = call_with_retry()
print(interaction.steps[-1].content[0].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-flash-preview",
        input: "Analyze this batch statement.",
        serviceTier: '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-flash-preview",
          input: "Analyze this batch statement.",
        });
      }
    }
  }
}

async function main() {
    const interaction = await callWithRetry();
    console.log(interaction.steps.at(-1).content[0].text);
}

await main();

Precios

La inferencia flexible tiene un precio del 50% de la API estándar y se factura por token.

Modelos compatibles

Los siguientes modelos admiten la inferencia flexible:

Modelo Inferencia flexible
Gemini 3.1 Flash-Lite ✔️
Versión preliminar de Gemini 3.1 Flash-Lite ✔️
Versión preliminar de Gemini 3.1 Pro ✔️
Versión preliminar de Gemini 3 Flash ✔️
Gemini 2.5 Pro ✔️
Gemini 2.5 Flash ✔️
Gemini 2.5 Flash-Lite ✔️

¿Qué sigue?