API för bakgrundsborttagning: en förfrågan in, färdig PNG ut.

Skicka din bild

POST /v1/remove tar emot bilden på fyra sätt. Skicka ett av dem; om en förfrågan innehåller flera vinner image_file, sedan image_file_b64, sedan image_url och sist den råa bodyn. Exemplen läser din nyckel från miljövariabeln REMOVEBG_API_KEY (ange den med export REMOVEBG_API_KEY=…); observera de dubbla citattecknen, som låter skalet fylla i värdet.

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

Varje exempel sparar bodyn till en fil. Filen är bara en bild när statusen är 200; se Hantera svaret.

Hantera svaret

De flesta enskilda bilder kommer tillbaka färdiga i samma svar. När kön är ovanligt full och en bild tar längre tid än cirka 55 sekunder får du i stället 202 Accepted med ett jobb-id. Jobbet fortsätter att köras: hämta resultatet med id:t. Om du skickar bilden igen startas ett andra jobb, som kan kosta en andra kredit.

Ett komplett exempel

Hanterar den färdiga bilden, en 202, ett jobb som misslyckas och en lokal tidsgräns. Det skickar bilden en gång och gör bara om de säkra statuskontrollerna.

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

• Om du stoppar ditt skript stoppas inte jobbet; det kan ändå bli klart och debiteras. Resultatet dyker upp i din Studio.
• Tidsgränserna väljer du själv, de är inget löfte från oss; de flesta bilder är klara på några sekunder.
• Den remove.bg-kompatibla endpointen fungerar annorlunda: den svarar aldrig med 202 (se nedan).

Batchar från början till slut

1. Skicka in

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

Upp till 100 publika bild-URL:er plus valfria alternativ från /v1/remove. De två platshållar-URL:erna ovan skulle kosta upp till 2 krediter om de var riktiga bilder. Svaret kommer direkt:

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 räknar poster som inte är http(s)-URL:er och duplicates räknar upprepningar; båda tas bort och debiteras aldrig. Spara id: det är så du hittar jobbet igen efter en omstart.

2. Polla jobbet

GET /v1/jobs/:id med några sekunders mellanrum tills done är true. status går från queued till processing och slutar som succeeded, partial (vissa bilder misslyckades) eller failed. Ett objekt som försöks igen visar 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. Ladda ner varje resultat

GET /v1/jobs/:id/result?item=N för varje lyckat objekt (eller använd dess result_url). item är den nollbaserade position. Positionerna följer din lista efter att ogiltiga och upprepade URL:er tagits bort, så när någon av räknarna är över 0 bör du matcha resultaten via input i stället för index.

• En batch slutar räknas mot gränsen på 3 öppna batchar när done är true.
• API:t har ingen endpoint för att avbryta, inga webhooks och ingen ZIP-nedladdning. Batchar som startats på Bulk-sidan kan avbrytas eller laddas ner som ZIP där.

Omförsök, dubbletter och debitering

Skicka en Idempotency-Key så kan omförsök aldrig debiteras två gånger. Lägg till en Idempotency-Key-header (valfri unik sträng på upp till 255 tecken, till exempel ett UUID) i POST /v1/remove eller POST /v1/batch, en nyckel per bild eller batch. Om du skickar samma förfrågan igen med samma nyckel får du jobbet som den första skapade, med Idempotent-Replayed: true: inget nytt jobb och ingen ny debitering, även om den första förfrågan fortfarande körs. Samma nyckel med en annan bild eller andra alternativ ger 409 idempotency_key_reused. Nycklarna hör till ditt konto och går inte ut.

Utan nyckel skapar varje POST ett nytt jobb, och varje jobb som lyckas kostar 1 kredit (den remove.bg-kompatibla POST /v1.0/removebg har inga nycklar). Att läsa ett jobb (GET /v1/jobs/…) är alltid gratis och säkert att upprepa.

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

Vad som kostar en kredit

När du ska försöka igen

Gränser och lagring

Hur länge resultat sparas

Varje resultat lagras privat i ditt konto i 48 timmar efter att det skapats och raderas sedan. Fram till dess kan du ladda ner det igen gratis med GET /v1/jobs/:id/result eller från din Studio. Därefter svarar resultatlänkarna med 410 result_unavailable; att bearbeta bilden igen är ett nytt jobb. Jobbets statusposter går fortfarande att läsa när bilden är borta. Se integritetspolicyn för hur uppladdningar hanteras; vi använder inte dina bilder för att träna modeller.

Säkerhet

Förvara din API-nyckel på en server som du kontrollerar. Lägg den inte i webbläsarkod, mobilappar, publika repon eller URL:er. Om dina egna användare ska kunna ta bort bakgrunder skickar du deras bilder via din backend och lägger till egen inloggning och egna utgiftsgränser där.

• API:t tillåter CORS så att det fungerar från verktyg och kod på servern. Det gör det inte säkert att lägga en nyckel på en webbsida: där kan vem som helst läsa den.
• Alla nycklar på ett konto använder samma kreditsaldo. Skapa en separat nyckel per app eller miljö på din kontosida, så att du kan återkalla en utan att de andra slutar fungera.
• Om en nyckel läcker, återkalla den direkt på kontosidan (den slutar fungera omedelbart) och skapa en ny. Vi lagrar bara en hash av varje nyckel, så vi kan inte visa den för dig igen.

Felsökning