DEV Community

Cover image for Cómo Usar la API Gemini 3.5 Flash
Roobia
Roobia

Posted on • Originally published at apidog.com

Cómo Usar la API Gemini 3.5 Flash

La API de Gemini 3.5 Flash se lanzó junto con el modelo el 19 de mayo de 2026. Flash es la única variante 3.5 disponible hoy; Pro llega en junio. Esta guía le lleva de cero a una integración funcional: obtener una clave, ejecutar la primera llamada, enviar entradas multimodales, usar streaming, declarar herramientas y probar el flujo completo con Apidog.

Prueba Apidog hoy

Si ya usa la API de Gemini, el cambio principal es el nombre del modelo: gemini-3.5-flash. Si empieza desde cero, puede tener una solicitud funcional en unos minutos.

Gemini 3.5 Flash API

Qué obtiene con la API de Gemini 3.5 Flash

Para empezar, tenga claras estas tres piezas:

  • Modelo: gemini-3.5-flash
  • Endpoint: mismo patrón que en Gemini 3 y Gemini 3.1
  • Acceso inicial: capa gratuita en Google AI Studio, con aproximadamente 1,500 solicitudes al día sin tarjeta de crédito

Capacidades disponibles vía API:

  • Contexto de entrada de 1 millón de tokens y salida de hasta 64 mil tokens
  • Entrada de texto e imagen
  • Salida de texto y salida estructurada
  • Llamadas a funciones y uso de herramientas
  • Respuestas en streaming
  • Razonamiento sobre documentos, gráficos e imágenes

Para detalles de costos, consulte la guía de precios de Gemini 3.5 Flash.

Paso 1: Obtener una clave de API

Tiene dos rutas: AI Studio para pruebas rápidas o Vertex AI para producción.

Ruta A: Google AI Studio

Use esta opción si quiere probar Flash con cuota gratuita.

  1. Abra aistudio.google.com
  2. Inicie sesión con su cuenta de Google
  3. En el menú izquierdo, haga clic en Obtener clave de API
  4. Seleccione un proyecto existente o cree uno nuevo
  5. Haga clic en Crear clave de API
  6. Copie la clave y guárdela como variable de entorno 
export GEMINI_API_KEY="su_clave"
Enter fullscreen mode Exit fullscreen mode

Este flujo es el mismo que se explica en la guía gratuita de claves de API de Gemini. La clave funciona con gemini-3.5-flash inmediatamente.

Google AI Studio API key

Ruta B: Vertex AI

Use Vertex AI si necesita facturación, permisos de organización y registros de auditoría.

  1. Abra Google Cloud Console
  2. Habilite la API de Vertex AI
  3. Cree una cuenta de servicio con el rol aiplatform.user
  4. Descargue el archivo JSON de credenciales
  5. Autentíquese con: 
gcloud auth application-default login
Enter fullscreen mode Exit fullscreen mode

O configure la variable de entorno:

export GOOGLE_APPLICATION_CREDENTIALS="/ruta/credenciales.json"
Enter fullscreen mode Exit fullscreen mode

La mayoría de equipos empiezan con AI Studio y migran a Vertex AI cuando necesitan controles de producción.

Paso 2: Instalar el SDK

El SDK oficial de Google GenAI está disponible para Python, Node.js, Go y Java.

# Python
pip install -U google-genai

# Node.js
npm install @google/genai

# Go
go get google.golang.org/genai
Enter fullscreen mode Exit fullscreen mode

También puede usar REST directamente con curl, sin SDK.

Paso 3: Ejecutar la primera llamada

Python 

import os
from google import genai

client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Explain how OAuth 2.0 PKCE flow works in 3 short paragraphs."
)

print(response.text)
Enter fullscreen mode Exit fullscreen mode

Node.js 

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

const ai = new GoogleGenAI({
  apiKey: process.env.GEMINI_API_KEY,
});

const response = await ai.models.generateContent({
  model: "gemini-3.5-flash",
  contents: "Explain how OAuth 2.0 PKCE flow works in 3 short paragraphs.",
});

console.log(response.text);
Enter fullscreen mode Exit fullscreen mode

