Blog

Tutorial

Cómo llamar a flux-1-fill-pro mediante la API de HiAPI: curl, Python y sondeo asíncrono

Nov 12, 2026
Imagen de portada del blog de HiAPI: sobre un fondo azul índigo oscuro, tres flechas anchas anidadas avanzan progresivamente en dirección horizontal, con el borde frontal en naranja albaricoque, en un estilo de diagrama de flujo de señales plano.
En esta página

Qué hace flux-1-fill-pro y cuándo usarlo

flux-1-fill-pro es un modelo de edición de imágenes de tipo relleno. Le proporcionas una imagen de origen y una máscara que marca las regiones que se van a regenerar, y devuelve una nueva imagen en la que esas regiones han sido sustituidas. Las zonas fuera de la máscara deberían permanecer inalteradas, y ahí radica precisamente su diferencia con los modelos de texto a imagen puros o los de estilización de la imagen completa.

Úsalo cuando la edición sea local y el contexto circundante importe:

  • Eliminación de objetos — delimita con la máscara los elementos no deseados y deja que el modelo reconstruya lo que debería haber detrás de ellos.
  • Sustitución de objetos — delimita la región con la máscara, describe el nuevo contenido en el prompt y mantén el resto de la escena sin cambios.
  • Retoque local — corrige texturas, reflejos o pequeños defectos sin regenerar toda la imagen.
  • Inserción en el canal de procesamiento — retoca mediante código imágenes de producto, miniaturas o material generado, donde solo una región necesita un segundo tratamiento.

No es la herramienta adecuada cuando quieres una composición totalmente nueva a partir de un prompt, ni cuando tu región con máscara es tan grande que el modelo, en la práctica, genera la imagen desde cero: en esos casos, el endpoint de generación estándar resulta mucho más predecible.

El resto de esta guía trata sobre cómo integrar flux-1-fill-pro en tu código mediante la API de HiAPI: la estructura de la solicitud, la llamada con curl, el equivalente en Python y la gestión de tareas asíncronas, que es donde suelen tropezar la mayoría de las primeras integraciones.

Preparación y configuración de la autenticación

Antes de enviar tu primera solicitud, confirma tres cosas.

Clave de API

Crea una clave en tu cuenta de HiAPI y mantenla alejada del control de versiones. Los ejemplos siguientes la leen de una variable de entorno, de modo que los fragmentos pueden copiarse sin riesgo:

export HIAPI_API_KEY="your_key_here"

En Python, cárgala del mismo modo mediante os.environ. Si ejecutas esto en CI, inyéctala como secreto en lugar de confirmar un archivo .env.

Identificador del modelo

Cada solicitud especifica el modelo por su nombre. En esta guía, el identificador es flux-1-fill-pro. Consérvalo como constante en el código en lugar de dispersar literales de cadena: así, cambiar de modelo más adelante será cuestión de una sola línea.

URL base

Todas las llamadas van a la URL base de la API de HiAPI que se documenta en la referencia de la plataforma. Guárdala en la configuración junto con la clave, de modo que los entornos de preproducción y producción puedan diferir sin cambios en el código.

Un recordatorio estructural antes de empezar: las solicitudes de relleno transportan datos de imagen. Envíalas como imágenes codificadas en base64 dentro de JSON, en lugar de intentar forzar una carga mediante formulario; y mantén un tiempo de espera de solicitud holgado en el cliente, ya que codificar imágenes grandes añade latencia antes incluso de que la solicitud salga de tu proceso. Consulta la documentación de la plataforma para conocer los límites actuales de tamaño de carga útil; si tu imagen de origen supera el límite documentado, redúcela antes de codificarla en lugar de dejar que la solicitud falle en el borde.

Estructura de una solicitud de reparación local

Cada llamada a flux-1-fill-pro tiene la misma composición lógica, sea cual sea el lenguaje en que la escribas.

Imagen de origen

La imagen que vas a editar, codificada como cadena. Define el lienzo: sus dimensiones determinan el espacio de coordenadas en el que vive la máscara, y su contenido proporciona al modelo el contexto que hace que el relleno resulte creíble.

Máscara

La máscara marca qué regiones se van a regenerar. Esta es la fuente de confusión más habitual, así que ten claro qué convención usa tu carga útil: las regiones marcadas por la máscara son las que el modelo puede modificar. Construye la máscara como una imagen aparte, en la que el área a rellenar y el área a conservar se distingan visualmente con claridad. Invertir la máscara es el error clásico: obtendrás un resultado en el que el modelo ha editado todo excepto la región que querías.

