Bildhintergrund per API entfernen: Anleitung mit Code

Einen Hintergrund von Hand zu entfernen dauert pro Foto ein paar Minuten. Für jeden Produkt-Upload, jedes Profilbild oder jedes Thumbnail in deiner App brauchst du eine API zum Entfernen von Hintergründen: eine HTTP-Anfrage rein, ein fertiges Freisteller-Bild raus.

Dieser Leitfaden zeigt, wie du sie sauber integrierst. Du bekommst funktionierenden cURL-, Python- und JavaScript-Code, die wichtigsten Ausgabeoptionen, den Umgang mit langsamen Bildern und Massenjobs und erfährst, wie du Anfragen wiederholst, ohne doppelt zu zahlen. Die Beispiele nutzen removebackground.dev, unser Schwesterprodukt, aber die Muster gelten für jeden Anbieter.

So funktioniert eine API zum Entfernen von Hintergründen

Du sendest ein Bild, der Anbieter führt ein Segmentierungsmodell aus, das das Motiv vom Hintergrund trennt, und du erhältst ein neues Bild zurück. Der Kern des Ergebnisses ist ein Alphakanal: ein Wert pro Pixel, der angibt, wie viel von jedem Pixel zum Motiv gehört. Vollständig deckende Pixel sind das Motiv, vollständig transparente Pixel sind Hintergrund, und die Werte dazwischen erfassen weiche Kanten wie Haare, Fell und Glas.

Aus dieser Maske kann die API verschiedene Dinge zurückgeben:

• Einen transparenten Freisteller, meist ein PNG oder WebP ohne Hintergrund
• Das Motiv auf einer Volltonfarbe, als JPG für Marktplätze, die weiße Hintergründe verlangen
• Die Maske selbst, ein Graustufenbild für deine eigene Compositing-Pipeline
• Eine zugeschnittene oder skalierte Version, auf das Motiv beschnitten und auf eine exakte Größe gebracht

Die Anfrage ist der einfache Teil. Eine Integration in Produktion muss auch mit Bildern umgehen, die länger als üblich dauern, mit großen Batches, Rate Limits, Retries und damit, den API-Schlüssel von Nutzern fernzuhalten.

Worauf du bei einer API zum Entfernen von Hintergründen achten solltest

Bevor du Code schreibst, prüfe diese Punkte mit deinen eigenen Bildern und deinem eigenen Traffic.

Schritt 1: API-Schlüssel erstellen

Registriere dich auf removebackground.dev und erstelle auf deiner Kontoseite einen Schlüssel. Neue Konten erhalten 50 kostenlose Credits, genug, um die Beispiele unten auszuführen und mit eigenen Bildern zu testen.

Speichere den Schlüssel in einer Umgebungsvariable auf deinem Server:

export REMOVEBG_API_KEY="your_api_key"

Jeder Aufruf sendet den Schlüssel im Header x-api-key, und jeder Aufruf verbraucht die Credits dieses Kontos. Erstelle pro App oder Umgebung einen eigenen Schlüssel, damit du einen widerrufen kannst, ohne die anderen zu beeinträchtigen.

Schritt 2: Hintergrund mit cURL entfernen

Der Echtzeit-Endpoint ist POST https://removebackground.dev/v1/remove. Der schnellste Test ist ein Datei-Upload:

curl -X POST https://removebackground.dev/v1/remove \
  -H "x-api-key: $REMOVEBG_API_KEY" \
  -F 'image_file=@photo.jpg' \
  -o photo-no-bg.png

Die meisten Einzelbilder kommen fertig in derselben Antwort zurück, meist innerhalb weniger Sekunden, als transparentes PNG in voller Auflösung.

Der Endpoint nimmt das Bild auf vier Arten an. Sende eine davon:

Enthält eine Anfrage mehrere davon, gewinnt image_file, dann image_file_b64, dann image_url, dann der rohe Body. Optionen können als Formularfelder, JSON-Schlüssel oder Query-String-Werte gesendet werden.

Ein Punkt, auf den du achten solltest: -o speichert den Body unabhängig vom Status. Ist der Schlüssel falsch oder das Bild ungültig, ist dein "PNG" in Wahrheit ein JSON-Fehler. Prüfe den Statuscode, bevor du der Datei vertraust.

Schritt 3: 200, 202 und Fehler in Python behandeln

