So verwendest du die Bria Eraser API: curl, Python und eine lauffähige Anfrage

bria-eraser entfernt Objekte aus Fotos. Du sendest ein Bild und eine Schwarz-Weiß-Maske, und das Modell füllt den maskierten Bereich mit passendem Hintergrund. Es gibt kein prompt-Feld. Diese Anleitung zeigt eine vollständig lauffähige Anfrage, den Python-Code zu ihrer Ausführung und die Details, die entscheiden, ob deine eigene Maske funktioniert. Du benötigst einen HiAPI-Key aus dem Dashboard.

Minimale Anfrage (curl)

Das Modell nutzt den einheitlichen asynchronen Endpunkt POST /v1/tasks. Beide folgenden URLs sind öffentlich und waren zum Zeitpunkt der Erstellung dieses Artikels erreichbar:

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

Der Aufruf gibt sofort eine Task-ID zurück, kein Bild:

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

Frage GET /v1/tasks/<taskId> ab, bis data.status den Wert success hat, und lies dann data.output[0].url aus.

Python: Senden, Abfragen, Herunterladen

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

Behalte die Task-ID. Wenn eine Abfrage fehlschlägt, frage dieselbe ID erneut ab. Sende die Anfrage nicht erneut, denn jede Übermittlung ist ein separat abgerechneter Task.

Anfragefelder

Feld	Erforderlich	Beschreibung
input.image_url	Ja	Öffentliche http/https-URL. JPEG, PNG oder WEBP.
input.mask_url	Ja	Schwarz-Weiß-Bild mit demselben Seitenverhältnis wie das Quellbild. Weiß wird ausradiert, Schwarz bleibt erhalten.
input.mask_type	Nein	manual (Standard) für mit dem Pinsel gezeichnete Masken, automatic für Masken aus Segmentierungswerkzeugen.
input.preserve_alpha	Nein	Standard ist false. Auf true setzen, um die Transparenz von Eingaben mit Alpha-Kanal zu erhalten.

Produktivumgebung: Callbacks verwenden

Polling eignet sich für Tests. Für einen Dienst übergibst du auf oberster Ebene callback, damit HiAPI dich benachrichtigt, wenn der Task abgeschlossen ist:

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

Behalte das Polling als Fallback bei, falls ein Callback verloren geht. Ausgabe-URLs laufen ab, daher solltest du die Datei nach einem erfolgreichen Task so schnell wie möglich in deinen eigenen Speicher kopieren.

Was ich tatsächlich ausgeführt und gesehen habe

Ich habe die Anfrage aus dem curl-Abschnitt am Tag des Verfassens einmal ausgeführt und bis zum Abschluss abgefragt.

• Statusreihenfolge: handling → archiving → success. archiving erscheint, nachdem die Arbeit abgeschlossen ist, aber bevor output erscheint. Betrachte es als „noch nicht fertig“ und frage weiter ab.
• Dauer: Der Task benötigte von der Erstellung bis zum Abschluss 16 Sekunden. Die output-URL erschien einige Sekunden danach.
• Ausgabe: Ein PNG auf temp.hiapi.ai, 1360 × 768, mit Alpha-Kanal. Das entspricht der Größe des Quellbilds und passt zur Dokumentation, die die Beibehaltung der Originalauflösung angibt.
• Abrechnung: Zum Zeitpunkt meiner Prüfung lag der Preis für dieses Modell in den öffentlichen Preisdaten bei $0,0575 pro Bild. Aktuelle Preise findest du unter Preise.
• Validierungsfehler: Ich habe absichtlich mask_type: "bogus" gesendet. Die API lehnte dies mit HTTP 400 ab:

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

Ich habe nur eine Anfrage mit einem Bild geprüft. Ich habe keine anderen Maskenstile, übergroße Bilder oder Masken mit einem vom Bild abweichenden Seitenverhältnis getestet. Die folgenden Hinweise zu diesen Fällen stammen aus der Modelldokumentation, nicht aus meinen Tests.

Maskenhinweise (aus der Dokumentation)

• Male etwas über den Objektrand hinaus. Masken, die genau an der Kontur anliegen, hinterlassen oft einen Lichthof um das ursprüngliche Objekt.
• Die Maske behält dasselbe Seitenverhältnis wie das Foto. Die Dokumentation verlangt dies, sagt aber nicht, was andernfalls passiert.
• Verwende automatic nur für Masken aus Segmentierungs- oder Freistellungswerkzeugen. Für Pinselmasken verwendest du manual.

Welche Seite sollte ich lesen?

Diese Anleitung behandelt die maskenbasierte Entfernung über einen dedizierten Endpunkt. Für promptgesteuerte Bearbeitung mit einem allgemeinen Bild-zu-Bild-Modell siehe Bildinpainting und Objektentfernung. Wenn du den gesamten Hintergrund statt eines einzelnen Objekts entfernen möchtest, siehe die Anleitung zur Hintergrundentfernung. Die Modellseite findest du unter bria-eraser, die Feldreferenz in der API-Dokumentation.

Häufig gestellte Fragen

Benötigt bria-eraser einen Prompt?

Nein. Die Dokumentation gibt an, dass kein Prompt erforderlich ist, und die von mir ausgeführte Anfrage enthielt nur Bild, Maske und mask_type.

Welche Farbe in der Maske wird entfernt?

Weiß wird ausradiert, Schwarz bleibt erhalten.

Ist die Ausgabe kleiner als die Eingabe?

In meinem Lauf war die Ausgabe 1360 × 768 und damit exakt identisch mit dem Quellbild.

Sollte ich Polling oder Callbacks verwenden?

Beim Testen Polling. Im Produktivbetrieb callback.url und when: "final" verwenden und Polling als Fallback einsetzen.