La máscara debe tener exactamente las mismas dimensiones que la imagen de origen. Una máscara dibujada a otra resolución se rechaza o se desalinea en silencio, y ambos resultados desperdician un viaje de ida y vuelta.

Prompt

La descripción textual de lo que debe aparecer dentro de la máscara. Sé concreto y local: describe el contenido y su relación con el entorno en cuanto a iluminación o textura, no toda la escena. «Un banco de madera que continúa la moldura del escaparate, con luz suave de tarde por la izquierda» da al modelo mucho más en qué basarse que «un fondo más bonito».

Controles opcionales

Según el conjunto de parámetros documentado, es posible que también puedas pasar parámetros como una semilla para lograr reproducibilidad, o parámetros de intensidad que controlan cuánto puede el relleno desviarse de los píxeles originales. Para los parámetros que no existan en la referencia actual, trátalos como no admitidos en lugar de adivinar sus nombres.

Estos cuatro elementos —modelo, prompt, imagen de origen y máscara— se envían en el mismo cuerpo JSON. Las dos secciones siguientes envían precisamente ese cuerpo.

Una solicitud curl funcional

Empieza con curl, para que puedas ver el sobre sin procesar antes de que cualquier biblioteca cliente lo oculte.

curl -sS -X POST "$HIAPI_BASE_URL/v1/images/edits" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json

Donde request.json tiene este aspecto:

{
  "model": "flux-1-fill-pro",
  "prompt": "Un banco de madera que continúa la moldura del escaparate, con luz suave de tarde por la izquierda",
  "image": "<base64-encoded source image>",
  "mask": "<base64-encoded mask image>"
}

Hay dos trucos prácticos para construir ese archivo. Primero, genera las cargas útiles en base64 con un comando, en lugar de pegarlas a mano:

base64 -w 0 source.png > source.b64
base64 -w 0 mask.png > mask.b64

Después, insértalas con un pequeño paso de jq o Python y ensambla request.json. Editar a mano bloques base64 de varios megabytes dentro de JSON es justo la raíz de las cargas útiles truncadas y de los errores 400 desconcertantes.

Interpretación de la respuesta

El sobre de respuesta te indica qué hacer a continuación. Una tarea completada devuelve la imagen editada, normalmente como URL o como campo base64, según el formato que estipule la referencia actual. Una tarea en cola devuelve un identificador y un estado, que después tendrás que sondear (véase más abajo). No des por hecho que la primera respuesta siempre contiene píxeles; escribe tu analizador desde el primer día para manejar ambas formas, o tendrás que reescribirlo la primera vez que las tareas se pongan en cola bajo carga.

Comprueba el código de estado HTTP antes de analizar el cuerpo de la respuesta. Un 4xx significa que la solicitud en sí es errónea y reintentarla no servirá de nada; corrige la carga útil en su lugar.

La misma llamada implementada en Python

La versión en Python es la misma solicitud, pero más cómoda de usar. No se necesita SDK: con requests para llamar al endpoint de HiAPI es suficiente.

import base64
import json
import os
import time

import requests

BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "flux-1-fill-pro"


def b64(path: str) -> str:
    with open(path, "rb") as f:
        return base64.b64encode(f.read()).decode("ascii")


def create_fill(source_path: str, mask_path: str, prompt: str) -> dict:
    payload = {
        "model": MODEL,
        "prompt": prompt,
        "image": b64(source_path),
        "mask": b64(mask_path),
    }
    resp = requests.post(
        f"{BASE_URL}/v1/images/edits",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        data=json.dumps(payload),
        timeout=120,
    )
    if resp.status_code >= 400:
        raise RuntimeError(f"HiAPI error {resp.status_code}: {resp.text}")
    return resp.json()

El timeout está ahí a propósito. Codificar y subir imágenes grandes tarda más que una llamada JSON típica, y las solicitudes sin límite son la causa de que los scripts se queden colgados en silencio en tareas por lotes. Lanzar una excepción ante un 4xx junto con el cuerpo de la respuesta convierte un fallo misterioso en un fallo legible.

Mantén el identificador del modelo y el endpoint en la configuración a nivel de módulo, de modo que una actualización de versión requiera un solo cambio. Si procesas muchas imágenes, reutiliza una requests.Session para que las conexiones se agrupen en lugar de reabrirse en cada llamada.

