Cómo usar la API Gemini 3.8 Flash: API de interacciones, niveles de pensamiento y tu primera llamada en Apidog

Google lanzó Gemini 3.8 Flash el 2 de septiembre de 2026, y el ID del modelo de API es la cadena simple gemini-3.8-flash, sin sufijo de vista previa. Mantiene el precio de introducción de 3.7 Flash de $0.75 por millón de tokens de entrada y $3.75 por millón de tokens de salida hasta el 31 de diciembre de 2026, y Google lo describe como un modelo que “trabaja más duro”: realiza más pasos de razonamiento y llama a herramientas con más frecuencia en tareas complejas, lo que se refleja en tu factura de tokens.

Esta guía cubre el camino completo hacia una integración funcional: obtener una clave en AI Studio, enviar una primera solicitud a través de la API de Interacciones (la API principal de Google para Gemini 3.x ahora), el equivalente heredado generateContent que la mayoría del código existente aún utiliza, dónde va thinking_level en cada uno, el streaming, y cómo leer thoughtsTokenCount para que el costo de pensamiento nunca te sorprenda. Cada llamada es HTTP puro con JSON, por lo que puedes construir y verificar cada una en Apidog antes de que pase al código de la aplicación.

Para la descripción general del modelo, los benchmarks y los cambios, comienza con qué es Gemini 3.8 Flash. La publicación de lanzamiento de Google tiene el encuadre oficial.

API de Gemini 3.8 Flash de un vistazo

Dos detalles destacan antes de escribir código. El nivel de pensamiento predeterminado es medium, no high como en Gemini 3 Pro. Y los tokens de pensamiento se facturan a la tarifa de salida en la página oficial de precios, por lo que el nivel que elijas es una decisión de costo tanto como de calidad. El desglose de precios detalla los números por tarea.

Paso 1: Obtener una clave de API en AI Studio

Abre Google AI Studio, inicia sesión con una cuenta de Google y crea una clave de API desde la página de claves. La clave funciona directamente con el nivel gratuito, con límites de velocidad y la advertencia de que Google dice que los datos del nivel gratuito se “utilizan para mejorar nuestros productos”. Vincula una cuenta de facturación para pasar al Nivel 1 para límites de producción.

Exporta la clave en lugar de pegarla en el código:

export GEMINI_API_KEY="AIza..."

El SDK oficial de Python lee GEMINI_API_KEY del entorno, por lo que genai.Client() no necesita argumentos. Instálalo con pip install google-genai.

Paso 2: Tu primera llamada con la API de Interacciones

Google ahora trata la API de Interacciones como la forma principal de llamar a los modelos Gemini 3.x. La solicitud es un objeto JSON: el modelo, una input, y una generation_config opcional donde reside thinking_level.

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Explain HTTP caching in 3 sentences.",
    "generation_config": {"thinking_level": "medium"}
  }'

La respuesta es una lista de pasos de ejecución en lugar de un solo mensaje. Los pensamientos del modelo y las llamadas a herramientas aparecen como pasos, y el paso final es model_output, que contiene el texto. En Python, el SDK lo aplana por ti:

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Explain HTTP caching in 3 sentences.",
    generation_config={"thinking_level": "medium"},
)

print(interaction.output_text)

Omite temperature, top_p y top_k. La guía de Google para cada modelo Gemini 3 es mantener la temperatura en su valor predeterminado de 1.0, porque reducirla “puede causar bucles o un rendimiento degradado”. Si copiaste una configuración de un modelo anterior, esa es la primera línea a eliminar.

Paso 3: Conversaciones multi-turno con previous_interaction_id

La API de Interacciones mantiene el estado de la conversación en el servidor por defecto. Para continuar una conversación, envía el id de la respuesta anterior como previous_interaction_id junto con solo la nueva entrada del usuario. No tienes que reenviar el historial.

follow_up = client.interactions.create(
    model="gemini-3.8-flash",
    input="Now give one example of a Cache-Control header.",
    previous_interaction_id=interaction.id,
)
print(follow_up.output_text)

Si tus reglas de cumplimiento prohíben el almacenamiento del lado del servidor, establece store: false. La desventaja es que entonces gestionas el estado tú mismo, incluyendo el envío de los bloques de pensamiento y las firmas de pensamiento del modelo exactamente como los recibiste en cada turno. Esa es la misma regla que causa problemas en el uso de herramientas, cubierta en la guía de llamada de funciones para 3.8 Flash.

