Come usare l'API Bria Eraser: curl, Python e una richiesta eseguibile

bria-eraser rimuove oggetti dalle foto. Invii un'immagine e una maschera in bianco e nero, e il modello riempie l'area della maschera con uno sfondo corrispondente. Non esiste un campo prompt. Questa guida mostra una richiesta completa ed eseguibile, il codice Python che la esegue e i dettagli che determinano se la tua maschera funzionerà. Devi ottenere una chiave HiAPI dalla dashboard.

Richiesta minima (curl)

Il modello usa l'endpoint asincrono unificato POST /v1/tasks. Entrambi gli URL seguenti sono pubblici e accessibili al momento della stesura:

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 chiamata restituisce immediatamente un id del task, non un'immagine:

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

Esegui il polling di GET /v1/tasks/<taskId> finché data.status non è success, poi leggi data.output[0].url.

Python: invia, esegui il polling, scarica

# 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 l'id del task. Se un polling fallisce, esegui di nuovo il polling di quell'id. Non inviare di nuovo la richiesta, perché ogni invio è un task fatturato separatamente.

Campi della richiesta

Campo	Obbligatorio	Descrizione
input.image_url	Sì	URL http/https pubblico. JPEG, PNG o WEBP.
input.mask_url	Sì	Immagine in bianco e nero con lo stesso rapporto d'aspetto dell'immagine sorgente. Il bianco viene cancellato, il nero viene mantenuto.
input.mask_type	No	manual (predefinito) per maschere disegnate a pennello, automatic per maschere generate da strumenti di segmentazione.
input.preserve_alpha	No	Predefinito false. Imposta true per preservare la trasparenza di input con canale alpha.

Produzione: usare i callback

Il polling va bene per i test. Per i servizi, passa un callback di primo livello affinché HiAPI ti notifichi al completamento del task:

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

Mantieni il polling come fallback nel caso i callback vadano persi. Gli URL di output scadono, quindi copia i file nel tuo storage il prima possibile dopo il successo del task.

Cosa ho effettivamente eseguito e visto

Ho eseguito la richiesta della sezione curl il giorno della stesura e ho fatto polling fino al completamento.

• Sequenza degli stati: handling → archiving → success. archiving compare dopo che il lavoro è terminato e prima che appaia output. Trattalo come "non ancora completato" e continua il polling.
• Tempi: il task ha impiegato 16 secondi dalla creazione al completamento. L'URL di output è apparso pochi secondi dopo.
• Output: un PNG su temp.hiapi.ai, 1360 × 768, con canale alpha. È della stessa dimensione della sorgente, in linea con la documentazione che indica la conservazione della risoluzione originale.
• Fatturazione: al momento della verifica, i dati di prezzo pubblici indicavano $0.0575 per immagine per questo modello. Per i prezzi attuali vedi la pagina prezzi.
• Errore di validazione: ho testato intenzionalmente l'invio di mask_type: "bogus". L'API lo ha rifiutato con HTTP 400:

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

Ho verificato una sola richiesta su una sola immagine. Non ho testato altri stili di maschera, immagini molto grandi o maschere con rapporto d'aspetto diverso da quello dell'immagine. Le indicazioni seguenti su questi casi provengono dalla documentazione del modello, non dai miei test.

Consigli sulla maschera (dalla documentazione)

• Dipingi leggermente oltre il bordo dell'oggetto. Le maschere aderenti al contorno tendono a lasciare un alone attorno all'oggetto originale.
• Mantieni la maschera con lo stesso rapporto d'aspetto della foto. La documentazione lo richiede, ma non specifica cosa succede in caso contrario.
• Usa automatic solo per maschere provenienti da strumenti di segmentazione o scontorno. Per le maschere a pennello usa manual.

Quale pagina dovrei leggere?

Questa guida tratta la rimozione basata su maschera con un endpoint dedicato. Per modifiche guidate da prompt con un modello generico di image-to-image, vedi inpainting e rimozione di oggetti. Se vuoi rimuovere l'intero sfondo invece di un singolo oggetto, vedi la guida alla rimozione dello sfondo. La pagina del modello è bria-eraser, e il riferimento ai campi è nella documentazione API.

Domande frequenti

bria-eraser richiede un prompt?

No. La documentazione indica che non serve un prompt, e la richiesta che ho eseguito conteneva solo immagine, maschera e mask_type.

Quale colore viene rimosso nella maschera?

Il bianco viene cancellato, il nero viene mantenuto.

L'output è più piccolo dell'input?

Nella mia esecuzione, l'output era 1360 × 768, esattamente come la sorgente.

Dovrei fare polling o usare i callback?

Fai polling durante i test. In produzione usa callback.url e when: "final", con il polling come fallback.