API voor achtergrond verwijderen: één request erin, kant-en-klare PNG eruit.

Je afbeelding versturen

POST /v1/remove accepteert de afbeelding op vier manieren. Stuur er één; bevat een request er meerdere, dan gaat image_file voor, dan image_file_b64, dan image_url en dan de ruwe body. Deze voorbeelden lezen je sleutel uit de omgevingsvariabele REMOVEBG_API_KEY (stel die in met export REMOVEBG_API_KEY=…); let op de dubbele aanhalingstekens, waardoor de shell de waarde invult.

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

Elk voorbeeld slaat de body op in een bestand. Dat bestand is alleen een afbeelding als de status 200 is; zie Het antwoord verwerken.

Het antwoord verwerken

De meeste losse afbeeldingen komen kant-en-klaar terug in hetzelfde antwoord. Is de wachtrij uitzonderlijk druk en duurt een afbeelding langer dan ongeveer 55 seconden, dan krijg je in plaats daarvan 202 Accepted met een job-id. De job loopt door: haal het resultaat op met de id. Als je de afbeelding opnieuw stuurt, start je een tweede job die een tweede credit kan kosten.

Een volledig voorbeeld

Verwerkt de kant-en-klare afbeelding, een 202, een job die mislukt en een lokale tijdslimiet. Het stuurt de afbeelding één keer en herhaalt alleen de veilige statuscontroles.

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

• Als je je script stopt, stopt de job niet; die kan nog steeds klaar zijn en in rekening worden gebracht. Het resultaat verschijnt in je Studio.
• De tijdslimieten kies je zelf, het is geen belofte van ons; de meeste afbeeldingen zijn binnen een paar seconden klaar.
• Het remove.bg-compatibele endpoint werkt anders: het antwoordt nooit met 202 (zie hieronder).

Batches van begin tot eind

1. Indienen

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

Maximaal 100 openbare afbeeldings-URL's plus alle opties van /v1/remove. De twee placeholder-URL's hierboven zouden tot 2 credits kosten als het echte afbeeldingen waren. Het antwoord komt meteen:

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 telt items die geen http(s)-URL zijn en duplicates telt herhalingen; beide worden weggelaten en nooit in rekening gebracht. Bewaar de id: daarmee pak je de job weer op na een herstart.

2. De job pollen

GET /v1/jobs/:id om de paar seconden tot done true is. status gaat van queued naar processing en eindigt als succeeded, partial (sommige afbeeldingen mislukt) of failed. Een item dat opnieuw wordt geprobeerd, toont 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. Elk resultaat downloaden

GET /v1/jobs/:id/result?item=N voor elk geslaagd item (of gebruik de result_url ervan). item is de position, vanaf nul geteld. Posities volgen je lijst nadat ongeldige en herhaalde URL's zijn verwijderd; is een van beide tellingen hoger dan 0, koppel resultaten dan aan input in plaats van aan de index.

• Een batch telt niet meer mee voor de limiet van 3 open batches zodra done true is.
• De API heeft geen endpoint om te annuleren, geen webhooks en geen ZIP-download. Batches die je op de Bulk-pagina start, kun je daar annuleren of als ZIP downloaden.

Opnieuw proberen, dubbele requests en kosten

Stuur een Idempotency-Key mee, dan kunnen herhaalde pogingen nooit dubbel kosten. Voeg een header Idempotency-Key toe (elke unieke string tot 255 tekens, zoals een UUID) aan POST /v1/remove of POST /v1/batch, één sleutel per afbeelding of batch. Stuur je hetzelfde request opnieuw met dezelfde sleutel, dan krijg je de job die het eerste request heeft gemaakt, met Idempotent-Replayed: true: geen nieuwe job en geen nieuwe kosten, ook als het eerste request nog loopt. Dezelfde sleutel met een andere afbeelding of andere opties geeft 409 idempotency_key_reused. Sleutels horen bij je account en verlopen niet.

Zonder sleutel maakt elke POST een nieuwe job, en elke geslaagde job kost 1 credit (het remove.bg-compatibele POST /v1.0/removebg heeft geen sleutels). Een job uitlezen (GET /v1/jobs/…) is altijd gratis en veilig om te herhalen.

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

Wat een credit kost

Wanneer je opnieuw probeert

Limieten en opslag

Hoe lang resultaten worden bewaard

Elk resultaat wordt na het maken 48 uur privé in je account bewaard en daarna verwijderd. Tot dan kun je het gratis opnieuw downloaden met GET /v1/jobs/:id/result of vanuit je Studio. Daarna antwoorden resultaatlinks met 410 result_unavailable; de afbeelding opnieuw verwerken is een nieuwe job. Statusgegevens van jobs blijven leesbaar nadat de afbeelding weg is. In het privacybeleid lees je hoe uploads worden behandeld; we gebruiken je afbeeldingen niet om modellen te trainen.

Beveiliging

Bewaar je API-sleutel op een server die je zelf beheert. Zet hem niet in browsercode, mobiele apps, openbare repositories of URL's. Wil je je eigen gebruikers achtergronden laten verwijderen, stuur hun afbeeldingen dan via je backend en voeg daar je eigen login en bestedingslimieten toe.

• De API staat CORS toe, zodat hij werkt vanuit tools en servercode. Dat maakt het niet veilig om een sleutel in een webpagina te zetten: daar kan iedereen hem lezen.
• Alle sleutels op een account gebruiken hetzelfde creditsaldo. Maak op je accountpagina een aparte sleutel per app of omgeving, zodat je er een kunt intrekken zonder de andere te breken.
• Lekt een sleutel uit, trek hem dan meteen in op de accountpagina (hij werkt direct niet meer) en maak een nieuwe aan. We bewaren alleen een hash van elke sleutel, dus we kunnen hem niet opnieuw tonen.

Problemen oplossen