¿Cómo usar la API de Gemini 3.7 Flash?

Google lanzó Gemini 3.7 Flash el 13 de agosto de 2026, tres semanas después de 3.6 Flash, y lo llama “nuestro modelo de caballo de batalla más inteligente”. Los titulares para los desarrolladores: las puntuaciones de codificación agéntica aumentaron drásticamente (DeepSWE v1.1 pasó de 49.0% a 65.3%), el precio de introducción es la mitad del precio de lanzamiento de 3.6 Flash, y la superficie de la API no ha cambiado. Si ya llamas a Gemini, solo cambias un ID de modelo. Si no lo haces, este es el punto de entrada más económico que Google ha ofrecido para un modelo tan capaz.

Esta guía es el inicio rápido práctico. Obtendrá una clave de API, hará su primera llamada en cURL, la portará a Python y Node.js, transmitirá respuestas, ajustará generationConfig y conectará todo a Apidog para que pueda iterar en las indicaciones sin quemar tokens en un bucle de código. Las especificaciones del anuncio oficial: contexto de 1 millón de tokens, salida de 64k, entrada multimodal, llamada a funciones, búsqueda como herramienta y uso de computadora.

Si construyó con la generación anterior, la forma de la solicitud se mantiene desde nuestra guía de la API de vista previa de Gemini 3 Flash; este artículo cubre todo lo nuevo en el flujo de trabajo de 3.7.

En Resumen

• El ID del modelo es gemini-3.7-flash. Punto final: POST https://generativelanguage.googleapis.com/v1beta/models/gemini-3.7-flash:generateContent con encabezado x-goog-api-key: <KEY>.
• Los precios de introducción son de $0.75 por 1 millón de tokens de entrada y $3.75 por 1 millón de tokens de salida hasta el 31 de diciembre de 2026. A partir del 1 de enero de 2027 se duplican a $1.50 y $7.50.
• Especificaciones: contexto de entrada de 1 millón de tokens, límite de salida de 64k tokens. La entrada acepta texto, imagen, video, audio y PDF. La salida es texto.
• Diferencias de rendimiento respecto a 3.6 Flash: DeepSWE 49.0% a 65.3%, FrontierCode 34.4% a 43.6%, AutomationBench 17.0% a 30.4%, WebDev Arena Elo 1538 a 1588.
• La transmisión usa :streamGenerateContent?alt=sse. El cuerpo de la solicitud mantiene el esquema contents más generationConfig de Google.
• Pruebe el punto final en Apidog antes de escribir código de aplicación: importe la especificación, almacene la clave como una variable de entorno y observe cómo los fragmentos SSE se renderizan en vivo.

Para qué sirve Gemini 3.7 Flash

Los modelos Flash sacrifican un poco de inteligencia máxima por velocidad y precio, y 3.7 reduce ese compromiso más que cualquier lanzamiento anterior. Las diferencias de rendimiento con respecto a 3.6 Flash son inusualmente grandes para una brecha de tres semanas: DeepSWE v1.1 saltó de 49.0% a 65.3%, FrontierCode 1.1 Main de 34.4% a 43.6%, y AutomationBench de 17.0% a 30.4%. WebDev Arena Elo subió 50 puntos, de 1538 a 1588.

Interprete esos números como una señal sobre la idoneidad de la carga de trabajo. Recurra a 3.7 Flash cuando:

• Ejecuta bucles de agentes. La puntuación de AutomationBench casi se duplicó, y Google dice que el modelo "piensa con más diligencia en la planificación de varios pasos y las llamadas a herramientas". Las tuberías de agentes con muchas vueltas cortas y con muchas herramientas son el caso de uso objetivo.
• Genera o depura código. Google afirma que 3.7 es mejor para depurar y más capaz de producir código desplegable al primer intento. Las ganancias de DeepSWE y FrontierCode lo respaldan.
• Procesa documentos. El PIB.pdf saltó del 22.0% al 34.0%, y el PDF es un tipo de entrada de primera clase. La recuperación de contexto largo también se mantiene: 97.0% en la prueba de aguja de 128k.
• Necesita entrada multimodal con un presupuesto ajustado. Texto, imagen, video, audio y PDF entran a través del mismo array contents.

