Blog

Tutorial

Cómo llamar a fibo-2.0/text-to-image mediante la API de HiAPI: práctica con curl y Python

Nov 13, 2026
Imagen de portada: planos de vidrio translúcido apilados sobre un fondo gris azulado claro, refractando bandas de color azul contenidas, formando una composición geométrica abstracta.
En esta página

Qué construye este tutorial

Esta es una guía práctica en la que obtendrás una imagen real de fibo-2.0/text-to-image en HiAPI. Al terminar, tendrás dos cosas listas para ejecutar: un comando curl que genera una solicitud válida de generación de imágenes y una pequeña función de Python que hace lo mismo y devuelve el resultado para su posterior procesamiento.

Avanzaremos en el orden en que la mayoría de los desarrolladores trabajan. Primero, confirmaremos que el entorno y las credenciales están listos. Luego leeremos el cuerpo de la solicitud campo por campo, para que tengas claro qué controla cada parte. Después enviaremos la llamada con curl para demostrar que el endpoint, la clave y la carga útil concuerdan. Solo después de eso trasladaremos la misma solicitud a Python, donde comienza el trabajo realmente interesante: analizar la respuesta, manejar fallos y encapsularlo todo en una función.

El objetivo no es enumerar todos los parámetros posibles, sino darte una forma de solicitud que entiendas por completo, para que puedas ajustar el prompt, el tamaño de salida y el código circundante a tu propio caso de uso sin adivinar.

Antes de enviar la primera solicitud

Hacen falta tres condiciones para que la primera llamada tenga éxito.

Cuenta de HiAPI y clave de API

Las solicitudes a fibo-2.0/text-to-image requieren autenticación. Genera una clave de API en tu cuenta de HiAPI y mantenla alejada del control de versiones. Los ejemplos siguientes leen la clave desde una variable de entorno en lugar de codificarla directamente; hazlo así desde el primer día, porque añadir el manejo de claves después resulta engorroso.

export HIAPI_API_KEY="your-api-key-here"

Una herramienta capaz de enviar solicitudes HTTP

Para la parte práctica con curl necesitas curl en tu máquina. Viene con macOS y con la mayoría de las distribuciones de Linux; en Windows también está disponible en las versiones actuales y en Windows Terminal. Para la parte de Python necesitas Python 3 y la biblioteca requests, la forma más común de hacer llamadas HTTP desde un script. Si aún no la tienes instalada:

pip install requests

Tener claro qué quieres generar

Prepara un prompt. Los modelos de imagen responden con fuerza a descripciones concretas y explícitas —sujeto, estilo, iluminación y composición—, así que una sola línea de idea suele bastar para empezar a probar. Seguirás refinándolo después de ver el primer resultado; este es un ciclo normal.

Con estos tres elementos en su sitio, todo lo demás gira en torno al cuerpo de la solicitud.

Análisis del cuerpo de la solicitud campo por campo

La llamada a fibo-2.0/text-to-image es una solicitud POST con un cuerpo JSON. El cuerpo es pequeño: un prompt y los ajustes que dan forma a la salida. En lugar de memorizar la carga útil completa, entiende cada campo para poder modificarlo con criterio.

Identificador del modelo

La propia ruta del endpoint indica el modelo: fibo-2.0/text-to-image. En la mayoría de los casos no necesitas pasar una cadena de modelo adicional: la ruta que llamas determina qué modelo se ejecuta. Si tu integración admite el enrutamiento mediante un endpoint compartido, coloca el nombre del modelo en una constante de configuración para poder cambiarlo sin tocar el punto de llamada.

El prompt

Esta es la entrada central: la descripción textual de la imagen que deseas. Trátalo como una especificación, no como un deseo. Indicar el sujeto, el estilo visual y la composición da al modelo mucha más información útil que los conceptos abstractos. Guarda el prompt en una variable o en un archivo aparte para poder iterar rápidamente sin reescribir el código de la solicitud.

Ajustes de salida

Las solicitudes de imagen suelen incluir un pequeño conjunto de controles de salida —los más habituales son el tamaño o la relación de aspecto de la imagen generada y, si quieres varios resultados, la cantidad—. Usa los nombres de campo documentados para fibo-2.0/text-to-image en la referencia de modelos de HiAPI; la carga útil de ejemplo siguiente utiliza esos nombres canónicos. Si un ajuste no está documentado para ese modelo, omítelo en lugar de adivinarlo: los campos desconocidos son una fuente habitual de errores de validación.

