Cómo usar imagen-4.0 a través de la API de HiAPI: curl, Python y ejemplos de solicitudes disponibles

Las capacidades de imagen-4.0 que HiAPI pone a tu disposición

imagen-4.0 es un modelo de texto a imagen: envías un prompt en lenguaje natural y devuelve una imagen generada. Como desarrollador de integraciones, lo que realmente importa no es la arquitectura del modelo, sino el contrato de interfaz que lo rodea. A través de HiAPI, ese contrato es un único endpoint HTTP —que acepta JSON y se autentica con una clave bearer— exactamente el mismo patrón que ya conoces de las llamadas a chat completion y embedding.

Beneficios reales de usar HiAPI en lugar de conectarte directamente al modelo:

• Esquema de autenticación unificado. La misma API key sirve para todos los modelos de la plataforma, así que no tienes que alternar entre credenciales de varios proveedores.
• Formato de solicitud unificado. Un cuerpo JSON que contiene el identificador del modelo y el prompt. No hay que aprender la estructura de solicitud de un SDK específico.
• Retorno síncrono. imagen-4.0 devuelve el resultado en la misma respuesta HTTP, así que en escenarios básicos no necesitas construir bucles de sondeo ni webhooks.

Esta guía te lleva desde cero hasta construir una solicitud funcional con curl y otra con Python, y luego explica cómo leer la respuesta y qué preparar antes de salir a producción.

Obtener la API key y configurar la autenticación

Cada llamada a imagen-4.0 en HiAPI se autentica con un bearer token. Creas una API key en tu cuenta de HiAPI y, a partir de ahí, esa clave es la única credencial necesaria para las solicitudes: no hace falta un ID de proyecto aparte ni cabeceras firmadas.

El principio que evita la mayoría de los incidentes: la clave debe ir en una variable de entorno y nunca confirmarse en el código fuente. Una clave pegada en un script y subida al repositorio es una clave que tendrás que rotar.

Configuración local

Exporta la clave en tu sesión de shell:

export HIAPI_API_KEY="your-key-here"

Si quieres que la variable persista, añade esa línea a tu archivo de configuración del shell; o bien usa un archivo .env, inclúyelo en .gitignore y cárgalo al iniciar la aplicación.

Entornos desplegados

En CI y producción, define HIAPI_API_KEY mediante el gestor de secretos de la plataforma: inyecta la variable de entorno en tiempo de ejecución en lugar de incrustar el archivo en la imagen. Así el código de la aplicación es idéntico en local y en entornos desplegados, y solo cambia el origen de la variable.

Cabeceras de la solicitud

Cada solicitud lleva:

Authorization: Bearer $HIAPI_API_KEY

Si ves un 401, lo primero que debes comprobar es si la cabecera se está enviando realmente y si la variable se resuelve a un valor no vacío. Un shell que nunca exportó la variable enviará igualmente Bearer sin nada detrás.

Entender la estructura de la solicitud antes de enviarla

El cuerpo de una solicitud a imagen-4.0 es tan pequeño que puedes memorizarlo, y esa es precisamente la clave: una vez entiendes su estructura, puedes construir la solicitud en cualquier lenguaje sin traducir un fragmento de código copiado y pegado.

Como mínimo debes enviar:

{
  "model": "imagen-4.0",
  "prompt": "A weathered lighthouse on a cliff at dusk, long exposure, muted colors"
}

Dos campos hacen el trabajo principal:

• model identifica qué modelo procesa la solicitud. Es una cadena y es el mismo identificador que la plataforma usa en todos los lugares donde se lista imagen-4.0. Un error de escritura produce una respuesta de error, no un fallback silencioso.
• prompt es la descripción de la imagen que quieres. Escríbelo como describirías una escena a una persona: sujeto, escenario, estilo, iluminación. Un prompt concreto produce resultados más predecibles que uno de una sola palabra.

La solicitud se envía con POST, con Content-Type: application/json, al endpoint de generación de imágenes de la plataforma. Es posible que el modelo tenga parámetros opcionales adicionales, pero el cuerpo de dos campos anterior es una solicitud completa y válida: empieza por ahí y añade opciones solo cuando las necesites.

Como el cuerpo es JSON puro, curl, Python, Node y cualquier herramienta con un cliente HTTP son ciudadanos de primera clase. Las dos secciones siguientes muestran dos formas de escribir la misma solicitud.

Una solicitud curl funcional

Empieza desde la terminal, donde puedes ver la respuesta en bruto sin interferencias de análisis.

curl -sS -X POST "$HIAPI_BASE_URL/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "imagen-4.0",
    "prompt": "A weathered lighthouse on a cliff at dusk, long exposure, muted colors"
  }'

Explicación línea por línea:

• -sS silencia la barra de progreso pero sigue mostrando los errores, de modo que la salida es legible sin ocultar fallos.
• -X POST define el método de la solicitud. La generación de imágenes crea contenido, así que es POST.
• La URL es el endpoint de generación de imágenes de la plataforma, formado por tu URL base más la ruta. Guarda la URL base en una variable para que el mismo comando funcione en distintos entornos.
• La primera cabecera lleva tu bearer key, leída de la variable de entorno exportada anteriormente.
• Content-Type: application/json indica al servidor cómo interpretar el cuerpo.
• -d proporciona el cuerpo JSON. Las comillas simples evitan que el shell interprete llaves y comillas; el JSON interior es literal.