Para conocer todos los detalles de las características, incluyendo la puntuación LAB-AA de Harvey en el ámbito legal del 90.7% y las salvaguardas actualizadas de CBRN y cibernéticas, consulte novedades de Gemini 3.7 Flash. Contexto que vale la pena conocer: Gemini 3.5 Pro sigue retrasado, y Axios informa que Google está enviando deliberadamente actualizaciones de Flash antes de su próximo modelo insignia.

Obtener una clave de API

Dos caminos, y no son equivalentes.

AI Studio (ruta rápida). Abra aistudio.google.com/apikey, haga clic en Obtener clave de API, elija un proyecto de Google Cloud y copie la cadena. La clave funciona inmediatamente con generativelanguage.googleapis.com, y el nivel gratuito le da suficiente cuota para prototipar. Gemini 3.7 Flash está disponible en más de 160 países.

Vertex AI (ruta de producción). Si su infraestructura se encuentra en GCP, use Vertex. La autenticación cambia de una clave de API a OAuth (cuentas de servicio o tokens de corta duración), las llamadas se dirigen a través de aiplatform.googleapis.com, y usted obtiene IAM, registros de auditoría y puntos de conexión regionales. El ID del modelo y el cuerpo de la solicitud permanecen idénticos; solo cambian la URL y el mecanismo de autenticación.

Prototipo en AI Studio, muévase a Vertex antes del tráfico de producción. De cualquier manera, exporte la clave una vez:

export GEMINI_API_KEY="AIza..."

Nunca codifique la clave ni la pase como un parámetro de consulta ?key= en producción; las cadenas de consulta terminan en los registros del servidor.

Punto final y autenticación

El punto final base para una llamada síncrona:

POST https://generativelanguage.googleapis.com/v1beta/models/gemini-3.7-flash:generateContent

La transmisión intercambia el sufijo del método y añade la bandera SSE:

POST https://generativelanguage.googleapis.com/v1beta/models/gemini-3.7-flash:streamGenerateContent?alt=sse

La autenticación es un encabezado: x-goog-api-key: $GEMINI_API_KEY. Ese es todo el proceso de conexión. Sin tokens de portador, sin esquema de firma, sin configuración de sesión.

Su primera solicitud en cURL

Aquí hay una llamada completa y funcional:

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.7-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{ "text": "Revisa este SQL en busca de riesgo de inyección: SELECT * FROM orders WHERE id = ${orderId}" }]
    }],
    "generationConfig": {
      "temperature": 0.3,
      "maxOutputTokens": 1024
    }
  }'

La respuesta devuelve un array candidates. Cada candidato lleva un objeto content con parts (texto, o llamadas a funciones si declaró herramientas) y un finishReason. Los recuentos de tokens residen en usageMetadata en el nivel superior; observe ese bloque, porque los tokens de salida cuestan cinco veces más que los tokens de entrada a la tarifa introductoria.

Observe el esquema: Google utiliza contents con role y parts, no la forma messages de OpenAI. Si está migrando desde otro proveedor, asegúrese de que esta asignación sea correcta primero.

Inicio rápido de Python

Instale o actualice el SDK oficial:

pip install --upgrade google-generativeai

Una llamada básica con una instrucción del sistema:

import os
import google.generativeai as genai

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

model = genai.GenerativeModel(
    model_name="gemini-3.7-flash",
    system_instruction="Eres un revisor de código. Marca los problemas como bloqueantes o no bloqueantes.",
    generation_config={
        "temperature": 0.3,
        "max_output_tokens": 2048,
    },
)

response = model.generate_content(
    "Revisa esta ruta de Flask en busca de problemas de seguridad:\n\n"
    "@app.route('/user/<id>')\n"
    "def get_user(id):\n"
    "    return db.execute(f'SELECT * FROM users WHERE id = {id}')"
)

print(response.text)
print("tokens de entrada:", response.usage_metadata.prompt_token_count)
print("tokens de salida:", response.usage_metadata.candidates_token_count)

La entrada multimodal viaja en el mismo array contents. Para enviar un PDF, súbalo a través de la API de Archivos y haga referencia a él como una parte:

invoice = genai.upload_file("q3-invoice.pdf")

response = model.generate_content([
    invoice,
    "Extrae el número de factura, el total y la fecha de vencimiento como JSON.",
])
print(response.text)

La mejora del rendimiento de GDP.pdf (del 22.0% al 34.0%) se observa precisamente en esta carga de trabajo: extracción estructurada de documentos complejos del mundo real.

Inicio rápido de Node.js

