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

Llamas a Gemini 3.6 Flash con el ID de modelo gemini-3.6-flash a través de la API Gemini de Google. Esa es la base. Google lanzó la actualización de Flash el 21 de julio de 2026, y 3.6 Flash es el nivel principal: salida más barata que 3.5 Flash, una ventana de contexto de 1 millón de tokens, y entradas de texto, imagen, video, audio y PDF. Esta guía te lleva de cero a una solicitud probada. Obtendrás una clave, harás tu primera llamada en curl y Python, aprenderás los parámetros importantes y configurarás una prueba de regresión para que la llamada siga funcionando después de implementarla.

Lo que necesitas antes de empezar

Tres cosas, y ninguna de ellas cuesta dinero para empezar.

• Una cuenta de Google. Así es como inicias sesión para obtener una clave.
• Una clave de API de Gemini. Es gratuita desde Google AI Studio, y la siguiente sección lo cubre.
• Una forma de enviar una solicitud HTTP. curl funciona desde cualquier terminal. Python funciona si prefieres escribir código. También puedes usar un cliente de API como Apidog si deseas una interfaz de usuario para todo el proceso. Mostraremos los tres.

No se requiere configuración de facturación por adelantado. El nivel gratuito funciona a través de AI Studio y tiene un límite de velocidad, por lo que puedes probar sin una tarjeta registrada. Más información sobre esos límites a continuación.

Obtener una clave de API de Gemini

Ve a Google AI Studio e inicia sesión con tu cuenta de Google. Haz clic en “Obtener clave de API”, luego en “Crear clave de API”. Copia la cadena que te da y guárdala en un lugar seguro. Trátala como una contraseña: cualquiera que tenga la clave puede realizar gastos en tu cuenta.

No pegues la clave en el código del lado del cliente, ni la confirmes en un repositorio. En su lugar, configúrala como una variable de entorno:

export GEMINI_API_KEY="your_key_here"

El SDK oficial de Python lee esa variable por sí solo, lo que mantiene el secreto fuera de tus archivos fuente. Para los pasos de configuración canónicos, consulta la documentación de la API de Gemini de Google.

Haz tu primera llamada a la API

El endpoint REST es una solicitud POST al método generateContent del modelo. Aquí está en curl:

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.6-flash:generateContent" \
  -H "x-goog-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {"text": "Explain how APIs work"}
        ]
      }
    ]
  }'

La clave va en el encabezado x-goog-api-key. El cuerpo es un array contents; cada entrada tiene un array parts; cada parte aquí es una cadena text. Esa anidación parece complicada para una sola instrucción, pero es la misma estructura que más tarde te permite mezclar texto con imágenes y archivos en una sola solicitud.

¿Prefieres Python? Instala el SDK con pip install google-genai, luego:

from google import genai

client = genai.Client()  # lee GEMINI_API_KEY del entorno
resp = client.models.generate_content(
    model="gemini-3.6-flash",
    contents="Explain how APIs work",
)
print(resp.text)

El cliente recoge GEMINI_API_KEY por sí mismo, por lo que no hay ninguna clave en tu código. resp.text contiene la respuesta generada. Esa es una llamada funcional en cinco líneas.

Internamente, la API devuelve JSON. El texto generado se encuentra en candidates[0].content.parts[0].text. Es importante tener esto en cuenta ahora, porque es el campo exacto sobre el que harás una aserción cuando conviertas esta llamada en una prueba más adelante en la guía.

Parámetros clave que vale la pena conocer

La solicitud básica funciona, pero un puñado de configuraciones cambian lo que obtienes.

• Instrucción del sistema. Establece una persona o un conjunto de reglas que se aplican a toda la conversación, mantenidas separadas de la instrucción del usuario. Úsalo para “Responder solo en JSON” o “Eres un revisor de código conciso”. Dirige el tono y el formato de manera mucho más confiable que metiendo instrucciones en cada mensaje.
• Tokens de salida máximos. Limita la longitud de la respuesta. 3.6 Flash puede producir hasta 64k tokens de salida, así que aumenta el límite para generaciones largas y bájalo cuando quieras controlar el costo y la latencia.
• Entradas multimodales. El modelo lee texto, imágenes, video, audio y PDF en la misma llamada. Los añades como entradas adicionales en el array parts junto con tu texto. La salida es solo texto, así que piénsalo como muchos tipos de entrada, palabras de salida. La ventana de contexto admite hasta 1M de tokens de entrada, lo que es espacio para un PDF largo o una transcripción completa de video.
• Pensamiento y razonamiento. 3.6 Flash razona antes de responder a instrucciones difíciles. Eso es lo que mejora el trabajo de varios pasos, y es la razón por la que el precio de salida incluye tokens de pensamiento (más sobre esto en la siguiente sección). Puedes ajustar el esfuerzo de razonamiento cuando quieras cambiar profundidad por velocidad.

La lista completa de parámetros se encuentra en la documentación de la API de Gemini. No adivines los nombres de los campos; la documentación es la fuente de la verdad y se actualiza cuando lo hace la API.

Precios y el nivel gratuito

Gemini 3.6 Flash cuesta $1.50 por cada millón de tokens de entrada y $7.50 por cada millón de tokens de salida. Esa tasa de salida es una reducción de los $9.00 que cobraba 3.5 Flash, y 3.6 Flash también tiende a generar alrededor de un 17% menos de tokens de salida en la misma tarea, por lo que los ahorros se multiplican. Un detalle a interiorizar: el precio de salida incluye los tokens de pensamiento. El razonamiento interno del modelo se factura a la tasa de salida, por lo que una instrucción que desencadena un razonamiento intenso puede costar más de lo que sugiere la longitud visible de la respuesta. Tenlo en cuenta en tu presupuesto. Desglosamos todos los cálculos en nuestra guía de precios de Gemini 3.6 Flash.