Eine API zum Entfernen von Hintergründen kann nicht versprechen, dass jedes Bild innerhalb einer HTTP-Anfrage fertig wird. Wenn die Queue ungewöhnlich ausgelastet ist und ein Bild länger als etwa 55 Sekunden braucht, antwortet removebackground.dev mit 202 Accepted und einer Job-ID statt mit dem Bild. Der Job läuft weiter, und du holst das Ergebnis über die ID ab.

Die wichtigste Regel: Sende das Bild nach einem 202 niemals erneut. Das startet einen zweiten Job und kann einen zweiten Credit kosten. Hier ist eine vollständige Python-Version, die das Bild einmal sendet und nur die sicheren Aufrufe wiederholt:

import os
import time
import uuid
import requests

API = "https://removebackground.dev"
KEY = os.environ["REMOVEBG_API_KEY"]  # keep the key on your server
EXT = {"image/png": ".png", "image/jpeg": ".jpg", "image/webp": ".webp"}


def save(res, stem):
    """Save an image response with the right extension; raise on anything else."""
    mime = res.headers.get("Content-Type", "").split(";")[0]
    if res.status_code != 200 or mime not in EXT:
        raise RuntimeError(f"HTTP {res.status_code}: {res.text[:500]}")
    path = stem + EXT[mime]
    with open(path, "wb") as f:
        f.write(res.content)
    return path


def remove_background(image_url, stem="result", max_wait=300):
    s = requests.Session()
    s.headers["x-api-key"] = KEY
    # One key per image: a retry with the same key returns the same job, never a second charge.
    idem = {"Idempotency-Key": str(uuid.uuid4())}

    for attempt in range(3):
        try:
            res = s.post(f"{API}/v1/remove", data={"image_url": image_url},
                         headers=idem, timeout=(10, 120))
            break
        except requests.ConnectionError:
            if attempt == 2:
                raise
            time.sleep(2)

    if res.status_code != 202:
        return save(res, stem)  # 200 is the image; anything else raises

    # 202: still processing. Wait for the same job.
    job_id = res.json()["id"]
    deadline = time.monotonic() + max_wait
    while time.monotonic() < deadline:
        time.sleep(2)  # the API sends Retry-After: 2
        res = s.get(f"{API}/v1/jobs/{job_id}/result", timeout=30)
        if res.status_code == 409 and res.json()["error"]["code"] == "not_ready":
            continue
        return save(res, stem)  # the image, or the job's own error
    raise TimeoutError(f"Job {job_id} is still running. Check /v1/jobs/{job_id} later.")


print(remove_background("https://example.com/photo.jpg"))

Du brauchst Python 3 und requests (pip install requests). Zwei Details übersieht man leicht. Erstens stoppt das Beenden deines Skripts den Job nicht: Er kann trotzdem fertig werden und abgerechnet werden, und das Ergebnis erscheint im Studio deines Kontos. Zweitens antwortet GET /v1/jobs/:id/result mit 409 not_ready, solange der Job läuft. Behandle das also als "warten", nicht als Fehler.

Derselbe Ablauf in JavaScript (Node.js)

Derselbe Ablauf in Node.js 18 oder neuer, mit den eingebauten fetch, FormData und Blob und einem lokalen Datei-Upload:

import { readFile, writeFile } from "node:fs/promises"
import { randomUUID } from "node:crypto"

const API = "https://removebackground.dev"
const KEY = process.env.REMOVEBG_API_KEY // server side only
const EXT = { "image/png": ".png", "image/jpeg": ".jpg", "image/webp": ".webp" }
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))

async function save(res, stem) {
  const mime = (res.headers.get("content-type") || "").split(";")[0]
  if (res.status !== 200 || !EXT[mime]) {
    throw new Error("HTTP " + res.status + ": " + (await res.text()).slice(0, 500))
  }
  const path = stem + EXT[mime]
  await writeFile(path, Buffer.from(await res.arrayBuffer()))
  return path
}