El SDK de Node es @google/generative-ai y refleja la forma de Python:

import { GoogleGenerativeAI } from "@google/generative-ai";

const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY);

const model = genAI.getGenerativeModel({
  model: "gemini-3.7-flash",
  generationConfig: {
    temperature: 0.3,
    maxOutputTokens: 2048,
    responseMimeType: "application/json",
    responseSchema: {
      type: "object",
      properties: {
        severity: { type: "string", enum: ["blocking", "non-blocking"] },
        issues: { type: "array", items: { type: "string" } },
      },
      required: ["severity", "issues"],
    },
  },
});

const result = await model.generateContent(
  "Revisa este manejador de Express: app.get('/search', (req, res) => res.send(eval(req.query.q)))"
);

console.log(JSON.parse(result.response.text()));

La línea responseSchema es más importante de lo que parece. Fuerza al candidato a un objeto analizable, para que el código posterior nunca toque texto de forma libre. Combínelo con responseMimeType: "application/json" o será ignorado.

Streaming (Transmisión)

Para interfaces de chat y cualquier cosa orientada al usuario, utilice streaming. En Python, añada stream=True:

stream = model.generate_content(
    "Explica el problema de consulta N+1 con un ejemplo ORM concreto.",
    stream=True,
)

for chunk in stream:
    if chunk.text:
        print(chunk.text, end="", flush=True) # flush=True es necesario para imprimir cada fragmento inmediatamente

Sobre HTTP puro, acceda a :streamGenerateContent?alt=sse y analice los eventos enviados por el servidor. Cada línea data: contiene una carga útil parcial de candidates; el fragmento final incluye usageMetadata, por lo que la contabilidad de tokens solo es precisa después de que la transmisión se cierra.

Ajuste de generationConfig

Los parámetros que más tocará, en orden aproximado de impacto:

Los tokens de salida cuestan $3.75 por millón a la tasa introductoria y $7.50 a partir de enero de 2027, así que limite la salida a lo que su caso de uso necesita, no al límite de 64k. Las matemáticas completas de los tokens, con ejemplos trabajados por carga de trabajo, se encuentran en nuestro desglose de precios de Gemini 3.7 Flash.

Más allá de generationConfig, el cuerpo de la solicitud también acepta tools (declaraciones de funciones, búsqueda como herramienta, uso de computadora) y toolConfig para forzar llamadas a herramientas. El uso de herramientas es donde 3.7 Flash mejoró más, y merece su propia explicación: consulte el tutorial de llamada a funciones de Gemini 3.7 Flash para declaraciones, llamadas paralelas y el patrón de bucle de respuesta.

Pruebe el punto final en Apidog antes de escribir el código de la aplicación

La iteración de prompts dentro de un script de Python es lenta y costosa: editar, volver a ejecutar, desplazar, repetir, y cada ciclo factura tokens. El bucle más rápido es bloquear la forma de la solicitud en un cliente API primero, luego portar al código una vez que las respuestas se vean correctas.

Apidog maneja el esquema de solicitud de Gemini de forma nativa. La configuración:

1. Cree un proyecto e importe la especificación OpenAPI de la API de Lenguaje Generativo desde la documentación de la API de Google. La colección llega con un nombre predefinido, por lo que generateContent está a una búsqueda de distancia.
2. Añada una variable de entorno llamada GEMINI_API_KEY y vincúlela al encabezado x-goog-api-key a nivel de entorno. Cada solicitud la hereda, y la clave nunca aparece en el cuerpo de una solicitud guardada.
3. Guarde el ID del modelo como una variable establecida en gemini-3.7-flash. Cuando quiera hacer una prueba A/B contra gemini-3.6-flash, cambiará una variable en lugar de editar las URL en una docena de solicitudes guardadas.
4. Construya el array contents en el editor visual de JSON. Las partes anidadas se renderizan limpiamente, y la validación del esquema detecta un cuerpo mal formado antes de que gaste un solo token en un error 400.
5. Acceda al punto final de transmisión. Apidog renderiza los fragmentos SSE en vivo, para que pueda ver cómo se ensambla la respuesta exactamente como la verá su SDK, incluida la latencia.
6. Guarde las buenas respuestas como ejemplos. Las pruebas posteriores utilizan el accesorio en lugar de la API en vivo. Esto es el mayor ahorro de tokens en todo el flujo de trabajo.

