Comment utiliser l'API Bria Eraser : curl, Python et une requête exécutable

bria-eraser supprime des objets d'une photo. Vous envoyez une image et un masque en noir et blanc, et il remplit la zone masquée avec un arrière-plan assorti. Il n'y a pas de champ prompt. Ce guide présente une requête complète exécutée, le code Python qui l'exécute, et les détails qui déterminent si votre propre masque fonctionnera. Vous devez obtenir une clé HiAPI depuis le tableau de bord.

Requête minimale (curl)

Le modèle utilise le point de terminaison asynchrone unifié POST /v1/tasks. Les deux URL ci-dessous sont publiques et accessibles au moment de la rédaction :

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"
    }
  }'

L'appel renvoie immédiatement un identifiant de tâche, et non une image :

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

Interrogez GET /v1/tasks/<taskId> jusqu'à ce que data.status vaille success, puis lisez data.output[0].url.

Python : soumettre, interroger, télécharger

# 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)

Conservez l'identifiant de tâche. Si une interrogation échoue, interrogez à nouveau cet identifiant. Ne soumettez pas à nouveau, car chaque soumission est une tâche facturée séparément.

Champs de la requête

Champ	Obligatoire	Description
input.image_url	Oui	URL http/https publique. JPEG, PNG ou WEBP.
input.mask_url	Oui	Image en noir et blanc avec le même rapport d'aspect que l'image source. Le blanc est effacé, le noir est conservé.
input.mask_type	Non	manual (par défaut) pour un masque dessiné au pinceau, automatic pour un masque généré par un outil de segmentation.
input.preserve_alpha	Non	false par défaut. Réglez sur true pour conserver la transparence d'une entrée avec canal alpha.

Production : utiliser les callbacks

L'interrogation convient aux tests. Pour un service, passez un callback de niveau supérieur afin que HiAPI vous notifie à la fin de la tâche :

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

Conservez l'interrogation comme solution de repli au cas où le callback serait perdu. Les URL de sortie expirent, donc copiez le fichier dans votre propre stockage dès que la tâche réussit.

Ce que j'ai réellement exécuté et observé

J'ai exécuté une fois la requête de la section curl le jour de la rédaction, et je l'ai interrogée jusqu'à son achèvement.

• Ordre des statuts : handling → archiving → success. archiving apparaît une fois le travail terminé, avant l'apparition de output. Considérez cela comme « pas encore terminé » et continuez d'interroger.
• Durée : la tâche a pris 16 secondes de la création à l'achèvement. L'URL output est apparue quelques secondes plus tard.
• Sortie : un PNG sur temp.hiapi.ai, 1360 × 768, avec canal alpha. C'est identique à la taille de l'image source, conformément à la documentation qui indique que la résolution d'origine est conservée.
• Facturation : au moment de ma consultation, le prix de ce modèle dans les données de tarification publiques était de 0,0575 $ par image. Consultez la page tarifs pour les prix actuels.
• Erreur de validation : j'ai délibérément testé l'envoi de mask_type: "bogus". L'API l'a rejeté avec HTTP 400 :

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

Je n'ai vérifié qu'une seule requête sur une seule image. Je n'ai pas testé d'autres styles de masque, des images très grandes, ni des masques dont le rapport d'aspect diffère de celui de l'image. Les remarques ci-dessous sur ces cas proviennent de la documentation du modèle, et non de mes tests.

Conseils pour le masque (issus de la documentation)

• Peignez légèrement au-delà du bord de l'objet. Un masque qui suit étroitement le contour laisse souvent un halo autour de l'objet d'origine.
• Gardez le masque au même rapport d'aspect que la photo. La documentation l'exige, mais n'indique pas ce qui se passe sinon.
• N'utilisez automatic que pour les masques issus d'outils de segmentation ou de détourage. Les masques au pinceau utilisent manual.

Quelle page dois-je lire ?

Ce guide couvre la suppression basée sur un masque à l'aide d'un point de terminaison dédié. Pour l'édition pilotée par prompt avec un modèle générique image-vers-image, consultez Inpainting d'image et suppression d'objets. Pour supprimer un arrière-plan entier plutôt qu'un objet unique, consultez le guide de suppression d'arrière-plan. La page du modèle se trouve à bria-eraser, et la référence des champs dans la documentation de l'API.

Questions fréquentes

bria-eraser a-t-il besoin d'un prompt ?

Non. La documentation indique qu'aucun prompt n'est nécessaire, et la requête que j'ai exécutée ne contenait que l'image, le masque et mask_type.

Quelle couleur du masque est supprimée ?

Le blanc est effacé, le noir est conservé.

La sortie est-elle plus petite que l'entrée ?

Dans mon exécution, la sortie était 1360 × 768, exactement identique à l'image source.

Dois-je interroger ou utiliser un callback ?

Interrogez pendant les tests. En production, utilisez callback.url avec when: "final", et gardez l'interrogation comme solution de repli.