REST con curl 

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "Explain how OAuth 2.0 PKCE flow works in 3 short paragraphs."
          }
        ]
      }
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

Si recibe una respuesta de texto, la integración básica ya funciona. Desde aquí puede agregar streaming, imágenes, herramientas o salida JSON.

Streaming de respuestas

Use streaming cuando quiera mostrar tokens en tiempo real en una interfaz de usuario, CLI o agente.

Python 

stream = client.models.generate_content_stream(
    model="gemini-3.5-flash",
    contents="Write a 5-step tutorial on writing a REST API client in Go."
)

for chunk in stream:
    print(chunk.text, end="", flush=True)
Enter fullscreen mode Exit fullscreen mode

Node.js 

const stream = await ai.models.generateContentStream({
  model: "gemini-3.5-flash",
  contents: "Write a 5-step tutorial on writing a REST API client in Go.",
});

for await (const chunk of stream) {
  process.stdout.write(chunk.text);
}
Enter fullscreen mode Exit fullscreen mode

En REST, cambie el sufijo del endpoint:

:generateContent
Enter fullscreen mode Exit fullscreen mode

por:

:streamGenerateContent
Enter fullscreen mode Exit fullscreen mode

Entrada multimodal con Gemini 3.5 Flash

Gemini 3.5 Flash acepta imágenes junto con texto. Esto permite casos como extracción de métricas desde dashboards, análisis de gráficos o lectura de capturas de pantalla.

Python: imagen desde disco 

import os
from google import genai
from google.genai import types

client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

with open("dashboard.png", "rb") as f:
    image_bytes = f.read()

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents=[
        types.Part.from_bytes(
            data=image_bytes,
            mime_type="image/png"
        ),
        "Extract every metric in this dashboard as a JSON object."
    ]
)

print(response.text)
Enter fullscreen mode Exit fullscreen mode

Tipos MIME de imagen compatibles:

  • image/png
  • image/jpeg
  • image/webp
  • image/heic
  • image/heif

PDFs y videos también pueden enviarse mediante types.Part.from_uri().

Llamada a funciones y uso de herramientas

La llamada a herramientas permite que el modelo devuelva una función a ejecutar, en lugar de intentar responder directamente. Es útil para agentes, integraciones con CRMs, búsquedas internas o sistemas de reserva.

Declarar una herramienta en Python 

from google.genai import types

weather_tool = types.Tool(
    function_declarations=[
        {
            "name": "get_current_weather",
            "description": "Get the current weather for a city.",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "City name"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"]
                    }
                },
                "required": ["city"]
            }
        }
    ]
)
Enter fullscreen mode Exit fullscreen mode

Enviar la solicitud con herramientas 

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="What's the weather in Singapore right now?",
    config=types.GenerateContentConfig(
        tools=[weather_tool]
    )
)

for part in response.candidates[0].content.parts:
    if part.function_call:
        print(f"Call: {part.function_call.name}")
        print(f"Args: {dict(part.function_call.args)}")
Enter fullscreen mode Exit fullscreen mode

Gemini devuelve un objeto function_call con:

  • Nombre de la función
  • Argumentos
  • Estructura declarada en el esquema

Después, su aplicación debe:

  1. Ejecutar la función local o remota
  2. Capturar el resultado
  3. Enviar el resultado de vuelta al modelo
  4. Continuar la conversación

El patrón es similar al usado con la API de Gemini 3 Flash.

Salida estructurada en JSON

Para evitar parsing manual o expresiones regulares, configure response_mime_type y response_schema.

from google.genai import types
import json

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="List 3 popular API testing tools with their pricing.",
    config=types.GenerateContentConfig(
        response_mime_type="application/json",
        response_schema={
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "price_per_month": {"type": "number"},
                    "free_tier": {"type": "boolean"}
                },
                "required": ["name", "free_tier"]
            }
        }
    )
)

data = json.loads(response.text)
print(data)
Enter fullscreen mode Exit fullscreen mode

