Blog

Tutorial

Gemini-4 Argon y Carbon en HiAPI: curl, Python y solicitudes ejecutables

Una guía de integración práctica para desarrolladores que eligen entre gemini-4-argon, gemini-4-carbon y gemini-4-carbon@vertex

Nov 17, 2026
Ilustración de portada plana en índigo profundo con flechas chevron anchas y anidadas, con bordes delanteros albaricoque, avanzando en diagonal hacia arriba, para un artículo tutorial de HiAPI.
En esta página

Elige la variante de Gemini-4 antes de escribir código

La primera decisión de cualquier integración con Gemini-4 no es curl o Python, sino qué ID de modelo envías. En HiAPI, gemini-4-argon, gemini-4-carbon y gemini-4-carbon@vertex son tres objetivos enrutables distintos, y la cadena que pasas en el campo model determina qué backend atiende tu solicitud. Elegirlo desde el principio te ahorra depurar un cuerpo de solicitud que nunca iba a funcionar.

Los tres objetivos en la práctica

  • gemini-4-argon: una variante independiente de Gemini-4 con su propio ID de modelo. Trátala como su propio modelo, no como un alias: su comportamiento, características de latencia y propiedades de salida pueden diferir de Carbon.
  • gemini-4-carbon: el objetivo Carbon predeterminado bajo el enrutamiento estándar de HiAPI.
  • gemini-4-carbon@vertex: la misma familia Carbon, pero servida a través de una ruta respaldada por Vertex. El sufijo @vertex forma parte del propio ID de modelo, no es un parámetro separado.

Cómo decidir

Parte de la carga de trabajo. Si estás evaluando Gemini-4 de forma amplia, ejecuta el mismo prompt contra gemini-4-argon y gemini-4-carbon por separado y compara las salidas antes de decidir. Si realmente necesitas el enrutamiento de Vertex —por ejemplo, porque coincide con el entorno que tu equipo ya opera—, apunta directamente a gemini-4-carbon@vertex.

Punto práctico: los tres usan la misma estructura de solicitud. Elegir la variante es cuestión de cambiar una línea, así que puedes posponer la decisión final hasta tener una solicitud que funcione. Si quieres ver primero las fichas de modelo, consulta gemini-4-argon y gemini-4-carbon.

Los ejemplos de esta guía usan gemini-4-carbon en todo momento; para seguir cualquier variante, solo tienes que sustituir ese ID.

Prepara las credenciales y la URL base

Antes de que cualquier cuerpo de solicitud importe, hay que asegurar tres cosas: la URL base, la clave de API y el formato del encabezado de autenticación. La mayoría de los fallos en la primera solicitud se deben a una de estas tres.

Qué necesitas

  1. Una clave de API del panel de tu cuenta de HiAPI. Trátala como un secreto: cárgala desde una variable de entorno en lugar de pegarla en un archivo fuente.
  2. La URL base de HiAPI. Todas las llamadas a modelos van al mismo host; la variante de modelo la selecciona el campo model, no la ruta.
  3. Dos encabezados en cada solicitud:
    • Authorization: Bearer $HIAPI_API_KEY
    • Content-Type: application/json

Configura tu entorno

export HIAPI_API_KEY="your-key-here"

Después, antes de escribir cualquier código, verifica que tu shell la ve:

echo "${HIAPI_API_KEY:0:4}..."

Si no imprime nada, tu clave no está exportada en el shell actual y todas las solicitudes fallarán con un error de autenticación. Corrígelo aquí, no en tu cliente.

La estructura de solicitud que reutilizarás

Todos los ejemplos siguientes envían un cuerpo JSON que contiene una cadena model y un array messages. Esta estructura no cambia entre curl y Python, entre no streaming y streaming, ni entre variantes de modelo. Mantenla estable y podrás portar el código copiando el cuerpo de la solicitud.

Una solicitud curl ejecutable

Aquí tienes una llamada no streaming completa, lista para copiar y pegar. Ejecútala antes de añadir cualquier otra cosa: si esta solicitud pasa, demuestra que tu clave, la URL base y los encabezados son correctos.