Si quieres inspeccionar la salida, pásala por una herramienta de formateo JSON:

curl -sS -X POST "$HIAPI_BASE_URL/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"imagen-4.0","prompt":"A weathered lighthouse on a cliff at dusk"}' \
  | python -m json.tool

Si la respuesta contiene una referencia a la imagen, la solicitud se completó correctamente. La siguiente sección la convierte en código de aplicación.

Escribir la misma solicitud en Python

La llamada curl se puede traducir directamente. La única decisión real es el cliente HTTP; el urllib de la biblioteca estándar funciona en todas partes, pero requests produce código más corto y es la biblioteca de la que ya dependen la mayoría de los proyectos.

Una función auxiliar reutilizable

import os
import requests

HIAPI_BASE_URL = os.environ.get("HIAPI_BASE_URL", "https://api.hiapi.ai/v1")


def generate_image(prompt: str, model: str = "imagen-4.0") -> dict:
    api_key = os.environ["HIAPI_API_KEY"]
    response = requests.post(
        f"{HIAPI_BASE_URL}/images/generations",
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        },
        json={"model": model, "prompt": prompt},
        timeout=120,
    )
    response.raise_for_status()
    return response.json()


result = generate_image("A weathered lighthouse on a cliff at dusk")
print(result)

Tres cosas que merecen atención:

• os.environ["HIAPI_API_KEY"] lanza un KeyError inmediato si falta la variable, de modo que falla rápido y de forma visible en lugar de enviar un token vacío.
• json= serializa el diccionario y establece el tipo de contenido automáticamente, así que el comportamiento de la solicitud coincide exactamente con la versión curl.
• timeout=120 limita la duración de la llamada. La generación de imágenes tarda más que una completación de texto, así que usa un timeout holgado en lugar del valor predeterminado sin límite.

La función recibe el prompt como parámetro y devuelve el JSON analizado, lo que significa que el resto de tu código no necesita tocar los detalles HTTP. Pruébala en un REPL antes de conectarla a nada.

Leer la respuesta síncrona y gestionar errores

imagen-4.0 responde de forma síncrona: la imagen generada se devuelve en el cuerpo de la misma respuesta HTTP. En escenarios básicos no hay un ID de tarea que sondear ni un bucle de sondeo que escribir: trata la llamada como cualquier otra interacción de solicitud-respuesta.

Qué devuelve

Una respuesta correcta es un objeto JSON. En Python, analízala con response.json(), o pasa la salida de curl por una herramienta de formateo JSON; después localiza los datos de la imagen en la estructura devuelta —normalmente una URL o una carga de imagen codificada, junto con metadatos sobre la generación. Lee los nombres de campo exactos de una respuesta real una vez y luego escribe el código en consecuencia.

Problemas que conviene prever

Envuelve la llamada y comprueba el estado antes de analizar:

try:
    result = generate_image("A weathered lighthouse on a cliff at dusk")
except requests.HTTPError as e:
    print("HTTP error:", e.response.status_code, e.response.text)
except requests.Timeout:
    print("Request timed out")

Modos de fallo que merece la pena manejar explícitamente:

• 401: clave ausente o no válida. Corrige la variable de entorno, no el código.
• 4xx en general: cuerpo de solicitud mal formado, identificador de modelo incorrecto o prompt rechazado. El cuerpo de la respuesta suele indicar cuál es. Regístralo en el log.
• 5xx: fallo del lado del servidor. Estos merecen reintentos con backoff.
• Timeout: trátalo como resultado desconocido, no como éxito; no asumas que la imagen se generó.

Registra siempre el código de estado y el cuerpo de respuesta truncado cuando haya un fallo. Depurar sin esa información es adivinar.

De la primera solicitud a producción

La solicitud ya funciona. Antes de escalar, revisa punto por punto:

• Configuración. Tanto la URL base como la API key provienen del entorno. No hay literales en el código fuente ni claves en las imágenes.
• Timeouts. Cada llamada de imagen tiene un timeout. Sin él, una solicitud bloqueada puede ocupar un worker indefinidamente.
• Reintentos. Reintenta solo 5xx y timeouts, con backoff exponencial y un límite máximo. Nunca reintentes un 401 ni un 4xx por cuerpo mal formado: fallarán exactamente igual.
• Registro en logs. Registra el modelo, la longitud del prompt, el código de estado y la latencia de cada llamada. No registres claves y, si los prompts pueden contener datos de usuario, no registres el prompt completo.
• Conciencia de costes. La generación de imágenes se factura por la salida producida, así que haz seguimiento de cuántas imágenes solicita cada usuario o cada tarea y establece límites en la capa de aplicación. Para las tarifas vigentes, consulta el panel de precios de la plataforma, no esta guía.
• Concurrencia. Las llamadas de imagen son más lentas que las de texto. Dimensiona el pool de workers en consecuencia y no asumas la latencia de chat-completion.

Cuando esto esté listo, la misma función auxiliar generate_image sirve sin modificaciones para tareas por lotes, funcionalidades orientadas al usuario y herramientas internas. Para más detalles de integración, consulta la documentación de la plataforma.