Hydrogen llegó el 12 de noviembre como el modelo rápido de ejecución de la familia Gemini 4, el que Google construyó para la codificación de todos los días y el trabajo de agentes. Luego viene el giro que da forma a tu factura. Gemini 4 Hydrogen piensa en high por defecto. Un modelo vendido por su velocidad empieza cada trabajo en el segundo ajuste de razonamiento más profundo que tiene, y los tokens de pensamiento se cobran a la tarifa de salida.
Ese valor por defecto no es un error. Google reporta resultados fuertes en high, y mucho trabajo de agentes necesita razonamiento real antes de la primera llamada a una herramienta. Pero el trabajo de rutina paga el mismo peaje. Una revisión de enrutamiento, un resumen, una extracción corta y una dura sesión de depuración empiezan todos en high a menos que tu código diga otra cosa. Este tutorial pone ese selector en tus manos.
Lo que vas a construir o aprender
Vas a terminar con una pequeña función auxiliar en Python que llama a gemini-4-hydrogen en cualquiera de sus cuatro niveles, más la misma llamada en REST sin formato para pilas que no usan el SDK de Python. En el camino vas a aprender para qué sirve cada nivel, en las palabras que Google usa en su guía de pensamiento, y cómo probar una elección de nivel con números de tu propia carga de trabajo en vez de la costumbre.
También vas a aprender los tres datos que hacen que valga la pena ajustar este selector. Los tokens de pensamiento cuentan como tokens de salida para la facturación, a 7,50 dólares por millón de tokens de salida en el nivel estándar pagado. El pensamiento, la entrada y la salida toman todos de una sola ventana compartida de 1.048.576 tokens. Y un segmento de respuesta tiene un límite de 65.536 tokens de salida, pensamiento incluido, así que un nivel profundo y un límite bajo pueden gastar todo el presupuesto en pensamiento y no devolver ninguna respuesta.
Cuatro niveles, cuatro tirones de palanca. Cuanto más alto el tirón, más pensamiento gasta el modelo antes de responder. Ilustración: Dirty Static
Antes de empezar
Aprende primero los rechazos, porque Hydrogen rechaza dos ajustes que código más viejo aún puede traer. El nivel minimal no es compatible con ningún modelo Gemini 4, Hydrogen incluido, y una solicitud que lo pide falla. El viejo control thinking_budget pertenece a Gemini 2.5 y modelos anteriores. La cobertura de las notas de migración de Hydrogen y la guía de pensamiento coinciden en que Hydrogen lo rechaza, y enviar thinking_level y thinking_budget juntos devuelve un error en modelos Gemini 3 y posteriores en todo caso. Un selector a la vez, y en Hydrogen ese selector es el nivel.
Una nota de alcance. Este tutorial sigue la forma del ajuste en la API de Gemini, donde el campo se ubica dentro de thinkingConfig. Google Cloud documenta los mismos niveles para su plataforma empresarial, con los mismos valores y el mismo valor por defecto para Hydrogen, y la forma en Python ahí usa thinking_config de la misma manera. Los nombres de nivel, los valores por defecto y los rechazos en este tutorial se revisaron contra esa guía de pensamiento de Google el 13 de noviembre de 2026. Aquí no se afirma ninguna llamada en vivo con una clave real.
| Nivel | Guía de Google en breve | Trabajo que le queda bien |
|---|---|---|
low | Menos tokens de pensamiento, respuestas más rápidas, baja complejidad de tarea | Enrutamiento, clasificación, resúmenes cortos, extracción |
medium | Equilibra calidad de razonamiento y latencia, complejidad moderada | Codificación general, preguntas sobre documentos, trabajo interactivo |
high | Razonamiento profundo, resolución de problemas en varios pasos, revisiones formales de código, uso de herramientas en varios turnos. Valor por defecto en Hydrogen | Ejecuciones de agentes, depuración dura, análisis complejo |
xhigh | Capacidad máxima de pensamiento, para las matemáticas más duras, ciencia, revisiones formales y trabajo de software de largo alcance | Los pocos trabajos donde high se queda visiblemente corto |
Paso 1: Instala el SDK y ajusta tu clave
Acción: instala el SDK Google Gen AI, crea una clave en Google AI Studio, y guárdala en una variable de entorno. Mantén el valor real fuera del código, los registros y los chats, y usa la forma de marcador en cada nota que compartas.
pip install --upgrade google-genai
export GEMINI_API_KEY="your-key-here"
Resultado esperado: la instalación termina y la variable queda ajustada para esta sesión de terminal. El cliente del SDK en los pasos siguientes lee esa variable por su cuenta, así que ningún paso de este tutorial pega una clave en una solicitud a mano, aparte del encabezado REST en el Paso 6, que lee la misma variable.
Paso 2: Haz una primera llamada y lee el conteo de pensamiento
Acción: ejecuta esta llamada sin ningún ajuste de pensamiento. Este es tu punto de partida, y en Hydrogen el punto de partida significa high.
from google import genai
client = genai.Client()
response = client.models.generate_content(
model="gemini-4-hydrogen",
contents="Explain in two sentences why a queue forms at a single open checkout.",
)
print(response.text)
print(response.usage_metadata)
Resultado esperado: la respuesta se imprime, y el bloque de uso se imprime con ella. Busca el conteo de tokens de pensamiento en ese bloque. Ese conteo es la parte de la factura que la mayoría de los equipos nunca mira, y es el número que cada paso posterior trata de controlar. Google también advierte que un modelo puede responder algunas solicitudes simples sin ninguna parte de pensamiento, aun con el pensamiento activado. El código que lee el uso o los resúmenes de pensamiento debe manejar un conteo faltante o vacío sin fallar.
Paso 3: Ajusta bajo para trabajo de rutina rápido
Acción: suma una configuración de pensamiento con el nivel ajustado en LOW. La forma en Python nombra las clases de configuración del SDK, y los valores de nivel son los miembros de enumeración que la guía de Google lista, LOW, MEDIUM, HIGH y XHIGH.
from google import genai
from google.genai import types
client = genai.Client()
response = client.models.generate_content(
model="gemini-4-hydrogen",
contents="Classify this ticket as billing, shipping or product help: My invoice shows the wrong total.",
config=types.GenerateContentConfig(
thinking_config=types.ThinkingConfig(
thinking_level=types.ThinkingLevel.LOW
)
),
)
print(response.text)
print(response.usage_metadata)
Resultado esperado: la misma forma de respuesta vuelve, más rápido, con un conteo de tokens de pensamiento más bajo que el punto de partida en una solicitud de este tamaño. Este es el nivel para trabajo de alto volumen donde cada llamada es simple y el costo de un error raro es bajo. Si el trabajo es un juicio fijo con un conjunto fijo de respuestas, piensa si necesita un modelo de chat en absoluto. Nuestro tutorial sobre la API Gemini Decisions cubre esa herramienta más estrecha.
Paso 4: Ajusta medio y alto por tarea, no por costumbre
Acción: envuelve la llamada en una pequeña función auxiliar que toma el nivel como argumento. Tu código puede entonces enrutar cada clase de tarea a un nivel en un solo lugar, donde un cambio es fácil de revisar.
from google import genai
from google.genai import types
client = genai.Client()
def ask(prompt, level):
return client.models.generate_content(
model="gemini-4-hydrogen",
contents=prompt,
config=types.GenerateContentConfig(
thinking_config=types.ThinkingConfig(thinking_level=level)
),
)
draft = ask("Draft a commit message for a fix to a login timeout.", types.ThinkingLevel.MEDIUM)
review = ask("Review this function for race conditions and list each one you find.", types.ThinkingLevel.HIGH)
print(draft.text)
print(review.text)
Resultado esperado: ambas llamadas vuelven, y los bloques de uso muestran la brecha entre los niveles en solicitudes reales de tu propio trabajo. medium es el punto de equilibrio que Google describe, adecuado para complejidad moderada. high se gana su costo en problemas de varios pasos, revisiones formales de código y uso de herramientas en varios turnos. Una nota sobre chats largos aplica en ambos niveles. Las firmas de pensamiento, el registro cifrado del estado de razonamiento que Google usa para mantener el contexto entre turnos, viajan con la respuesta. Si usas sesiones de chat o sumas respuestas completas a tu historial, el SDK las maneja por ti. Si reconstruyes el historial a mano, devuelve las partes recibidas completas, o los turnos posteriores pueden perder el hilo.
Paso 5: Reserva muy alto para los trabajos más duros
Acción: ajusta el nivel en XHIGH solo para un trabajo donde high ya mostró una falla real, como una prueba, un duro problema de ciencia o una larga tarea de software con muchos pasos ligados.
from google import genai
from google.genai import types
client = genai.Client()
response = client.models.generate_content(
model="gemini-4-hydrogen",
contents="Prove that the sum of the first n odd numbers equals n squared, and check each step.",
config=types.GenerateContentConfig(
thinking_config=types.ThinkingConfig(
thinking_level=types.ThinkingLevel.XHIGH
)
),
)
print(response.text)
print(response.usage_metadata)
Resultado esperado: la respuesta tarda más en empezar y el conteo de tokens de pensamiento sube bien por encima de la ejecución en high de una solicitud parecida. Ese intercambio es el punto del nivel, y también es la razón por la que se mantiene raro. xhigh es nuevo con Hydrogen. Ningún otro modelo Gemini 4 en la tabla de Google lo ofrece, y Carbon y Argon se detienen en high. Trátalo como una herramienta de especialista, no como un nuevo valor por defecto con un nombre mejor.
Paso 6: Ajusta el mismo nivel en REST sin formato
Acción: para pilas sin el SDK de Python, envía el nivel dentro de generationConfig en el cuerpo de la solicitud. El nombre del campo en REST es thinkingConfig y el campo de nivel dentro de él es thinkingLevel, escrito como una cadena simple.
curl -s "https://generativelanguage.googleapis.com/v1beta/models/gemini-4-hydrogen:generateContent" -H "Content-Type: application/json" -H "x-goog-api-key: $GEMINI_API_KEY" -d '{"contents": [{"parts": [{"text": "Summarize this release note in one line: The server now retries failed uploads twice."}]}], "generationConfig": {"thinkingConfig": {"thinkingLevel": "low"}}}'
Resultado esperado: una respuesta JSON vuelve con el texto de respuesta y un bloque de uso que trae el conteo de tokens de pensamiento bajo su nombre en REST. Cambia solo la cadena para moverte entre low, medium, high y xhigh. Si un cuerpo de solicitud aún trae un campo thinkingBudget de código de la era Gemini 2.5, quítalo antes de depurar cualquier otra cosa. Ese campo es la razón más común por la que una solicitud sana de Hydrogen vuelve como un error.
Paso 7: Prueba el nivel más barato que aún pasa
Acción: construye un pequeño conjunto de pruebas de tu propio trabajo, diez a veinte solicitudes donde ya sabes cómo se ve una buena respuesta. Ejecuta cada solicitud en low, medium y high, y en xhigh solo para los casos duros. Califica cada respuesta contra tu buen resultado conocido, y registra el conteo de tokens de pensamiento junto a la calificación.
Resultado esperado: una tabla que puedes defender. La mayoría de las solicitudes de rutina pasan en low o medium, y el ahorro contra el valor por defecto high es visible en los conteos. Un pequeño conjunto de solicitudes va a necesitar high, y esas solicitudes definen tus reglas de enrutamiento en el Paso 4. Guarda el conjunto de pruebas y ejecútalo de nuevo cuando Google actualice el modelo, porque un nivel que pasó el mes pasado es una afirmación sobre una versión del modelo, no una ley de la naturaleza.
Verificación
Ejecuta estas revisiones y registra lo que ves. Una llamada sin nivel ajustado se comporta como high, y su uso muestra un conteo de pensamiento en cualquier solicitud que necesita pensamiento. La misma solicitud en low vuelve con un conteo más bajo y un inicio más rápido. La llamada REST del Paso 6 devuelve la misma forma de respuesta que las llamadas en Python. Tu tabla del conjunto de pruebas del Paso 7 nombra, para cada clase de tarea que ejecutas, el nivel más bajo que pasó, y tu código de enrutamiento usa esos niveles y ningún otro.
Termina con la revisión del dinero. Toma una solicitud de alto volumen, pon precio a sus tokens de pensamiento a 7,50 dólares por millón, una vez con el conteo high y una vez con el conteo más bajo que pasa en tu conjunto de pruebas. Multiplica la brecha por tu volumen mensual de llamadas. Esa cifra es lo que este ajuste vale para ti, dicho en tus propios números.
Solución de problemas
| Problema | Causa probable | Corrección |
|---|---|---|
| La solicitud devuelve un error 400 que nombra el nivel de pensamiento | El nivel estaba ajustado en minimal, que ningún modelo Gemini 4 admite | Usa low como piso en Hydrogen y quita cualquier valor minimal dejado por código de la era Gemini 3 |
| La solicitud devuelve un error tras un cambio desde Gemini 2.5 | El cuerpo aún trae thinking_budget o thinkingBudget, o trae ese campo junto al nivel | Quita el campo de presupuesto y ajusta el nivel solo, como en los Pasos 3 y 6 |
| La respuesta está vacía y la razón de fin habla de un límite de tokens | El pensamiento gastó todo el límite de salida antes de que se produjera texto de respuesta | Sube el límite de tokens de salida para esa llamada, hasta el límite de segmento de 65.536, o baja el nivel para esa solicitud |
Las ejecuciones en xhigh se sienten lentas y la factura sube sin mejores respuestas | El nivel está ajustado en solicitudes que no lo necesitan, y el modelo piensa de más en trabajo simple | Devuelve esos sitios de llamada a high o más bajo y reserva xhigh para trabajos donde high ha fallado en tu conjunto de pruebas |
| Ningún resumen de pensamiento ni conteo de pensamiento aparece en una solicitud simple | El modelo respondió una solicitud de baja complejidad sin partes de pensamiento, lo que Google dice que puede pasar | Trata un conteo faltante como cero para el registro y nunca hagas fallar una solicitud porque los campos de pensamiento están vacíos |
| Cambiar el nivel parece no cambiar nada en un chat largo | El historial reconstruido dejó caer las firmas de pensamiento que traen el estado de razonamiento entre turnos | Usa una sesión de chat, o suma objetos de respuesta completos al historial, para que el SDK devuelva las firmas por ti |
Próximos pasos
Conecta los niveles en los lugares donde el trabajo entra a tu sistema. Da a cada fila, ruta o herramienta un nivel con nombre en la configuración, para que un cambio sea una edición de configuración con un rastro de revisión, y no una cacería por los sitios de llamada. Luego revisa la división misma una vez al mes. Los trabajos que se reducen a un juicio fijo pueden dejar el modelo de chat por completo, como muestra el tutorial de la API Decisions enlazado en el Paso 3. Los trabajos que crecen en pasos y llamadas a herramientas pueden ganarse high más seguido que al principio.
El hábito que vale la pena mantener es simple de decir y fácil de saltar. Nunca dejes que un valor por defecto elija tu presupuesto de razonamiento por ti. Hydrogen empieza en high porque Google eligió un ajuste general seguro. Tu carga de trabajo no es general, y ahora tu código puede decirlo, un nivel por trabajo.
Datos, valores de nivel, valores por defecto y ajustes revisados contra la guía de pensamiento de Google y la cobertura del lanzamiento de Hydrogen el 13 de noviembre de 2026. Los precios son las tarifas del nivel estándar pagado de Google y pueden cambiar. Este procedimiento se verificó contra esos documentos y no se presenta como una prueba personal con una clave en vivo.
Fuentes
- Google Cloud, Thinking, documentación de Gemini Enterprise Agent Platform, valores de nivel, valores por defecto por modelo, firmas de pensamiento y notas de precios, revisado el 13 de noviembre de 2026: https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/thinking
- Google, publicación de lanzamiento de Gemini 4 Hydrogen, vía la cobertura de Yoopya con los datos de precios, niveles y contexto, 13 de noviembre de 2026: https://www.yoopya.com/technology/artificial-intelligence/gemini-4-hydrogen-google-ai
- Hesham Saad, Gemini 4 Hydrogen, precios, niveles de pensamiento y notas de migración, 12 de noviembre de 2026: https://heshamsaad.com/en/gemini-4-hydrogen/
- Smteon, Gemini 4 Hydrogen, características, niveles de pensamiento y forma en REST, 13 de noviembre de 2026: https://smteon.com/blog/gemini-4-hydrogen
- Ilustraciones del héroe y de las palancas: Dirty Static
FIN DE LA TRANSMISIÓN
Mantén la curiosidad. Cuestiónalo todo.