curl -sS "$HIAPI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-4-carbon",
    "messages": [
      {"role": "system", "content": "You are a concise technical assistant."},
      {"role": "user", "content": "Explain what an idempotency key is in two sentences."}
    ]
  }'

Qué hace cada campo

  • model: el selector de variante. Cámbialo por gemini-4-argon o gemini-4-carbon@vertex y llegarás a un objetivo distinto sin ningún otro cambio.
  • messages: un array ordenado. Los roles son system, user y assistant. Si usas un mensaje de sistema, colócalo primero.
  • content: el texto del mensaje. Para turnos de texto simple, es una cadena normal.

Lee el cuerpo de la respuesta

La respuesta es un objeto JSON que contiene la réplica del modelo y metadatos como el uso de tokens. Como es no streaming, el cuerpo completo llega de una vez y curl termina tras imprimirlo. Si obtienes un objeto JSON parseable con una réplica de mensaje, tu solicitud funciona: todo lo demás se construye sobre esta base.

Una comprobación rápida de sanidad: pasa la salida por un formateador JSON (| jq .) para que la estructura de la respuesta se lea con claridad en lugar de una sola línea larga.

Envía la misma solicitud con Python

La versión en Python mantiene el cuerpo de la solicitud exactamente igual: solo cambia el transporte. Usa requests:

import os
import requests

api_key = os.environ["HIAPI_API_KEY"]
base_url = os.environ["HIAPI_BASE_URL"]

payload = {
    "model": "gemini-4-carbon",
    "messages": [
        {"role": "system", "content": "You are a concise technical assistant."},
        {"role": "user", "content": "Explain what an idempotency key is in two sentences."},
    ],
}

response = requests.post(
    f"{base_url}/chat/completions",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=60,
)
response.raise_for_status()
data = response.json()
print(data["choices"][0]["message"]["content"])

Por qué esto corresponde exactamente a la llamada curl

Fíjate en que payload es byte a byte idéntico al cuerpo JSON de la sección anterior. El parámetro json= lo serializa y establece Content-Type por ti; el diccionario de encabezados aporta la autenticación. No cambia ni el modelo, ni los mensajes, ni los roles.

Dos hábitos que conviene mantener

  • Establece un timeout. Sin timeout, una conexión que se estanca deja tu proceso colgado indefinidamente. Para llamadas no streaming, timeout=60 es un punto de partida razonable.
  • Llama a raise_for_status() antes de leer el cuerpo de la respuesta. Las solicitudes fallidas devuelven objetos de error estructurados, no completaciones: inspeccionar json() en un 4xx te llevará a engaño. Deja que la excepción se lance primero y luego registra el texto de la respuesta.

Coloca el cuerpo de la solicitud en una función o en un pequeño objeto de configuración, de modo que las secciones de streaming y llamada a herramientas lo amplíen en lugar de duplicarlo.

Añade soporte de streaming a la llamada

Primero haz que funcione la solicitud no streaming. Luego activa el streaming: los modos de fallo son distintos, y superponer ambos cambios hace que los errores sean difíciles de distinguir.

Activa el streaming

Añade un campo al cuerpo de la solicitud existente:

{
  "model": "gemini-4-carbon",
  "stream": true,
  "messages": [
    {"role": "user", "content": "List three uses for a message queue."}
  ]
}

Ese es todo el cambio de protocolo. El servidor ahora devuelve una secuencia de eventos en lugar de un único documento JSON.

Consume el stream correctamente

Regla clave: no llames a .json() sobre una respuesta en streaming. Obtendrás un error de parseo porque el cuerpo de la respuesta no es un único objeto JSON. Con requests, itera línea a línea y parsea cada fragmento por separado:

import json, os, requests

response = requests.post(
    f"{os.environ['HIAPI_BASE_URL']}/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json={
        "model": "gemini-4-carbon",
        "stream": True,
        "messages": [{"role": "user", "content": "List three uses for a message queue."}],
    },
    stream=True,
    timeout=60,
)
response.raise_for_status()

