Gemini 3.7 Flash a 3.8 Flash: Guía de migración de API

Google lanzó Gemini 3.8 Flash el 2 de septiembre de 2026, tres semanas después de 3.7 Flash, al mismo precio de introducción y aproximadamente la misma velocidad. El ID del modelo es gemini-3.8-flash, sin sufijo de vista previa, y la tarjeta del modelo lo describe como “basado en Gemini 3.7 Flash”. Por lo tanto, la mayoría de los equipos esperan un cambio de una sola línea. Para un mensaje de chat simple, lo es. Para cualquier cosa que establezca parámetros de pensamiento, ajuste el muestreo o ejecute un bucle de herramientas, hay nueve cosas que verificar, y dos de ellas devuelven errores que 3.7 Flash nunca hizo.

Esta guía es esa lista de verificación, elaborada a partir de la página de Google Novedades de Gemini 3.8 Flash y la guía para desarrolladores de Gemini 3. Cada elemento tiene un fragmento de antes y después para ambas formas de API: la API de interacciones, que Google ahora trata como la ruta principal, y el endpoint heredado generateContent que la mayoría del código de 3.7 Flash todavía utiliza. Cada fragmento se puede pegar en Apidog y enviarse al endpoint en vivo antes de que llegue a producción. Si desea primero una descripción general del modelo, comience con qué es Gemini 3.8 Flash.

Una nota contextual antes de la lista. Google dice que 3.8 Flash “trabaja más duro” por diseño: en tareas complejas, da pasos de razonamiento más pequeños, verifica su trabajo y llama a herramientas de forma iterativa. Esa es la fuente de la mayoría de sus beneficios y también la razón por la que una migración necesita una revisión del presupuesto de tokens, no solo una diferencia de configuración.

botón

Qué cambia y qué no

Fuente para las filas de precios: la página de precios de la API de Gemini de Google, donde las filas 3.6, 3.7 y 3.8 Flash son idénticas.

Paso 0: decide si migrar o no

Nada obliga a la migración. La publicación de lanzamiento de Google afirma que “Gemini 3.7 Flash sigue siendo totalmente compatible”, y no se ha publicado una fecha de finalización de soporte. El precio por token no ha cambiado, por lo que la única diferencia de costo es el uso. Artificial Analysis midió que 3.8 Flash en pensamiento de alto nivel utilizaba aproximadamente 48k tokens de salida por tarea en su índice, un 30% más que 3.7 Flash, lo que aumentó el costo por tarea de $0.40 a $0.58 con tarifas idénticas. Su puntuación en el índice subió de 56 a 59, y la precisión en el uso de herramientas en τ³-Banking aumentó 12 puntos, llegando al 45%.

Así que la compensación es más capacidad por tarea a cambio de más tokens por tarea. Si su carga de trabajo es corta, sensible a la latencia o ya está pasando sus evaluaciones con 3.7 Flash, puede quedarse. La comparación completa de 3.8 Flash vs 3.7 Flash tiene una matriz de decisión por carga de trabajo. Si va a migrar, siga leyendo.

Paso 1: intercambiar el ID del modelo en ambas formas

API de interacciones (API principal de Google para Gemini 3.x):

{"model": "gemini-3.7-flash", "input": "..."}
{"model": "gemini-3.8-flash", "input": "..."}

generateContent heredado (aún compatible, sin fecha de finalización):

POST /v1beta/models/gemini-3.7-flash:generateContent
POST /v1beta/models/gemini-3.8-flash:generateContent

SDK de Python, ambas rutas:

client.interactions.create(model="gemini-3.8-flash", input=..., generation_config={"thinking_level": "medium"})
client.models.generate_content(model="gemini-3.8-flash", contents=..., config=types.GenerateContentConfig(thinking_config=types.ThinkingConfig(thinking_level="low")))

Si nunca ha utilizado la API de interacciones, la guía de la API de 3.8 Flash cubre ambas formas de principio a fin; la guía detallada de la API de 3.7 Flash más antigua solo cubría generateContent, por lo que esta guía muestra ambas.

La lista de verificación de migración de nueve elementos

Revise estos elementos en orden. Los elementos 1 a 4 son cambios de configuración que surgen inmediatamente. Los elementos 5 y 6 afectan los bucles de herramientas y el estado de múltiples turnos. Los elementos 7 a 9 son cambios de planificación y medios que solo detectará en las pruebas.

