Tutorial

¿Cómo usar la API de FLUX.1 Fill Pro? Domina tu primer repintado con máscara en 5 minutos

Los cuatro requisitos estrictos de la máscara, 4 pasos para la prueba en línea y 4 pasos para la integración con la API, con curl y Python listos para ejecutar.

Oct 28, 2026

TL;DR

Qué es: el modelo de repintado local con máscara de Black Forest Labs. Sube la imagen original, una máscara en blanco y negro del mismo tamaño y un prompt; solo se repinta la zona blanca y la zona negra se conserva tal cual. Ya está disponible en HiAPI: abre la página del modelo y pruébalo; los usuarios nuevos reciben 200 créditos al registrarse.
Cuánto cuesta: $0.0715 por imagen (143 créditos), se cobra por imagen generada con éxito; steps, guidance, seed y el formato de salida no añaden coste, y si falla se devuelve la retención. Con $10 obtienes unas 139 imágenes.
Cómo llamarlo lo más rápido: POST https://api.hiapi.ai/v1/tasks, escribe flux-1-fill-pro en model y coloca los tres campos image, mask y prompt dentro de input; tras obtener el taskId, consulta en bucle o espera el callback y descarga data.output[0].url.

El error más habitual en el repintado con máscara no son los parámetros, sino los materiales: la máscara debe tener el mismo tamaño que la imagen original y la zona blanca debe cubrir solo lo que quieres cambiar. A continuación aclaremos primero estas dos cosas y luego hagamos el primer repintado.

¿Qué es FLUX.1 Fill Pro?

Es un modelo de edición que «solo cambia la zona que marcas». El alcance del cambio lo determina la máscara, no el texto, así que los muebles, las sombras y la línea del horizonte de alrededor no cambian.

La máscara solo cubre el pequeño trozo de pared del reloj y la salida es de 1440 × 810. El tapiz de la izquierda, los platos trenzados, el cráneo de bisonte, las plantas, el sofá y la iluminación no se repintaron.

Tres entradas. Imagen original (JPEG / PNG / GIF / WebP), máscara en blanco y negro del mismo tamaño y prompt (máximo 4.000 caracteres).
Bordes controlables. Lo blanco se repinta y lo negro se conserva; el cambio se detiene en el borde de la máscara, ideal para tareas de «tocar solo un punto» como retoque de productos, sustitución de fondos o cambio de color de prendas.
La salida sigue a la imagen original. No hay parámetro de relación de aspecto: la proporción se copia de la imagen original; una imagen de 1600 × 900 devuelve 1440 × 810, ajustada a múltiplos de 32.
Parámetros suficientes y sencillos. steps 15–50 con 50 por defecto, guidance 1.5–100 con 60 por defecto, seed opcional y salida jpg / png.

A large framed abstract painting in warm terracotta, sand and cream tones, hanging on the wall, with a thin dark wood frame; keep the room, sofa, furniture and lighting unchanged.

Generar con este prompt → El enlace solo rellena el prompt: el campo de imagen original está vacío y el campo de máscara trae por defecto la máscara de ejemplo. Sustitúyelos por tu propia imagen original y una máscara del mismo tamaño, y luego pulsa ejecutar.

¿Cómo preparar la máscara?

Cuatro puntos clave, en este orden:

Solo dos valores, blanco y negro. La zona blanca es la que se repinta y la negra la que se conserva. Los bordes grises difuminan el límite; procura crear bordes nítidos.
El tamaño debe coincidir exactamente con el de la imagen original. Una imagen de 1600 × 900 va con una máscara de 1600 × 900. No hagas una captura de pantalla y luego la escales: exporta la máscara directamente desde el mismo archivo; si el ancho y el alto no coinciden, la tarea fallará.
La zona blanca debe ceñirse al objetivo. Detente cuando cubras lo que quieres cambiar; no incluyas muebles, superficies o sombras de alrededor.
Exporta en PNG a la resolución de la imagen original. El PNG no tiene ruido de compresión y deja los bordes más limpios; coloca la máscara y la imagen original en direcciones accesibles públicamente, porque la interfaz recibe URL, no archivos subidos.