for line in response.iter_lines():
    if not line:
        continue
    decoded = line.decode("utf-8")
    if decoded.startswith("data: "):
        decoded = decoded[len("data: "):]
    if decoded.strip() == "[DONE]":
        break
    try:
        chunk = json.loads(decoded)
    except json.JSONDecodeError:
        continue
    print(chunk)

Qué hay que tener en cuenta

  • Pasa stream=True a requests. De lo contrario, el cliente almacena en búfer todo el cuerpo de la respuesta antes de que veas una sola línea, lo que anula el propósito.
  • Omite las líneas vacías y los mensajes keep-alive que no sean JSON. El try/except anterior es deliberado: el stream puede contener líneas que no se parsean como fragmentos.
  • Acumula el texto entre fragmentos. Cada fragmento lleva una porción, no la réplica completa. Añádelas a medida que llegan los deltas de texto.

Cuando el streaming funcione, vuelve a poner stream en false en tus pruebas no streaming para que la llamada a herramientas siga siendo fácil de leer. Para una visión general del objetivo Carbon, la página del modelo gemini-4-carbon es un buen punto de referencia.

Añade llamada a herramientas al cuerpo de la solicitud

La llamada a herramientas cambia la solicitud en dos lugares: declaras las herramientas y además manejas un turno de respuesta que puede contener una solicitud de llamada a herramienta en lugar de texto. Añade esta funcionalidad solo después de que la llamada de texto no streaming funcione.

Declara las herramientas

Añade un array tools junto a model y messages. Cada herramienta tiene un nombre, una descripción y el JSON Schema de sus parámetros. La descripción es importante: es lo que usa el modelo para decidir si llamar a la herramienta.

{
  "model": "gemini-4-carbon",
  "messages": [
    {"role": "user", "content": "What is the weather in Lisbon?"}
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Return current weather for a city.",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {"type": "string", "description": "City name"}
          },
          "required": ["city"]
        }
      }
    }
  ]
}

El bucle de llamada a herramientas

Una solicitud que usa herramientas es una conversación, no una llamada única:

  1. Envía el mensaje del usuario junto con la declaración de herramientas.
  2. Inspecciona el turno del asistente. Si contiene parámetros de llamada a herramienta, el modelo quiere que ejecutes algo.
  3. Ejecuta la función local: HiAPI no ejecuta tu código.
  4. Añade dos mensajes: el turno de llamada a herramienta del asistente y un mensaje con rol tool que contenga el resultado de la función, asociado al ID de llamada correspondiente.
  5. Reenvía el historial completo de mensajes. El modelo ahora produce la respuesta final.

Puntos de fallo específicos de las herramientas

  • Desajuste de schema. Si tu schema de parameters marca un campo como obligatorio pero el resultado lo omite, los turnos posteriores pueden ser rechazados. Mantén el schema preciso.
  • Descartar el historial. Cada reenvío debe incluir el mensaje original del usuario y el turno de llamada a herramienta, no solo el resultado de la herramienta.
  • Streaming más herramientas. Los parámetros de llamada a herramienta pueden llegar divididos entre varios fragmentos del stream. Mientras aprendes el flujo, ejecuta las herramientas con stream: false para que cada turno llegue como un objeto legible.

Cambia de modelo y de proveedor sin reescribir el cliente

Como la variante de modelo es solo una cadena en el cuerpo de la solicitud, cambiar de objetivo es un cambio de configuración, no una refactorización. Diseña el cliente para que lea el ID de modelo desde una variable —variable de entorno, archivo de configuración, flag de CLI— y nunca lo codifiques directamente en varios lugares.

El cambio en sí

export HIAPI_MODEL="gemini-4-carbon"      # default
export HIAPI_MODEL="gemini-4-argon"       # different variant
export HIAPI_MODEL="gemini-4-carbon@vertex"  # Vertex-backed Carbon

En el código, haz referencia a esa variable en el cuerpo de la solicitud:

payload = {
    "model": os.environ["HIAPI_MODEL"],
    "messages": messages,
}

