Recraft Hintergrund-entfernen API: Ein lauffähiges Beispiel

Die meisten Hintergrund-entfernen-APIs verlangen, dass du ein allgemeines Bildbearbeitungsmodell auswählst und es dann mit passenden Prompts dazu bringst, das Motiv freizustellen. recraft/remove-background erspart dir diesen Schritt: Es ist ein spezialisiertes Modell, das eine Bild-URL entgegennimmt und ein transparentes PNG zurückgibt, das Haar- und Fellranddetails bewahrt. Kein Prompt, kein Negativ-Prompt, kein Stärkeparameter – nur das Quellbild einfügen, das Freisteller-Ergebnis erhalten.

Dieser Leitfaden führt durch einen vollständigen, getesteten Aufruf: die Anfragestruktur, die Antwort, die du tatsächlich erhältst, und produktionsreife Muster (Callbacks, Idempotenz, Fehlerbehandlung), damit Batch-Jobs nicht an einem Randfall hängen bleiben.

Voraussetzungen:

• hiapi API-Key aus deiner Konsole beziehen
• Python 3.9+ mit installiertem requests (pip install requests) oder direkt curl verwenden
• Dein Quellbild liegt unter einer öffentlichen URL – die Task-API von hiapi ruft Bilder über URL ab, nicht per Datei-Upload. Format PNG, JPG oder WEBP, maximal 5 MB, maximal 16 Megapixel, beide Dimensionen zwischen 256 und 4096 Pixeln.

Anfrage

Wie alle Generierungsmodelle auf hiapi läuft recraft/remove-background über die gemeinsame asynchrone Task-API: POST /v1/tasks mit model und input, und du erhältst sofort eine taskId, während die Freistellung im Hintergrund läuft. Der vollständige Vertrag – Header, Idempotenz-Key, Statuscodes – ist zentral unter Task erstellen dokumentiert; der modellspezifische Teil ist input, das für dieses Modell nur ein einziges Feld hat:

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "recraft/remove-background",
  "input": {
    "image_url": "https://static.hiapi.ai/model-covers/recraft-remove-background/2026/09/01/golden-input-2048.jpg"
  }
}'

import requests

payload = {
    "model": "recraft/remove-background",
    "input": {
        "image_url": "https://static.hiapi.ai/model-covers/recraft-remove-background/2026/09/01/golden-input-2048.jpg",
    },
}

response = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json=payload,
)
print(response.json())
# {"code": 200, "data": {"taskId": "tk-hiapi-..."}, "message": "success"}

image_url ist das einzige Feld, das dieses Modell akzeptiert – es gibt kein format, response_format oder Größenparameter. Sendest du irgendetwas anderes, weist die API die gesamte Anfrage noch vor Erreichen des Modells mit einem Schemafehler zurück (siehe Fehler unten). Die Ausgabe ist immer ein transparentes PNG.

Ergebnis abfragen

Nimm die taskId aus der obigen Antwort und frage GET /v1/tasks/{taskId} ab, bis data.status einen Endzustand erreicht. Die Status-Enumeration ist plattformweit über alle Modelle hinweg identisch: queued → handling → archiving → success (oder fail). Die tatsächliche Ausführung dieses Modells ist meist in unter 10 Sekunden abgeschlossen:

import time

task_id = response.json()["data"]["taskId"]

while True:
    r = requests.get(
        f"https://api.hiapi.ai/v1/tasks/{task_id}",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
    )
    data = r.json()["data"]
    if data["status"] in ("success", "fail"):
        break
    time.sleep(2)

print(data)

Im Status success ist data.output ein Array mit genau einem Element:

{
  "status": "success",
  "output": [
    {
      "artifactId": "119426",
      "type": "image",
      "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M1RYTHQ5F94S2405YSC65EWM-0.png",
      "expireAt": 1789222580
    }
  ]
}

url ist ein temporärer Link – expireAt ist ein Unix-Zeitstempel etwa eine Woche in der Zukunft, keine dauerhafte CDN-Adresse. Lade die Bytes herunter und speichere sie in deinem eigenen Speicher, sobald der Task erfolgreich ist:

image_bytes = requests.get(data["output"][0]["url"]).content
with open("cutout.png", "wb") as f:
    f.write(image_bytes)

Produktionsreife Muster