Lo que no debe ir en el cuerpo de la solicitud

No pongas la clave de API en el cuerpo JSON. La autenticación va en las cabeceras. Mantener las credenciales fuera de la carga útil significa que el cuerpo puede registrarse y compararse de forma segura durante la depuración, algo que agradecerás la primera vez que falle una solicitud.

Una solicitud curl funcional

A continuación se muestra una llamada completa. Sustituye tu propio prompt y ejecútala en un shell donde ya hayas definido HIAPI_API_KEY.

curl -X POST "https://api.hiapi.ai/v1/models/fibo-2.0/text-to-image" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "un puerto tranquilo al amanecer, una suave niebla sobre el agua, composición panorámica, estilo fotográfico",
    "size": "1024x1024",
    "n": 1
  }'

Qué hace cada parte

  • -X POST establece el método HTTP. La generación de imágenes es una operación de creación, así que es POST, no GET.
  • La URL apunta a la ruta fibo-2.0/text-to-image en el host de la API de HiAPI. Si tu cuenta usa una URL base regional o específica de un proyecto, sustituye ese host y conserva la ruta.
  • Authorization: Bearer $HIAPI_API_KEY pasa tu clave desde el entorno. El shell expande la variable, por lo que la clave nunca aparece como una cadena literal en el historial de tu comando.
  • Content-Type: application/json indica al servidor que el cuerpo es JSON. Sin esto, muchas pasarelas lo rechazan antes de que la solicitud llegue al modelo.
  • -d '...' es el cuerpo JSON: el prompt, el tamaño solicitado y la cantidad de imágenes.

Verificación del resultado

Ejecuta el comando y mira primero la salida sin procesar. Una llamada exitosa devuelve un documento JSON que describe la imagen generada; una llamada fallida devuelve un objeto de error. Antes de construir nada sobre esto, confirma que puedes distinguir ambos casos a simple vista. Si la respuesta es grande, procésala con una herramienta de formateo como jq para que la estructura sea legible:

curl -s -X POST "https://api.hiapi.ai/v1/models/fibo-2.0/text-to-image" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"un puerto tranquilo al amanecer","size":"1024x1024","n":1}' | jq .

Una vez que la llamada manual tiene éxito, habrás descartado las credenciales y la carga útil como sospechosas. A partir de ahí, todos los problemas estarán en tu código.

La misma llamada en Python

La versión en Python hace exactamente lo que hace el comando de shell, pero te ofrece un lugar para validar la entrada, reintentar y almacenar resultados. Mantenla pequeña y explícita.

import os
import requests

API_URL = "https://api.hiapi.ai/v1/models/fibo-2.0/text-to-image"

def generate_image(prompt: str, size: str = "1024x1024", n: int = 1) -> dict:
    api_key = os.environ["HIAPI_API_KEY"]
    payload = {
        "prompt": prompt,
        "size": size,
        "n": n,
    }
    response = requests.post(
        API_URL,
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=60,
    )
    response.raise_for_status()
    return response.json()

if __name__ == "__main__":
    result = generate_image(
        "un puerto tranquilo al amanecer, una suave niebla sobre el agua, composición panorámica, estilo fotográfico"
    )
    print(result)

Por qué está escrito así

  • La clave se lee del entorno dentro de la función, de modo que si falta, la llamada falla de forma ruidosa al iniciarse en lugar de enviar una solicitud sin autenticar.
  • json=payload hace que requests serialice el cuerpo y establezca correctamente el tipo de contenido. No construyas cadenas JSON a mano en Python; eso introduce errores de comillas que solo se descubren en tiempo de ejecución.
  • timeout=60 hace explícito el fallo lento. La generación de imágenes no es instantánea, así que elige un tiempo de espera que estés dispuesto a aguardar, pero siempre establece uno.
  • raise_for_status() convierte las respuestas 4xx y 5xx en excepciones. Esta línea es la que impide que una llamada fallida se trate silenciosamente como exitosa.
  • La función recibe prompt, size y n como parámetros, de modo que el resto de tu programa puede llamarla igual que a cualquier otra función de biblioteca.

