API do usuwania tła: jedno żądanie, gotowy PNG w odpowiedzi.

Wysyłanie zdjęcia

POST /v1/remove przyjmuje zdjęcie na cztery sposoby. Wyślij jeden z nich; jeśli żądanie zawiera kilka, pierwszeństwo ma image_file, potem image_file_b64, potem image_url, a na końcu surowa treść. Przykłady odczytują klucz ze zmiennej środowiskowej REMOVEBG_API_KEY (ustaw ją przez export REMOVEBG_API_KEY=…); zwróć uwagę na podwójne cudzysłowy, dzięki którym powłoka wstawi wartość.

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

Każdy przykład zapisuje treść odpowiedzi do pliku. Ten plik jest obrazem tylko przy statusie 200; zobacz Obsługa odpowiedzi.

Obsługa odpowiedzi

Większość pojedynczych zdjęć wraca gotowa w tej samej odpowiedzi. Gdy kolejka jest wyjątkowo obciążona, a zdjęcie trwa dłużej niż około 55 sekund, dostajesz zamiast tego 202 Accepted z identyfikatorem zadania. Zadanie dalej działa: pobierz jego wynik po identyfikatorze. Ponowne wysłanie zdjęcia uruchomiłoby drugie zadanie i mogłoby kosztować drugi kredyt.

Kompletny przykład

Obsługuje gotowy obraz, odpowiedź 202, nieudane zadanie i lokalny limit czasu. Wysyła zdjęcie raz i ponawia tylko bezpieczne sprawdzenia statusu.

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

• Zatrzymanie skryptu nie zatrzymuje zadania; może się ono zakończyć i zostać rozliczone. Jego wynik pojawi się w twoim Studio.
• Limity czasu wybierasz sam, to nie jest nasza obietnica; większość zdjęć jest gotowa w kilka sekund.
• Endpoint zgodny z remove.bg działa inaczej: nigdy nie zwraca 202 (zobacz niżej).

Partie od początku do końca

1. Wyślij

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

Do 100 publicznych adresów URL obrazów plus dowolne opcje /v1/remove. Dwa przykładowe adresy URL powyżej kosztowałyby do 2 kredytów, gdyby były prawdziwymi obrazami. Odpowiedź przychodzi od razu:

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 liczy wpisy, które nie są adresami http(s), a duplicates liczy powtórzenia; oba są pomijane i nigdy nie są rozliczane. Zapisz id: dzięki niemu podejmiesz zadanie ponownie po restarcie.

2. Odpytuj zadanie

GET /v1/jobs/:id co kilka sekund, aż done będzie true. status przechodzi z queued do processing, a kończy się jako succeeded, partial (część zdjęć się nie udała) lub failed. Element, który jest ponawiany, ma status 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. Pobierz każdy wynik

GET /v1/jobs/:id/result?item=N dla każdego udanego elementu (albo użyj jego result_url). item to liczona od zera position. Pozycje odpowiadają twojej liście po usunięciu nieprawidłowych i powtórzonych adresów URL, więc gdy któraś z tych liczb jest większa od 0, dopasowuj wyniki po input, a nie po indeksie.

• Partia przestaje się liczyć do limitu 3 otwartych partii, gdy done ma wartość true.
• API nie ma endpointu anulowania, webhooków ani pobierania ZIP. Partie uruchomione na stronie Bulk można tam anulować lub pobrać jako ZIP.

Ponowienia, duplikaty i rozliczenia

Wyślij Idempotency-Key, a ponowienia nie naliczą opłaty dwa razy. Dodaj nagłówek Idempotency-Key (dowolny unikalny ciąg do 255 znaków, np. UUID) do POST /v1/remove lub POST /v1/batch, jeden klucz na zdjęcie lub partię. Jeśli wyślesz to samo żądanie ponownie z tym samym kluczem, dostaniesz zadanie utworzone przez pierwsze, z nagłówkiem Idempotent-Replayed: true: bez nowego zadania i bez nowej opłaty, nawet jeśli pierwsze żądanie wciąż trwa. Ten sam klucz z innym zdjęciem lub opcjami zwraca 409 idempotency_key_reused. Klucze należą do twojego konta i nie wygasają.

Bez klucza każde POST tworzy nowe zadanie, a każde udane zadanie kosztuje 1 kredyt (zgodny z remove.bg POST /v1.0/removebg nie obsługuje kluczy). Odczyt zadania (GET /v1/jobs/…) jest zawsze darmowy i można go bezpiecznie powtarzać.

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

Za co płacisz kredytem

Kiedy ponawiać

Limity i przechowywanie

Jak długo przechowujemy wyniki

Każdy wynik jest przechowywany prywatnie na twoim koncie przez 48 godz. od utworzenia, a potem usuwany. Do tego czasu możesz go pobrać ponownie za darmo przez GET /v1/jobs/:id/result lub ze Studio. Potem linki do wyniku zwracają 410 result_unavailable; ponowne przetworzenie zdjęcia to nowe zadanie. Rekordy statusu zadań można odczytywać także po usunięciu obrazu. Jak postępujemy z przesłanymi plikami, opisuje polityka prywatności; nie używamy twoich zdjęć do trenowania modeli.

Bezpieczeństwo

Trzymaj klucz API na serwerze, nad którym masz kontrolę. Nie umieszczaj go w kodzie przeglądarki, aplikacjach mobilnych, publicznych repozytoriach ani adresach URL. Aby twoi użytkownicy mogli usuwać tło, przesyłaj ich zdjęcia przez swój backend i dodaj tam własne logowanie oraz limity wydatków.

• API zezwala na CORS, więc działa z narzędzi i kodu po stronie serwera. Nie oznacza to, że można bezpiecznie umieścić klucz na stronie internetowej: każdy może go tam odczytać.
• Wszystkie klucze na koncie korzystają z tego samego salda kredytów. Utwórz osobny klucz dla każdej aplikacji lub środowiska na stronie konta, aby móc unieważnić jeden bez psucia pozostałych.
• Jeśli klucz wycieknie, od razu unieważnij go na stronie konta (natychmiast przestaje działać) i utwórz nowy. Przechowujemy tylko skrót każdego klucza, więc nie możemy pokazać ci go ponownie.

Rozwiązywanie problemów