Callbacks statt Polling-Schleife verwenden. Übergib bei der Erstellung callback.url, und hiapi POSTet das Endergebnis an dich, sobald der Task abgeschlossen ist, statt dass du in einer Polling-Schleife Anfragen verbrauchst:

payload = {
    "model": "recraft/remove-background",
    "callback": {"url": "https://example.com/hiapi/callback", "when": "final"},
    "input": {"image_url": "https://your-cdn.example.com/product-01.jpg"},
}

when: "final" bedeutet, dass du genau einen Callback erhältst, ausgelöst im Endzustand (success oder fail), nicht einen pro Zwischenzustand. Für einen Stapel Produktfotos ist das die passende Standardeinstellung, bei der du nicht für jedes Bild eine Polling-Schleife unterhalten musst.

Idempotenz. Wenn eine Anfrage auf deiner Seite in einen Timeout läuft, aber hiapi tatsächlich erreicht hat, liefert ein erneuter Versuch mit demselben Idempotency-Key-Header (dokumentiert unter Task erstellen) den ursprünglichen Task zurück, ohne dass die zweite Freistellung berechnet wird. Das lohnt sich für jeden Batch-Job, der bei Netzwerkfehlern erneut versucht.

Fehler – zwei Formen, nicht eine. Fehlerhafte Anfragen und Authentifizierungsfehler werden in unterschiedlichen Envelopes zurückgegeben, und Code, der nur einen davon prüft, verschluckt den anderen stillschweigend:

// Eingabefehler (Schema-Validierung) – HTTP 400
{"code": 400, "data": null, "error_code": "INVALID_REQUEST", "message": "invalid input: image_url: missing required field \"image_url\""}

// API-Key ungültig oder abgelaufen – HTTP 401
{"error": {"code": "permission_denied", "message": "This API key is invalid...", "request_id": "...", "type": "hiapi_error"}}

Prüfe zuerst error_code und falle dann auf error.code zurück – gehe nicht davon aus, dass alle Fehler dieselben Top-Level-Schlüssel haben.

Preisgestaltung. $0.01 pro Bild (20 Credits), unabhängig von der Eingangsauflösung, einheitliche Abrechnung. Der aktuelle Preis steht stets auf der Preisseite.

Wenn du den Hintergrund ersetzen statt nur freistellen willst

recraft/remove-background erzeugt nur einen transparenten Freisteller – keine Füllung, keine Szene. Ist das Ziel, in demselben Aufruf einen Studiohintergrund oder eine Lifestyle-Szene einzusetzen, ist das eine andere Aufgabe: Verwende ein Bild-zu-Bild-Modell und prompte es, den Hintergrund um das beibehaltene Motiv herum neu zu generieren. Siehe Bildhintergrund per API entfernen: promptbasierte Bearbeitung, um diese Methode kennenzulernen und wann es sich lohnt, dafür mehr als für eine gewöhnliche Freistellung zu zahlen.

Häufig gestellte Fragen

Akzeptiert recraft/remove-background Prompts oder Stärkeparameter? Nein. Das Schema ist strikt – image_url ist das einzige akzeptierte Feld. Das Senden zusätzlicher Felder wie format oder response_format liefert einen 400 mit der Meldung "additional properties not allowed".

Welche Bildformate und -größen werden unterstützt? Eingabe: PNG, JPG oder WEBP, maximal 5 MB, maximal 16 Megapixel, beide Dimensionen zwischen 256 und 4096 Pixeln. Ausgabe ist immer ein PNG mit Alpha-Kanal.

Kann ich eine lokale Datei statt einer URL hochladen? Nein – image_url muss eine öffentliche http(s)://-URL sein, die ein hiapi-Server abrufen kann. Lade sie zuerst in Objektspeicher oder ein CDN hoch.

Wie lange ist die Ausgabe-URL gültig? Das Feld expireAt jedes Ausgabeeintrags ist ein Unix-Zeitstempel, üblicherweise etwa eine Woche in der Zukunft. Behandle ihn als temporären Link und kopiere die Bytes sofort nach erfolgreichem Task in deinen eigenen Speicher – speichere temp.hiapi.ai-Links nicht langfristig.

Eignet sich das für die Batch-Verarbeitung hunderter Produktfotos? Ja – reiche einen Task pro Bild ein, teile eine gemeinsame callback.url und lasse hiapi die Ergebnisse zurückpushen, statt einzeln zu pollen. Bei $0.01/Bild kostet die Verarbeitung eines Katalogs von 1.000 Bildern $10 an Generierung.