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
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@vertexforma 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
- 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.
- 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. - Dos encabezados en cada solicitud:
Authorization: Bearer $HIAPI_API_KEYContent-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 porgemini-4-argonogemini-4-carbon@vertexy llegarás a un objetivo distinto sin ningún otro cambio.messages: un array ordenado. Los roles sonsystem,useryassistant. 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=60es 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: inspeccionarjson()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=Truearequests. 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/exceptanterior 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:
- Envía el mensaje del usuario junto con la declaración de herramientas.
- Inspecciona el turno del asistente. Si contiene parámetros de llamada a herramienta, el modelo quiere que ejecutes algo.
- Ejecuta la función local: HiAPI no ejecuta tu código.
- Añade dos mensajes: el turno de llamada a herramienta del asistente y un mensaje con rol
toolque contenga el resultado de la función, asociado al ID de llamada correspondiente. - 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
parametersmarca 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: falsepara 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
- Turnos de texto simple: confirma que el ID se reconoce y que la autenticación sigue siendo válida.
- Tu prompt real más largo: distintas variantes pueden manejar entradas largas o estructuradas de forma diferente; verifica el truncado y el formato.
- 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.
- 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-carbonygemini-4-carbon@vertex: el sufijo@vertexes el que más se pasa por alto.
Problemas del cuerpo de la solicitud
- 400 con un mensaje de schema. Normalmente es un
messagesmal formado: faltarole,contentdeberí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
parameterses 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=Trueen la llamada del cliente, así querequestsalmacenó 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 →-
Tutorial
Casos prácticos de Tripo H3.1: 5 usos de alto valor y puntos clave de implementación
De texto a 3D a la reconstrucción multivista: elige el modo y los parámetros correctos según el escenario de negocio
-
Tutorial
Casos prácticos de gemini-4-neon: 5 usos de alto valor y puntos clave de integración
-
Tutorial
Tutorial de la API seedance-2.5-flash de imagen a video: curl y Python Requests
Recorrido práctico de integración para desarrolladores: estructura de la solicitud, entradas de primer y último fotograma, sondeo asíncrono y solución de errores