Cómo usar la API de Bria Eraser: curl, Python y una solicitud que funciona

bria-eraser elimina objetos de las fotos. Envías una imagen y una máscara en blanco y negro, y rellena la zona de la máscara con el fondo correspondiente. No hay campo prompt. Esta guía muestra una solicitud completa en funcionamiento, el código Python que la ejecuta y los detalles que determinan si tu propia máscara funcionará. Necesitas una clave de HiAPI desde el panel.

Solicitud mínima (curl)

El modelo usa el endpoint asíncrono unificado POST /v1/tasks. Las dos URL siguientes son públicas y accesibles en el momento de escribir esto:

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bria-eraser",
    "input": {
      "image_url": "https://dev-static.hiapi.ai/model-onboarding/bria-eraser/2026/10/21/1792546025379-46c31ddb2b52110d-e1-street-src.png",
      "mask_url": "https://dev-static.hiapi.ai/model-onboarding/bria-eraser/2026/10/21/1792546025861-e5d2a17ae1d12d41-e1-street-mask.png",
      "mask_type": "manual"
    }
  }'

La llamada devuelve inmediatamente un id de tarea, no una imagen:

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

Consulta repetidamente GET /v1/tasks/<taskId> hasta que data.status sea success, y luego lee data.output[0].url.

Python: enviar, consultar, descargar

# pip install requests; export HIAPI_KEY=your-key first
import os, time, requests

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

def erase(image_url: str, mask_url: str, out_path: str) -> str:
    r = requests.post(API, headers=HEADERS, timeout=30, json={
        "model": "bria-eraser",
        "input": {"image_url": image_url, "mask_url": mask_url, "mask_type": "manual"},
    })
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]

    for _ in range(60):
        time.sleep(3)
        try:
            d = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        except requests.RequestException:
            continue  # transient network error: poll the SAME task id again
        if d["status"] == "success":
            img = requests.get(d["output"][0]["url"], timeout=60)
            img.raise_for_status()
            with open(out_path, "wb") as f:
                f.write(img.content)
            return task_id
        if d["status"] == "fail":
            raise RuntimeError(f"task {task_id} failed: {d}")
    raise TimeoutError(task_id)

Conserva el id de la tarea. Si una consulta falla, vuelve a consultar ese id. No vuelvas a enviar la solicitud, porque cada envío es una tarea facturada por separado.

Campos de la solicitud

Campo	¿Obligatorio?	Descripción
input.image_url	Sí	URL pública http/https. JPEG, PNG o WEBP.
input.mask_url	Sí	Imagen en blanco y negro con la misma relación de aspecto que la imagen de origen. El blanco se elimina, el negro se conserva.
input.mask_type	No	manual (predeterminado) para máscaras dibujadas con pincel, automatic para máscaras generadas por herramientas de segmentación.
input.preserve_alpha	No	Predeterminado false. Establece true para conservar la transparencia de una entrada con canal alfa.

Producción: usar callbacks

La consulta repetida es adecuada para pruebas. Para un servicio, pasa un callback de nivel superior para que HiAPI te notifique cuando la tarea termine:

{
  "model": "bria-eraser",
  "input": { "image_url": "...", "mask_url": "..." },
  "callback": { "url": "https://your-domain.com/hiapi/callback", "when": "final" }
}

Mantén la consulta repetida como respaldo en caso de que se pierda el callback. Las URL de salida caducan, así que copia el archivo a tu propio almacenamiento en cuanto la tarea tenga éxito.

Lo que ejecuté realmente y lo que vi

Ejecuté la solicitud de la sección de curl el día que escribí esto y la consulté hasta que terminó.

• Secuencia de estados: handling → archiving → success. archiving aparece después de que termina el trabajo y antes de que aparezca output. Considéralo como «aún no terminado» y sigue consultando.
• Tiempo: la tarea tardó 16 segundos desde su creación hasta su finalización. La URL de output apareció unos segundos después.
• Salida: un PNG en temp.hiapi.ai, de 1360 × 768, con canal alfa. Es el mismo tamaño que la imagen de origen, lo que coincide con la indicación de la documentación de conservar la resolución original.
• Facturación: cuando lo consulté, el precio de este modelo en los datos de precios públicos era de $0.0575 por imagen. Consulta los precios actuales en precios.
• Error de validación: probé a propósito a enviar mask_type: "bogus". La API lo rechazó con HTTP 400:

{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: mask_type: value must be one of 'manual', 'automatic'"}

Solo comprobé una solicitud con una imagen. No probé otros estilos de máscara, imágenes muy grandes ni máscaras con una relación de aspecto distinta a la de la imagen. Las indicaciones siguientes sobre esos casos provienen de la documentación del modelo, no de mis pruebas.

Consejos sobre la máscara (según la documentación)

• Pinta un poco más allá del borde del objeto. Las máscaras ajustadas al contorno suelen dejar un halo alrededor del objeto original.
• Mantén la máscara con la misma relación de aspecto que la foto. La documentación lo exige, pero no indica qué ocurre si no se cumple.
• Usa automatic solo para máscaras procedentes de herramientas de segmentación o recorte. Usa manual para máscaras de pincel.

¿Qué página debería leer?

Esta guía trata sobre la eliminación basada en máscaras mediante un endpoint dedicado. Para la edición guiada por prompt con modelos genéricos de imagen a imagen, consulta reparación de imágenes y eliminación de objetos. Si quieres eliminar todo el fondo en lugar de un objeto individual, consulta la guía de eliminación de fondos. La página del modelo está en bria-eraser y la referencia de campos en la documentación de la API.

Preguntas frecuentes

¿bria-eraser necesita un prompt?

No. La documentación indica que no se necesita prompt, y la solicitud que ejecuté solo contenía la imagen, la máscara y mask_type.

¿Qué color de la máscara se elimina?

El blanco se elimina, el negro se conserva.

¿La salida será más pequeña que la entrada?

En mi ejecución, la salida fue de 1360 × 768, exactamente igual que la imagen de origen.

¿Debería consultar repetidamente o usar callbacks?

Consulta repetidamente durante las pruebas. En producción, usa callback.url y when: "final", con la consulta repetida como respaldo.