Este patrón es útil para:

  • Pipelines ETL
  • Extracción de datos desde documentos
  • APIs internas
  • Validación automática en pruebas
  • Agentes que necesitan estructuras predecibles

Precios a mayo de 2026

Tarifas de pago por uso para gemini-3.5-flash:

Nivel Entrada Salida
Estándar ~$1.50 / 1 millón de tokens ~$9.00 / 1 millón de tokens
Entrada en caché tarifa reducida n/a
Modo por lotes ~50% de descuento ~50% de descuento

Para cargas de trabajo no interactivas, el modo por lotes de la API de Gemini puede reducir costos cuando no necesita latencia en tiempo real.

Para escenarios más completos, revise el desglose de precios de Flash. Para la referencia oficial, consulte la página de precios de la API para desarrolladores de Gemini.

Probar la integración de Gemini 3.5 Flash con Apidog

Una llamada SDK exitosa no basta para producción. También debe validar:

  • Fragmentos de streaming
  • Esquemas JSON
  • Llamadas a herramientas
  • Cargas multimodales
  • Reintentos
  • Límites de velocidad
  • Errores de autenticación

Apidog Gemini testing

Con Apidog, puede probar la superficie de la API de Gemini Flash en un solo espacio de trabajo:

  • Guardar el endpoint de Flash como solicitud: pegue la URL, agregue x-goog-api-key y ejecute.
  • Comparar modelos: cambie gemini-3.5-flash por gemini-3-flash y compare salidas.
  • Probar streaming: use :streamGenerateContent y revise los fragmentos conforme llegan.
  • Validar JSON: agregue aserciones para detectar cambios en la forma de la respuesta.
  • Simular el endpoint: genere respuestas mock para probar código downstream sin consumir cuota.
  • Probar bucles de agente: encadene llamadas y valide function_call entre pasos.

Para empezar, descargue Apidog, cree una nueva solicitud al endpoint de Flash e importe el ejemplo curl de esta guía.

Manejo de errores y límites de velocidad

Códigos comunes:

Código Causa probable Acción recomendada
400 Solicitud mal formada, contents incorrecto o MIME no compatible Validar payload
401 Clave de API incorrecta Revisar GEMINI_API_KEY
403 Cuota agotada o modelo no habilitado Revisar cuota/proyecto
429 Límite de velocidad Reintentar con espera
500/503 Error del servidor Reintentar con backoff exponencial

Ejemplo simple de reintentos en Python:

import time
from google import genai

def call_with_retry(client, model, prompt, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.models.generate_content(
                model=model,
                contents=prompt
            )
        except Exception:
            if attempt == max_retries - 1:
                raise

            wait_seconds = 2 ** attempt
            time.sleep(wait_seconds)
Enter fullscreen mode Exit fullscreen mode

Las cuotas de la capa gratuita se restablecen diariamente. Para Flash, el límite indicado es de aproximadamente 15 solicitudes por minuto y 1,500 por día. En producción, las cuotas se controlan por minuto y por día.

Si necesita alto rendimiento, evalúe el modo por lotes o una alternativa escalonada como Gemini 3 Flash cuando alcance límites.

Migrar de Gemini 3.1 a 3.5 Flash

En muchos proyectos, la migración empieza cambiando solo el nombre del modelo.

# Antes
model = "gemini-3.1-pro"  # o gemini-3.1-flash

# Después
model = "gemini-3.5-flash"
Enter fullscreen mode Exit fullscreen mode

Después del cambio, valide:

  1. Esquemas de herramientas: asegúrese de que los argumentos generados sigan coincidiendo.
  2. Streaming: si la salida llega más rápido, revise throttling o renderizado en UI.
  3. Presupuesto de tokens: confirme costos y longitud de respuestas reales.
  4. Rechazos: ejecute sus casos límite, porque las respuestas de seguridad pueden cambiar.

Para más contexto sobre el patrón de SDK, revise la guía de la API de Gemini 3.1 Pro.

Patrones comunes con Gemini 3.5 Flash

1. Análisis de documentos largos 

from google.genai import types

with open("large_report.pdf", "rb") as f:
    pdf_bytes = f.read()

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents=[
        types.Part.from_bytes(
            data=pdf_bytes,
            mime_type="application/pdf"
        ),
        "Summarize the financial outlook from this report in 5 bullet points."
    ]
)

