DEV Community

Cover image for Cómo usar la API de Gemini 4 Neon
Roobia
Roobia

Posted on Originally published at apidog.com

Cómo usar la API de Gemini 4 Neon

Cómo usar la API de Gemini 4 Neon: solicitudes, migración, salidas largas y costes

La API de Gemini 4 Neon utiliza el ID de modelo gemini-4-neon. Se invoca con un POST a https://generativelanguage.googleapis.com/v1beta/interactions, con tu clave en la cabecera x-goog-api-key y model más input en el cuerpo JSON. Funciona solo en el nivel de pago, a 3 $ por millón de tokens de entrada y 15 $ por millón de tokens de salida, y su nivel de razonamiento predeterminado es high.

Prueba Apidog hoy

Esta guía cubre lo que diferencia a Neon: la configuración del nivel de pago, cómo migrar desde otro modelo de Gemini 4, salidas de más de 64K tokens, cómo combinar Neon con Hydrogen y cómo mantener la factura bajo control. Todos los nombres de campos provienen de la documentación de Google.

¿Qué necesitas antes de tu primera llamada a la API de Gemini 4 Neon?

Necesitas una clave de la API de Gemini en un proyecto con facturación activada, el ID de modelo gemini-4-neon y el endpoint de Interactions. Google lanzó Neon el 18 de noviembre de 2026 como el modelo intermedio de la familia Gemini 4, entre Hydrogen y Carbon.

Elemento Valor
ID de modelo gemini-4-neon
Endpoint POST /v1beta/interactions en generativelanguage.googleapis.com
Cabecera de autenticación x-goog-api-key: $GEMINI_API_KEY
APIs API de Interactions y generateContent
Niveles de razonamiento low, medium, high (predeterminado), xhigh
Ventana de contexto 1.048.576 tokens, compartidos entre entrada, razonamiento y salida
Salida por ciclo síncrono 65.536 tokens
Decodificación larga Hasta 1.048.576 tokens menos tu entrada
Nivel gratuito No
Precio de pago 3,00 $ / 1M de entrada, 15,00 $ / 1M de salida (razonamiento incluido)
Entrada en caché 0,15 $ / 1M mediante caché implícita

Para PDFs, llamadas a funciones y streaming, la estructura de las solicitudes coincide con nuestra guía de la API de Gemini 4 Hydrogen; solo tienes que cambiar el ID de modelo.

Imagen

¿Cómo obtener una clave de la API de Gemini que funcione con Neon?

Neon no está disponible en el nivel gratuito, por lo que una clave por sí sola no basta. El proyecto asociado necesita facturación activada.

  1. Abre la página de claves de API en Google AI Studio y crea una clave, o reutiliza una que ya tengas.
  2. Asegúrate de que el proyecto de la clave esté en el nivel de pago. La guía de Google lo dice claramente: «Neon está disponible solo en el nivel de pago (no en el nivel gratuito)».
  3. Exporta la clave: export GEMINI_API_KEY="YOUR_API_KEY". Los SDK de Google GenAI la leen automáticamente.
  4. Consulta los límites de tarifas de tu nivel de pago en la página de límites de tarifas antes de planificar un lote grande.

¿Cómo enviar tu primera solicitud a la API de Gemini 4 Neon?

Envía model e input al endpoint de Interactions. Esta es la estructura del inicio rápido de Google:

curl "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "model": "gemini-4-neon",
    "input": "Review this Go handler for missing error checks and suggest fixes."
  }'
Enter fullscreen mode Exit fullscreen mode

La misma llamada con el SDK de Python (pip install -U google-genai):

from google import genai

client = genai.Client()  # reads GEMINI_API_KEY

interaction = client.interactions.create(
    model="gemini-4-neon",
    input="Review this Go handler for missing error checks and suggest fixes.",
)

print(interaction.output_text)
print(interaction.usage)
Enter fullscreen mode Exit fullscreen mode

Lee usage en cada respuesta mientras haces pruebas: los tokens de razonamiento se facturan a la tarifa de salida de 15 $, así que la cantidad de razonamiento es donde se acumula el coste.

Estos fragmentos siguen la guía de Google. No los ejecutamos para este artículo, así que verifica la estructura de la respuesta con tu propia primera llamada.

¿Qué cambia al migrar desde Hydrogen o Carbon?

Si ya utilizas otro modelo de Gemini 4, el cambio no requiere modificar el esquema de las solicitudes. Cambia la cadena de model y verifica tres cosas:

Verificación Neon Hydrogen Carbon y Argon
Nivel de razonamiento predeterminado high high medium
Nivel máximo xhigh xhigh high
Entrada / salida por 1M 3 $ / 15 $ 1,50 $ / 7,50 $ Ver Precios de Carbon

