Tutorial
Cómo llamar a la generación de imagen a imagen de minimax-h3-image con curl y Python en hiapi
En esta página
Qué espera el endpoint de imagen a imagen
Antes de escribir cualquier código, resulta útil entender la estructura de una llamada de imagen a imagen. El endpoint de imagen a imagen de minimax-h3-image recibe tus imágenes de referencia (una o varias) junto con un prompt de texto y devuelve un resultado recién generado que sigue el prompt y, a la vez, se ancla a las imágenes de referencia.
Conceptualmente, cada solicitud consta de tres partes:
- Enrutamiento del modelo: direccionas
minimax-h3-imagemediante la tareaimage-to-image, todo a través de un único endpoint de hiapi. No necesitas credenciales ni hosts separados para cada capacidad. - Entrada: una cadena de prompt, una o varias imágenes de referencia (URL o carga útil en base64) y controles de generación como el nivel de resolución.
- Contrato de salida: la llamada es asíncrona. Obtienes un identificador de tarea, luego consultas el estado y, cuando la tarea termina, recuperas la URL de la imagen generada.
Este último punto es importante. La imagen a imagen no es una llamada bloqueante que te devuelve los píxeles en la misma respuesta. Considera la llamada de envío como "poner el trabajo en cola" y diseña el cliente en torno al ciclo de vida de la tarea desde el principio. Si diseñas primero asumiendo un comportamiento síncrono, más adelante tendrás que reescribir el código de integración.
Como todo fluye a través de la misma interfaz de hiapi, las cabeceras, la autenticación y el envoltorio de respuesta son consistentes entre modelos y tareas. Apréndelo una vez para minimax-h3-image y el mismo patrón se aplicará en el resto de la plataforma.
Una solicitud mínima ejecutable
Empieza con la solicitud más pequeña que demuestre que tus credenciales, el endpoint y la estructura de la carga útil son correctos. No te apresures a añadir todos los campos opcionales desde el principio.
El cuerpo mínimo de la solicitud contiene:
- El nombre del modelo
minimax-h3-image - El tipo de tarea
image-to-image - Un
promptque describa qué transformación deseas - Un único campo de imagen de referencia
- Un nivel de resolución
Conceptualmente, la carga útil se ve más o menos así:
{
"model": "minimax-h3-image",
"task": "image-to-image",
"input": {
"prompt": "Convierte este boceto en un render de producto limpio sobre fondo blanco",
"image": "https://example.com/reference.png",
"resolution": "1024"
}
}
Envíala, confirma que se devolvió un id de tarea y luego consulta manualmente una o dos veces para observar las transiciones de estado. Si obtienes un id de tarea, la conectividad y la autenticación están bien y puedes pasar a construir el cliente real. Si no, detente y lee el cuerpo de la respuesta de error; normalmente señalará directamente el campo problemático.
Guarda esta solicitud como prueba de humo. Cuando cambios posteriores rompan tu canalización, volver a ejecutar esta solicitud mínima te dirá de inmediato si el problema está en tu carga útil o en el código circundante.
Llamada con curl
curl es la forma más rápida de ver la solicitud y la respuesta sin procesar. Escribe el cuerpo JSON en un archivo para no tener que pelearte con las comillas del shell al editarlo.
cat > payload.json <<'JSON'
{
"model": "minimax-h3-image",
"task": "image-to-image",
"input": {
"prompt": "Convierte esta foto a un estilo de ilustración en acuarela",
"image": "https://example.com/reference.png",
"resolution": "1024"
}
}
JSON
curl -sS -X POST "$HIAPI_BASE_URL/v1/tasks" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
--data @payload.json
Dos cabeceras hacen el trabajo principal: Authorization con el token bearer y Content-Type: application/json. Mantén ambas fuera del control de versiones: lee la clave de una variable de entorno en lugar de pegarla en el comando.
Cuando el envío tenga éxito, captura el id de tarea devuelto y consúltalo:
curl -sS "$HIAPI_BASE_URL/v1/tasks/$TASK_ID" \
-H "Authorization: Bearer $HIAPI_API_KEY"
La respuesta incluye un campo de estado y, cuando termina, el resultado. Usa jq para extraer solo los campos que te interesan:
curl -sS "$HIAPI_BASE_URL/v1/tasks/$TASK_ID" \
-H "Authorization: Bearer $HIAPI_API_KEY" | jq '.status, .result'
También es la forma más sencilla de depurar la carga útil: curl muestra exactamente qué enviaste y qué se devolvió, sin que ninguna biblioteca cliente oculte nada.
Llamada con Python
La versión en Python debe reflejar el flujo de curl: enviar, capturar el id, consultar hasta el estado terminal y obtener el resultado. Usa requests y una Session para gestionar una sola vez la reutilización de conexiones y las cabeceras predeterminadas.
import os
import time
import requests
BASE = os.environ["HIAPI_BASE_URL"]
KEY = os.environ["HIAPI_API_KEY"]
HEADERS = {
"Authorization": f"Bearer {KEY}",
"Content-Type": "application/json",
}
def submit(prompt: str, image: str, resolution: str = "1024") -> str:
body = {
"model": "minimax-h3-image",
"task": "image-to-image",
"input": {
"prompt": prompt,
"image": image,
"resolution": resolution,
},
}
resp = requests.post(f"{BASE}/v1/tasks", json=body, headers=HEADERS, timeout=30)
resp.raise_for_status()
return resp.json()["id"]
def poll(task_id: str, timeout: float = 300, interval: float = 2.0) -> dict:
deadline = time.monotonic() + timeout
while time.monotonic() < deadline:
resp = requests.get(f"{BASE}/v1/tasks/{task_id}", headers=HEADERS, timeout=30)
resp.raise_for_status()
data = resp.json()
status = data.get("status")
if status in ("succeeded", "failed"):
return data
time.sleep(interval)
raise TimeoutError(f"La tarea {task_id} no se completó en {timeout} segundos")
if __name__ == "__main__":
task_id = submit(
"Convierte esta imagen en un póster vectorial plano",
"https://example.com/reference.png",
)
print("Enviada:", task_id)
result = poll(task_id)
print(result)
Detalles clave: raise_for_status() convierte los errores HTTP en excepciones en lugar de fallar silenciosamente; el bucle de sondeo tiene tanto una fecha límite como un intervalo; los estados terminales se comprueban explícitamente. Solo analiza la URL de la imagen desde el objeto de resultado después de que el estado haya llegado a un estado terminal, nunca antes.
Uso de varias imágenes de referencia
A menudo una sola imagen de referencia no basta. Puede que quieras conservar la cara de una foto y tomar la composición de otra, o combinar una textura y un contorno. La generación de imagen a imagen de Minimax-h3-image admite entradas de referencia múltiples mediante el campo plural image.
Estructuralmente, el objeto input puede llevar una sola imagen de referencia en el campo image, y cuando tienes varias, un array images:
{
"model": "minimax-h3-image",
"task": "image-to-image",
"input": {
"prompt": "Conserva la persona de la primera imagen y usa el estilo de fondo de la segunda",
"images": [
"https://example.com/person.png",
"https://example.com/background.png"
],
"resolution": "1024"
}
}
El orden importa. El índice de referencia 0 es tu sujeto principal y las entradas posteriores son contexto auxiliar, así que redacta el prompt de forma coherente con el orden en que las envías. Si el resultado ignora una imagen de referencia, la causa habitual es un prompt ambiguo, no un campo roto: haz que el prompt diga explícitamente qué imagen determina qué atributo.
Reglas prácticas para trabajar con múltiples referencias:
- Mantén el número reducido. Usa solo las imágenes de referencia que el prompt específico realmente necesita; añadir extras diluye el control.
- Iguala la relación de aspecto en la medida de lo posible, para que el modelo no tenga que conciliar composiciones en conflicto.
- Usa de forma coherente URL públicas o base64 dentro de la misma solicitud, sin mezclar métodos de transporte.
Durante la integración, envía una vez una solicitud con dos imágenes para verificar que ambas referencias influyen claramente en la salida, y luego construye lógica más compleja sobre esa base.
Selección del nivel de resolución
El campo resolution elige el nivel de salida para la generación de imagen a imagen de minimax-h3-image. No es solo un ajuste estético: cambia la cantidad de cómputo, la latencia de respuesta y el tamaño de la carga útil que acabarás manejando.
Cómo sopesarlo:
- Elige el nivel más pequeño que satisfaga el caso de uso objetivo. Una miniatura para una vista de lista no necesita el mismo nivel que un banner principal. Reducir la resolución de una salida de alta resolución después es una pérdida de tiempo y de dinero.
- Espera que la latencia crezca con la resolución. Los niveles más altos hacen más trabajo por solicitud, así que tu presupuesto de tiempo de espera y de intervalo de sondeo debe reflejar el nivel elegido.
- Vigila el tamaño de la carga útil. Tanto las entradas de referencia en base64 como las salidas de alta resolución aumentan el volumen de transferencia; si mueves muchas imágenes, presta atención al cuerpo de la solicitud y de la respuesta.
La facturación sigue el nivel de resolución que solicitas: las solicitudes se facturan según el nivel con el que se ejecutan, así que usar un nivel demasiado grande para casos pequeños encarece las cosas sin que te des cuenta. Consulta las tarifas en vivo en el panel de precios en lugar de codificar suposiciones fijas.
Una estrategia de integración razonable es usar un nivel medio durante el desarrollo a cambio de velocidad y, una vez fijados el prompt y el conjunto de imágenes de referencia, subir los recursos clave a un nivel superior. Cambiar la resolución más tarde invalida tus mediciones de latencia, así que haz las pruebas de referencia en el nivel que realmente piensas usar en producción.
Gestión del ciclo de vida asíncrono
Cada llamada de imagen a imagen en hiapi sigue el mismo ciclo: enviar, capturar el id de tarea, consultar hasta el estado terminal y luego obtener el resultado. Hacer robusto este ciclo es la mayor parte del trabajo de un cliente de nivel de producción.
Enviar y registrar
Trata el id de tarea como tu identificador persistente. Regístralo en cuanto llegue la respuesta de envío, antes de hacer cualquier otra cosa: si el proceso falla durante el sondeo, este id te permite reanudar en lugar de volver a generar.
Sondear con retroceso
Un sondeo fijo de dos segundos está bien para uso interactivo, pero desperdicia recursos en lotes largos. Empieza con un intervalo corto y auméntalo gradualmente, con un límite máximo para seguir detectando la finalización a tiempo.
def next_interval(current: float, cap: float = 15.0, factor: float = 1.5) -> float:
return min(current * factor, cap)
Respetar los estados terminales
Sal del bucle solo cuando haya éxito o fracaso. Tratar cualquier respuesta no vacía como "completada" es el error asíncrono más común: acabarás leyendo un resultado que aún no existe.
Poner límites a todo
Establece tiempos de espera para cada llamada HTTP y una fecha límite global para la tarea. Si pasa la fecha límite, lanza un error claro en lugar de seguir girando en vacío. Para errores de red transitorios, reintenta el sondeo con retroceso; no reenvíes a ciegas, ya que eso genera trabajo duplicado.
Limpieza
Una vez obtenido el resultado, conserva la URL de la imagen o los bytes en tu propio almacenamiento sin demora. Los resultados de las tareas son identificadores temporales, no el CDN a largo plazo de tu aplicación.
Solución de problemas y lista de verificación para producción
Estos son los fallos que los desarrolladores encuentran primero al usar la generación de imagen a imagen de minimax-h3-image, junto con las comprobaciones que los evitan.
Fallos en la primera ejecución
- 401 / 403: el token bearer falta, ha caducado o tiene espacios en blanco al principio o al final. Confirma que la variable de entorno está exportada en el shell que ejecuta la solicitud.
- 422 o error de validación: revisa el cuerpo de la respuesta de error; normalmente indicará el campo. Una causa común es poner
prompten el nivel superior en lugar de dentro deinput. - JSON mal formado: valida tu archivo de carga útil con
jq .antes de enviarlo.
Fallos en tiempo de ejecución
- La tarea nunca termina: confirma que estás consultando con el id que realmente recibiste, no con un marcador de posición. Comprueba que tu fecha límite sea lo bastante larga para el nivel de resolución elegido.
- El resultado de una tarea "completada" está vacío: lee el campo de estado con precisión; los estados de fallo también devuelven un cuerpo de respuesta.
- Se ignoran las imágenes de referencia: antes de culpar al modelo, revisa la redacción del prompt y el orden de las imágenes de referencia.
Lista de verificación antes del lanzamiento
- La clave de API y la URL base se leen de variables de entorno y nunca se confirman en el repositorio.
- Cada llamada HTTP tiene un tiempo de espera explícito.
- El sondeo usa retroceso acotado con una fecha límite global estricta.
- Los estados terminales se gestionan explícitamente; no se cae en la rama de análisis del resultado.
- Los resultados los descarga y almacena tu aplicación, en lugar de enlazarlos en caliente desde la respuesta de la tarea.
- Los prompts con múltiples referencias indican qué imagen controla qué atributo.
- El nivel de resolución se ha probado en el valor que piensas usar en producción.
- Los registros guardan el id de tarea para que los trabajos fallidos puedan rastrearse y reanudarse.
Siempre que algo falle, vuelve a ejecutar la solicitud mínima anterior: aislará si el problema está en tu carga útil o en el código circundante. Con la estructura de la solicitud, los clientes en curl y Python, el manejo de múltiples referencias y un bucle de sondeo disciplinado, tienes todo lo necesario para lanzar de forma fiable la generación de imagen a imagen de minimax-h3-image en hiapi.
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