Tutorial
Cómo usar minimax-h3-image de texto a imagen con la API de HiAPI: curl y Python
En esta página
Qué cubre este tutorial y qué necesitas preparar primero
Este tutorial trata un único tema concreto: enviar un prompt de generación de imágenes al modelo de texto a imagen minimax-h3-image a través de la API de HiAPI, primero con una solicitud curl y luego con una pequeña función de Python que puedas integrar en tu aplicación. Cubre la estructura de la solicitud, cómo interpretar la respuesta, cómo se manifiestan los errores y qué aspectos conviene reforzar antes de pasar a producción.
Deliberadamente no aborda teoría de ingeniería de prompts, posprocesamiento de imágenes ni la creación de interfaces de usuario. El objetivo es más acotado: al terminar, deberías tener una solicitud fiable y saber exactamente por qué falló la última vez.
Requisitos previos
- Una cuenta de HiAPI. Antes que nada, necesitas un proyecto y una clave de API: todas las solicitudes siguientes requieren autenticación.
- Guardar la clave en un lugar seguro. Colócala en una variable de entorno (
HIAPI_API_KEY) en lugar de un archivo de código fuente, para que el mismo código funcione tanto en local como en CI. - El identificador del modelo. Este tutorial usa
minimax-h3-imagey su capacidadtext-to-image. Trata tanto el nombre del modelo como la ruta de la tarea como valores de configuración en tu código, no como cadenas mágicas dispersas por todas partes. - Herramientas.
curlpara la primera solicitud, y Python 3.9+ conrequestspara la segunda. No se necesitan otras bibliotecas. - Una forma de ver la imagen. Leerás una carga de respuesta que contiene los datos de la imagen o una referencia a ella; inspecciona manualmente los campos de la respuesta antes de asumir cualquier esquema.
Un hábito que deberías adoptar ya
Consigue tu primera solicitud exitosa fuera de tu código de aplicación. Un comando curl que funciona es la fuente de verdad: cada vez que la versión de Python se comporte de forma extraña, compárala con él. Si la llamada curl funciona y la de Python no, el problema está en tu cliente, no en el modelo ni en la red.
Construir una solicitud de texto a imagen funcional con curl
Empieza con la solicitud más pequeña posible y luego vuelve a añadir un ajuste a la vez. Una solicitud de generación consta de tres partes: el endpoint, la cabecera de autenticación y el cuerpo JSON.
La solicitud
curl -X POST "https://api.hiapi.ai/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "minimax-h3-image",
"task": "text-to-image",
"prompt": "Un bol de cerámica sobre un mantel de lino, luz suave de una ventana orientada al norte, objetivo de 50 mm, profundidad de campo reducida",
"size": "1024x1024",
"n": 1
}'
Hay tres cosas que destacar en ese comando:
- La clave se pasa como token bearer en la cabecera
Authorization. Nunca la pongas en la URL ni en el cuerpo de la solicitud, o terminará en los registros y en el historial del shell. modelytaskdescriben lo que quieres: la familia de modelos y la capacidad. Escribe ambos explícitamente aunque existan valores predeterminados; las solicitudes explícitas resisten mejor el paso del tiempo.promptes una cadena normal. Todo lo demás (size,n) son ajustes de imagen, no una descripción del sujeto.
Interpretar la respuesta
Pasa la salida por un formateador para poder leerla de verdad:
curl -s -X POST "https://api.hiapi.ai/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @request.json | python -m json.tool
Mientras iteras, guarda el cuerpo de la solicitud en un archivo (request.json): así el prompt se mantiene legible y editar el prompt se convierte en un diff de una línea en lugar de un juego de adivinanzas con comillas.
Inspecciona la carga antes de escribir el analizador. Fíjate en si la imagen se devuelve en línea o como URL, qué campos llevan el identificador de la imagen y cualquier prompt modificado, y si la respuesta incluye metadatos de uso. Anota esos nombres de campo; tu cliente de Python dependerá de ellos.
Confirmar todo el flujo de extremo a extremo
Guarda la imagen devuelta, ábrela y comprueba que lo que recibiste es lo que pediste. Una respuesta 200 con un cuerpo JSON plausible no equivale a una imagen correcta: es precisamente en este punto donde los problemas de prompt y de parámetros se detectan con menos coste.
Traducir la solicitud a Python
Ahora porta exactamente la misma solicitud. Mantenlo sencillo: una función, tiempos de espera explícitos y, por ahora, sin reintentos ocultos.
import os
import requests
HIAPI_API_KEY = os.environ["HIAPI_API_KEY"]
ENDPOINT = "https://api.hiapi.ai/v1/images/generations"
def generate_image(prompt: str, size: str = "1024x1024", n: int = 1) -> dict:
"""Genera una imagen con minimax-h3-image a través de HiAPI."""
payload = {
"model": "minimax-h3-image",
"task": "text-to-image",
"prompt": prompt,
"size": size,
"n": n,
}
response = requests.post(
ENDPOINT,
headers={
"Authorization": f"Bearer {HIAPI_API_KEY}",
"Content-Type": "application/json",
},
json=payload,
timeout=(5, 120), # tiempo de espera de conexión, de lectura
)
response.raise_for_status()
return response.json()
Hay cuatro decisiones deliberadas en esa función:
- Tiempo de espera en tupla. El tiempo de espera de conexión es corto, porque una conexión lenta indica un problema; el de lectura es más holgado, porque la generación de imágenes naturalmente lleva tiempo. Un único valor de tiempo de espera te obliga a hacerlo mal en uno de los dos modos de fallo.
json=payload. Deja que la biblioteca serialice el cuerpo. Las cadenas JSON concatenadas a mano son un caldo de cultivo para errores de comillas.raise_for_status()antes de analizar. La comprobación del estado no es opcional: analizar un cuerpo de error como si fuera un éxito es el tipo de bug más confuso en este tipo de integraciones.- Devolver un
dictsimple. Más adelante podrás envolverlo con modelos tipados; primero asegúrate de saber qué campos contiene realmente la respuesta.
Aislar la búsqueda de la clave
Si falta la variable, os.environ["HIAPI_API_KEY"] lanza una excepción inmediatamente. Esto es intencionado: falla al arrancar, no en la primera solicitud del usuario. En un código base más grande, resuelve la clave una vez durante la carga de la configuración y pasa un cliente ya configurado en lugar de leer la variable de entorno en el punto de llamada.
Conectar la ejecución
if __name__ == "__main__":
result = generate_image("Una cometa roja sobre una playa húmeda con la marea baja, luz de día nublado")
print(result)
Ejecútalo y compara con la salida de curl. La estructura de la carga debería coincidir. Si no coincide, has encontrado una discrepancia que merece la pena aclarar antes de seguir construyendo.
Gestionar errores en lugar de adivinar
El bug de integración más común es reintentar un error que nunca tendrá éxito. Clasifica los fallos en tres categorías y trátalos de forma diferente.
Fallos de autenticación y autorización
Normalmente se manifiestan como 401 o 403. Las causas incluyen: una cabecera ausente, un prefijo Bearer mal formado, una clave revocada o mal configurada, o un proyecto sin acceso a ese modelo. No son reintentables. Reintentar solo pierde tiempo y contamina los registros con el mismo fallo. Corrige las credenciales y continúa.
Fallos de validación de la solicitud
Normalmente son respuestas de nivel 400: valores de model o task desconocidos, un size no compatible con el modelo, n fuera de rango, un prompt vacío, JSON mal formado. Tampoco son reintentables: la misma solicitud fallará de la misma manera. El trabajo útil consiste en presentar el mensaje de error tal cual al desarrollador que escribió la solicitud, en lugar de tragárselo con una excepción genérica.
Fallos transitorios del servidor y de la red
Las respuestas 429 y 5xx, junto con los reinicios de conexión y los tiempos de espera de lectura, son la categoría realmente reintentable. Gestiona estos con retroceso exponencial acotado y jitter:
import time, random, requests
def post_with_retry(session, url, payload, max_attempts=4):
for attempt in range(max_attempts):
try:
r = session.post(url, json=payload, timeout=(5, 120))
if r.status_code in (429, 500, 502, 503, 504):
raise requests.HTTPError(f"Error transitorio {r.status_code}", response=r)
r.raise_for_status()
return r.json()
except (requests.ConnectionError, requests.Timeout, requests.HTTPError) as exc:
if attempt == max_attempts - 1:
raise
time.sleep(min(2 ** attempt + random.random(), 30))
Dos advertencias. Primera: un HTTPError provocado por un 4xx que no sea 429 debe propagarse inmediatamente hacia fuera; no dejes que la cláusula except absorba los fallos de validación. Segunda: sigue cualquier indicación de reintento que venga en la respuesta, en lugar de inventar tú mismo el retraso.
Aquí los reintentos no son idempotentes
Cada generación reintentada es una nueva generación facturada. Si la solicitud agota el tiempo de espera, es posible que la imagen ya se haya generado y facturado. Mantén el número de reintentos bajo, registra el número de intentos junto con los metadatos de la solicitud en los registros y prioriza mostrar un fallo explícito en lugar de generar silenciosamente la misma imagen cuatro veces.
Hábitos prácticos de higiene para prompts y parámetros
El sentido de estos hábitos es la comparabilidad: cuando cambias una cosa, deberías poder determinar si el cambio en la salida se debe a ello.
Escribir prompts que especifiquen el contenido de la escena
Describe en el orden: sujeto, escena, iluminación, composición. Los sustantivos concretos y los términos fotográficos (como "luz suave de una ventana orientada al norte", "profundidad de campo reducida") aportan más señal que apilar adjetivos estéticos. Evita el uso masivo de prompts negativos; describe lo que debería aparecer.
Cambiar una sola variable a la vez
Mantén un pequeño archivo de prompts por proyecto y edítalo entre ejecuciones, en lugar de reescribirlo desde cero. Si una ejecución decepciona, cambia el prompt o cambia los ajustes, pero no ambos. De lo contrario, no podrás saber qué cambio fue el responsable.
Tratar los ajustes como un contrato explícito
size y n afectan tanto a la salida como al coste. Fíjalos en un objeto de configuración en lugar de pasar literales por los distintos puntos de llamada, de modo que cambiar la relación de aspecto de toda una función sea una sola edición. Si necesitas varias imágenes para comparar, solicítalas en una sola llamada en lugar de en varias: menos idas y vueltas y registros más legibles.
Almacenar el prompt junto con la salida
Persiste junto a cada imagen generada la cadena de prompt exacta, los ajustes y el identificador del modelo. Un prompt que no se puede reproducir es una imagen que no se puede regenerar, depurar ni mejorar. Este hábito ahorra más tiempo que cualquier truco de prompting.
Establecer una base para comparar
Un mismo prompt puede producir imágenes distintas entre ejecuciones. Cuando evalúes un cambio, compara resultados agregados (varias imágenes por configuración) en lugar de confiar en una única muestra afortunada o desafortunada.
Versionar los prompts
Trata el texto del prompt como código: guárdalo en archivos, revisa los cambios y registra qué versión del prompt produjo qué recurso. Esto convierte "¿por qué empeoraron las imágenes el martes pasado?" en una pregunta respondible.
Lista de comprobación de producción antes de desplegar
Una solicitud que funciona es la parte fácil. Las siguientes comprobaciones distinguen una demostración de una integración.
- Establecer tiempos de espera en cada llamada. Define explícitamente el tiempo de espera de conexión y el de lectura, nunca uses los valores predeterminados. Un endpoint de generación sin tiempo de espera de lectura acabará bloqueando un worker.
- Reintentos acotados, solo para errores reintentables. Limita el número de intentos, añade jitter y asegúrate de que los fallos de validación y autenticación evitan por completo la ruta de reintento.
- Gestión de claves. Lee la clave del entorno o de un almacén de secretos, nunca del código fuente. Rótala sin necesidad de cambiar el código.
- Registro estructurado. Registra el identificador del modelo, el prompt (o su hash más una referencia), los ajustes, el estado HTTP, el número de intentos y cualquier identificador de solicitud de la respuesta. Sin esto, los problemas de imagen no serán reproducibles.
- Visibilidad de costes. La generación se factura por salida, así que el uso depende de cuántas imágenes pidas y con qué frecuencia reintentes. Decide de antemano si las solicitudes se ejecutan por usuario, por tarea o en segundo plano, y haz un seguimiento del volumen en consecuencia: consulta el panel de precios en tiempo real del sitio web para conocer las tarifas actuales, en lugar de codificar suposiciones.
- Definir el comportamiento ante fallos. Decide qué encuentra el usuario cuando la generación falla tras el intento final: un estado de error, un marcador de posición o un reintento en cola. Un respaldo indefinido se convierte en una experiencia de usuario indefinida.
- Fijar el esquema de la carga. Almacena y valida los campos de respuesta de los que dependes, para que los cambios en la carga se manifiesten como errores explícitos en lugar de
Nonesilenciosos.
Paso final de verificación
Ejecuta el comando curl, la función de Python y una solicitud rota a propósito (primero una clave incorrecta, luego un parámetro incorrecto), y confirma que cada una produce el fallo que esperas. Este último paso es el que te dice que el manejo de errores es real y no decorativo.
Una vez que la solicitud está autenticada, portada, reintentada de forma sensata y registrada, la integración puede pasar a segundo plano detrás del resto de la aplicación.
Artículos relacionados
Ver todos los artículos →-
Tutorial
Guía práctica de gpt-6.2-sol: 5 usos de alto valor de los modelos de texto en el negocio
-
Tutorial
Guía práctica de gpt-6.2-astra: puntos clave de integración e implementación en 5 escenarios de texto de alto valor
Lista de verificación desde la perspectiva del desarrollador: de la selección de escenarios a la implementación en ingeniería
-
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