El nivel gratuito funciona a través de AI Studio, y es real, pero tiene un límite de velocidad: solicitudes limitadas por minuto y por día, y Google puede usar datos del nivel gratuito para mejorar sus productos. Está diseñado para prototipos, no para tráfico de producción. Para aprender y probar, es suficiente. Para ver hasta dónde llega, lee cómo usar Gemini 3.6 Flash de forma gratuita. Cuando lo superes, habilitas la facturación y la misma clave sigue funcionando, sin necesidad de cambios en el código.

Probar y depurar la API de Gemini en Apidog

curl demuestra que la llamada funciona una vez. No te dirá cuándo Google cambia un campo de respuesta, cuándo tu clave expira o cuándo una implementación rompe silenciosamente la solicitud. Para eso necesitas una prueba guardada y repetible. Aquí es donde Apidog se gana su lugar en el flujo de trabajo.

Apidog es un cliente de API y una plataforma de pruebas. Aquí está el flujo para la llamada a Gemini, de principio a fin:

1. Crea la solicitud. Añade una nueva solicitud POST con la URL https://generativelanguage.googleapis.com/v1beta/models/gemini-3.6-flash:generateContent. Pega el cuerpo JSON anterior en el cuerpo de la solicitud.
2. Almacena la clave en una variable de entorno. Añade una variable llamada GEMINI_API_KEY a un entorno de Apidog, luego referénciala en el encabezado x-goog-api-key como {{GEMINI_API_KEY}}. El secreto se mantiene fuera de la solicitud compartida, y puedes intercambiar claves por entorno (desarrollo, staging, producción) sin tocar la llamada en sí.
3. Añade aserciones. Después de que se ejecute la solicitud, haz una aserción sobre la respuesta JSON: el estado es 200, y candidates[0].content.parts[0].text existe y no está vacío. Ahora una ejecución exitosa significa que la API realmente respondió, no solo que devolvió algo.
4. Guárdala y prográmala. Mantén la solicitud en una colección y prográmala como una prueba de regresión. Ejecútala con un temporizador o dentro de CI, y sabrás en el momento en que la llamada a Gemini deje de funcionar correctamente, antes que tus usuarios.

Descarga Apidog y podrás tener esta prueba funcionando en unos minutos. Esa es la verdadera ventaja aquí: Apidog no ejecuta el modelo, se asegura de que la API de la que dependes siga respondiendo como tu aplicación espera.

Errores comunes y soluciones

Tres fallos cubren la mayoría de lo que encontrarás al principio.

• 401 No autorizado (clave inválida). La clave es incorrecta, ha sido revocada o falta en el encabezado. Verifica que x-goog-api-key contenga la cadena exacta de AI Studio y que tu variable de entorno se haya resuelto correctamente. Un espacio al final o un {{GEMINI_API_KEY}} no expandido suelen ser los culpables.
• 429 Demasiadas solicitudes (límite de velocidad). Has alcanzado el límite por minuto o por día del nivel gratuito. Reduce la tasa de solicitudes, añade un reintento con retroceso exponencial, o habilita la facturación para aumentar el límite. Los bucles de prueba ajustados activan esto rápidamente.
• 404 No encontrado (modelo no encontrado). Esto es casi siempre un error tipográfico en el ID del modelo. Es gemini-3.6-flash, exactamente. No gemini-3.5-flash, ni gemini-flash-3.6. El nivel Lite en esta misma versión es gemini-3.5-flash-lite, un modelo diferente en la línea 3.5, así que no confundas los cables entre ellos.

Preguntas frecuentes

• ¿Cuál es el ID exacto del modelo para Gemini 3.6 Flash? Es gemini-3.6-flash. Úsalo como nombre del modelo en el SDK, y en la ruta de la URL REST justo antes de :generateContent.
• ¿Es gratuita la API de Gemini 3.6 Flash? Hay un nivel gratuito a través de AI Studio, y tiene un límite de velocidad. Está bien para prototipos y aprendizaje. El tráfico de producción requiere la facturación habilitada. Para más detalles, consulta cómo usarlo gratis.
• ¿Qué puedo enviar al modelo? Texto, imágenes, video, audio y PDF, hasta una ventana de contexto de 1 millón de tokens. La salida es solo texto.
• ¿Por qué mi factura fue más alta que las respuestas visibles? El precio de salida de $7.50 por cada millón de tokens incluye los tokens de pensamiento del modelo. Las instrucciones que requieren mucho razonamiento se facturan por más de lo que muestra la longitud de la respuesta en pantalla.
• ¿Es esta la misma API que la anterior Gemini 3.5 Flash? La forma de la llamada es la misma, así que si usaste la API de Gemini 3.5, simplemente cambias el ID del modelo y listo. 3.6 Flash reduce el precio de salida y usa menos tokens de salida para el mismo trabajo.
• ¿Puedo usar la misma clave en curl, Python y Apidog? Sí. Una clave de AI Studio funciona en todos ellos. Mantenla en una variable de entorno en cada herramienta en lugar de codificarla directamente, y podrás rotarla o revocarla en un solo lugar.

Adónde ir desde aquí

Ya tienes una clave, una llamada funcional en curl y Python, los parámetros importantes y una prueba de regresión guardada que monitorea el endpoint. Empieza con el nivel gratuito, mantén tu clave en una variable de entorno y apóyate en la documentación oficial para cualquier cosa más allá de lo básico. Cuando la llamada se convierta en algo de lo que tu aplicación dependa, envuélvela en una prueba de Apidog para que un cambio silencioso en la API nunca llegue a tus usuarios primero.