1. Mapear thinking_level: "minimal" a "low"

Este es el que falla primero. 3.8 Flash acepta low, medium y high. Enviar minimal devuelve un error de validación. El valor predeterminado cuando no envía nada es medium. Gemini 3 Pro se establece de forma predeterminada en high, así que no copie una configuración de Pro y asuma que coincide.

Antes (3.7 Flash, Interacciones):

{"generation_config": {"thinking_level": "minimal"}}

Después (3.8 Flash):

{"generation_config": {"thinking_level": "low"}}

Forma heredada, después:

{"generationConfig": {"thinkingConfig": {"thinkingLevel": "low"}}}

La documentación de pensamiento de Google describe low como la configuración de latencia y medium como el valor predeterminado para código complejo y trabajo de agente. Qué nivel usar por ruta es un artículo aparte; para fines de migración, low es el reemplazo directo de minimal.

2. Eliminar temperature, top_p y top_k

La guía de Google para cada modelo de Gemini 3 es mantener la temperatura en su valor predeterminado de 1.0. Bajarla “puede causar bucles o un rendimiento degradado”. Muchas configuraciones de 3.7 Flash conservan un temperature: 0.2 de generaciones anteriores. Elimine las claves de muestreo en lugar de configurarlas.

Antes:

{"generationConfig": {"temperature": 0.2, "topP": 0.9, "topK": 40}}

Después:

{"generationConfig": {"thinkingConfig": {"thinkingLevel": "medium"}}}

Si utilizó una temperatura baja para obtener JSON repetible, use salidas estructuradas en su lugar. Son compatibles con 3.8 Flash y le brindan una respuesta con forma de esquema sin tocar el muestreo.

3. Reemplazar thinking_budget con thinking_level

thinking_budget era un límite entero de tokens. thinking_level es una enumeración de cadena. No existe un mapeo aritmético entre ellos, así que elija el nivel por intención: las rutas de baja latencia obtienen low, las rutas predeterminadas obtienen medium, las rutas de varios pasos más difíciles obtienen high.

Antes:

{"generationConfig": {"thinkingConfig": {"thinkingBudget": 4096}}}

Después:

{"generationConfig": {"thinkingConfig": {"thinkingLevel": "low"}}}

Los tokens de pensamiento todavía se facturan como tokens de salida y se informan en usageMetadata.thoughtsTokenCount, por lo que el control de costos pasa de un límite estricto a una elección de nivel más una aserción en sus pruebas (consulte la sección de regresión a continuación).

4. Eliminar candidate_count

Gemini 3 y versiones posteriores no admiten múltiples candidatos. Elimine la clave y cualquier código que indexara candidates[1] o más allá.

Antes:

{"generationConfig": {"candidateCount": 2}}

Después:

{"generationConfig": {}}

Si muestreó varios candidatos para elegir el mejor, el reemplazo en 3.8 Flash es un nivel de pensamiento más alto, que realiza la verificación dentro de una sola respuesta.

5. Poner call_id y name en cada resultado de función

Esta es la segunda ruptura importante. En 3.8 Flash, cada resultado de función que envíe debe llevar tanto el id de la llamada como el name de la función. La guía de Gemini 3 de Google dice que “asegúrese de que todos los objetos FunctionResponse incluyan call_id y name”. El código que solo hacía eco del nombre fallará en el turno del resultado de la herramienta.

API de interacciones, después:

{
  "previous_interaction_id": "<id from the function_call step>",
  "input": [{
    "type": "function_result",
    "name": "get_weather",
    "call_id": "<id from the function_call step>",
    "result": [{"type": "text", "text": "{\"temp_c\": 24}"}]
  }]
}

El paso function_call del modelo le proporciona id, name y arguments; copie los dos primeros directamente. En la forma heredada, la parte functionResponse lleva el mismo valor en un campo llamado id (que coincide con el id de la parte functionCall del modelo) junto con name y response. La referencia de llamadas a funciones de Google tiene los ejemplos canónicos, y la guía de llamadas a funciones de 3.8 Flash explica el bucle completo de dos turnos, incluyendo por qué 3.8 Flash llama a las herramientas más veces por tarea que 3.7 Flash.

6. Transmitir las firmas de pensamiento exactamente como se recibieron

Los modelos Gemini 3 adjuntan firmas de pensamiento a las partes de la respuesta. Cuando construya el siguiente turno usted mismo, devuelva cada parte sin cambios, incluyendo las firmas, para todos los tipos de partes, no solo texto. Eliminar o volver a serializarlas degrada la continuidad del modelo en el siguiente paso.

