Tutorial
Uso de flux-2/image-to-image a través de la API de HiAPI: tutorial con curl y Python
En esta página
Qué hace flux-2/image-to-image y en qué escenarios se usa
flux-2/image-to-image es un endpoint de edición, no un generador puro de texto a imagen. Debes darle dos cosas: una imagen de referencia y una instrucción de edición escrita en lenguaje natural. El modelo lee la imagen de referencia como contexto visual —sujeto, composición, estilo, iluminación— y genera una nueva imagen que sigue tus instrucciones y a la vez está anclada en esa referencia.
Esta distinción importa al diseñar el pipeline. Con texto a imagen describes todo desde cero y luego confías en que el modelo caiga cerca de tu intención. Con imagen a imagen ya tienes un material visual y lo que quieres es una transformación controlada: rediseñar el estilo de una foto de producto, reemplazar el fondo, ajustar el ambiente de una escena o iterar un diseño manteniendo estable la composición de base.
Escenarios adecuados
- Variantes de material. Generar varios tratamientos estilizados a partir de una referencia ya aprobada.
- Edición guiada. Aplicar cambios puntuales («haz que la luz sea más cálida», «cambia el fondo por una pared de estudio de color liso») sin regenerar toda la escena.
- Consistencia en un conjunto de resultados. Reutilizar la misma imagen de referencia para que un lote de salidas comparta el mismo ancla visual.
- Herramientas de colaboración humano-máquina. Permitir que el usuario suba una imagen, describa la modificación y reciba el resultado dentro de tu propia interfaz.
Escenarios no adecuados
- Retoque o composición con precisión a nivel de píxel. Es un modelo generativo, no un editor de imágenes raster.
- Casos sin ninguna imagen de referencia: en esos casos, texto a imagen es un mejor punto de partida.
- Cualquier flujo de trabajo en el que se espere que la instrucción por sí sola cargue con todo el detalle; la referencia cumple su función en la práctica, y una referencia mala solo produce resultados malos.
Entiende este endpoint como imagen de referencia + instrucción -> imagen editada. Todo el contenido de este tutorial se basa en esa forma: cómo enviar, cómo leer el resultado devuelto y cómo mantenerlo funcionando cuando la red no colabora.
Requisitos previos y configuración de autenticación
Antes de la primera llamada, prepara tres cosas.
1. Una cuenta de HiAPI
Regístrate y abre la consola. Todas las solicitudes de este tutorial se envían a través de la API unificada de HiAPI, así que no necesitas registrarte por separado en cada proveedor ni instalar un SDK para cada uno.
2. Una clave de API
Crea una clave de API en la consola. Trátala como una contraseña: no la confirmes en el repositorio, no la pegues en el código del cliente ni la registres en los logs. La práctica estándar es cargarla en tiempo de ejecución desde una variable de entorno:
export HIAPI_API_KEY="your-api-key-here"
Luego referencia HIAPI_API_KEY allí donde necesites la clave. Si despliegas en un contenedor o en una plataforma serverless, configúrala como secreto en ese entorno en lugar de hornearla en la imagen.
3. Una imagen de referencia accesible
El endpoint necesita una imagen de referencia, así que decide de antemano cómo la vas a proporcionar. Dos formas habituales:
- Una URL que la API pueda descargar, por ejemplo un enlace firmado que apunte a tu propio almacenamiento de objetos.
- Bytes codificados en Base64, enviados en línea dentro del cuerpo de la solicitud; esto evita exponer URLs internas, pero aumenta el tamaño del payload.
Elige primero una imagen de prueba pequeña: unos cientos de KB bastan para validar la integración. Las cargas de archivos grandes ralentizan cada reintento y también dificultan la depuración.
Punto de control
A estas alturas ya deberías tener una clave almacenada en una variable de entorno y una imagen de prueba accesible desde tu máquina. Procura que la clave no aparezca en el historial del shell (un archivo .env cargado por la herramienta suele ser más limpio que exportarla en línea dentro de la línea de comandos).
Hay otro hábito que conviene adoptar desde ahora: registrar el ID de solicitud y el tiempo de ejecución desde el primer día. Cuando algo falla en producción, la diferencia entre una solicitud rastreable y una que no lo es resulta enorme.
Construir la solicitud: imagen de referencia e instrucción de edición
Cada llamada de imagen a imagen se construye en torno a dos entradas. Si aciertas con estas dos, el resto es trabajo de infraestructura.
Entrada uno: la imagen de referencia
La imagen de referencia es el ancla. Le dice al modelo qué contiene la escena y cómo se ve antes de cualquier edición. Consejos prácticos:
- Haz coincidir la relación de aspecto con la salida que deseas. Si la referencia es un plano panorámico ancho y necesitas una salida cuadrada, según la configuración de la llamada, espera recortes o deformación.
- Parte de una imagen limpia y bien iluminada. Una referencia turbia produce ediciones turbias.
- Mejor con un único sujeto claro. Un collage desordenado da al modelo demasiados anclas que compiten entre sí.
Entrada dos: la instrucción de edición
La instrucción es la descripción en lenguaje natural del cambio que quieres. Aquí es donde se origina la mayor parte de la diferencia de calidad. Trátala como un prompt que lleva adjunta una imagen de referencia.
- Expresa el cambio, no toda la escena. «Cambia el fondo por una pared de estudio de color blanco puro» es mejor que «producto sobre fondo blanco»; esto último induce al modelo a redibujarlo todo.
- Indica qué debe conservarse. Expresiones como «mantén la pose y la composición del sujeto sin cambios» reducen notablemente la deriva.
- Especifica estilo e iluminación. «Luz suave de día nublado, colores poco saturados» da al modelo más información útil que «hazlo más bonito».
- Evita contradicciones. Si la referencia es una escena exterior de día y pides un interior nocturno, espera que el modelo tome una decisión que quizá no te guste.
Cuerpo de la solicitud
Lo que envías a flux-2/image-to-image contiene el identificador del modelo, la imagen de referencia y la instrucción. Un modelo mental útil:
{
"model": "flux-2/image-to-image",
"input": {
"image": "<URL o imagen de referencia en base64>",
"prompt": "<instrucción de edición>"
}
}
Si tu referencia está en base64, constrúyela como data URI según el esquema de la solicitud, o pasa la codificación sin procesar junto con el tipo MIME. Si es una URL, asegúrate de que el enlace sea accesible públicamente durante la llamada; un enlace firmado que caduca a mitad de la solicitud produce fallos difíciles de entender.
Itera primero, integra después
Antes de conectar nada al código, escribe dos o tres instrucciones para la misma imagen de referencia y compara las salidas. El modelo se comporta de forma predecible cuando la instrucción es concreta y de forma inestable cuando es ambigua; aprenderlo ahora resulta mucho más barato que en producción.
Una solicitud curl funcional
La forma más rápida de validar clave, imagen de referencia e instrucción es una llamada con curl. El ejemplo siguiente asume que tu clave está en HIAPI_API_KEY y que la imagen de referencia es accesible mediante URL.
curl -sS -X POST "https://api.hiapi.ai/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "flux-2/image-to-image",
"input": {
"image": "https://your-bucket.example.com/reference.jpg",
"prompt": "Cambia el fondo por una pared de estudio de color blanco puro. Mantén sin cambios la pose y la composición del sujeto, así como la iluminación sobre el sujeto."
}
}'
Hay varios puntos que conviene tener en cuenta:
- La clave viaja en la cabecera
Authorizationcomo token bearer. Nunca la pongas en la URL. Content-Typees JSON. Olvidar configurarlo es una causa habitual de errores 4xx confusos.- El id del modelo va en el cuerpo de la solicitud, de modo que el mismo endpoint puede enrutarse a otros modelos cambiando un solo campo.
- La instrucción es una frase completa, no una lista de palabras clave. Esto es intencional; consulta la sección anterior.
Leer la salida en bruto
Ejecútala una vez y observa la respuesta completa antes de escribir cualquier código de análisis. Si te resulta útil, procésala con una herramienta de formateo:
curl -sS -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
Guardar el cuerpo de la solicitud en un archivo (request.json) facilita la iteración más que editar cadenas entrecomilladas del shell, y además te da un artefacto persistente que luego puedes usar para reproducir errores.
Si necesitas base64 en lugar de URL
Sustituye el valor de image por un data URI construido a partir de tu archivo:
python - <<'PY'
import base64, json, pathlib
data = base64.b64encode(pathlib.Path("reference.jpg").read_bytes()).decode()
body = {
"model": "flux-2/image-to-image",
"input": {
"image": f"data:image/jpeg;base64,{data}",
"prompt": "Haz que la luz sea más cálida y reduce un poco el contraste.",
},
}
pathlib.Path("request.json").write_text(json.dumps(body))
PY
Ahora la misma llamada con curl funciona, porque el payload está guardado en request.json. Si la llamada tiene éxito, ya tienes todo lo necesario para pasar a Python.
La misma llamada en Python
La versión en Python se mantiene deliberadamente sencilla: construye el mismo diccionario, lo envía con las mismas cabeceras y coloca el endpoint y el modelo en constantes para que no se desvíen de la versión con curl.
import os
import requests
API_URL = "https://api.hiapi.ai/v1/images/generations"
MODEL = "flux-2/image-to-image"
def edit_image(reference_url: str, instruction: str, timeout: float = 60.0) -> dict:
api_key = os.environ["HIAPI_API_KEY"] # falla de inmediato si no está definida
payload = {
"model": MODEL,
"input": {
"image": reference_url,
"prompt": instruction,
},
}
response = requests.post(
API_URL,
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
json=payload,
timeout=timeout,
)
response.raise_for_status()
return response.json()
if __name__ == "__main__":
result = edit_image(
"https://your-bucket.example.com/reference.jpg",
"Cambia el fondo por una pared de estudio de color blanco puro. "
"Mantén sin cambios la pose y la composición del sujeto, así como la iluminación sobre el sujeto.",
)
print(result)
Por qué está organizado así
- Se usa
os.environ["HIAPI_API_KEY"]en lugar de.get(), de modo que la ausencia de la clave provoque un error inmediato en vez de enviar una solicitud sin autenticar. timeoutes explícito. La generación de imágenes no es instantánea; una solicitud sin tiempo de espera acaba bloqueando el proceso de trabajo.- Se llama a
raise_for_status()antes de analizar la respuesta. Quieres una excepción ante un 4xx o 5xx, no unKeyErrorconfuso en algún punto posterior. - El endpoint y el modelo son constantes a nivel de módulo, lo que facilita apuntar la suite de pruebas a un servidor simulado.
Usar entrada en base64
Si pasas bytes en lugar de una URL, codifica el archivo y construye el data URI en el mismo lugar donde construyes el payload:
import base64, pathlib
def as_data_uri(path: str, mime: str = "image/jpeg") -> str:
raw = pathlib.Path(path).read_bytes()
return f"data:{mime};base64," + base64.b64encode(raw).decode()
Luego llama a edit_image(as_data_uri("reference.jpg"), instruction). Separa el paso de codificación de la función de solicitud para poder hacer pruebas unitarias de la validación y del ensamblado del prompt sin tocar la red.
Analizar la respuesta
La llamada devuelve un objeto JSON. Ahora extrae la imagen editada de una forma que no se rompa aunque la respuesta gane campos en el futuro.
Comprueba primero, no supongas
Durante el desarrollo, vuelca una respuesta sin procesar y fíjate dónde está la referencia de la imagen: normalmente una URL o un payload base64 dentro de la estructura de resultados. Después escribe funciones de acceso que comprueben su existencia en lugar de recorrer claves anidadas directamente.
def extract_image_url(response: dict) -> str:
data = response.get("data") or []
if not data:
raise ValueError(f"La respuesta no contiene datos de imagen: {response}")
first = data[0]
url = first.get("url") or first.get("b64_json")
if not url:
raise ValueError(f"Payload de imagen no reconocido: {first}")
return url
Hay dos hábitos en este código que merece la pena conservar: fallar de forma ruidosa incluyendo el payload real en el mensaje de error y aceptar cualquiera de las dos formas (URL o base64) en lugar de fijar una sola. Los formatos de respuesta evolucionan; un lector tolerante sobrevive.
Persiste de inmediato
La URL devuelta puede ser temporal. Si la imagen importa, descárgala en la misma tarea y guárdala en tu propio bucket:
def persist(url: str, dest: str) -> None:
if url.startswith("data:"):
header, b64 = url.split(",", 1)
import base64, pathlib
pathlib.Path(dest).write_bytes(base64.b64decode(b64))
return
with requests.get(url, stream=True, timeout=60) as r:
r.raise_for_status()
with open(dest, "wb") as f:
for chunk in r.iter_content(1 << 16):
f.write(chunk)
La persistencia también te da una clave estable que registrar en la base de datos, mucho más útil que guardar un enlace que puede caducar.
Valida lo que has obtenido
Las comprobaciones baratas detectan errores caros. Confirma que el archivo no está vacío, que su número mágico coincide con algún formato de imagen y, opcionalmente, que sus dimensiones son las esperadas. Rechazar en el límite una imagen corrupta o truncada es mucho mejor que entregársela al usuario.
Registra la procedencia
Almacena junto con la salida el id del modelo, el texto de la instrucción, la clave de la imagen de referencia y la marca de tiempo. Cuando dentro de tres semanas alguien pregunte por qué cierta imagen se ve así, esa línea de registro es la respuesta, y además hace que volver a ejecutar una edición concreta sea trivial.
Reintentos y manejo de errores en producción
Las llamadas de generación de imágenes fallan por motivos muy distintos; mezclarlos es un bug de producción clásico.
Distingue errores transitorios de errores definitivos
- Transitorios: tiempos de espera agotados, conexiones reiniciadas, limitación de tasa 429, respuestas 5xx. La misma solicitud reintentada tras una pausa probablemente tenga éxito.
- Definitivos: 400 solicitud no válida, 401 clave incorrecta o ausente, 404 modelo desconocido, errores de validación del payload. Reintentarlos desperdicia tiempo y dinero, y retrasa la solución real.
Reintenta solo los primeros. Para los segundos, haz fallar la tarea de inmediato y expón el mensaje de error; casi siempre te indica con precisión qué campo tiene el problema.
Reintenta con retroceso exponencial y jitter
import random, time, requests
RETRYABLE = {429, 500, 502, 503, 504}
def call_with_retries(fn, attempts: int = 5, base: float = 1.0):
last = None
for i in range(attempts):
try:
return fn()
except requests.HTTPError as e:
status = e.response.status_code if e.response is not None else None
if status not in RETRYABLE:
raise
last = e
except (requests.Timeout, requests.ConnectionError) as e:
last = e
delay = base * (2 ** i) + random.uniform(0, 0.5)
time.sleep(delay)
raise RuntimeError("Se agotaron los reintentos") from last
El retroceso exponencial evita que golpees repetidamente un servicio ya sobrecargado; el jitter evita que un lote de procesos de trabajo reintente al mismo tiempo. Limita siempre el número de intentos y el tiempo total; un bucle sin límites es peor que un fallo limpio.
Respeta la limitación de tasa
Cuando recibas un 429, respeta cualquier indicación de reintento que venga en las cabeceras de la respuesta antes de aplicar el retroceso. Si ejecutas tareas en lote grandes, añade un límite de concurrencia de tu lado en lugar de depender de que el servidor te limite.
Haz visibles los fallos
- Marca los reintentos con un id de tarea único y registra cada intento con su resultado y su duración.
- Emite métricas sobre la tasa de reintentos; un aumento lento es una alerta temprana de que algo se está degradando en el nivel superior.
- Tras el fallo del último intento, mueve la tarea a una cola de mensajes no procesables con el cuerpo completo de la respuesta, nunca solo con un mensaje como «failed».
Idempotencia y racionalidad de costes
Una solicitud reintentada puede haber tenido éxito en el servidor aunque tu cliente nunca viera la respuesta. Si tu producto no puede tolerar salidas duplicadas, identifica las tareas con tus propios ids y reconcilia antes de reintentar. Y como las llamadas se facturan por uso, cuidado con los bucles de reintento que amplifican el gasto sin que lo notes: un consumidor atascado que reintenta para siempre es el bug más caro en este aspecto.
Errores comunes y próximos pasos
La mayoría de los problemas de integración con flux-2/image-to-image provienen de una pequeña lista de errores. Antes de publicar, revisa tu código contra estos puntos.
- Instrucciones ambiguas. «Mejóralo» produce resultados aleatorios; «elimina el texto del cartel y conserva la forma del cartel» produce resultados utilizables. La concreción es la palanca de calidad más importante.
- Referencia inadecuada. Una relación de aspecto equivocada, una imagen de origen borrosa o un collage desordenado no se salvan por tener un prompt mejor.
- URLs caducadas. Un enlace firmado que expira a mitad de la solicitud provoca fallos que parecen errores del servidor. Usa una validez suficientemente larga o pasa a base64.
- Estructura de respuesta codificada de forma rígida. Recorrer claves anidadas directamente convierte un pequeño cambio de esquema en una caída. Usa extractores defensivos con errores claros.
- Sin tiempo de espera. Un timeout ausente ocupa un proceso de trabajo indefinidamente y oculta el problema real.
- Reintentar errores definitivos. Un 400 no se arregla solo. Lee el mensaje.
- Salida perdida. Si la URL devuelta es temporal y no persistes la imagen, te quedas sin nada.
- Registrar secretos y prompts con descuido. Las claves nunca deben aparecer en los logs; las instrucciones proporcionadas por el usuario pueden requerir anonimización según tu dominio.
Próximos pasos
Cuando el flujo de una sola llamada sea sólido, las ampliaciones naturales son: envolver la llamada en una tarea en segundo plano para que tu interfaz siga respondiendo; almacenar pares instrucción/respuesta para hacer pruebas A/B sobre la redacción del prompt; y, si los usuarios aportan sus propias imágenes, añadir una capa de moderación o validación sobre la entrada. Consulta la página del modelo flux-2/image-to-image y la documentación de HiAPI para ver qué parámetros puede necesitar tu caso de uso a continuación. Construye lo mínimo que funcione, mide y deja que la calidad de las instrucciones cargue con el peso.
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