DEV Community

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

Posted on Originally published at apidog.com

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

Gemini 3.8 Flash: guía práctica para integrarlo con la API

Google lanzó Gemini 3.8 Flash el 2 de septiembre de 2026. Su ID de API es gemini-3.8-flash, sin sufijo de vista previa. Mantiene el precio introductorio de Gemini 3.7 Flash —$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. Google lo describe como un modelo que “trabaja más duro”: ejecuta más pasos de razonamiento y utiliza herramientas con mayor frecuencia en tareas complejas, algo que se refleja directamente en el consumo de tokens.

Prueba Apidog hoy

Esta guía muestra cómo obtener una clave en AI Studio, realizar una primera solicitud con la API de Interacciones, utilizar el endpoint heredado generateContent, configurar thinking_level, activar streaming y leer thoughtsTokenCount para controlar el costo del razonamiento. Todas las llamadas usan HTTP y JSON, así que puedes crearlas y validarlas en Apidog antes de integrarlas en tu aplicación.

Para conocer la descripción general, los benchmarks y los cambios del modelo, consulta qué es Gemini 3.8 Flash y la publicación de lanzamiento de Google.

Gemini 3.8 Flash de un vistazo

Elemento Valor
ID del modelo gemini-3.8-flash
Endpoint principal POST /v1beta/interactions
Endpoint heredado POST /v1beta/models/gemini-3.8-flash:generateContent
Encabezado de autenticación x-goog-api-key
Contexto / salida 1,048,576 tokens de entrada / 65,536 tokens de salida
Entradas Texto, imagen, video, audio y PDF; solo genera texto
Niveles de pensamiento low, medium (predeterminado) y high; minimal devuelve un error
Precio introductorio hasta el 31 de diciembre de 2026 $0.75 / $3.75 por 1 millón de tokens
Precio desde el 1 de enero de 2027 $1.50 / $7.50 por 1 millón de tokens

Dos detalles son importantes:

  • El nivel predeterminado es medium, no high como en Gemini 3 Pro.
  • Los tokens de pensamiento se facturan como tokens de salida. Consulta el desglose de precios y la página oficial de precios antes de definir la configuración de producción.

Paso 1: Obtén una clave de API en AI Studio

Abre Google AI Studio, inicia sesión y crea una clave desde la página de claves.

La clave funciona con el nivel gratuito, que tiene límites de velocidad. Google advierte que los datos del nivel gratuito se “utilizan para mejorar nuestros productos”. Para obtener límites de producción del Nivel 1, vincula una cuenta de facturación.

Guarda la clave como variable de entorno:

export GEMINI_API_KEY="AIza..."
Enter fullscreen mode Exit fullscreen mode

El SDK oficial de Python lee GEMINI_API_KEY automáticamente, por lo que genai.Client() no necesita argumentos. Instálalo con:

pip install google-genai
Enter fullscreen mode Exit fullscreen mode

Paso 2: Realiza tu primera llamada con la API de Interacciones

Google considera la API de Interacciones la forma principal de llamar a los modelos Gemini 3.x.

La solicitud incluye el modelo, una entrada y una configuración opcional de generación. En esta API, thinking_level se encuentra dentro de generation_config.

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-[REDACTED CREDENTIAL] \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Explain HTTP caching in 3 sentences.",
    "generation_config": {"thinking_level": "medium"}
  }'
Enter fullscreen mode Exit fullscreen mode

La respuesta contiene una lista de pasos de ejecución, no un único mensaje. Los pensamientos y las llamadas a herramientas aparecen como pasos; el último paso suele ser model_output.

El SDK de Python aplana esta estructura:

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)
Enter fullscreen mode Exit fullscreen mode

No establezcas temperature, top_p ni top_k. La guía de Google para Gemini 3 recomienda mantener la temperatura predeterminada de 1.0, porque reducirla “puede causar bucles o un rendimiento degradado”. Si reutilizas una configuración de un modelo anterior, elimina esos parámetros primero.

Paso 3: Mantén conversaciones multi-turno

La API de Interacciones conserva el estado de la conversación en el servidor por defecto. Para continuar una conversación, envía el ID de la interacción anterior mediante previous_interaction_id:

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)
Enter fullscreen mode Exit fullscreen mode

Si tus requisitos de cumplimiento prohíben el almacenamiento del lado del servidor, utiliza store: false. En ese caso, tendrás que gestionar el estado manualmente y reenviar los bloques y las firmas de pensamiento exactamente como los recibiste.