Si vienes de Carbon o Argon, el salto predeterminado de medium a high implica más tokens de razonamiento con el mismo prompt. Define thinking_level explícitamente si quieres conservar el comportamiento anterior:

interaction = client.interactions.create(
    model="gemini-4-neon",
    input="Audit this payment retry queue for race conditions.",
    generation_config={"thinking_level": "medium"},
)
Enter fullscreen mode Exit fullscreen mode

Si vienes de Gemini 3.8 Flash o una versión anterior, la lista es más larga. Según la lista de comprobación de migración de Google:

  • Aumenta los límites bajos de salida. max_output_tokens cubre el razonamiento y la respuesta juntos. Elimina los límites fijados en el código, como 8.192, o sube el límite a 65.536, y reduce el nivel de razonamiento si necesitas gastar menos.
  • Elimina minimal. Neon lo rechaza con un error.
  • Elimina los parámetros de muestreo. El servidor ignora los valores dentro del rango de temperature, top_p y top_k; los valores fuera de rango devuelven un 400.
  • Deja la caché explícita. Neon no admite cachedContents ni caches.create, así que elimina los campos cached_content.
  • Declara las herramientas de forma nativa. Solicitar llamadas a herramientas en JSON crudo sin herramientas declaradas puede devolver MALFORMED_FUNCTION_CALL. Usa llamadas a funciones o salidas estructuradas.

¿Cómo obtener más de 64K tokens de salida de Neon?

Una solicitud síncrona se detiene en 65.536 tokens, con o sin streaming. Para salidas más largas, como una especificación de migración completa junto con su suite de pruebas, define background en true y sube max_output_tokens por encima de 65.536. Los servidores de Google seguirán generando en ciclos de 64K tokens hasta alcanzar tu límite.

Gemini 4 Neon long decode: a background request with max_output_tokens 262,144 runs as four 65,536-token hops on Google's servers while the client polls GET /v1beta/interactions/{id} until status leaves in_progress, then joins the text from every model_output step

Inicia el trabajo y conserva su id:

export ID=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-4-neon",
    "input": "Generate a complete multi-module migration specification and test suite for this service.",
    "background": true,
    "generation_config": {
      "max_output_tokens": 262144,
      "thinking_level": "high"
    }
  }' | jq -r '.id')
Enter fullscreen mode Exit fullscreen mode

Luego sondea hasta que termine y une el texto de cada ciclo (Python, con el ID que exportaste):

import os, time

interaction = client.interactions.get(id=os.environ["ID"])
while interaction.status in ("in_progress", "queued"):
    time.sleep(5)
    interaction = client.interactions.get(id=interaction.id)

text = "".join(
    c.text
    for step in interaction.steps if step.type == "model_output"
    for c in step.content if c.type == "text"
)
Enter fullscreen mode Exit fullscreen mode

Tres reglas de la guía de Google evitan que esto salga mal:

  1. Si defines background sin max_output_tokens, el servidor se detiene en 65.536 tokens.
  2. El límite puede subir hasta 1.048.576 menos tus tokens de entrada. Google sugiere 131.072 o 262.144 para trabajos largos de varios pasos.
  3. Los prompts exigentes pueden tardar varios minutos. Usa el modo en segundo plano o configura los tiempos de espera de tu cliente HTTP en al menos 15 minutos.

Si prefieres no almacenar las interacciones del lado de Google, la guía de decodificación larga también documenta la continuación del lado del cliente en los SDK más recientes.

¿Cómo combinar Neon con Hydrogen?

Usa Neon para el criterio y Hydrogen para el volumen. Neon planifica o revisa un flujo de trabajo y luego pasas su id de interacción como previous_interaction_id a una llamada a gemini-4-hydrogen que ejecuta un solo paso. La guía para desarrolladores de Cloud de Google muestra el patrón:

plan = client.interactions.create(
    model="gemini-4-neon",
    input="Design a 3-step plan to migrate our REST order service to gRPC in Go.",
    store=True,
)

step = client.interactions.create(
    model="gemini-4-hydrogen",
    input="Implement step 1 (.proto service definition) from the plan.",
    previous_interaction_id=plan.id,
)
print(step.output_text)
Enter fullscreen mode Exit fullscreen mode

Gemini 4 Neon as planner and Gemini 4 Hydrogen as executor: Neon writes the plan at $15 per million output tokens, then each step runs on Hydrogen at $7.50 per million through previous_interaction_id, with Neon reviewing the final result

Cada token de salida que escribe Hydrogen en lugar de Neon cuesta la mitad. Nuestra guía del orquestador de Gemini 4 Hydrogen recorre el mismo bucle con Carbon como planificador.

¿Cómo reducir los costes de la API de Gemini 4 Neon?

