Cómo usar flux-2/image-to-image a través de la API de hiapi: curl, Python y ejemplos de solicitud disponibles

En resumen

• Qué es: la solución disponible para llamar a la API flux-2/image-to-image en hiapi: crear una tarea, consultar su estado y descargar el resultado.
• Endpoint: usa POST https://api.hiapi.ai/v1/tasks especificando "model": "flux-2/image-to-image", y luego GET /v1/tasks/<taskId> hasta que la tarea alcance un estado terminal.
• Campos de entrada obligatorios (los cuatro): prompt, image_urls (1–8 URL públicas; esta es la función de múltiples imágenes de referencia), aspect_ratio y resolution (1K o 2K).
• El esquema es estricto. Campos como strength o fidelity no existen y serán rechazados con un 400. La fidelidad se controla con tus imágenes de referencia, el prompt y resolution, no con un parámetro independiente.

Qué vas a construir y qué necesitas preparar

Objetivo: enviar a flux-2 una o varias imágenes de referencia junto con un prompt de texto y recibir una imagen editada/redibujada descargable, usando curl o Python, sin SDK.

Requisitos previos:

1. Una clave de API de hiapi; créala en la consola de hiapi. La clave tiene la forma sk-... y se incluye en la cabecera Authorization: Bearer.
2. Al menos una URL de imagen accesible públicamente para usar como referencia. La API obtiene image_urls en el servidor, por lo que los enlaces a localhost o las URL de buckets privados no sirven: usa un bucket público, un CDN o una URL prefirmada.
3. curl, o Python 3.8+ con requests (pip install requests).

Esquema de la solicitud

flux-2/image-to-image se ejecuta sobre la interfaz de tareas unificada de hiapi. El objeto input acepta exactamente los siguientes campos:

Campo	Tipo	Obligatorio	Descripción
prompt	string	Sí	Lo que se quiere modificar o generar. Mínimo 3 caracteres.
image_urls	string[]	Sí	1–8 URL de imágenes públicas. Más de una = múltiples imágenes de referencia: flux-2 fusiona las señales de identidad, producto o estilo entre todas las referencias.
aspect_ratio	string	Sí	Uno de 1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3 o auto (sigue la imagen de referencia).
resolution	string	Sí	1K o 2K.

Cualquier otro campo será rechazado. Por ejemplo, enviar un campo strength o fidelity devuelve:

{
  "code": 400,
  "error_code": "INVALID_REQUEST",
  "message": "invalid input: <root>: additional properties 'fidelity', 'strength' not allowed"
}

Conviene tenerlo presente: el modo imagen a imagen de flux-2 no tiene un parámetro de intensidad de ruido. El grado de fidelidad del resultado respecto a la imagen de referencia (edición "de alta fidelidad" frente a un redibujado más libre) depende de cómo redactes el prompt; por ejemplo, "mantén el producto, su etiqueta y sus proporciones exactamente como en la imagen de referencia; solo cambia el fondo", y además de usar resolution: "2K" para trabajos que exigen detalle.

Ejemplo mínimo funcional: curl

Paso 1: crear la tarea:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2/image-to-image",
    "input": {
      "prompt": "Place this product on a white marble countertop with soft morning light, keep the product itself unchanged",
      "image_urls": ["https://your-cdn.example.com/product.jpg"],
      "aspect_ratio": "1:1",
      "resolution": "2K"
    }
  }'

Si la creación se realiza correctamente, se devuelve el ID de tarea en data.taskId.

Paso 2: consultar hasta que termine:

curl -s https://api.hiapi.ai/v1/tasks/TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

Mientras data.status no sea un estado terminal, sigue consultando cada pocos segundos. Cuando "status": "success", la URL de la imagen está en data.output[0].url.

Paso 3: descargar el resultado de inmediato:

curl -s -o result.jpg "OUTPUT_URL"

Las URL de salida llevan una marca de tiempo expireAt: son temporales. Tras el éxito de la tarea, descarga los bytes de inmediato (o cópialos a tu propio almacenamiento); no enlaces directamente las salidas de la tarea en producción.

Ejemplo mínimo funcional: Python

Un script completo (crear, consultar, descargar) que solo usa requests:

import time
import requests

API_KEY = "sk-YOUR_KEY"
BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

def create_task() -> str:
    resp = requests.post(BASE, headers=HEADERS, json={
        "model": "flux-2/image-to-image",
        "input": {
            "prompt": ("Combine the person from the first image with the jacket "
                       "from the second image, studio lighting, neutral backdrop"),
            "image_urls": [
                "https://your-cdn.example.com/person.jpg",
                "https://your-cdn.example.com/jacket.jpg",
            ],
            "aspect_ratio": "3:4",
            "resolution": "2K",
        },
    }, timeout=30)
    body = resp.json()
    task_id = (body.get("data") or {}).get("taskId")
    if not task_id:
        raise RuntimeError(f"create failed: {body}")
    return task_id

