API zur Hintergrundentfernung: eine Anfrage rein, fertiges PNG raus.

Bild senden

POST /v1/remove nimmt das Bild auf vier Arten entgegen. Sende eine davon; enthält eine Anfrage mehrere, gewinnt image_file, dann image_file_b64, dann image_url, dann der rohe Body. Diese Beispiele lesen deinen Schlüssel aus der Umgebungsvariable REMOVEBG_API_KEY (setze sie mit export REMOVEBG_API_KEY=…); beachte die doppelten Anführungszeichen, damit die Shell den Wert einsetzt.

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

Jedes Beispiel speichert den Body in einer Datei. Diese Datei ist nur dann ein Bild, wenn der Status 200 ist; siehe Antwort verarbeiten.

Antwort verarbeiten

Die meisten Einzelbilder kommen fertig in derselben Antwort zurück. Ist die Warteschlange ungewöhnlich voll und dauert ein Bild länger als etwa 55 Sekunden, bekommst du stattdessen 202 Accepted mit einer Job-ID. Der Job läuft weiter: Rufe sein Ergebnis mit der ID ab. Würdest du das Bild erneut senden, startet ein zweiter Job, der einen zweiten Credit kosten kann.

Ein vollständiges Beispiel

Verarbeitet das fertige Bild, einen 202, einen fehlgeschlagenen Job und ein lokales Zeitlimit. Es sendet das Bild nur einmal und wiederholt nur die unbedenklichen Statusabfragen.

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: resending with the same key returns the same job, never a second
    # charge, so this POST is safe to retry after a timeout or a dropped connection.
    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 = the image; anything else raises

    # 202: still processing. Wait for the same job; never send the image again.
    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 it later at /v1/jobs/{job_id}.")


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

• Wenn du dein Skript stoppst, stoppt das nicht den Job; er kann trotzdem fertig werden und berechnet werden. Sein Ergebnis erscheint in deinem Studio.
• Die Zeitlimits legst du selbst fest, sie sind kein Versprechen von uns; die meisten Bilder sind in wenigen Sekunden fertig.
• Der remove.bg-kompatible Endpunkt verhält sich anders: Er antwortet nie mit 202 (siehe unten).

Batches von A bis Z

1. Absenden

curl -X POST https://removebackground.dev/v1/batch \
  -H "x-api-key: $REMOVEBG_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "image_urls": ["https://example.com/front.jpg", "https://example.com/back.jpg"], "format": "png", "size": "hd" }'

Bis zu 100 öffentliche Bild-URLs plus beliebige Optionen von /v1/remove. Die beiden Platzhalter-URLs oben würden bis zu 2 Credits kosten, wenn es echte Bilder wären. Die Antwort kommt sofort:

202 Accepted
{
  "id": "3f6c2a9e-8d1b-4c7a-9e2f-5b8d0a1c4e77",
  "status": "queued",
  "total": 2,
  "invalid": 0,
  "duplicates": 0,
  "status_url": "https://removebackground.dev/v1/jobs/3f6c2a9e-8d1b-4c7a-9e2f-5b8d0a1c4e77"
}

invalid zählt Einträge, die keine http(s)-URLs sind, und duplicates zählt Wiederholungen; beide werden verworfen und nie berechnet. Speichere die id: Damit nimmst du den Job nach einem Neustart wieder auf.

2. Job abfragen

GET /v1/jobs/:id alle paar Sekunden, bis done den Wert true hat. status wechselt von queued zu processing und endet als succeeded, partial (einige Bilder fehlgeschlagen) oder failed. Ein Element, das erneut versucht wird, zeigt retrying.

{
  "id": "3f6c2a9e-…",
  "status": "partial",
  "done": true,
  "total": 2, "succeeded": 1, "failed": 1, "skipped": 0,
  "credits_charged": 1,
  "items": [
    { "position": 0, "input": "https://example.com/front.jpg", "status": "succeeded",
      "removal_id": "…", "width": 1600, "height": 1200, "format": "png",
      "result_url": "https://removebackground.dev/v1/jobs/3f6c2a9e-…/result?item=0" },
    { "position": 1, "input": "https://example.com/back.jpg", "status": "failed",
      "error": { "code": "fetch_failed", "message": "…" } }
  ]
}