export async function removeBackground(filePath, stem = "result", maxWaitMs = 300000) {
  const form = new FormData()
  form.append("image_file", new Blob([await readFile(filePath)]), "upload")
  form.append("format", "png")

  const res = await fetch(API + "/v1/remove", {
    method: "POST",
    // Reuse the same Idempotency-Key if you retry this POST.
    headers: { "x-api-key": KEY, "Idempotency-Key": randomUUID() },
    body: form,
  })
  if (res.status !== 202) return save(res, stem)

  const { id } = await res.json()
  const deadline = Date.now() + maxWaitMs
  while (Date.now() < deadline) {
    await sleep(2000)
    const result = await fetch(API + "/v1/jobs/" + id + "/result", {
      headers: { "x-api-key": KEY },
    })
    if (result.status === 409) {
      const body = await result.json()
      if (body.error && body.error.code === "not_ready") continue
      throw new Error("Job " + id + ": " + body.error.code)
    }
    return save(result, stem)
  }
  throw new Error("Job " + id + " is still running. Check /v1/jobs/" + id + " later.")
}

console.log(await removeBackground("photo.jpg"))

Die API akzeptiert CORS-Anfragen, was für Tools und Tests praktisch ist. Das macht es aber nicht sicher, sie aus einer Webseite mit deinem Schlüssel darin aufzurufen. Mehr dazu im Sicherheitsabschnitt weiter unten.

Schritt 4: Die Ausgabe steuern

Die meisten Apps wollen keinen rohen Freisteller in voller Auflösung. Sie wollen ein quadratisches Produktbild auf Weiß, eine kleine Vorschau oder eine Maske. Wenn du die API direkt nach der fertigen Datei fragst, sparst du dir einen zweiten Verarbeitungsschritt. Das sind die Optionen von /v1/remove:

Jede Option kostet denselben 1 Credit, und unbekannte Parameter werden stillschweigend ignoriert, ein Tippfehler löst also keinen Fehler aus. Ein quadratisches Marktplatzbild mit zentriertem Produkt und 10 % Abstand sieht so aus:

curl -X POST https://removebackground.dev/v1/remove \
  -H "x-api-key: $REMOVEBG_API_KEY" \
  -F 'image_file=@product.jpg' \
  -F 'crop=1:1' -F 'padding=10%' \
  -F 'width=1000' -F 'height=1000' \
  -F 'format=jpg' -F 'bg_color=white' \
  -o product-square.jpg

Eine erfolgreiche Antwort enthält außerdem nützliche Header. X-Credits-Remaining zeigt dein Guthaben nach dem Bild. X-Matte-Confidence (0 bis 1) gibt an, wie eindeutig die Maske ist, und X-Matte-Ambiguous-Ratio den Anteil weicher Pixel wie Haare, Glas oder Bewegungsunschärfe. Wenn du diese beiden Werte loggst, kannst du Freisteller mit niedriger Konfidenz zur manuellen Prüfung markieren, statt jedes Bild zu kontrollieren.

Schritt 5: Bilder in großen Mengen verarbeiten

Für Katalogimporte und Nachbearbeitungen solltest du keine Hunderte Einzelanfragen abfeuern. POST /v1/batch stellt bis zu 100 öffentliche Bild-URLs als einen Job in die Queue, mit denselben Optionen wie /v1/remove, und antwortet sofort mit 202:

import os
import time
import uuid
import requests

API = "https://removebackground.dev"
s = requests.Session()
s.headers["x-api-key"] = os.environ["REMOVEBG_API_KEY"]

urls = ["https://example.com/front.jpg", "https://example.com/back.jpg"]

job = s.post(f"{API}/v1/batch",
             json={"image_urls": urls, "format": "png", "size": "hd"},
             headers={"Idempotency-Key": str(uuid.uuid4())}, timeout=30)
job.raise_for_status()
job_id = job.json()["id"]  # save it: it's how you resume after a restart

while True:
    time.sleep(3)
    status = s.get(f"{API}/v1/jobs/{job_id}", timeout=30).json()
    if status["done"]:
        break

print(status["status"], "credits charged:", status["credits_charged"])
for item in status["items"]:
    if item["status"] != "succeeded":
        print("failed:", item["input"], item.get("error"))
        continue
    img = s.get(item["result_url"], timeout=60)
    with open(f"out-{item['position']}.{item['format']}", "wb") as f:
        f.write(img.content)

Einige Regeln aus der Dokumentation, die du einplanen solltest:

• Der Status des Jobs endet als succeeded, partial (einige Bilder sind fehlgeschlagen) oder failed. Jedes Element in items hat einen eigenen Status und bei einem Fehler einen Fehlercode.
• Einträge, die keine http(s)-URLs sind, und doppelte URLs werden verworfen und nie berechnet. Ist einer dieser Zähler größer als 0, ordne die Ergebnisse über input statt über die Position zu.
• Du kannst höchstens 3 offene Batch-Jobs pro Konto haben. Ein Batch zählt nicht mehr, sobald done true ist.
• Gehen die Credits mitten im Batch aus, bleiben fertige Bilder bezahlt und der Rest wird kostenlos mit out_of_credits als übersprungen markiert.
• Die API hat keinen Abbruch-Endpoint, keine Webhooks und keinen ZIP-Download, daher ist Polling das Muster. Das Lesen eines Jobs ist kostenlos und unterliegt keinem Rate Limit.

Lieber ein Skript, das du direkt ausführen kannst? Der Leitfaden zur Batch-Verarbeitung mit Python zeigt einen kompletten Ablauf von Ordner zu Ordner.

Schritt 6: Sicher wiederholen und die Abrechnung planbar halten

Netzwerk-Timeouts sind die Ursache für doppelte Abrechnungen. Dein Client gibt auf, wiederholt die Anfrage, und schon gibt es zwei Jobs für ein Bild. Die Lösung ist ein Idempotency-Key-Header: eine beliebige eindeutige Zeichenkette mit bis zu 255 Zeichen, etwa eine UUID, eine pro Bild oder Batch. Sendest du dieselbe Anfrage mit demselben Schlüssel erneut, bekommst du den Job, den die erste angelegt hat, mit dem Header Idempotent-Replayed: true und ohne neue Abrechnung. Wird ein Schlüssel für ein anderes Bild wiederverwendet, lautet die Antwort 409 idempotency_key_reused.

Die Abrechnung folgt einer einfachen Regel: 1 Credit, wenn ein Bild erfolgreich ist, nichts, wenn es fehlschlägt. Anfragen, die vor der Verarbeitung abgelehnt werden, unlesbare Bilder und Fehler nach den eigenen Retries des Anbieters sind kostenlos, und ein fertiges Ergebnis erneut herunterzuladen ist kostenlos, solange es gespeichert ist.

Limits, die du einplanen solltest

Brauchst du mehr als 60 Bilder pro Minute, ist der Batch-Endpoint die Lösung: Eine Anfrage deckt bis zu 100 Bilder ab. Speichere Ergebnisse direkt nach dem Herunterladen in deinem eigenen Bucket, denn nach 48 Stunden antworten die Ergebnis-Links mit 410. Laut Dokumentation des Anbieters werden hochgeladene Bilder nicht zum Training von Modellen verwendet.

Umstieg von der remove.bg-API

Die eigenständige Website und die Self-Service-API von remove.bg enden am 1. Dezember 2026 um 09:00 Uhr MEZ. Die API zieht zu Leonardo.Ai um, was eine Änderung deiner Integration erfordert. Wenn du nichts neu schreiben willst: removebackground.dev hat einen remove.bg-kompatiblen Endpoint, und der Umstieg ist eine Zeile:

Du behältst denselben Header X-Api-Key (mit einem removebackground.dev-Schlüssel), dieselben Parameternamen, dieselben Response-Header und dasselbe Fehlerformat:

curl -H "X-Api-Key: $REMOVEBG_API_KEY" \
  -F 'image_file=@photo.jpg' -F 'size=auto' \
  -F 'crop=true' -F 'crop_margin=10%' -F 'bg_color=ffffff' \
  -o no-bg.jpg https://removebackground.dev/v1.0/removebg

Kenne die Unterschiede, bevor du wechselst:

• Kein 202. Der kompatible Endpoint wartet bis zu 110 Sekunden und gibt dann einen 503-Timeout zurück. Der Job läuft weiter und wird bei Erfolg berechnet, ein blindes Wiederholen dieser Anfrage startet also einen zweiten Job.
• Keine Idempotency-Keys auf diesem Endpoint. Wenn du sichere Retries brauchst, steige mit der Zeit auf /v1/remove um.
• Einige Optionen werden akzeptiert, aber ignoriert: type und type_level (das Motiv wird automatisch erkannt), semitransparency und die Schatten-Optionen (es werden keine Schatten hinzugefügt).
• Jede Größe kostet 1 Credit, auch volle Auflösung.

Der Migrationsleitfaden enthält Vorher-Nachher-Code für cURL, Python, Node und PHP sowie Schritte für Zapier, Make und n8n.