print(response.text)
Enter fullscreen mode Exit fullscreen mode

El contexto de 1 millón de tokens permite procesar PDFs completos sin fragmentarlos manualmente en muchos casos.

2. Extracción de gráficos a JSON 

with open("chart.png", "rb") as f:
    chart = f.read()

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents=[
        types.Part.from_bytes(
            data=chart,
            mime_type="image/png"
        ),
        """
        Extract the chart data as JSON.
        Include title, x_axis, y_axis and data_points.
        """
    ],
    config=types.GenerateContentConfig(
        response_mime_type="application/json"
    )
)
Enter fullscreen mode Exit fullscreen mode

3. Bucle de agente con herramientas 

conversation = [
    {
        "role": "user",
        "parts": [
            {"text": "Book me a flight to Tokyo"}
        ]
    }
]

while True:
    response = client.models.generate_content(
        model="gemini-3.5-flash",
        contents=conversation,
        config=types.GenerateContentConfig(
            tools=[flight_search_tool, booking_tool]
        )
    )

    part = response.candidates[0].content.parts[0]

    if not part.function_call:
        print(part.text)
        break

    result = execute_tool(part.function_call)

    conversation.append({
        "role": "model",
        "parts": [part]
    })

    conversation.append({
        "role": "user",
        "parts": [
            {
                "function_response": result
            }
        ]
    })
Enter fullscreen mode Exit fullscreen mode

Este patrón sirve para agentes que necesitan consultar APIs externas, ejecutar acciones y continuar razonando con los resultados.

Preguntas frecuentes

¿Existe una capa gratuita para la API de Gemini 3.5 Flash?

Sí. Está disponible mediante Google AI Studio, con cuotas diarias aproximadas de 1,500 solicitudes. No se requiere tarjeta de crédito.

¿Flash es compatible con endpoints compatibles con OpenAI?

Sí. Google expone una interfaz compatible con OpenAI en /v1beta/openai/. Puede apuntar un SDK de OpenAI configurando base_url y usando su clave de Gemini. El modelo sigue siendo gemini-3.5-flash.

¿Puedo usar Flash con LangChain o LlamaIndex?

Sí. Ambos tienen integraciones nativas con Gemini. Configure model="gemini-3.5-flash" en el wrapper correspondiente.

¿Cuándo se lanza Gemini 3.5 Pro?

Junio de 2026, según el anuncio de lanzamiento de Google. Hasta entonces, Flash es la única variante 3.5 disponible.

¿Cuál es el tamaño máximo recomendado de imagen?

Se recomienda 3072×3072. Imágenes más grandes se remuestrean. Para trabajos intensivos de OCR, revise el flujo de trabajo OCR de Gemini 2.0 Flash; los mismos patrones aplican.

¿Cómo pruebo endpoints de streaming en Apidog?

Abra la solicitud, use el sufijo :streamGenerateContent y ejecute. Apidog renderiza los fragmentos SSE conforme llegan, lo que ayuda a depurar respuestas incompletas.

¿Dónde veo los registros de la API?

En AI Studio, revise Actividad. En Vertex AI, use Explorador de registros para implementaciones de producción.

Qué construir primero

Ideas prácticas para la primera semana:

  • Bot de preguntas y respuestas sobre PDFs: cargue un documento largo y responda con citas.
  • Pipeline de dashboard a JSON: procese capturas de pantalla y extraiga métricas estructuradas.
  • Agente de soporte: conecte llamadas a funciones contra su CRM.
  • Asistente de revisión de código: analice diffs y devuelva severidad, archivo y recomendación.
  • Agente de búsqueda interna: combine contexto largo con llamadas a APIs internas.

Para cada caso, siga el mismo flujo:

  1. Defina el prompt.
  2. Ejecute la llamada SDK o REST.
  3. Valide la forma de la respuesta.
  4. Pruebe errores y límites.
  5. Automatice la verificación con Apidog.

Top comments (0)