Este mismo requisito es importante cuando utilizas herramientas. Consulta la guía de llamada de funciones para Gemini 3.8 Flash.

Paso 4: Utiliza el endpoint heredado generateContent

La mayoría del código Gemini en producción todavía utiliza generateContent. Google lo considera heredado, pero sigue siendo totalmente compatible y no tiene una fecha de finalización publicada.

La forma de la solicitud es igual que en la guía de la API de Gemini 3.7 Flash, aunque thinking_level se configura en una ubicación diferente.

En generateContent, el nivel se encuentra dentro de generationConfig.thinkingConfig.thinkingLevel:

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

En Python:

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)
Enter fullscreen mode Exit fullscreen mode

Si tu configuración anterior utilizaba thinking_budget como entero, reemplázalo por el enumerado de cadena. candidate_count también desapareció en Gemini 3 y versiones posteriores. La guía de migración de Gemini 3.7 a 3.8 Flash incluye ejemplos JSON antes y después.

Diferencias entre ambas APIs

Preocupación API de Interacciones generateContent heredado
Nivel de pensamiento generation_config.thinking_level generationConfig.thinkingConfig.thinkingLevel
Estado de conversación previous_interaction_id en el servidor Reenviar el array completo de contents
Resultado de herramienta function_result con call_id y name functionResponse con id y name
Texto final Paso model_output; output_text en el SDK candidates[0].content.parts[].text
Firmas de pensamiento Gestionarlas manualmente cuando store: false Devolver cada parte exactamente como se recibió

Paso 5: Activa el streaming y controla el costo

Para interfaces de chat, utiliza streamGenerateContent y añade ?alt=sse para recibir eventos enviados por el servidor:

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."}]}]}'
Enter fullscreen mode Exit fullscreen mode

Con o sin streaming, las respuestas de generateContent terminan con usageMetadata. Regístralo en cada llamada:

"usageMetadata": {
  "promptTokenCount": 12,
  "candidatesTokenCount": 84,
  "thoughtsTokenCount": 310,
  "totalTokenCount": 406
}
Enter fullscreen mode Exit fullscreen mode

El campo clave en Gemini 3.8 Flash es thoughtsTokenCount. Durante el período introductorio, estos tokens se facturan como tokens de salida a $3.75 por millón. Google también 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 48.000 tokens de salida por tarea en high, un 30 % más que Gemini 3.7 Flash. Con los mismos precios por token, el costo por tarea aumentó de $0.40 a $0-3-8-flash-thinking-levels?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation) ayuda a convertir estos datos en una estrategia por ruta.

Para inspeccionar el razonamiento resumido, añade includeThoughts: true dentro de thinkingConfig:

{
  "thinkingConfig": {
    "thinkingLevel": "medium",
    "includeThoughts": true
  }
}
Enter fullscreen mode Exit fullscreen mode

Los resúmenes aparecen como partes con "thought": true. Exclúyelos al ensamblar la respuesta visible para el usuario.

Errores frecuentes

thinking_level: "minimal" devuelve 400 INVALID_ARGUMENT

Gemini 3.8 Flash solo admite low, medium y high. Enviar minimal produce:

Thinking level MINIMAL is not supported for this model.
Please retry with other thinking level.
Enter fullscreen mode Exit fullscreen mode

La solución es cambiar minimal por low. Las configuraciones antiguas de Gemini 3.x y los fragmentos copiados son la causa más habitual.

429 significa que alcanzaste el límite

Un 429 normalmente indica que superaste el límite de velocidad de tu nivel, no que la solicitud sea inválida.

Según la página de límites de velocidad:

  • El nivel gratuito tiene límites de velocidad.
  • El Nivel 1 se habilita al vincular una cuenta de facturación.
  • El Nivel 2 requiere $100 de gasto y tres días.
  • El Nivel 3 requiere $1.000 de gasto y 30 días.

Las solicitudes por minuto y los tokens por minuto disponibles para cada modelo se muestran en AI Studio para tu cuenta. Ante un 429, aplica backoff y reintenta. Si los errores continúan con poco volumen, considera actualizar de nivel.

Para trabajos fuera de línea, la API Batch ofrece un descuento del 50 %: $0.375 por millón de tokens de entrada y $1.875 por millón de tokens de salida durante el período introductorio. Sus límites de tokens en cola son:

  • Nivel 1: 3 millones
  • Nivel 2: 400 millones
  • Nivel 3: 1.000 millones

