Gemini 4 Argon API: un chat en Python con streaming nativo

Una conversación con la API de Gemini 4 Argon utiliza contenido nativo de Gemini: contents, roles y parts. La primera solicitud es pequeña. Lo más difícil es conservar correctamente la respuesta antes de enviar una pregunta de seguimiento. Reconstruir un turno del modelo a partir del texto visible puede hacer que se pierda contenido firmado; añadir un mensaje de carga vacío al historial puede invalidar la siguiente solicitud.

Este tutorial utiliza la biblioteca estándar de Python y el endpoint nativo de SeedRouter. Cubre el chat de texto y el streaming. La referencia API completa describe toda la especificación de parámetros; este artículo sigue una solicitud hasta convertirla en una conversación utilizable.

Antes de la primera solicitud

Necesitas Python 3, una clave API de SeedRouter y saldo suficiente en tu cuenta. Guarda la clave en una variable de entorno llamada SEEDROUTER_API_KEY; no la incluyas en el código fuente ni en un paquete enviado al navegador. Cada mensaje que envíes puede generar cargos. El ejemplo no reintenta solicitudes automáticamente ni realiza llamadas de continuación.

El ID del modelo es gemini-4-argon, y el modelo se indica en la ruta del endpoint. Google documenta este formato en su guía de generación nativa. SeedRouter utiliza autenticación Bearer, como se muestra a continuación.

Enviar una solicitud a la API de Gemini 4 Argon

curl --no-buffer --fail-with-body \
  'https://api.seedrouter.ai/v1beta/models/gemini-4-argon:streamGenerateContent?alt=sse' \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"contents":[{"role":"user","parts":[{"text":"Explain a mutex in one sentence."}]}],"generationConfig":{"maxOutputTokens":1024,"thinkingConfig":{"thinkingLevel":"low"}}}'

La respuesta es una secuencia de eventos enviados por el servidor, no un único documento JSON. Cada evento data: contiene JSON nativo de Gemini. El texto visible aparece en candidates[].content.parts[].text; algunas partes contienen razonamiento o firmas en su lugar. usageMetadata puede llegar por separado del texto, así que lee hasta el último evento antes de considerar completa la respuesta.

Este presupuesto de salida deliberadamente pequeño sirve para una prueba básica de funcionamiento. El razonamiento también consume el presupuesto, por lo que la respuesta puede quedar incompleta. Auméntalo de forma deliberada para tareas más exigentes; no conviertas una respuesta incompleta en un bucle de reintentos invisible.

Ejecutar una conversación de dos turnos en Python

Descarga el ejemplo completo de Python, guárdalo localmente y ejecuta:

python3 gemini-4-argon-chat.py

Pregunta «Explain a mutex in one sentence» y después «Give a Python example of that idea». El script espera tu entrada antes de cada solicitud. Introduce una línea vacía para terminar. Su regla principal para el historial es:

user = {"role": "user", "parts": [{"text": text}]}
body = {"contents": [*history, user]}
history = [*history, user, {"role": "model", "parts": parts}]

El script descargable también proporciona los ajustes de generación, analiza las tramas SSE, imprime solo el texto que no es razonamiento y guarda el historial únicamente después de un motivo de finalización STOP con parts no vacías. Un error de API, un flujo interrumpido o una respuesta vacía deja intacto el historial anterior. No vuelve a enviar un mensaje de forma silenciosa.

El pequeño fragmento anterior explica la estructura de los datos; ejecuta el archivo completo para disponer de todo el tratamiento de solicitudes. Para respuestas sin streaming, la operación correspondiente es generateContent, y los ejemplos de referencia muestran cURL, Python, Node.js y Go.

Conservar las parts nativas, no el indicador de carga

La segunda solicitud debe contener tres turnos reales: el primer mensaje del usuario, la respuesta completada del modelo y el segundo mensaje del usuario. El texto «Pensando…» de la interfaz no es otro turno del modelo.