Cuatro palancas, en el orden en que suelen dar resultados:

  1. Elige el nivel de razonamiento más bajo que supere tus pruebas. El consejo de Google es ejecutar tus evaluaciones en los cuatro niveles con un max_output_tokens alto y luego elegir el thinking_level más bajo que cumpla tu barra de calidad.
  2. Reutiliza prompts largos. La caché implícita se activa por defecto en prompts de al menos 4.096 tokens y reduce la entrada en caché un 95 %, de 3,00 $ a 0,15 $ por millón. Mantén la parte larga y estable de tu prompt (texto del sistema, documentación, esquemas) al principio.
  3. Delega la ejecución en Hydrogen. Consulta el patrón de emparejamiento anterior.
  4. Cuenta todo. Google factura cada token que procesa el modelo, incluidos los tokens de razonamiento y las instrucciones internas añadidas cuando usas grounding. El grounding con Google Search también se factura por consulta.

Una comprobación rápida: una llamada con 20.000 tokens de entrada y 8.000 tokens de salida (razonamiento incluido) cuesta 0,06 $ de entrada y 0,12 $ de salida, es decir, 0,18 $ al precio de lista.

Deja que tu agente de código compare Neon y Hydrogen con Apidog CLI

¿Vale Neon el doble del precio de Hydrogen con tus prompts? Deja que tu agente de código (Claude Code, Codex, Cursor) construya un caso de prueba y lo ejecute contra ambos modelos con Apidog CLI.

Configúralo una vez:

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com   # pick your agent when prompted
Enter fullscreen mode Exit fullscreen mode

Luego dale a tu agente un único prompt:

In Apidog project <projectId>, create an environment "gemini" with base URL
https://generativelanguage.googleapis.com and variables GEMINI_API_KEY,
MODEL (default "gemini-4-hydrogen") and THINKING (default "high"). Add an
endpoint for POST /v1beta/interactions with the x-goog-api-key header from
GEMINI_API_KEY. Create a test case that sends model {{MODEL}}, our code-review
prompt and generation_config.thinking_level {{THINKING}}, and asserts: HTTP 200,
status is "completed", a non-empty model_output step, and usage.total_tokens
exists. Run it for gemini-4-hydrogen and gemini-4-neon, then compare
usage.total_thought_tokens and usage.total_output_tokens.
Enter fullscreen mode Exit fullscreen mode

El agente lee el esquema de cada payload y valida su JSON antes de escribir nada:

apidog environment create gemini --project <projectId> --base-url https://generativelanguage.googleapis.com
apidog cli-schema get endpoint-create
apidog cli-schema validate endpoint-create --file endpoint.json
apidog endpoint create --project <projectId> --file endpoint.json
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <projectId> --file case.json
apidog run --test-case <caseId> --project <projectId> -e <envId> --env-var "MODEL=gemini-4-hydrogen" -r cli,json
apidog run --test-case <caseId> --project <projectId> -e <envId> --env-var "MODEL=gemini-4-neon" -r cli,json
Enter fullscreen mode Exit fullscreen mode

Multiplica los tokens de cada ejecución por el precio del modelo y tendrás un coste real por tarea para tu prompt, no un promedio de nota de lanzamiento. Añade --upload-report para ver la ejecución en la app de Apidog, o cambia -r cli,json por -r junit para integrar la misma comprobación en CI. La guía de CI/CD de Apidog CLI muestra el pipeline, y Apidog CLI en Claude Code cubre la configuración del agente. El plan gratuito de Apidog cubre hasta 4 usuarios.

FAQ

¿Cuál es el ID de modelo de Gemini 4 Neon? gemini-4-neon. Funciona tanto con la API de Interactions como con generateContent.

¿Es gratuita la API de Gemini 4 Neon? No. Neon está disponible solo en el nivel de pago de la API de Gemini, a 3 $ por millón de tokens de entrada y 15 $ por millón de tokens de salida. Los suscriptores de Google AI Pro y Ultra pueden probarlo en el chat de AI Studio.

¿Funciona mi código de Hydrogen con Neon? Sí. Google afirma que el cambio entre modelos de Gemini 4 no requiere modificaciones en el esquema de las solicitudes. Actualiza la cadena de model y decide si quieres el nivel de razonamiento predeterminado high.

¿Cuál es la salida máxima de la API de Gemini 4 Neon? 65.536 tokens por solicitud síncrona. Con background definido en true y un max_output_tokens mayor, Neon puede generar hasta la ventana de 1.048.576 tokens menos tu entrada.

¿Admite Gemini 4 Neon temperature? No. El servidor ignora los valores dentro del rango de temperature, top_p y top_k y devuelve un 400 para los valores fuera de rango. Usa thinking_level para intercambiar calidad por velocidad y coste.

¿Admite Neon la caché de contexto explícita? No. Elimina cached_content de tus solicitudes. La caché implícita se sigue aplicando automáticamente a los prompts de 4.096 tokens o más, con un descuento del 95 % en la entrada en caché.

Top comments (0)