API per la rimozione dello sfondo: una richiesta in entrata, un PNG finito in uscita.

Invia l’immagine

POST /v1/remove accetta l’immagine in quattro modi. Usane uno; se una richiesta ne contiene più di uno, vince image_file, poi image_file_b64, poi image_url, poi il body grezzo. Questi esempi leggono la chiave dalla variabile d’ambiente REMOVEBG_API_KEY (impostala con export REMOVEBG_API_KEY=…); nota le virgolette doppie, che permettono alla shell di sostituirla.

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

Ogni esempio salva il body in un file. Quel file è un’immagine solo se lo stato è 200; vedi Gestisci la risposta.

Gestisci la risposta

La maggior parte delle immagini singole torna finita nella stessa risposta. Quando la coda è insolitamente piena e un’immagine richiede più di circa 55 secondi, ricevi invece 202 Accepted con un id del job. Il job continua: recupera il risultato con l’id. Inviare di nuovo l’immagine avvierebbe un secondo job e potrebbe costare un secondo credito.

Un esempio completo

Gestisce l’immagine finita, un 202, un job non riuscito e un limite di tempo locale. Invia l’immagine una sola volta e ripete solo i controlli di stato, che sono sicuri.

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

• Interrompere lo script non interrompe il job: potrebbe comunque terminare ed essere addebitato. Il risultato compare nel tuo Studio.
• I limiti di tempo li scegli tu, non sono una nostra promessa; la maggior parte delle immagini termina in pochi secondi.
• L’endpoint compatibile con remove.bg si comporta diversamente: non risponde mai 202 (vedi sotto).

I lotti, dall’inizio alla fine

1. Invia

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

Fino a 100 URL pubblici di immagini, più qualsiasi opzione di /v1/remove. I due URL di esempio qui sopra costerebbero fino a 2 crediti se fossero immagini reali. La risposta arriva subito:

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 conta le voci che non sono URL http(s) e duplicates conta le ripetizioni; entrambe vengono scartate e mai addebitate. Salva l’id: ti serve per riprendere il job dopo un riavvio.

2. Interroga il job

GET /v1/jobs/:id ogni pochi secondi finché done non è true. status passa da queued a processing, poi termina come succeeded, partial (alcune immagini non sono riuscite) o failed. Un elemento in fase di nuovo tentativo mostra 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. Scarica ogni risultato

GET /v1/jobs/:id/result?item=N per ogni elemento riuscito (oppure usa il suo result_url). item è la position, contata da zero. Le posizioni seguono la tua lista dopo la rimozione degli URL non validi e ripetuti, quindi quando uno dei due conteggi è maggiore di 0 abbina i risultati tramite input anziché tramite indice.

• Un lotto smette di contare nel limite di 3 lotti aperti appena done è true.
• L’API non ha endpoint di annullamento, webhook né download ZIP. I lotti avviati dalla pagina Bulk possono essere annullati o scaricati come ZIP da lì.

Nuovi tentativi, duplicati e fatturazione

Invia una Idempotency-Key e i nuovi tentativi non potranno addebitarti due volte. Aggiungi un header Idempotency-Key (qualsiasi stringa univoca fino a 255 caratteri, ad esempio un UUID) a POST /v1/remove o POST /v1/batch, una chiave per immagine o per lotto. Se invii di nuovo la stessa richiesta con la stessa chiave, ricevi il job creato dalla prima, con Idempotent-Replayed: true: nessun nuovo job e nessun nuovo addebito, anche se la prima richiesta è ancora in corso. La stessa chiave con un’immagine o opzioni diverse risponde 409 idempotency_key_reused. Le chiavi appartengono al tuo account e non scadono.

Senza chiave, ogni POST crea un nuovo job e ogni job riuscito costa 1 credito (il POST /v1.0/removebg compatibile con remove.bg non supporta le chiavi). Leggere un job (GET /v1/jobs/…) è sempre gratuito e si può ripetere senza rischi.

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

Cosa costa un credito

Quando riprovare

Limiti e archiviazione

Per quanto tempo vengono conservati i risultati

Ogni risultato viene conservato in modo privato nel tuo account per 48 ore dalla creazione, poi viene eliminato. Fino ad allora puoi scaricarlo di nuovo gratis con GET /v1/jobs/:id/result o dal tuo Studio. Dopo di che, i link ai risultati rispondono 410 result_unavailable; elaborare di nuovo l’immagine è un nuovo job. Gli stati dei job restano consultabili anche dopo l’eliminazione dell’immagine. Consulta l’informativa sulla privacy per sapere come vengono gestiti i caricamenti; non usiamo le tue immagini per addestrare modelli.

Sicurezza

Tieni la tua chiave API su un server che controlli. Non inserirla nel codice del browser, in app mobili, in repository pubblici o negli URL. Per permettere ai tuoi utenti di rimuovere gli sfondi, fai passare le loro immagini dal tuo backend e aggiungi lì il tuo sistema di accesso e i tuoi limiti di spesa.

• L’API consente CORS per funzionare da strumenti e codice lato server. Questo non rende sicuro inserire una chiave in una pagina web: chiunque potrebbe leggerla.
• Tutte le chiavi di un account consumano lo stesso saldo di crediti. Crea una chiave separata per ogni app o ambiente nella pagina dell’account, così puoi revocarne una senza bloccare le altre.
• Se una chiave viene esposta, revocala subito nella pagina dell’account (smette di funzionare immediatamente) e creane una nuova. Conserviamo solo un hash di ogni chiave, quindi non possiamo mostrartela di nuovo.

Risoluzione dei problemi