Un error como contents.3.parts: Too small: expected array to have >=1 items significa que la cuarta entrada de contenido tiene un array parts vacío. El índice empieza en cero. Revisa cómo se construye el historial antes de cambiar el prompt o el modelo. Un indicador de carga pertenece al estado de la interfaz; nunca debe convertirse en { "role": "model", "parts": [] } dentro de la solicitud.

Conserva cada parte devuelta en su orden, incluido thoughtSignature y las partes marcadas como razonamiento, aunque la interfaz las oculte. La guía de firmas de razonamiento de Google explica por qué estos campos opacos deben mantenerse en los turnos posteriores. No edites, inventes ni reconstruyas una firma. Guarda el historial nativo por separado del texto que muestras en la interfaz.

El mismo principio de conservación se aplica a las conversaciones con herramientas, pero ejecutar una herramienta y devolver su resultado requiere un bucle de aplicación más amplio. Este ejemplo de texto no implementa ese bucle y no debe presentarse como un agente de programación completo.

Leer el uso y gestionar la detención

En las solicitudes directas, conserva los últimos valores de uso comunicados por el flujo. No sumes las instantáneas acumulativas que se repiten dentro de la misma solicitud. La entrada ordinaria es promptTokenCount menos cachedContentTokenCount; la salida facturada incluye tanto candidatesTokenCount como thoughtsTokenCount. La guía de precios convierte esos contadores en un presupuesto.

Ctrl+C detiene el ejemplo sin enviar más solicitudes. Dejar de leer localmente no demuestra que la generación remota no haya usado tokens. Si el flujo termina antes de que llegue el uso, consulta el registro de consumo de tu cuenta. Por prudencia, el ejemplo excluye el turno incompleto del historial futuro; conservar respuestas parciales es una decisión de aplicación independiente.

La decodificación larga es otro caso distinto. Un motivo de finalización CONTINUATION reanuda la generación original con un token de continuación; no es un nuevo mensaje del usuario. Google exige la solicitud original y el último token, sin añadir la salida parcial a contents. Consulta la guía de decodificación larga. Este script de introducción se detiene en lugar de implementar continuación automática.

¿Qué se ha verificado?

El streaming de texto básico ha superado una prueba local de extremo a extremo a través del Playground de SeedRouter. El análisis y la gestión del historial del ejemplo se comprueban con flujos sintéticos que incluyen partes firmadas, respuestas vacías e interrupciones. Estos datos de prueba verifican el software; no son ejecuciones adicionales del modelo. Las herramientas, los medios y la continuación aún requieren pruebas de capacidad separadas antes de describirse como integraciones verificadas.

Preguntas sobre la API

¿Puedo sustituir el nombre de un modelo OpenAI por gemini-4-argon?

Eso por sí solo no convierte los formatos de los mensajes. Esta guía utiliza los campos nativos de Gemini contents y parts. Comprueba que el cliente admite ese protocolo, así como la autenticación y el endpoint que configures.

¿Por qué la respuesta está vacía aunque se hayan usado tokens?

El razonamiento puede consumir el presupuesto de salida, y la seguridad o una generación incompleta también pueden impedir que aparezca texto visible. Revisa el motivo de finalización y el uso. No insertes un turno vacío del modelo ni repitas automáticamente la solicitud de pago.

¿Un contexto de un millón de tokens implica un millón de tokens de salida?

No. La entrada, el razonamiento y la salida comparten el contexto. Las generaciones largas también tienen límites por solicitud y pueden requerir continuación. Calcula el presupuesto para el total compartido, no para asignaciones independientes de entrada y salida.

Añadir funciones cuando la conversación ya funcione

Empieza con una respuesta completa y después confirma que el segundo turno recibe el contenido nativo original. Mantén separados el historial de la API de Gemini 4 Argon y el estado de la interfaz al añadir archivos adjuntos, herramientas o persistencia. El Playground del modelo y la guía de acceso son los siguientes pasos para el uso interactivo y los requisitos de la cuenta.