3. Jedes Ergebnis herunterladen

GET /v1/jobs/:id/result?item=N für jedes erfolgreiche Element (oder nutze dessen result_url). item ist die nullbasierte position. Die Positionen folgen deiner Liste, nachdem ungültige und doppelte URLs entfernt wurden. Ist einer der beiden Zähler größer als 0, ordne die Ergebnisse daher über input statt über den Index zu.

• Ein Batch zählt nicht mehr zum Limit von 3 offenen Batches, sobald done true ist.
• Die API hat keinen Abbruch-Endpunkt, keine Webhooks und keinen ZIP-Download. Batches, die auf der Bulk-Seite gestartet wurden, kannst du dort abbrechen oder als ZIP herunterladen.

Wiederholungen, Duplikate und Abrechnung

Sende einen Idempotency-Key, dann kosten Wiederholungen nie doppelt. Füge POST /v1/remove oder POST /v1/batch einen Idempotency-Key-Header hinzu (eine beliebige eindeutige Zeichenkette mit bis zu 255 Zeichen, z. B. eine UUID), ein Schlüssel pro Bild oder Batch. Sendest du dieselbe Anfrage mit demselben Schlüssel erneut, bekommst du den Job der ersten Anfrage mit Idempotent-Replayed: true: kein neuer Job und keine neue Abrechnung, selbst wenn die erste Anfrage noch läuft. Derselbe Schlüssel mit einem anderen Bild oder anderen Optionen ergibt 409 idempotency_key_reused. Die Schlüssel gehören zu deinem Konto und verfallen nicht.

Ohne Schlüssel erzeugt jeder POST einen neuen Job, und jeder erfolgreiche Job kostet 1 Credit (der remove.bg-kompatible POST /v1.0/removebg hat keine Schlüssel). Das Lesen eines Jobs (GET /v1/jobs/…) ist immer kostenlos und kann beliebig wiederholt werden.

IDEMPOTENCY_KEY=$(uuidgen)   # one per image; send the same one on every retry

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

Was einen Credit kostet

Wann wiederholen

Limits und Speicherung

Wie lange Ergebnisse gespeichert werden

Jedes Ergebnis wird nach der Erstellung 48 Stunden lang privat in deinem Konto gespeichert und danach gelöscht. Bis dahin kannst du es kostenlos erneut herunterladen, mit GET /v1/jobs/:id/result oder in deinem Studio. Danach antworten Ergebnis-Links mit 410 result_unavailable; das Bild erneut zu verarbeiten ist ein neuer Job. Job-Statusdaten bleiben lesbar, auch wenn das Bild weg ist. Wie Uploads behandelt werden, steht in der Datenschutzerklärung; wir verwenden deine Bilder nicht zum Trainieren von Modellen.

Sicherheit

Bewahre deinen API-Schlüssel auf einem Server auf, den du kontrollierst. Pack ihn nicht in Browser-Code, mobile Apps, öffentliche Repositorys oder URLs. Wenn deine eigenen Nutzer Hintergründe entfernen sollen, leite ihre Bilder über dein Backend und ergänze dort eine eigene Anmeldung und Ausgabelimits.

• Die API erlaubt CORS, damit sie aus Tools und serverseitigem Code funktioniert. Das macht es aber nicht sicher, einen Schlüssel in eine Webseite einzubauen: Dort kann ihn jeder lesen.
• Alle Schlüssel eines Kontos nutzen dasselbe Credit-Guthaben. Erstelle auf deiner Kontoseite einen eigenen Schlüssel pro App oder Umgebung, damit du einen widerrufen kannst, ohne die anderen zu beeinträchtigen.
• Wenn ein Schlüssel öffentlich wird, widerrufe ihn sofort auf der Kontoseite (er funktioniert dann sofort nicht mehr) und erstelle einen neuen. Wir speichern nur einen Hash jedes Schlüssels und können ihn dir daher nicht noch einmal anzeigen.

Fehlerbehebung