La API de interacciones elimina este trabajo cuando permite que el servidor mantenga el estado: pase previous_interaction_id y Google conserva el historial. Si establece store: false para una llamada sin estado, usted es nuevamente el propietario del historial y debe enviar los bloques de pensamiento y las firmas usted mismo. En el generateContent heredado, siempre es el propietario del historial, así que audite cualquier código que reconstruya contents a partir de una copia recortada de la última respuesta.

7. Presupuestar más tokens por ruta

Este elemento no tiene ningún error que detectar, por lo que a menudo se pasa por alto. La cifra de +30% de tokens de salida de Artificial Analysis es un promedio en su índice con pensamiento de alto nivel. La propia redacción de Google es que el modelo “puede usar más tokens en tareas más largas y complejas, por diseño” y que el uso aumenta “especialmente en niveles de esfuerzo más altos”.

• Planificar por ruta, no globalmente:
• Endpoints sensibles a la latencia: low. AA midió 0.8 minutos por tarea en bajo nivel frente a 2.5 en alto nivel, y $0.24 por tarea frente a $0.58.
• Rutas predeterminadas: medium, a unos $0.41 por tarea en el mismo índice.
• Bucles de agente: espere más turnos de llamada de herramientas por tarea, así que limite el bucle por recuento de turnos, no solo por tokens.

También revise el límite de 65,536 tokens de salida. Un prompt de 3.7 Flash que devolvía 40k tokens con pensamiento ahora puede acercarse más al límite. Si está modelando la factura, el desglose de precios de 3.8 Flash muestra los números por tarea en los tres niveles.

8. Probar media_resolution_high en PDFs versus video

3.8 Flash acepta entrada de texto, imagen, video, audio y PDF. La configuración de resolución de medios cambia cuántos tokens consume cada entrada de medios, y el costo difiere según el tipo de medio, por lo que la misma configuración que es barata en una página PDF puede ser costosa en un video largo. No traslade una configuración global de alta resolución de 3.7 Flash sin medir. Envíe un PDF representativo y un video representativo en cada resolución y compare usageMetadata.promptTokenCount entre ellos.

9. Eliminar cualquier llamada de segmentación de imágenes

La segmentación de imágenes no es compatible con los modelos Gemini 3. Si una canalización de la era 3.7 Flash todavía enrutaba la segmentación a través de un modelo Gemini más antiguo, esa ruta es independiente de esta migración; si un prompt le pedía a 3.8 Flash máscaras de segmentación, espere que falle en lugar de devolver una salida utilizable. La generación de imágenes, la generación de audio y la API Live tampoco son compatibles con 3.8 Flash, según la página del modelo.

Construir el plan de regresión en Apidog

Una migración con dos cambios importantes y un cambio en el uso de tokens necesita una comparación repetible, no un curl puntual. Aquí está la configuración que usamos en Apidog, que funciona porque Apidog es un cliente API y ejecutor de pruebas: envía las solicitudes, verifica las respuestas y programa la ejecución. No ejecuta el modelo.

Entorno y variables.

Entorno y variables. Cree un entorno Gemini con GEMINI_API_KEY almacenado como una variable secreta y una variable MODEL. Use {{MODEL}} en la URL de la solicitud generateContent y en el campo model de la solicitud de interacciones, para que la misma solicitud guardada se ejecute contra cualquiera de los modelos.

Prompts de oro.

Prompts de oro. Guarde de 10 a 20 prompts que representen sus rutas reales: un breve turno de chat, una extracción de salida estructurada, una llamada a función de dos turnos con una herramienta simulada, una entrada de PDF y una de video. Cada uno es una solicitud en un escenario de prueba.

Aserciones.

Aserciones. Agregue tres por solicitud:

• El estado es 200, y el cuerpo de la respuesta coincide con un esquema JSON. Para rutas de salida estructurada, afirme sobre los campos que analiza posteriormente.
• usageMetadata.thoughtsTokenCount se mantiene por debajo de un límite que usted establece por ruta (por ejemplo, 8,000 en una ruta low). Esta es la protección que detecta una configuración que silenciosamente volvió a medium.
• usageMetadata.totalTokenCount se mantiene por debajo del presupuesto de la ruta del elemento 7.

Comparación lado a lado.