Lo negro se conserva y lo blanco se repinta. Esta máscara de 1600 × 900 solo deja un marco blanco en la posición del reloj, por eso solo se repinta ese trozo de pared.

Prueba en línea: la primera imagen en 4 pasos

La página del modelo no permite dibujar máscaras; la máscara debe prepararse en tu propia herramienta y subirse después.

Abre la página del modelo FLUX.1 Fill Pro, regístrate o inicia sesión; las cuentas nuevas incluyen 200 créditos.
Sube la imagen original y luego una máscara en blanco y negro del mismo tamaño.
Pega el prompt: describe solo lo que debe aparecer en la zona blanca y especifica claramente qué debe conservarse.
Pulsa ejecutar. Por defecto: steps 50, guidance 60 y salida jpg; primero logra que funcione y luego ajusta los parámetros.

Al pulsar «Generar con este prompt» para abrir la página, el prompt se rellena automáticamente. El campo de imagen original está vacío y el campo de máscara trae la máscara de ejemplo por defecto; cámbiala por la tuya antes de ejecutar.

Integración con la API: 4 pasos

Crea una API Key (sk-...) en la consola.
POST /v1/tasks crea la tarea; incluye image, mask y prompt dentro de input.
Consulta con GET /v1/tasks/{taskId} o añade callback.url en la solicitud y espera la notificación.
Cuando data.status pase a success, descarga la imagen desde data.output[0].url y guárdala de inmediato en tu propio almacenamiento.

La tabla completa de campos, los códigos de error y la descripción de parámetros están en la documentación en chino.

Primer repintado con máscara: versión curl

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-1-fill-pro",
    "input": {
      "image": "https://static.hiapi.ai/model-onboarding/flux-1-fill-pro/prod-migrate/2026/10/21/1792572565867-4e5072a121d7018f-1792418738578-4e5072a121d7018f-source.jpg",
      "mask": "https://static.hiapi.ai/model-onboarding/flux-1-fill-pro/prod-migrate/2026/10/21/1792572569695-82bb18075f29c864-1792418739459-82bb18075f29c864-mask.png",
      "prompt": "A large framed abstract painting in warm terracotta, sand and cream tones, hanging on the wall, with a thin dark wood frame; keep the room, sofa, furniture and lighting unchanged.",
      "steps": 50,
      "guidance": 60,
      "output_format": "png"
    }
  }'

El ID de la tarea devuelta está en data.taskId:

{"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

Consulta del resultado:

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

Las dos imágenes anteriores son precisamente el material de referencia uno a uno: la imagen original de 1600 × 900 y la máscara del mismo tamaño; ejecútalas directamente y obtendrás el efecto del cuadro colgado de la primera imagen de este artículo.

Primer repintado con máscara: versión Python

Creación, consulta en bucle y descarga en una sola pieza; solo tienes que poner tu propia Key y ejecutar:

import requests, time

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

payload = {
    "model": "flux-1-fill-pro",
    "input": {
        "image": "https://static.hiapi.ai/model-onboarding/flux-1-fill-pro/prod-migrate/2026/10/21/1792572565867-4e5072a121d7018f-1792418738578-4e5072a121d7018f-source.jpg",
        "mask": "https://static.hiapi.ai/model-onboarding/flux-1-fill-pro/prod-migrate/2026/10/21/1792572569695-82bb18075f29c864-1792418739459-82bb18075f29c864-mask.png",
        "prompt": "A large framed abstract painting in warm terracotta, sand and cream tones, hanging on the wall, with a thin dark wood frame; keep the room, sofa, furniture and lighting unchanged.",
        "steps": 50,
        "guidance": 60,
        "output_format": "png",
    },
}

resp = requests.post(API, headers=HEADERS, json=payload, timeout=30)
task_id = resp.json()["data"]["taskId"]

while True:
    status = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    if status["status"] in ("success", "fail"):
        break
    time.sleep(3)

if status["status"] == "success":
    image_url = status["output"][0]["url"]
    with open("fill-pro-edit.png", "wb") as f:
        f.write(requests.get(image_url, timeout=60).content)
else:
    print(status.get("error"))

¿Cómo ajustar los parámetros?

Cambia solo uno a la vez; así, cuando notes la diferencia, sabrás qué elemento la produjo.

steps (15–50, por defecto 50): cuanto más alto, más fino el detalle; el valor por defecto ya sirve para entregar, y bajarlo solo tiene sentido cuando primas la velocidad.
guidance (1.5–100, por defecto 60): cuanto más alto, más se ciñe al prompt. Si el estilo se desvía, súbelo primero; si la imagen se vuelve rígida, bájalo.
seed: tras la versión final, fija un valor para volver a resultados similares con la misma imagen, la misma máscara y el mismo prompt, lo que facilita revertir y unificar lotes.
output_format: por defecto jpg; si quieres conservar el máximo detalle o vas a procesar la imagen de nuevo después, escribe png.
prompt_upsampling: por defecto false. Al activarlo se reescribe automáticamente tu prompt; si quieres controlar por completo la redacción, déjalo desactivado.

4 cosas a tener en cuenta antes de publicar

No se puede dibujar la máscara en la página. Tanto la página del modelo como la API solo aceptan una imagen de máscara ya preparada, y su tamaño debe coincidir con el de la imagen original. Prepara la máscara en Photoshop, Figma o una herramienta de segmentación antes de subirla; en la página solo se puede subir, no pintar.
En el servidor, usa callbacks. Añade al cuerpo de la solicitud "callback": {"url": "https://yourapp.com/webhook", "when": "final"}; la tarea notifica automáticamente al terminar, lo que es más cómodo que consultar en bucle; mantén la consulta en bucle como respaldo.
Ante un timeout, no repitas el POST. Cada POST /v1/tasks crea una tarea nueva y se cobra por separado. Guarda primero el taskId y, al reintentar, reutiliza la misma tarea para consultar.
La dirección de salida caduca. Descarga y guarda el archivo en cuanto recibas el resultado; no trates la URL como una dirección permanente. Además, la proporción de salida sigue a la imagen original y no hay parámetro de relación de aspecto; si necesitas una posición fija, recorta tú mismo según la proporción.

Preguntas frecuentes

¿Se puede usar sin pasar máscara? No. image, mask y prompt son obligatorios; la máscara debe ser una imagen en blanco y negro del mismo tamaño que la imagen original.

¿Cuánto debe medir el prompt? Máximo 4.000 caracteres, pero basta con lo necesario: una frase sobre lo que debe aparecer en la zona blanca y otra sobre lo que debe conservarse. Cuanto más concreta sea la descripción de los detalles, más estable será el resultado.

¿El tamaño de salida es igual al de la imagen original? La proporción es la misma, pero los píxeles se ajustan a múltiplos de 32. Una imagen de 1600 × 900 devuelve 1440 × 810; si vas a superponerla sobre la original, primero unifica los tamaños.

¿Se cobra si la generación falla? No. El importe retenido de las tareas fallidas se devuelve automáticamente en su totalidad.

Genera tu primera imagen ahora

Los dos materiales de referencia anteriores (imagen original + máscara) sirven directamente para practicar: copia el cuerpo de la solicitud de curl, cámbialo por tu propia API Key y ejecútalo una vez, o abre la página del modelo, sube estas dos imágenes; el prompt ya está rellenado y al pulsar ejecutar obtendrás el mismo resultado. Esta imagen cuesta $0.0715; los 200 créditos de regalo del registro alcanzan para una imagen.

Artículos de la serie FLUX.1 Fill Pro

Etiquetasintegración-de-api Tutorial Integración de API Tutorial