Paso 4: La ruta heredada de generateContent

La mayoría del código Gemini en producción todavía llama a generateContent. Google lo llama heredado, pero “sigue siendo totalmente compatible” sin fecha de finalización, por lo que no tienes que reescribir nada hoy. Nuestra guía de la API de Gemini 3.7 Flash cubrió solo esta ruta; la forma es idéntica para 3.8 Flash, y la configuración de pensamiento se encuentra en un lugar diferente al de Interacciones.

En generateContent, el nivel va bajo generationConfig.thinkingConfig.thinkingLevel, en camelCase:

curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "Explain HTTP caching in 3 sentences."}]}],
    "generationConfig": {"thinkingConfig": {"thinkingLevel": "low"}}
  }'

El equivalente en Python utiliza objetos de configuración tipados:

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents="Explain HTTP caching in 3 sentences.",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_level="low")
    ),
)
print(response.text)

Si vienes de una configuración que usaba thinking_budget como un entero, reemplázalo con el enumerado de cadena. candidate_count también ha desaparecido en Gemini 3 y versiones posteriores. La lista de verificación completa, con JSON antes y después para cada cambio, se encuentra en la guía de migración de 3.7 a 3.8 Flash.

Aquí tienes el mismo conjunto de preocupaciones lado a lado, para que puedas traducir entre las dos APIs sin tener que releer ambas documentaciones:

Paso 5: Streaming y lectura del costo de pensamiento

Para interfaces de chat, cambia el nombre del método a streamGenerateContent y añade ?alt=sse para obtener eventos enviados por el servidor (SSE), un fragmento parcial de candidates por evento:

curl -N "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:streamGenerateContent?alt=sse" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"parts":[{"text":"List three HTTP caching headers."}]}]}'

Con o sin streaming, cada respuesta de generateContent termina con un objeto usageMetadata. Léelo en cada llamada:

"usageMetadata": {
  "promptTokenCount": 12,
  "candidatesTokenCount": 84,
  "thoughtsTokenCount": 310,
  "totalTokenCount": 406
}

thoughtsTokenCount es el número a vigilar en 3.8 Flash. Los tokens de pensamiento se facturan como tokens de salida a $3.75 por millón durante el período de introducción, y Google afirma que el modelo “podría usar más tokens para maximizar el rendimiento, especialmente en niveles de esfuerzo más altos”. Artificial Analysis midió aproximadamente 48k tokens de salida por tarea en su ejecución de índice en high, un 30% más que 3.7 Flash, lo que elevó el costo por tarea de $0.40 a $0.58 con precios por token sin cambios. Sus ejecuciones en medium y low resultaron en $0.41 y $0.24 por tarea. La guía de niveles de pensamiento convierte esos números en una estrategia por ruta.

Para ver sobre qué razonó el modelo, añade "includeThoughts": true dentro de thinkingConfig. Los resúmenes de pensamiento se devuelven como partes marcadas con "thought": true; omítelos al ensamblar la respuesta visible.

Errores que encontrarás en la primera hora

thinking_level: "minimal" falla la validación. Gemini 3.8 Flash solo soporta low, medium y high. Enviar minimal devuelve un 400 INVALID_ARGUMENT con el mensaje “Thinking level MINIMAL is not supported for this model. Please retry with other thinking level.” (verificado con una llamada en vivo el 3 de septiembre de 2026), y la solución es un cambio de una palabra a low. Las configuraciones de 3.x más antiguas y los fragmentos copiados son la fuente habitual.

429 significa que alcanzaste el límite de tu nivel, no un error. La página de límites de velocidad explica los niveles: el nivel gratuito está limitado por velocidad, el Nivel 1 se desbloquea al vincular una cuenta de facturación, el Nivel 2 requiere $100 de gasto más tres días, y el Nivel 3 requiere $1,000 más 30 días. Las cifras de solicitudes por minuto y tokens por minuto por modelo solo se muestran en la página de límites de velocidad de AI Studio para tu cuenta, así que verifica allí en lugar de confiar en un número de una publicación de blog. Ante un 429, retrocede e inténtalo de nuevo; si se repiten los 429s con poco volumen, actualiza el nivel. Para trabajos fuera de línea, la API Batch es la mejor solución: se ejecuta con un 50% de descuento ($0.375 / $1.875 por millón de tokens durante el período de introducción) y tiene sus propios límites de tokens en cola de 3M en el Nivel 1, 400M en el Nivel 2 y 1B en el Nivel 3. La guía del modo por lotes de Gemini muestra la forma de la solicitud.