Consulta la guía del modo por lotes de Gemini para conocer el formato de la solicitud.

Falta call_id en el resultado de una función

Cuando utilizas herramientas:

  • Cada function_result de Interacciones debe incluir call_id y name.
  • Cada functionResponse heredada debe incluir el id coincidente y name.

Omitir cualquiera de estos campos hace que falle el turno.

Prueba ambos endpoints en Apidog

Cuando las solicitudes funcionen desde la terminal, guárdalas en un proyecto compartido de Apidog para que todo el equipo pueda ejecutarlas.

1. Mantén la clave fuera de la solicitud

Añade GEMINI_API_KEY como variable de entorno y referencia la variable en el encabezado:

x-goog-[REDACTED CREDENTIAL]_KEY}}
Enter fullscreen mode Exit fullscreen mode

La solicitud guardada no contendrá el secreto, y podrás cambiar entre una clave gratuita y una facturable modificando el entorno.

2. Verifica el estado y los tokens

Añade una aserción para comprobar que el estado sea 200 y otra para verificar que:

usageMetadata.thoughtsTokenCount
Enter fullscreen mode Exit fullscreen mode

se mantenga por debajo del límite que definas para cada prompt. Ese límite funciona como alarma de regresión de costos: si cambia el prompt o el modelo consume más tokens de pensamiento, la prueba fallará antes de que aumente la factura.

La guía de pruebas SSE cubre la variante de streaming, que Apidog muestra como un flujo de eventos fusionado.

3. Compara los tres niveles

Duplica la solicitud para low, medium y high. Compara thoughtsTokenCount y el tiempo de respuesta para obtener datos reales de tus prompts, en lugar de depender de promedios de benchmarks.

4. Programa las pruebas

Convierte las solicitudes en un escenario y ejecútalo periódicamente. Así, un cambio en los límites, una modificación de validación —como la eliminación de minimal— o un aumento inesperado de tokens aparecerá en un informe antes de llegar a producción.

Consulta Cómo programar pruebas de API en Apidog.

Apidog no ejecuta el modelo ni reemplaza el SDK. Proporciona una versión guardada, compartible y verificable de las llamadas HTTP: una capa que muchos equipos no crean hasta que algo falla.

Preguntas frecuentes

¿Qué endpoint deberían usar los proyectos nuevos?

La API de Interacciones. Google considera generateContent heredado, aunque sigue siendo totalmente compatible. Las nuevas funciones llegan primero a Interacciones y el estado del servidor simplifica el código multi-turno.

Mantén generateContent en los servicios existentes hasta que tengas una razón concreta para migrar.

¿Necesito una cuenta de pago?

No. Una clave gratuita de AI Studio funciona, aunque tiene límites de velocidad y está sujeta a los términos de uso de datos de Google. La guía para usar Gemini 3.8 Flash gratis explica qué incluye y qué no incluye el nivel gratuito. La aplicación Gemini requiere un plan AI Pro o Ultra para usar Gemini 3.8 Flash.

¿Gemini 3.8 Flash es más lento que Gemini 3.7 Flash?

Por token, no. Logan Kilpatrick, de Google, indicó que la velocidad es aproximadamente la misma, y Artificial Analysis midió cerca de 300 tokens de salida por segundo.

Por tarea, high tarda más porque genera más tokens: 2,5 minutos frente a 2,2 minutos en sus pruebas.

¿Puedo seguir utilizando Gemini 3.7 Flash?

Sí. Google afirma que Gemini 3.7 Flash sigue siendo totalmente compatible y no ha publicado una fecha de desuso. Si el consumo adicional de tokens de Gemini 3.8 Flash no mejora tus resultados, mantener el modelo actual sigue siendo una opción válida.

¿Gemini 3.8 Flash admite Live API o generación de imágenes?

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

Próximos pasos

Ya tienes dos rutas de llamada funcionales, un patrón multi-turno y una forma de controlar el consumo de tokens.

A partir de aquí:

  1. Integra herramientas con la guía de llamada de funciones.
  2. Define los niveles de pensamiento por ruta con la guía de niveles de pensamiento.
  3. Compara las ventajas y desventajas en la comparación entre Gemini 3.8 y 3.7 Flash.
  4. Mantén el escenario de Apidog activo para detectar las variaciones de costo como pruebas fallidas.

Top comments (0)