Ejecuta el archivo y deberías ver la misma estructura JSON que devolvió la llamada con curl.

Leer la respuesta y manejar errores

Una respuesta exitosa te devuelve un objeto JSON que describe la salida generada. El detalle que te interesa es la imagen generada en sí —normalmente una URL o referencia que puedes descargar o almacenar— junto con los metadatos que la API devuelva sobre la solicitud. Analiza la respuesta como datos; no la extraigas con manipulación de cadenas. Si la forma no coincide con lo esperado cuando revises por primera vez una respuesta en vivo, consulta la referencia del modelo antes de ajustar el analizador, porque adivinar nombres de campo es precisamente la forma en que una integración se rompe en silencio.

Detección de fallos

Hay tres capas de fallo que conviene manejar de forma deliberada.

Errores de transporte. La solicitud nunca se completó: fallo de DNS, conexión restablecida, tiempo de espera agotado. En Python, estos se manifiestan como requests.exceptions, que son seguros de reintentar con retroceso exponencial.

Estados HTTP de error. El servidor respondió pero rechazó la solicitud. Un 401 suele significar que la clave falta o es incorrecta; un error de validación 4xx normalmente significa que el nombre o el valor de un campo no es correcto; un 429 significa que enviaste demasiado rápido; un 5xx significa que algo falló en el servidor. raise_for_status() captura todos ellos como una sola excepción, así que revisa el mensaje del cuerpo de la respuesta antes de decidir qué hacer.

Código de estado 200 pero cuerpo de respuesta inesperado. Por eso debes validar la estructura en lugar de asumirla. Antes de usarlos, comprueba que existen los campos de los que dependes y, aunque el código de estado sea 200, trata la falta de referencia de imagen como un fallo.

try:
    result = generate_image("un puerto tranquilo al amanecer")
    image = result.get("data", [{}])[0]
except requests.HTTPError as exc:
    print("request failed:", exc.response.status_code, exc.response.text)

Un hábito importante: nunca te tragues los errores en silencio. Como mínimo, registra el código de estado y el cuerpo de la respuesta, porque ese par de datos te indica si debes corregir la carga útil o esperar y reintentar.

Camino a producción

Una vez que la llamada individual funciona y los fallos son visibles, unos cuantos hábitos pequeños hacen que la integración resista con tráfico real.

Reintentar solo lo que es seguro reintentar

Los errores de transporte, los tiempos de espera agotados, las respuestas 429 y 5xx merecen reintentarse con retroceso exponencial y un límite de intentos. Los errores de validación y los 401 no lo merecen: reintentar una solicitud mal formada solo consume cuota. Distingue claramente ambos grupos en el manejo de errores.

Mantener la configuración fuera del código

Coloca la URL base de la API, la ruta del modelo, el tamaño predeterminado y el tiempo de espera en la configuración, no dispersos por las funciones. Cuando pases de un entorno de pruebas a otro distinto, o pruebes más adelante un modelo similar, solo tendrás que cambiar un lugar.

Registrar solicitudes y respuestas, pero sin claves

Registra el prompt, los parámetros, los códigos de estado y la respuesta truncada. Nunca registres la clave de API. Así podrás responder dentro de una semana a la pregunta «por qué esta imagen volvió mal» sin necesidad de reproducir el problema.

Validar la entrada antes de enviarla

Comprueba que el prompt no está vacío y que tiene una longitud razonable, y verifica que size y n coinciden con los valores documentados del modelo. Detectar valores incorrectos en local es más rápido y barato que un viaje de ida y vuelta.

Almacenar los resultados, no solo imprimirlos

Las referencias de imagen generadas pueden ser temporales. Como parte del mismo trabajo, descarga o copia la salida en tu propio almacenamiento y registra qué prompt y parámetros la produjeron. Ese registro hace posibles la regeneración y la auditoría.

Envuelve fibo-2.0/text-to-image en la pequeña función generate_image de este tutorial y haz que el resto de tu aplicación dependa de esa función en lugar de llamadas HTTP directas. Cuando estés listo para variar prompts a gran escala, la referencia de modelos de HiAPI es el lugar donde confirmar los parámetros compatibles antes de ampliar la interfaz.

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