Comparación lado a lado. Duplique el escenario, establezca MODEL en gemini-3.7-flash en uno y gemini-3.8-flash en el otro, y ejecute ambos. Los informes de prueba de Apidog muestran éxito/fallo por aserción y los cuerpos de respuesta, de modo que la diferencia de tokens por prompt es visible en una sola vista en lugar de reconstruirse a partir de los logs. Para el escenario de llamada a función, agregue una aserción de que el call_id que envió de vuelta es igual al id del function_call del paso anterior.

Programarlo.

Programarlo. Convierta el escenario de 3.8 Flash en una ejecución programada para que los límites de tokens se verifiquen diariamente durante la ventana de lanzamiento. La guía de pruebas API programadas cubre la configuración. Si prefiere seguirlo en la aplicación, Descargue Apidog e importe los fragmentos curl anteriores.

Reversión: mantener 3.7 Flash detrás de un indicador de configuración

Dado que 3.7 Flash sigue siendo totalmente compatible y comparte el precio de 3.8 Flash, la reversión es económica: mantenga el ID del modelo en la configuración en lugar de en el código.

{"gemini_model": "gemini-3.8-flash", "gemini_fallback_model": "gemini-3.7-flash"}

Tres reglas hacen que el indicador sea seguro:

• Mantenga la forma de solicitud migrada en ambos modelos. Los elementos 1 a 6 (sin minimal, sin claves de muestreo, thinking_level en lugar de thinking_budget, sin candidate_count, call_id + name, firmas preservadas) también son válidos en 3.7 Flash, por lo que un indicador activado nunca necesita una segunda ruta de código.
• Despliegue por ruta. Active primero las rutas de baja latencia low, ya que su diferencia de tokens es la más pequeña; active los bucles de agente al final, después de que el escenario de comparación lado a lado haya pasado durante unos días.
• Vigile los tokens, no solo los errores. Un activador de reversión en 3.8 Flash es más probable que sea una regresión de costo o latencia que un error 4xx, así que conecte las aserciones de límite de tokens a su sistema de alertas.

Preguntas frecuentes

¿Gemini 3.8 Flash cuesta más que 3.7 Flash? No por token. Ambos cuestan $0.75 de entrada / $3.75 de salida por 1M hasta el 31 de diciembre de 2026, y ambos aumentan a $1.50 / $7.50 el 1 de enero de 2027. Por tarea, 3.8 Flash usa más tokens por diseño; Artificial Analysis midió aproximadamente un 30% más de tokens de salida en su índice con pensamiento de alto nivel.

¿Qué sucede si mantengo thinking_level: "minimal"? La solicitud fallará con un error de validación en 3.8 Flash. Reemplácelo con low. La guía de niveles de pensamiento explica qué hace cada nivel restante y cómo medir la diferencia.

¿Tengo que migrar a la API de interacciones para usar 3.8 Flash? No. generateContent se describe como heredado, pero sigue siendo totalmente compatible sin fecha de finalización de soporte, y 3.8 Flash funciona con él. La API de interacciones agrega estado de conversación del lado del servidor a través de previous_interaction_id, lo que elimina el seguimiento de firmas de pensamiento del elemento 6.

¿Se está deprecando 3.7 Flash? Google dice que “sigue siendo totalmente compatible” y no ha publicado una fecha de deprecación. Eso es lo que hace que la reversión con indicador de configuración sea viable.

¿Puedo mantener la misma temperatura que ajusté para 3.7 Flash? El consejo de Google para todos los modelos Gemini 3 es dejar la temperatura en 1.0. Si ya la estaba sobrescribiendo en 3.7 Flash, esta migración es el momento de eliminarla y verificar sus evaluaciones; las salidas estructuradas son la ruta compatible para formas deterministas.

Lanzarlo por etapas

La migración en sí es pequeña: un cambio de ID, cuatro eliminaciones o renombramientos de configuración, dos campos de bucle de herramientas y una auditoría de firmas. La parte que lleva tiempo es probar que el presupuesto de tokens se mantiene por ruta, y eso es un problema de pruebas. Guarde los prompts de oro, afirme sobre el esquema y los límites de tokens, ejecute 3.7 y 3.8 Flash lado a lado hasta que los números se estabilicen, luego active el indicador una ruta a la vez. Si una ruta retrocede, el indicador la devuelve a 3.7 Flash sin cambios de código, y usted conserva las rutas mejoradas.