Tutorial

Cómo usar la API de FLUX.1 Fill Pro: inpainting con máscara mediante curl y Python

Oct 24, 2026

flux-1-fill-pro es el modelo de inpainting basado en máscara de hiapi: envías una imagen de origen, una máscara en blanco y negro y un prompt, y solo se repintan las zonas blancas. Esta guía ofrece solicitudes funcionales con curl y Python, el flujo asíncrono, y lo que mostró una ejecución real en cuanto a los bordes de la máscara y las dimensiones de salida. Necesitas obtener una API key desde el dashboard.

Estructura de la solicitud

El modelo funciona sobre la API de tareas unificada. Crea una tarea con POST https://api.hiapi.ai/v1/tasks, consulta GET /v1/tasks/<taskId> de forma periódica y luego lee data.output[0].url. Los siguientes campos provienen de la página del modelo y de la documentación de la API:

Campo	Tipo	Descripción
`input.image`	URL, obligatorio	Imagen de origen. JPEG, PNG, GIF o WebP.
`input.mask`	URL, obligatorio	El negro conserva la imagen de origen; el blanco se repinta. Debe coincidir en tamaño con la imagen de origen.
`input.prompt`	string, obligatorio	Describe el nuevo contenido dentro de la zona blanca. Máximo 4.000 caracteres.
`input.steps`	int, 15–50	Predeterminado 50.
`input.guidance`	number, 1.5–100	Predeterminado 60.
`input.seed`	int	Con las mismas entradas, un seed fijo produce resultados consistentes.
`input.output_format`	`jpg` \| `png`	Predeterminado `jpg`.
`input.prompt_upsampling`	bool	Predeterminado `false`. Mantenlo desactivado para conservar tu redacción exacta.

Tanto image como mask son URL, no base64 ni cargas de archivos. Alójalas en una ubicación accesible por la API mediante http(s).

Solicitud curl mínima

curl -s https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-1-fill-pro",
    "input": {
      "image": "https://dev-static.hiapi.ai/model-onboarding/flux-1-fill-pro/2026/10/19/2026/10/19/1792418738578-4e5072a121d7018f-source.jpg",
      "mask": "https://dev-static.hiapi.ai/model-onboarding/flux-1-fill-pro/2026/10/19/2026/10/19/1792418739459-82bb18075f29c864-mask.png",
      "prompt": "Una gran pintura al óleo de un paisaje de montaña y lago brumoso en la niebla matinal, con un marco delgado negro, colgada plana en la pared; mantén el sofá, el suelo y la iluminación sin cambios.",
      "steps": 30,
      "guidance": 60,
      "seed": 42,
      "output_format": "png"
    }
  }'

La respuesta es {"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}. Consulta ese ID de forma periódica hasta que data.status sea success o fail.

Python: crear, consultar y descargar

import os, time, requests

API = "https://api.hiapi.ai"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

def inpaint(image_url, mask_url, prompt, **opts):
    body = {"model": "flux-1-fill-pro",
            "input": {"image": image_url, "mask": mask_url, "prompt": prompt, **opts}}
    r = requests.post(f"{API}/v1/tasks", headers=HEADERS, json=body, timeout=30)
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]

    while True:
        try:
            d = requests.get(f"{API}/v1/tasks/{task_id}", headers=HEADERS, timeout=20).json()["data"]
        except requests.RequestException:
            time.sleep(5)          # error de red transitorio: consulta de nuevo el mismo taskId
            continue
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] == "fail":
            raise RuntimeError(d.get("error", d))
        time.sleep(5)

url = inpaint(
    "https://example.com/room.jpg",
    "https://example.com/room-mask.png",
    "Una pintura de paisaje enmarcada, con un marco delgado negro; mantén la habitación sin cambios.",
    steps=30, seed=42, output_format="png",
)
open("out.png", "wb").write(requests.get(url, timeout=60).content)

Descarga el resultado de inmediato. La URL de salida incluye expireAt y el archivo se almacena de forma temporal, así que no guardes ese enlace como dirección permanente.

Consideraciones para producción