Halte deinen API-Schlüssel vom Client fern

Das ist der Fehler, der echtes Geld kostet. Steht dein Schlüssel in einer Webseite, einer Mobile-App, einem öffentlichen Repository oder einer URL, kann ihn jeder lesen und deine Credits ausgeben.

• Wenn deine eigenen Nutzer Hintergründe entfernen sollen, leite ihre Bilder über dein Backend und rufe die API von dort auf.
• Ergänze in diesem Backend eigene Anmeldung und Ausgabenlimits pro Nutzer.
• Nutze einen Schlüssel pro App oder Umgebung.
• Wenn ein Schlüssel geleakt wird, widerrufe ihn auf der Kontoseite. Er funktioniert sofort nicht mehr. Der Anbieter speichert nur einen Hash jedes Schlüssels, erstelle also einen neuen, statt den alten wiederherstellen zu wollen.

Beispiel: Freisteller für YouTube-Thumbnails

Wenn du Tools für Creator baust, sind Thumbnails ein naheliegender Einsatz. Ein Thumbnail wird meist klein gesehen, deshalb muss der Freisteller es tragen: ein Gesicht oder ein Produkt, groß, mit klarer Kante vor einem schlichten Hintergrund. YouTube empfiehlt 3840 x 2160 px im Format 16:9 mit einer Mindestbreite von 640 px und akzeptiert JPG oder PNG bis 50 MB vom Computer, aus der Mobile-App aber nur 2 MB.

Auf API-Seite ist es ein einziger Aufruf, der ein transparentes, auf das Motiv zugeschnittenes PNG zurückgibt, bereit für eine 16:9-Fläche:

curl -X POST https://removebackground.dev/v1/remove \
  -H "x-api-key: $REMOVEBG_API_KEY" \
  -F 'image_file=@me.jpg' \
  -F 'crop=true' -F 'padding=5%' \
  -o me-cutout.png

Nimm für den Freisteller ein echtes Foto auf, statt ein Videobild zu nehmen, denn Einzelbilder aus Videos sind oft bewegungsunscharf, und halte die rechte untere Ecke frei, weil YouTube dort die Videolänge einblendet. Die Seite zu YouTube-Thumbnails behandelt die Gestaltung, und unser Leitfaden zu den ersten 1.000 Abonnenten erklärt, warum Thumbnails so wichtig sind.

Hintergründe aus ChatGPT, Claude oder Cursor entfernen

Nicht jede Aufgabe braucht Code. removebackground.dev betreibt auch einen MCP-Server unter https://removebackground.dev/mcp, sodass du ein Foto in ChatGPT, Claude, Cursor, VS Code oder n8n hochladen und den Hintergrund entfernen lassen kannst. In Claude Code ist es ein Befehl:

claude mcp add --transport http removebackground https://removebackground.dev/mcp

Gib dann /mcp in Claude Code ein, um dich anzumelden. Der Server stellt drei Tools bereit: remove_background, get_job für Freistellungen, die länger als ein paar Sekunden dauern, und check_credits. Jedes Bild kostet 1 Credit, genau wie über die API.

Was es kostet

removebackground.dev funktioniert nach Verbrauch, ohne Abo. Credits verfallen nie, fehlgeschlagene Bilder sind kostenlos und neue Konten erhalten 50 kostenlose Credits. Über die API entspricht 1 Credit einer erfolgreichen Hintergrundentfernung in voller Auflösung.

Die Preise sind in USD, und ungenutzte Credits werden innerhalb von 30 Tagen erstattet. Mengenpreise oberhalb von Scale gibt es auf Anfrage. Aktuelle Details findest du auf der Preisseite.

Fazit

Eine solide Integration zum Entfernen von Hintergründen beruht auf wenigen Gewohnheiten: Behalte den Schlüssel auf deinem Server, prüfe den Status, bevor du den Body speicherst, warte nach einem 202 auf den Job statt erneut zu senden, sende bei jedem POST einen Idempotency-Key und nutze den Batch-Endpoint für große Mengen.

Die vollständige Referenz, einschließlich der OpenAPI-3.1-Spezifikation, findest du in der API-Dokumentation. Wenn du neben Bildern auch mit Videos arbeitest, nutzen unser Vergleich von YouTube-Transkript-APIs und unser Leitfaden zur Speech-to-Text-Integration dieselben Produktionsmuster für Text.