El sufijo @vertex viaja junto con la cadena del modelo. No lo separes en un campo aparte ni lo elimines: forma parte del ID enrutable, y quitarlo te enruta silenciosamente al objetivo sin Vertex.

Qué hay que volver a probar tras el cambio

  1. Turnos de texto simple: confirma que el ID se reconoce y que la autenticación sigue siendo válida.
  2. Tu prompt real más largo: distintas variantes pueden manejar entradas largas o estructuradas de forma diferente; verifica el truncado y el formato.
  3. Streaming: vuelve a ejecutar la ruta de streaming, ya que el ritmo y los límites de los fragmentos pueden variar según el objetivo.
  4. Llamada a herramientas: vuelve a validar el bucle completo de llamada a herramientas; el formato de los parámetros es donde más suelen aflorar las diferencias entre variantes.

Mantén un pequeño script de prueba de humo que ejecute estas cuatro comprobaciones contra el HIAPI_MODEL configurado actualmente. Así, cambiar de proveedor se convierte en un cambio de configuración más un comando, en lugar de una sesión de depuración.

Soluciona los fallos de solicitud habituales

Casi todos los fallos de integración encajan en unas pocas categorías. Identifica el síntoma, aplica la corrección y vuelve a ejecutar la base no streaming antes de tocar cualquier otra cosa.

Autenticación y enrutamiento

  • 401 o 403. Clave ausente, caducada o con prefijo incorrecto. Comprueba que el encabezado sea exactamente Authorization: Bearer <key>, con un solo espacio en medio, y confirma que la variable está realmente exportada en el shell o proceso que ejecuta el código. Imprime los primeros caracteres para confirmarlo.
  • El endpoint devuelve 404. Tu URL base es incorrecta o el segmento de ruta está duplicado. El modelo va en el cuerpo de la solicitud, no en la URL.
  • Modelo no encontrado. Hay una errata en el ID de modelo. Compara carácter a carácter con gemini-4-argon, gemini-4-carbon y gemini-4-carbon@vertex: el sufijo @vertex es el que más se pasa por alto.

Problemas del cuerpo de la solicitud

  • 400 con un mensaje de schema. Normalmente es un messages mal formado: falta role, content debería ser una cadena y no lo es, o el array está vacío. Empieza por el cuerpo mínimo de dos líneas de esta guía y añade un campo cada vez.
  • 400 tras añadir herramientas. Tu schema de parameters es un JSON Schema inválido, o el turno de resultado de la herramienta no coincide con el ID de llamada del mensaje del asistente. Registra el cuerpo completo de la respuesta: el texto del error señalará el campo problemático.

Fallos de streaming

  • Error de parseo JSON sobre la respuesta. Estás llamando a .json() sobre un stream. Itera línea a línea, parsea cada fragmento y omite las líneas vacías y el marcador [DONE].
  • La respuesta llega de una vez. Olvidaste establecer stream=True en la llamada del cliente, así que requests almacenó en búfer todo el cuerpo de la respuesta.
  • Salida truncada. Tu bucle se interrumpe antes de tiempo, normalmente en una línea vacía o en un mensaje keep-alive. Detente solo en el marcador explícito de fin de stream.

Disciplina de depuración

Biseca en el mismo orden en que construiste: autenticación y encabezados, luego texto no streaming, luego streaming, luego herramientas. Cada capa tiene una firma de fallo distinta, así que lo último que cambiaste es casi siempre la causa. Registra el estado HTTP y el cuerpo completo de la respuesta en cada fallo: el mensaje suele señalar el campo concreto.

Haz que la base funcione primero con gemini-4-argon o gemini-4-carbon y luego amplía el cuerpo de la solicitud desde ahí. Si aún estás decidiendo qué variante se ajusta a tu carga de trabajo, la página del modelo gemini-4-argon es el punto de partida.

Artículos relacionados

Ver todos los artículos →

Empieza a crear con artefactos de IA persistentes

Consigue tu API key y llama a modelos de imagen, vídeo y audio a través de una única API basada en tasks.

Leer la documentación de la API