Falta call_id en el resultado de una función. Si usas herramientas, cada function_result (Interacciones) debe llevar tanto call_id como name en 3.8 Flash, y cada functionResponse heredada debe llevar el id coincidente más name. Omitir cualquiera de los dos hace que el turno falle.

Prueba ambos endpoints en Apidog antes de implementarlos

Una vez que ambas solicitudes funcionen desde la terminal, muévelas a un lugar donde todo el equipo pueda ejecutarlas. Descarga Apidog, crea un proyecto y añade los dos endpoints anteriores como solicitudes guardadas. Cuatro hábitos rinden frutos:

• Mantén la clave fuera de la solicitud. Añade GEMINI_API_KEY como variable de entorno y referénciala como {{GEMINI_API_KEY}} en el encabezado x-goog-api-key. La solicitud guardada nunca contendrá el secreto, y cambiar entre una clave de nivel gratuito y una clave facturable es un cambio de entorno.
• Afirma el estado y el uso de tokens. Añade una aserción de que el estado es 200, luego una aserción de ruta JSON de que usageMetadata.thoughtsTokenCount se mantiene por debajo de un límite que elijas por prompt. El límite es tu alarma de regresión de costos: si una actualización de prompt o un cambio silencioso del modelo eleva los tokens de pensamiento, la prueba falla antes de que lo haga la factura. La guía de pruebas SSE cubre la variante de streaming, que Apidog renderiza como un flujo de eventos fusionado en lugar de fragmentos brutos.
• Envía el mismo prompt en los tres niveles. Duplica la solicitud con low, medium y high, y compara thoughtsTokenCount y el tiempo de respuesta lado a lado. Eso te dará números reales para tus prompts en lugar de promedios de índice.
• Prográmalo. Convierte las solicitudes en un escenario de prueba y ejecútalo en un horario, para que un cambio en el límite de velocidad, un cambio de validación como la eliminación de minimal, o un pico de tokens aparezca en un informe, no en producción. Cómo programar pruebas de API en Apidog explica la configuración.

Apidog no ejecuta el modelo ni reemplaza el SDK. Te proporciona una versión guardada, compartible y asertiva de las llamadas HTTP, que es la parte que la mayoría de los equipos omiten hasta que algo se rompe.

Preguntas frecuentes

¿Qué endpoint deberían usar los nuevos proyectos? La API de Interacciones. Google llama a generateContent heredado, y sigue siendo totalmente compatible, pero las nuevas características llegan primero a Interacciones y el estado del lado del servidor hace que el código multi-turno sea más corto. Mantén generateContent para los servicios existentes hasta que tengas una razón para migrar.

¿Necesito una cuenta de pago para llamar a Gemini 3.8 Flash? No. Una clave gratuita de AI Studio funciona, con límites de velocidad y los términos de uso de datos de Google. La guía de uso gratuito enumera lo que el nivel gratuito te proporcionará y lo que no, incluyendo el hecho de que la aplicación Gemini requiere un plan AI Pro o Ultra para 3.8 Flash.

¿Es 3.8 Flash más lento que 3.7 Flash? Por token, no. Logan Kilpatrick de Google dijo que la velocidad es aproximadamente la misma, y Artificial Analysis midió aproximadamente 300 tokens de salida por segundo. Por tarea, tarda más en high (2.5 minutos versus 2.2 en sus pruebas) porque genera más tokens.

¿Puedo seguir llamando a Gemini 3.7 Flash? Sí. Google dice que 3.7 Flash “sigue siendo totalmente compatible” y no ha publicado una fecha de desuso. Si el gasto adicional de tokens en 3.8 Flash no te aporta nada en tu carga de trabajo, quedarte donde estás es una opción válida.

¿3.8 Flash soporta la API Live o la generación de imágenes? No. Solo genera texto. La generación de audio, la generación de imágenes y la API Live no son compatibles con este modelo.

A dónde ir ahora

Ahora tienes dos rutas de llamada que funcionan, un patrón multi-turno y una verificación del uso de tokens. A partir de aquí, conecta herramientas con la guía de llamada de funciones, decide tus niveles por ruta con la publicación de niveles de pensamiento, y si aún estás decidiendo si moverte, la comparación de 3.8 vs 3.7 Flash expone las ventajas y desventajas. Mantén el escenario de Apidog funcionando para que la variación de costos aparezca como una prueba fallida.