Curso
Google ha lanzado 3 modelos Flash en 6 semanas: 3.6 a finales de julio, 3.7 Flash el 13 de agosto y ahora Gemini 3.8 Flash el 2 de septiembre de 2026. Si vienes de 3.7, la actualización es de 1 línea, porque la superficie del API es idéntica. Configuraciones más antiguas seguirán fallando si no ajustas los parámetros.
En lugar de parchear código heredado, este tutorial construye una configuración limpia desde cero. Inicializaremos un cliente de Python con la Interactions API, compararemos los 3 niveles de razonamiento en una tarea práctica de depuración con conteos reales de tokens, extraeremos JSON limpio según esquema desde un PDF de factura y implementaremos un bucle completo de function calling. Por último, cubriremos la checklist de migración para desarrolladores que actualizan desde 3.6 Flash o anteriores.
Para seguir el tutorial, necesitas Python 3.10+ y una clave de API de Google AI Studio. Esta guía se centra en la implementación en código, no en anuncios de funcionalidades.
Resumen
-
Gemini 3.8 Flash (
gemini-3.8-flash) usa la Interactions API mediante client.interactions.create() en el SDKgoogle-genai. -
La profundidad de razonamiento se ajusta con valores de cadena (
thinking_level:low,medium,high). -
Las opciones de muestreo heredadas (
temperature,top_p,top_k) están obsoletas -
El estado multi-turno se gestiona en el servidor con
previous_interaction_id. -
Precio de lanzamiento: $0.75 / $3.75 por millón de tokens de entrada/salida hasta el 31 de diciembre de 2026.
-
Si vienes de 3.7 Flash, solo cambia la cadena del modelo.
Ingeniero Asociado de IA para Científicos de Datos
¿Qué es Gemini 3.8 Flash?
Gemini 3.8 Flash es el modelo todoterreno de Google, disponible de forma general desde el 2 de septiembre de 2026, con el ID de modelo gemini-3.8-flash. Llegó 3 semanas después de 3.7 Flash, y Google lo posiciona para programación de largo recorrido, flujos agentic y razonamiento de varios pasos en dominios especializados como finanzas y jurídico.
Las especificaciones que importan para llamadas a la API no han cambiado respecto a 3.7:
- ventana de contexto de 1M de tokens
- 64k tokens máximos de salida
- entrada multimodal (texto, imágenes, vídeo, audio, PDFs) con salida en texto
- El mismo precio promocional de $0.75 por 1M de tokens de entrada y $3.75 por 1M de tokens de salida hasta el 31 de diciembre de 2026 (sube a $1.50 y $7.50 desde el 1 de enero de 2027)
Lo que cambia es el comportamiento, no la superficie: Google afirma que 3.8 se esfuerza más en tareas complejas, dando pasos extra de razonamiento y llamando a herramientas de forma iterativa, lo que puede aumentar el uso de tokens a niveles de esfuerzo más altos. 3.7 Flash sigue totalmente soportado para cargas donde prima la eficiencia sobre la profundidad.
Para benchmarks y precios detallados, consulta nuestra guía de Gemini 3.8 Flash, o lee la guía ¿Qué es Google Gemini? para una visión general de la plataforma.
Gemini 3.8 Flash vs. 3.8 Flash Cyber
El lanzamiento incluye 2 variantes, y solo 1 tiene un ID de modelo que puedas teclear.
- Gemini 3.8 Flash es el modelo general, disponible hoy en Google AI Studio y la Gemini API.
- Gemini 3.8 Flash Cyber es una variante de ciberseguridad ajustada para descubrimiento de vulnerabilidades y parcheo automatizado.
La variante Cyber no está disponible en la API pública: el acceso pasa por el Fairwind Program de Google, que está limitado a autoridades gubernamentales aprobadas, operadores de infraestructuras críticas y mantenedores de software.
Si sigues este tutorial, tu ID de modelo es gemini-3.8-flash. Nada de lo que viene a continuación requiere ni usa la variante Cyber.
Interactions API vs. generateContent
Para llamar a Gemini 3.8 Flash, usa client.interactions.create() en el SDK google-genai. Google hizo GA la Interactions API en junio de 2026 y la recomienda para todo trabajo nuevo. Aunque generateContent sigue funcionando, ahora es legado. Las nuevas funciones como historial en servidor, ejecución en background y pasos de ejecución observables llegan primero a Interactions.
El mayor cambio práctico es la gestión de estado. Las llamadas multi-turno usan ahora un previous_interaction_id del lado del servidor: pasas el ID de la última interacción y el servidor restaura el estado. Ya no necesitas añadir o reenviar manualmente todo el historial del chat desde tu cliente. Evita también pre-rellenar turnos del modelo; eso es un patrón legado de generateContent y fallará en Gemini 3.x.
Hay algo que pilla a casi todo el mundo, y vuelve a salir en la sección de PDF: previous_interaction_id restaura el historial de conversación y nada más. tools, system_instruction, generation_config y response_format tienen alcance de interacción, así que cualquier turno que los necesite debe volver a pasarlos.
thinking_level sustituye a los mandos de muestreo
En modelos Gemini antiguos, los desarrolladores usaban temperature, top_p y top_k para controlar la aleatoriedad. Gemini 3.x elimina estos mandos y los sustituye por thinking_level, que es ahora el único ajuste.
Acepta 3 valores:
-
low: el mínimo de tokens de razonamiento, más rápido y barato. Ideal para extracción, clasificación y cualquier cosa que vayas a revisar tú mismo. -
medium: el valor por defecto, y la recomendación de Google para código y trabajo con agentes. -
high: el mayor presupuesto de razonamiento, para lógica difícil de varios pasos y tareas con muchas herramientas.
No envíes minimal. Es inválido desde Gemini Flash 3.7 y devuelve un 400 de validación.
Otra regla que se mantiene desde 3.7: frequency_penalty, presence_penalty y candidate_count ahora lanzan un error de API activo, así que elimínalos también de las configuraciones heredadas.
¿Cómo configuras la API de Gemini 3.8 Flash?
Configurar el entorno te lleva unos 2 minutos. Necesitas una clave de API de Google AI Studio y la librería de Python actualizada google-genai.
Consigue una clave de API en Google AI Studio
Visita Google AI Studio en tu navegador e inicia sesión con tu cuenta de Google. Haz clic en Create API Key, selecciona o crea un proyecto de Google Cloud y copia tu clave secreta.