Una vez que las solicitudes están guardadas, encadénelas en escenarios de prueba con aserciones sobre finishReason, el esquema de respuesta y los recuentos de tokens de usageMetadata. Eso convierte una prueba de humo manual en una suite de regresión que puede ejecutar con cada cambio de prompt; el mismo patrón que usan los equipos de QA se cubre en nuestra guía de pruebas de API para ingenieros de QA.

Manejo de errores y límites de velocidad

Los errores de Gemini devuelven un objeto error de nivel superior con code, status y message. Los que encontrará:

Tres hábitos mantienen la producción estable:

• Envuelva cada llamada en una función de reintento que maneje los errores 429 y 5xx con retroceso exponencial con fluctuación. Los SDKs reintentan algunas veces por sí solos, pero un wrapper delgado le proporciona registro y disyuntores que usted controla.
• No invente números de límite de velocidad. Los límites varían según el nivel y cambian con el tiempo; lea los valores en vivo en la página de precios y límites de la API de Gemini y configure una alerta al 80% de la cuota.
• Fije el ID del modelo detrás de una variable de entorno. Si un cambio de comportamiento de 3.7 rompe un prompt, volver a gemini-3.6-flash se convierte en un cambio de configuración en lugar de un despliegue.

Preguntas frecuentes

¿Es Gemini 3.7 Flash de uso gratuito?

AI Studio ofrece un nivel gratuito con una cuota diaria suficiente para la creación de prototipos, y la tarifa de introducción pagada es de $0.75 por 1 millón de tokens de entrada hasta el 31 de diciembre de 2026. Si desea extender el camino sin costo aún más, nuestra guía para el acceso gratuito a la API de Gemini cubre los niveles y sus límites.

¿Cuál es la diferencia entre llamarlo a través de AI Studio y Vertex AI?

Mismo modelo, mismo cuerpo de solicitud, diferente infraestructura. AI Studio usa una clave de API contra generativelanguage.googleapis.com; Vertex usa OAuth contra aiplatform.googleapis.com y agrega IAM, registro de auditoría y puntos finales regionales. Comience en AI Studio, pase a Vertex cuando el tráfico se vuelva real.

¿Puedo enviar imágenes, audio y PDFs a Gemini 3.7 Flash?

Sí. La entrada es multimodal: texto, imagen, video, audio y PDF, todos viajan como partes en el array contents, en línea como base64 o por referencia a través de la API de Archivos. La salida es solo texto.

¿Qué tan grandes son la ventana de contexto y el límite de salida?

1 millón de tokens de entrada, 64k tokens de salida. La puntuación de recuperación de aguja de 128k del 97.0% sugiere que la recuperación de contexto largo es fiable mucho más allá de lo que la mayoría de las aplicaciones necesitan, pero dividir las entradas largas sigue ahorrando dinero ya que cada token de entrada se factura.

¿Debo actualizar de Gemini 3.6 Flash?

Para cargas de trabajo de agentes y codificación, las brechas de rendimiento son lo suficientemente grandes como para que la respuesta sea generalmente sí, y el intercambio de ID de modelo es una sola línea. Las diferencias de comportamiento que vale la pena probar regresivamente antes de cambiar el tráfico de producción se cubren en la guía de migración de 3.6 a 3.7 Flash.

Dónde encaja 3.7 Flash en su pila

Gemini 3.7 Flash es el raro lanzamiento donde el precio bajó mientras la capacidad aumentó. Hasta finales de 2026, pagará la mitad de la tarifa de lanzamiento de 3.6 Flash por un modelo que obtiene 16 puntos más en DeepSWE y casi el doble en AutomationBench. El valor predeterminado sensato: dirija los bucles de agentes, las tareas de código y la extracción de documentos a 3.7 Flash ahora, tenga en cuenta la ventana de la tarifa de introducción para la planificación del presupuesto y mantenga una ruta de reversión a 3.6 detrás de una variable de entorno.

Comience con la llamada cURL anterior, confirme la forma de la respuesta, luego mueva la solicitud a un cliente API antes de escribir el código de la aplicación. Descargue Apidog para importar la especificación de Gemini, vincule su clave una vez y pruebe solicitudes síncronas, de transmisión y de llamada a herramientas desde un solo espacio de trabajo. Cuando el prompt es correcto, la portación a Python o Node lleva minutos porque ya sabe cómo se ve el tráfico de la red.