Consulta periódica o callback.Para tareas por lotes, añade "callback": {"url": "https://your-domain.com/hiapi/callback", "when": "final"} al body de la tarea y usa el ID de la tarea para deduplicar las notificaciones. Mantén la consulta periódica como plan de respaldo.
Reintenta la consulta, no la creación.Un nuevo POST crea y factura una tarea nueva. Si una solicitud de consulta falla, vuelve a consultar el mismo taskId.
La máscara debe coincidir con la imagen de origen.La máscara debe coincidir exactamente en tamaño con la imagen de origen, así que genérala a partir del mismo archivo (herramienta de polígonos, salida de segmentación) en lugar de escalar una captura de pantalla.
Fija el seed al ajustar.Usa el mismo seed y cambia solo steps o guidance, de modo que cada diferencia provenga de ese parámetro.

Consulta el costo por imagen en la página de precios y confírmalo antes de ejecutar grandes volúmenes de material.

Lo que mostró una ejecución real

Ejecuté la solicitud curl anterior una vez con la foto de habitación de ejemplo incluida en esta página (1600×900) y su máscara rectangular (recuadro blanco en x 840–1240, y 160–580). Ajustes: steps: 30, guidance: 60, seed: 42, output_format: png.

Duración.La tarea estuvo en handling unos 25 segundos, luego en archiving, y alcanzó success en aproximadamente 38 segundos de extremo a extremo.
Las dimensiones de salida difieren de las de origen.El PNG devuelto fue de 1440×810, no de 1600×900. La relación de aspecto coincide, pero las dimensiones en píxeles no. Si vas a componer el resultado sobre la imagen original, redimensiona una de las dos primero y no des por hecho una correspondencia 1:1.
Fuera de la máscara no cambia nada.Tras escalar la imagen de origen a 1440×810 y compararla con la salida, el 81 % de los píxeles dentro del recuadro blanco cambió más de 8 niveles (0–255), mientras que fuera del recuadro solo lo hizo el 0,03 %. A más de 12 px del borde de la máscara, la diferencia máxima fue de 11 niveles. El sofá, los cojines, la planta, el suelo y la luz de la ventana no se repintaron.
Alcance del prompt.El prompt solo describía el cuadro y lo que debía conservarse, y el resultado fue una escena de montaña y lago enmarcada que llena el recuadro blanco.
Una URL incorrecta falla al consultar, no al crear.Otra solicitud con image y mask establecidos como cadenas que no son URL devolvió 200 y un taskId, y luego la tarea terminó a los ~3 segundos con status: fail y error.code: TASK_FAILED. Que tu POST tenga éxito no significa que la entrada sea válida, así que comprueba siempre el estado final.

Sin probar:máscaras cuyas dimensiones no coinciden con la imagen de origen, máscaras con valores grises (bordes suaves), máscaras con canal alfa, y valores extremos de guidance o steps. La documentación indica que la máscara debe coincidir en tamaño con la imagen de origen, y yo solo probé un rectángulo binario duro. No ejecuté varios seeds, así que no puedo afirmar cuánto varía el relleno entre ejecuciones.

Cuándo elegir Fill Pro

Úsalo cuando la edición deba detenerse en un límite duro que tú controlas, como una etiqueta de producto, una línea de pared o una costura de ropa. Para ediciones descritas con texto y sin máscara, usa un modelo solo de prompt. La guía de inpainting de imágenes y eliminación de objetos los compara. Para borrar algo de una máscara sin escribir un prompt, consulta la guía de Bria Eraser.

Relacionado

Preguntas frecuentes

¿Son obligatorios `image` y `mask`?

Sí. La documentación actual enumera image, mask y prompt como obligatorios.

¿Qué color repinta el modelo?

El blanco. Los píxeles negros conservan la imagen de origen.

¿La máscara debe tener el mismo tamaño que la imagen de origen?

La documentación lo indica así. En mi ejecución usé un par que coincidía y no probé el caso de que no coincidieran.

¿Cómo son las dimensiones de salida?

En mi ejecución, una imagen de origen de 1600×900 devolvió un PNG de 1440×810, con la misma relación de aspecto.

Etiquetasinpainting Edición de imágenes