def wait_task(task_id: str, timeout_s: int = 600, poll_s: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        task = requests.get(f"{BASE}/{task_id}", headers=HEADERS,
                            timeout=30).json().get("data") or {}
        status = task.get("status")
        if status == "success":
            return task
        if status == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        time.sleep(poll_s)
    raise TimeoutError(f"task {task_id} still running after {timeout_s}s")

task_id = create_task()
print("task:", task_id)
task = wait_task(task_id)
url = task["output"][0]["url"]          # URL temporal: guárdala de inmediato
img = requests.get(url, timeout=120).content
with open("result.jpg", "wb") as f:
    f.write(img)
print("saved result.jpg,", len(img), "bytes")

Fíjate en que aquí se usan dos imágenes en image_urls: este es el uso real de las múltiples imágenes de referencia. Se aceptan hasta 8 imágenes de referencia; el modelo las combina entre sí (persona + prenda, producto + estilo de fondo, personaje + referencia de pose, etc.).

Notas para producción

Usa callbacks en lugar de sondeo. Para cualquier caso que vaya más allá de un script, registra un callback al crear la tarea para que hiapi envíe el resultado final a tu servicio:

{
  "model": "flux-2/image-to-image",
  "input": { "...": "..." },
  "callback": { "url": "https://your-app.example.com/hooks/hiapi", "when": "final" }
}

Con "when": "final", recibirás una única POST cuando la tarea alcance un estado terminal. Regla general: el sondeo va bien para CLI, procesamiento por lotes y cualquier escenario de vida corta; los callbacks son mejores para aplicaciones orientadas al usuario, porque mantener un bucle de sondeo por cada imagen en un worker no escala. Si no puedes exponer un endpoint de callback público, usa sondeo, pero espacia el intervalo a 5 segundos o más.

Haz que los reintentos sean seguros. Trata la creación de tareas como lo que es, un efecto secundario: antes de actuar según el resultado, guarda el taskId devuelto en tu propio registro de trabajos; al reintentar, vuelve a comprobar el estado de la tarea ya almacenada en lugar de crear una nueva tarea a ciegas (cada creación correcta se factura por separado). Si tu ejecutor de trabajos puede dispararse dos veces, deduplica primero por tu propio ID de trabajo.

Gestiona los errores que realmente encontrarás:

• 401 permission_denied: clave incorrecta, o la clave no tiene permiso para usar ese modelo. El cuerpo de la respuesta es:

  {"error": {"code": "permission_denied",
             "message": "This API key cannot use the selected model. ...",
             "type": "hiapi_error"}}
  

  Revisa la clave en la consola; nuestra lista de comprobación de claves de API no válidas cubre las causas habituales.

• 400 INVALID_REQUEST: infracción del esquema. message enumera de una vez todos los campos infractores (campos obligatorios ausentes, valores de enumeración incorrectos, campos adicionales desconocidos), así que léelo completo en lugar de corregir un solo campo por reintento.

• Tarea con status: "fail": la tarea se aceptó pero la generación falló; el error está en data.error. Gestiónalo en la ruta de sondeo/callback, no en el momento de la creación.

• URL de salida caducada: si la descarga devuelve 4xx unos minutos después del éxito, es que esperaste demasiado. Vuelve a comprobar expireAt y descarga siempre de inmediato.

Lecturas relacionadas

• Página del modelo flux-2/image-to-image: parámetros y precio actual
• Página del modelo flux-2/text-to-image: la misma familia, sin imágenes de referencia
• flux-2 para imágenes de producto de comercio electrónico: solución de extremo a extremo desde el lado de texto a imagen
• FLUX 1.1 Pro en hiapi: comparación con la opción de la generación anterior
• Precios de hiapi: coste por imagen según la resolución

Preguntas frecuentes

¿Cuántas imágenes de referencia puedo pasar a flux-2 imagen a imagen? De 1 a 8, como URL públicas en image_urls. Más de 8 provoca un fallo de validación (maxItems: got N, want 8).

¿Existe un parámetro strength o fidelity? No. El esquema de entrada solo acepta prompt, image_urls, aspect_ratio y resolution; los campos desconocidos se rechazan con un 400. Controla la fidelidad mediante la redacción del prompt (indica explícitamente qué debe permanecer sin cambios) y usa 2K cuando el detalle importe.

¿Qué resoluciones y relaciones de aspecto se admiten? resolution es 1K o 2K. aspect_ratio es uno de 1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3 o auto; auto sigue tu imagen de referencia, que suele ser lo deseado al editar.

¿Puedo enviar imágenes en base64 en lugar de URL? No: image_urls acepta URL y deben ser accesibles públicamente para que la API las obtenga. Sube primero a un bucket o CDN y pasa la URL generada (las URL prefirmadas sirven).

¿Cuánto cuesta cada imagen en flux-2 imagen a imagen? El precio varía según la resolución: consulta la página del modelo flux-2/image-to-image y la página de precios para conocer la tarifa actual por imagen.

¿Cuánto tiempo es válida la URL de la imagen generada? Las URL de salida son temporales e incluyen el campo expireAt. Tras el éxito de la tarea, descarga los bytes de la imagen de inmediato y guárdalos por tu cuenta.

¿Cuál es la diferencia entre flux-2/image-to-image y flux-2/text-to-image? Es la misma familia de modelos en modos distintos: texto a imagen genera solo a partir del prompt, mientras que imagen a imagen requiere de 1 a 8 imágenes de referencia y edita o combina a partir de ellas. Sus esquemas de entrada son diferentes, por lo que los cuerpos de solicitud no son intercambiables.