Abre tu terminal y guarda la clave como variable de entorno con export GEMINI_API_KEY=<your-key>.
Nunca pases la clave como un parámetro ?key= en una URL; las query strings acaban en logs del servidor, historial del navegador y cachés de proxy. Si quieres explorar el modelo en un playground antes de escribir código, el tutorial de Google AI Studio cubre los modos Chat, Build y Stream; este artículo se queda en la API.
Para sistemas en producción, la autenticación cambia: Vertex AI (ahora parte de Gemini Enterprise Agent Platform) te da OAuth, roles de IAM y endpoints regionales en lugar de una clave de API en bruto. Todo en este tutorial usa claves de AI Studio porque son la vía más rápida para aprender, pero planifica la migración a Vertex antes de tocar datos reales de usuarios.
Instala google-genai y crea un cliente
Muchos tutoriales aún dicen instalar google-generativeai. Ese es el SDK antiguo, y no tiene Interactions API. Instala google-genai (versión 2.3.0 o posterior):
pip install -U google-genai
Una vez instalado, verifica que Python carga la librería e inicializa tu cliente sin errores:
from google import genai # reads GEMINI_API_KEY from the environment
client = genai.Client()
print("Client initialized successfully.")
Haz tu primera llamada a Interactions API
Cada petición a Interactions API crea un recurso Interaction, que registra todo el turno: tu entrada, los pensamientos del modelo, cualquier llamada a herramientas y la salida final. El SDK expone el texto final mediante la propiedad de conveniencia output_text, así que rara vez necesitarás recorrer los pasos manualmente.
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-3.8-flash",
input=(
"Write a pandas one-liner that adds a 7-day rolling average "
"revenue column per store_id to a DataFrame with columns "
"date, store_id, revenue. Reply with only the code, no explanation."
),
generation_config={"thinking_level": "medium"},
)
print(interaction.output_text)
usage = interaction.usage
print(
f"input={usage.total_input_tokens} | output={usage.total_output_tokens} | "
f"thinking={usage.total_thought_tokens} | total={usage.total_tokens}"
)
En mi equipo, el modelo respondió con un one-liner encadenado de pandas y esta línea de uso:

Esas cifras esconden la primera diferencia real respecto a 3.7. Ejecuté la misma tarea otra vez con un prompt más largo y sin restricción de salida, y 3.8 gastó 1.436 tokens de razonamiento frente a 870 tokens de salida. Con la restricción, gastó 1.515 frente a 42. El presupuesto de razonamiento apenas cambió, lo contrario que en 3.7, donde los mismos 2 prompts movían el razonamiento de 838 a 1.530.
En otras palabras, 3.8 decide cuánto pensar según la tarea, no según cómo la redactes, lo que encaja con la afirmación de Google de que el modelo razona y verifica más de forma deliberada. Los tokens de razonamiento se facturan a la tarifa de salida, así que en la llamada restringida, alrededor del 97% de los tokens facturados fueron razonamiento que no vi. Por eso existe la siguiente sección.
Haz streaming de la respuesta
Para interfaces de chat o cualquier cosa que alguien esté viendo, esperar varios segundos a la respuesta completa se siente lento. Pasa stream=True a client.interactions.create() e imprime los fragmentos a medida que llegan:
from google import genai
client = genai.Client()
stream = client.interactions.create(
model="gemini-3.8-flash",
input="Explain the difference between a JOIN and a correlated subquery in SQL.",
generation_config={"thinking_level": "low"},
stream=True,
)
for event in stream:
if event.event_type == "step.delta" and event.delta.type == "text":
print(event.delta.text, end="", flush=True)
print()
Cuando lo ejecuté, el modelo devolvió una respuesta larga y bien organizada con thinking_level: "low": una comparación conceptual, una tabla resumen y 2 ejemplos de SQL para encontrar el pedido más reciente de cada cliente, uno con join a una tabla derivada y otro con subconsulta correlacionada en la lista SELECT. Las primeras palabras aparecieron casi al instante, que es justo la idea.
Ese print() final está ahí por un motivo. Sin él, el último fragmento termina a mitad de línea y zsh muestra un % suelto antes del prompt, porque el stream se corta justo donde se detiene el texto del modelo. Además, las deltas solo llevan texto; si registras los recuentos de tokens por petición, léelos del evento final de completion en lugar de sumar fragmentos.
¿Cómo cambia thinking_level el coste y la calidad?
thinking_level determina cuánto razona Gemini 3.8 Flash antes de escribir la respuesta. Los tokens de razonamiento se facturan a la tarifa de salida de $3.75 por 1M, así que el nivel que elijas controla directamente coste y latencia, y Google afirma que 3.8 se apoya en esto a propósito: da pasos extra de razonamiento en tareas complejas y puede gastar más tokens en niveles de esfuerzo altos que 3.7.
Ejecuta un prompt en low, medium y high
La prueba es una condición de carrera en una función de reintento de pago enviada con el mismo prompt en los 3 niveles. Los bugs de concurrencia penalizan leer por encima, así que si los niveles difieren, aquí debería notarse. Si solo vas a ejecutar 1 bloque de código de este artículo, que sea este, porque las cifras convencen más que cualquier prosa.
import time
from google import genai
client = genai.Client()
BUGGY_CODE = '''
import threading
payment_attempts = {}
def retry_payment(order_id, charge_fn, max_retries=3):
"""Retry a failed payment up to max_retries times."""
if order_id not in payment_attempts:
payment_attempts[order_id] = 0
while payment_attempts[order_id] < max_retries:
success = charge_fn(order_id)
if success:
del payment_attempts[order_id]
return True
payment_attempts[order_id] += 1
return False
'''
PROMPT = (
"Two worker threads can call retry_payment() with the same order_id "
"at the same time. Identify the concurrency bug that can double-charge "
"a customer, and rewrite the function to fix it.\n\n" + BUGGY_CODE
)
for level in ["low", "medium", "high"]:
start = time.perf_counter()
interaction = client.interactions.create(
model="gemini-3.8-flash",
input=PROMPT,
generation_config={"thinking_level": level},
)
elapsed = time.perf_counter() - start
usage = interaction.usage
print(f"\n=== thinking_level: {level} | {elapsed:.1f}s ===")
print(interaction.output_text)
print(
f"input={usage.total_input_tokens} | output={usage.total_output_tokens} | "
f"thinking={usage.total_thought_tokens}"
)
Como contexto, la vulnerabilidad es un check-then-act no atómico sobre payment_attempts[order_id]. En concurrencia, 2 hilos pueden pasar ambos la condición del while y ambos llamar a charge_fn() antes de que ninguno incremente el contador. Arreglarlo implica envolver la lectura-comprobación-cobro-incremento en un lock por pedido, o usar una clave de idempotencia en la pasarela.
Comparando los resultados
Resultados de mis ejecuciones:
|
|
¿Detectó la race? |
¿Arreglo correcto? |
Diseño del arreglo |
Latencia |
Thinking tokens |
Tokens de salida |
Coste |
|
|
Sí |
Sí |
Locks por pedido + conjunto de completados |
7.8 s |
0 |
791 |
$0.0031 |
|
|
Sí |
Sí |
Locks por pedido + diccionario de estado por pedido |
16.6 s |
3,158 |
627 |
$0.0143 |
|
|
Sí |
Sí |
Registro por pedido (lock, intentos, completado) con ruta de fallo documentada |
25.5 s |
4,512 |
896 |
$0.0204 |
Los 3 niveles encontraron el doble cobro, y los 3 aplicaron locks por pedido, así pedidos no relacionados se ejecutan en paralelo. Esa segunda parte es lo más destacado si lo comparas en 3.7: allí, low envolvía todo en un lock global mantenido durante la llamada de red, y los locks por pedido solo aparecían en medium. En 3.8, low escribe ese mejor diseño con 0 tokens de razonamiento, en 7.8 segundos, por menos de un tercio de céntimo.
Entonces, ¿qué aportan ahora los niveles? Profundidad de auditoría. Este código tiene 4 modos de fallo distintos (el doble cobro, un KeyError por borrado concurrente, un recobro tras borrar el estado en la ruta de éxito y los incrementos no atómicos del contador), y high fue el único nivel que nombró los 4; low se dejó el recobro, y medium se dejó el contador.
high también fue el único que detalló la semántica de la ruta de fallo de su arreglo: cuando se agotan los reintentos, las llamadas posteriores devuelven False en lugar de cobrar de nuevo.
La columna de thinking es la afirmación de "3.8 trabaja más" de Google apareciendo en tu terminal. Con el mismo prompt en 3.7, medium pasó de 2.343 tokens de razonamiento a 3.158, y high de 2.217 a 4.512, aproximadamente el doble, y los tokens extra compraron un análisis más completo, no un veredicto distinto. La latencia subió en paralelo en esta ejecución (7.8 s, 16.6 s, 25.5 s), pero los tiempos de una sola ejecución oscilan, así que compara recuentos de tokens más que segundos.
Elige un valor por defecto y cuándo escalar
Esta es mi regla general para los niveles de razonamiento:
-
En 3.8,
lowgana más peso del que sugiere el valor por defecto de Google (medium): produjo un arreglo correcto y bien diseñado con 0 tokens de razonamiento, así que empieza ahí para todo lo que una persona lea antes de que importe (triaje, borradores, resúmenes, código que vas a revisar). -
Mantén
mediumdonde la salida se entrega sin que nadie la lea, porque el razonamiento extra trajo un análisis de modos de fallo más completo, y un pipeline sin revisión es justo donde dispara el modo que no listaste. -
Reserva
highpara salidas donde la propia ruta de fallo es el producto, como flujos de pago, migraciones o cualquier cosa que un revisor auditaría línea a línea. En mi ejecución, fue el único nivel que detectó los 4 bugs y documentó qué pasa tras agotar los reintentos.
Con un coste 6.6 veces mayor que low para high, ese intercambio se lee distinto a $3.75 por 1M de tokens de salida ahora frente a $7.50 después del 31 de diciembre de 2026, así que escala por petición y no de forma global.
Un salvavidas a tener en cuenta: Google afirma que 3.7 Flash sigue totalmente soportado para cargas donde la eficiencia manda. Si la diligencia extra de 3.8 cuesta más de lo que tu tarea necesita, quedarte en gemini-3.7-flash para esa carga es una opción soportada, no un apaño.
¿Cómo extraes datos estructurados de un PDF?
Gemini 3.8 Flash lee PDFs directamente como entrada, así que puedes enviar una factura o un informe y hacer preguntas sobre él. Usé una factura de proveedor de 1 página con número de factura, fechas, 4 partidas y un total.
Adjunta un PDF al prompt
Vamos a subir una factura PDF local usando la Files API. La Files API gestiona el almacenamiento y la caché de archivos en la infraestructura de Google:
from google import genai
client = genai.Client()
print("Uploading invoice...")
doc = client.files.upload(file="invoice_aug_2026.pdf")
print(f"File uploaded: {doc.uri}\n")
interaction = client.interactions.create(
model="gemini-3.8-flash",
input=[
{
"type": "text",
"text": "Extract the invoice number, total amount due, and due date.",
},
{"type": "document", "uri": doc.uri, "mime_type": doc.mime_type},
],
)
print(interaction.output_text)
La salida de mi factura:

Los 3 valores son correctos. La subida ocurre una vez y el archivo queda disponible para peticiones posteriores, lo que importa en cuanto haces más de 1 pregunta sobre el mismo documento. La respuesta llega como viñetas en markdown, perfecto para leer y no tan perfecto para llevar a un pipeline.
Fuerza JSON con un esquema de respuesta
Para obtener JSON en lugar de prosa, pasa un esquema en response_format. En Interactions API, es un parámetro de nivel superior; el ajuste responseMimeType dentro de generationConfig que verás en tutoriales antiguos pertenece al endpoint legado generateContent.
import json
from google import genai
from pydantic import BaseModel
client = genai.Client()
class Invoice(BaseModel):
invoice_number: str
total_due_usd: float
due_date: str # ISO 8601
doc = client.files.upload(file="invoice_aug_2026.pdf")
interaction = client.interactions.create(
model="gemini-3.8-flash",
input=[
{
"type": "text",
"text": "Extract the invoice number, total amount due in USD, and due date.",
},
{"type": "document", "uri": doc.uri, "mime_type": doc.mime_type},
],
response_format={
"type": "text",
"mime_type": "application/json",
"schema": Invoice.model_json_schema(),
},
)
invoice = json.loads(interaction.output_text)
print(invoice)
Esta fue la salida que recibí:

Tu clase Pydantic define los campos obligatorios y tipos de datos, mientras que model_json_schema() genera el esquema JSON que exige la API de Gemini. Una vez procesado, json.loads() convierte la salida del modelo a un diccionario estándar de Python. Desde aquí, los datos estructurados están listos para pasarse a una fila de DataFrame, grabarse en una base de datos o añadirse a una Google Sheet.
Haz una repregunta con previous_interaction_id
Para una segunda pregunta sobre el mismo documento, pasa el id de la primera interacción como previous_interaction_id. El servidor ya tiene el PDF y el primer intercambio, así que no envías ninguno de nuevo:
follow_up = client.interactions.create(
model="gemini-3.8-flash",
previous_interaction_id=interaction.id,
input="List each line item on the invoice with its amount.",
)
print(follow_up.output_text)

Devolvió las 4 partidas en orden, incluida la línea de compute repetida, sin comentar la repetición. Es el comportamiento correcto para lo que se preguntó; si quieres que marque anomalías, pídelo.
Por si sirve, 3.7 se comportó igual aquí, así que la diligencia extra de 3.8 aplica a su propio razonamiento, no a ofrecer auditorías que no pediste.
2 cosas a saber sobre esta llamada:
-
response_formatno se arrastró, porque tiene alcance de interacción, así que este turno devolvió prosa. -
Y las interacciones se almacenan por defecto (
store=True) durante 55 días en la capa de pago y 1 día en la gratuita;store=Falsehace la llamada sin estado, pero entonces no puedes encadenar unprevious_interaction_id.
¿Cómo añades function calling a Gemini 3.8 Flash?
El function calling en Gemini 3.8 Flash es un único bucle: el modelo pide una herramienta, tu código la ejecuta, envías el resultado de vuelta y el modelo escribe la respuesta final. En esta sección construimos ese bucle a mano.
Si quieres que Google ejecute el bucle por ti con agentes con varias herramientas hospedados, lee nuestro tutorial sobre "Managed Agents" en la Gemini API a continuación. Y si tu objetivo a largo plazo son los agentes, el curso Building AI Agents with Google ADK construye un asistente completo de soporte al cliente con las mismas primitivas.
Define una herramienta y ejecuta el bucle de interacción
La herramienta es lookup_exchange_rate(currency, date), respaldada por un pequeño diccionario en memoria, así que el ejemplo corre sin una API externa. La declaración es un esquema JSON. El modelo nunca ejecuta la función; devuelve un paso function_call pidiendo a tu código que:
import json
from google import genai
client = genai.Client()
# Local "data source" standing in for a real FX API
RATES = {
("USD", "2026-08-03"): 87.42,
("USD", "2026-08-10"): 87.15,
("EUR", "2026-08-03"): 95.08,
}
def lookup_exchange_rate(currency: str, date: str) -> dict:
rate = RATES.get((currency.upper(), date))
if rate is None:
return {"error": f"No rate for {currency} on {date}"}
return {"currency": currency.upper(), "date": date, "inr_rate": rate}
rate_tool = {
"type": "function",
"name": "lookup_exchange_rate",
"description": "Look up the INR exchange rate for a currency on a date (YYYY-MM-DD).",
"parameters": {
"type": "object",
"properties": {
"currency": {"type": "string", "description": "ISO code, e.g. USD"},
"date": {"type": "string", "description": "YYYY-MM-DD"},
},
"required": ["currency", "date"],
},
}
# Turn 1: the model decides to call the tool
interaction = client.interactions.create(
model="gemini-3.8-flash",
input="What was the USD to INR exchange rate on 2026-08-03?",
tools=[rate_tool],
)
fc_step = next(s for s in interaction.steps if s.type == "function_call")
print(f"Model requested: {fc_step.name}({fc_step.arguments})")
# Your code executes the function locally
result = lookup_exchange_rate(**fc_step.arguments)
# Turn 2: send the result back; tools must be re-specified (interaction-scoped)
final = client.interactions.create(
model="gemini-3.8-flash",
previous_interaction_id=interaction.id,
input=[
{
"type": "function_result",
"name": fc_step.name,
"call_id": fc_step.id,
"result": [{"type": "text", "text": json.dumps(result)}],
}
],
tools=[rate_tool],
)
print(final.output_text)
La salida:

Pasaron 3 cosas:
-
El turno 1 devolvió un paso
function_callcon nombre, argumentos estructurados y unid. -
Tu Python ejecutó la consulta.
-
El turno 2 envió un bloque
function_resultreferenciando esa llamada.
El parámetro tools se vuelve a pasar en el turno 2 por el mismo motivo que tuvimos que re-pasar response_format en la sección de PDF: previous_interaction_id arrastra historial, no configuración.
Errores comunes de function calling en Gemini 3.x
Si se rompe un bucle de herramientas, casi siempre es por 1 de 2 razones.
Primero, cada resultado debe mapear a su llamada. En Interactions API, eso es call_id y name en el bloque function_result; en la API legada generateContent, el FunctionResponse debe coincidir con el id y el name del FunctionCall anterior. Ninguno es opcional en Gemini 3.x.
Segundo, un error Malformed_Function_Call suele ocurrir cuando el modelo emite comentarios antes de la llamada a la herramienta. La guía para desarrolladores de 3.8 de Google dice que limpies el texto previo a la herramienta, formatees las instrucciones inline con \n\n y envuelvas notas de trabajo en una llamada de función dedicada en lugar de texto en bruto. Endurece la system instruction; no reintentes a ciegas.
¿Qué se rompe al pasar a Gemini 3.8 Flash?
Depende de dónde empieces.
-
Desde Gemini 3.7 Flash: nada. Cambia la cadena del modelo a
gemini-3.8-flash, y todos los fragmentos de este artículo funcionan sin tocar nada, ya que la superficie del API es idéntica. -
Desde Gemini 3.6 Flash o anteriores, la configuración del modelo requiere la misma auditoría de 15 minutos de antes.
Checklist de migración (desde 3.6 Flash o anteriores)
Revísalos en orden. Los puntos 1 a 3 causan 400 inmediatos; los puntos 4 y 5 causan problemas de calidad silenciosos.
-
Cambia el ID de modelo a
gemini-3.8-flash. -
Elimina parámetros de muestreo obsoletos:
temperature,top_pytop_kse ignoran o rechazan en Gemini 3.x, yfrequency_penalty,presence_penaltyycandidate_countlanzan un error activo de API. Borra los 6 de las configuraciones heredadas. -
Sustituye
thinking_budgetporthinking_level: usa sololow,mediumohigh. El valor minimal antiguo devuelve un error de validación. Enviarthinking_budgetythinking_levela la vez devuelve un 400. -
Elimina turnos del modelo pre-rellenados: quítalos de cualquier conversación que construyas y asegúrate de que el último turno de usuario tenga texto no vacío. Los historiales no pueden terminar con un turno del modelo.
-
Estandariza los flujos multi-turno: apóyate en
previous_interaction_iden lugar de reemitir el historial desde el cliente. Debes volver a especificar tustools,system_instructionygeneration_configen cada turno en el que importen.
Google publica la versión oficial en la documentación de modelos de la Gemini API, incluida una ruta automatizada si tu agente de coding admite skills. Léela tú mismo al menos una vez; una migración automática no te dirá por qué tu temperature=0.2 estaba ahí en primer lugar.
Errores que verás en producción
Estos son los 4 códigos de estado para los que merece la pena cablear handlers, y lo que significa cada uno en esta API:
|
Estado |
Causa típica |
Qué hacer |
|
|
Campos heredados remanentes: |
Corrige la petición; reintentar no sirve de nada |
|
|
|
Vuelve a exportar la clave; comprueba que está definida, sin restricciones para esta API y no está en git |
|
|
Límite de tasa en tu plan, a menudo durante trabajos por lotes de extracción |
Reintenta con backoff exponencial y jitter; considera repartir la carga |
|
|
Sobrecarga transitoria en el lado de Google |
Mismo backoff con jitter; alerta solo si persiste más de unos minutos |
2 cosas más:
-
Define timeouts explícitos en el cliente cuando combines
thinking_level: "high"con bucles largos de herramientas, porque una petición colgada es peor que una fallida, y la diligencia extra de 3.8 hace más probables las ejecuciones largas de razonamiento, no menos. -
Y registra
interaction.iden cada petición; es tu identificador para recuperar, depurar o borrar interacciones almacenadas más tarde.
Reflexiones finales
Todo en este artículo se reduce a 3 cambios. La Interactions API cambió la convención de llamada, thinking_level sustituyó a todos los mandos de muestreo que solías ajustar, y el estado en servidor mediante previous_interaction_id es lo que permitió que tanto la repregunta del PDF como el bucle de herramientas fueran turnos de una línea, en lugar de ejercicios de reenvío de historial. Gemini 3.8 Flash no cambió nada de esa superficie; lo que cambió es cuánto trabaja el modelo por dentro, por eso las mediciones de este artículo se tomaron de nuevo en 3.8 y no se arrastraron desde 3.7.
Antes de tomar mis recomendaciones de nivel como dogma, apunta el script de comparación a una tarea real de tu backlog; el nivel que gana en una carrera de reintentos de pago puede perder en tu generación de SQL.
Cuando una sola llamada a la API ya no te baste y quieras sistemas de IA en producción, nuestro Associate AI Engineer for Developers cubre todo el recorrido, y el Associate AI Engineer for Data Scientists hace lo mismo desde el lado de datos.
Preguntas frecuentes
¿Qué paquete de Python debo instalar para Gemini 3.8 Flash?
Instala google-genai con pip (pip install -U google-genai). La librería antigua google-generativeai es legado y falla cuando pasas argumentos de configuración de Gemini 3.x.
¿Gemini 3.8 Flash admite temperature, top_p o top_k?
No. Los parámetros de muestreo están obsoletos en Gemini 3.x, y 3.8 además lanza un error activo de API para frequency_penalty, presence_penalty y candidate_count. Controlas el comportamiento de salida con thinking_level.
¿Qué valores de thinking_level acepta Gemini 3.8 Flash?
Acepta low, medium (por defecto) y high. El valor minimal es inválido y devuelve un error de validación de la API.
¿Cómo factura Google los tokens de razonamiento en Gemini 3.8 Flash?
Google cuenta los tokens de razonamiento como tokens de salida estándar a $3.75 por 1M de tokens durante el periodo de precio de lanzamiento, que termina el 31 de diciembre de 2026. Google también indica que 3.8 puede gastar más tokens de razonamiento a niveles de esfuerzo altos, así que pagas por los ciclos extra de verificación.
¿Qué es Gemini 3.8 Flash Cyber y puedo usarlo?
Es una variante de ciberseguridad ajustada para descubrir vulnerabilidades y aplicar parches de forma automatizada. No está en la API pública; el acceso se limita a defensores aprobados a través del Fairwind Program de Google. Los desarrolladores en general usan gemini-3.8-flash.
Escribo y creo en Internet. Experto desarrollador de Google para Google Workspace, licenciado en Informática por la NMIMS y apasionado creador en el ámbito de la automatización y la IA generativa.