El diccionario analizado será o bien un resultado completado, o bien un manejador de tarea; la siguiente sección aborda lo segundo.

Gestión de tareas asíncronas y sondeo

Las solicitudes de relleno pueden ser lentas, por lo que la API puede devolver un manejador de tarea en lugar de una imagen acabada. El patrón correcto es un bucle de sondeo acotado, no un sleep fijo y a rezar.

El bucle

def wait_for_result(job: dict, *, interval=2.0, timeout=180.0) -> dict:
    deadline = time.monotonic() + timeout
    current = job
    while time.monotonic() < deadline:
        status = current.get("status")
        if status in {"succeeded", "completed"}:
            return current
        if status in {"failed", "canceled", "cancelled"}:
            raise RuntimeError(f"Job ended as {status}: {current}")
        time.sleep(interval)
        interval = min(interval * 1.5, 15.0)  # retroceso suave
        current = fetch_job(current["id"])
    raise TimeoutError(f"Job {job.get('id')} exceeded {timeout}s")

fetch_job sigue el mismo patrón de solicitud que el anterior, usando el id de la tarea y tus cabeceras de autenticación contra el endpoint documentado de estado de tareas.

Por qué retroceso en lugar de intervalo fijo

Sondear una cola en un bucle apretado golpea la API sin ninguna ganancia. Empezar con un intervalo corto y multiplicarlo hasta un límite mantiene la capacidad de respuesta ante finalizaciones tempranas sin desperdiciar miles de sondeos en tareas lentas. Pon un techo al intervalo para seguir detectando la finalización en cuestión de segundos.

Por qué un tiempo de espera y un fallo no son lo mismo

Un tiempo de espera significa que tú has dejado de esperar, no que la tarea haya fallado. Conserva el id de la tarea al lanzar la excepción, para que quien llama pueda reanudar el sondeo más tarde sin volver a enviar la solicitud y pagar dos veces por el mismo trabajo. Trata el tiempo de espera, el fallo de la tarea y el error HTTP como tres excepciones distintas en tu canal de procesamiento: reducirlas a un único error genérico hace que los incidentes en producción sean mucho más difíciles de diagnosticar.

Depuración de fallos habituales

La mayoría de las respuestas de error encajan en unas pocas categorías. Compruébalas en este orden.

401 / 403 — autenticación

Comprueba primero: ¿la cabecera es exactamente Authorization: Bearer <key>, sin comillas y sin espacios en blanco sobrantes procedentes de una variable de shell que nunca se exportó? Un $HIAPI_API_KEY vacío produce un token Bearer que solo contiene la palabra Bearer, y falla igual que una clave incorrecta.

400 — carga útil mal formada

Comprueba primero: ¿el cuerpo sigue siendo JSON válido después de concatenar las cadenas base64? Extrae request.json y pásalo por python -m json.tool. El prefijo data:image/png;base64, en los campos de imagen es una causa habitual; elimínalo, salvo que la referencia exija explícitamente lo contrario.

Máscara e imagen no coinciden

Comprueba primero: ¿tienen la máscara y la imagen de origen exactamente las mismas dimensiones en píxeles? Después verifica la polaridad: confirma que la región blanca es la que quieres que el modelo regenere. Que el resultado parezca lo contrario de lo que pediste se debe casi siempre a una máscara invertida, no a un problema con el prompt.

Desbordamiento del prompt

Si las zonas sin máscara cambian, o si el relleno parece global, puede que tu máscara sea demasiado grande o que el prompt abarque toda la escena. Reduce ambos: ajusta la máscara a la región real de edición y describe solo lo que hay dentro de la máscara.

Tiempo de espera de la tarea

Comprueba primero: el tamaño de la carga útil. Una imagen de origen demasiado grande es la causa más frecuente de que una tarea nunca termine. Reduce la imagen, reinténtalo una vez y, si sigue agotándose el tiempo, contrasta con una imagen de prueba pequeña frente a los límites de la referencia antes de dar por hecho que el problema es del servicio.

Campo de resultado vacío o ausente

Comprueba primero: ¿has gestionado la forma de la respuesta en cola? Un analizador que solo lee la forma completada no verá nada en la primera llamada. Registra el sobre de respuesta completo durante el desarrollo, para que la forma quede visible antes de escribir código defensivo.

Artículos relacionados

Ver todos los artículos →

Empieza a crear con artefactos de IA persistentes

Consigue tu API key y llama a modelos de imagen, vídeo y audio a través de una única API basada en tasks.

Leer la documentación de la API