Come rimuovere lo sfondo dalle immagini con un'API

Rimuovere uno sfondo a mano richiede qualche minuto per foto. Farlo per ogni prodotto caricato, foto profilo o miniatura della tua app richiede un'API per rimuovere lo sfondo: entra una richiesta HTTP, esce un ritaglio pronto.

Questa guida mostra come integrarla nel modo giusto. Troverai codice cURL, Python e JavaScript funzionante, le opzioni di output da conoscere, come gestire le immagini lente e i job in blocco, e come riprovare senza pagare due volte. Gli esempi usano removebackground.dev, il nostro prodotto gemello, ma gli schemi valgono per qualsiasi provider.

Come funziona un'API per rimuovere lo sfondo

Invii un'immagine, il provider esegue un modello di segmentazione che separa il soggetto dallo sfondo e ricevi una nuova immagine. Il cuore del risultato è un canale alfa: un valore per pixel che indica quanto di ogni pixel appartiene al soggetto. I pixel completamente opachi sono il soggetto, quelli completamente trasparenti sono lo sfondo, e i valori intermedi gestiscono i bordi morbidi come capelli, pelo e vetro.

Da questa maschera, l'API può restituire diverse cose:

• Un ritaglio trasparente, di solito un PNG o WebP senza sfondo
• Il soggetto su un colore pieno, appiattito in un JPG per i marketplace che richiedono lo sfondo bianco
• La maschera stessa, un'immagine in scala di grigi da usare nella tua pipeline di compositing
• Una versione ritagliata o ridimensionata, adattata al soggetto e a una dimensione esatta

La richiesta è la parte facile. Un'integrazione in produzione deve gestire anche immagini che richiedono più tempo del solito, batch di grandi dimensioni, rate limit, retry e tenere la chiave API lontana dagli utenti.

Cosa valutare in un'API per rimuovere lo sfondo

Prima di scrivere codice, verifica questi punti con le tue immagini e il tuo traffico.

Passo 1: Crea una chiave API

Registrati su removebackground.dev e crea una chiave nella pagina del tuo account. I nuovi account ricevono 50 crediti gratis, sufficienti per eseguire gli esempi qui sotto e fare prove con le tue immagini.

Salva la chiave in una variabile d'ambiente sul tuo server:

export REMOVEBG_API_KEY="your_api_key"

Ogni chiamata invia la chiave nell'header x-api-key e ogni chiamata consuma i crediti di quell'account. Crea una chiave separata per ogni app o ambiente, così puoi revocarne una senza bloccare le altre.

Passo 2: Rimuovi lo sfondo con cURL

L'endpoint in tempo reale è POST https://removebackground.dev/v1/remove. Il test più rapido è il caricamento di un file:

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

La maggior parte delle singole immagini torna completa nella stessa risposta, di solito in pochi secondi, come PNG trasparente a piena risoluzione.

L'endpoint accetta l'immagine in quattro modi. Inviane uno:

Se una richiesta ne contiene più di uno, vince image_file, poi image_file_b64, poi image_url, poi il body grezzo. Le opzioni possono essere inviate come campi del form, chiavi JSON o valori della query string.

Una cosa a cui fare attenzione: -o salva il body qualunque sia lo stato. Se la chiave è sbagliata o l'immagine non è valida, il tuo "PNG" è in realtà un errore JSON. Controlla il codice di stato prima di fidarti del file.

Passo 3: Gestisci 200, 202 ed errori in Python

Un'API per rimuovere lo sfondo non può garantire che ogni immagine venga completata in una sola richiesta HTTP. Quando la coda è insolitamente carica e un'immagine richiede più di circa 55 secondi, removebackground.dev risponde 202 Accepted con un id del job invece dell'immagine. Il job continua e tu recuperi il risultato con l'id.

La regola chiave: non inviare mai di nuovo l'immagine dopo un 202. Avvieresti un secondo job e potresti spendere un secondo credito. Ecco una versione Python completa che invia l'immagine una sola volta e ripete solo le chiamate sicure:

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: a retry with the same key returns the same job, never a second charge.
    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 is the image; anything else raises

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


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

Servono Python 3 e requests (pip install requests). Due dettagli sono facili da trascurare. Primo, fermare lo script non ferma il job: potrebbe comunque completarsi ed essere addebitato, e il risultato compare nello Studio del tuo account. Secondo, GET /v1/jobs/:id/result risponde 409 not_ready mentre il job è in corso, quindi trattalo come "aspetta", non come un errore.

Lo stesso flusso in JavaScript (Node.js)

Lo stesso flusso in Node.js 18 o successivo, con fetch, FormData e Blob integrati e il caricamento di un file locale:

import { readFile, writeFile } from "node:fs/promises"
import { randomUUID } from "node:crypto"

const API = "https://removebackground.dev"
const KEY = process.env.REMOVEBG_API_KEY // server side only
const EXT = { "image/png": ".png", "image/jpeg": ".jpg", "image/webp": ".webp" }
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))

async function save(res, stem) {
  const mime = (res.headers.get("content-type") || "").split(";")[0]
  if (res.status !== 200 || !EXT[mime]) {
    throw new Error("HTTP " + res.status + ": " + (await res.text()).slice(0, 500))
  }
  const path = stem + EXT[mime]
  await writeFile(path, Buffer.from(await res.arrayBuffer()))
  return path
}

export async function removeBackground(filePath, stem = "result", maxWaitMs = 300000) {
  const form = new FormData()
  form.append("image_file", new Blob([await readFile(filePath)]), "upload")
  form.append("format", "png")

  const res = await fetch(API + "/v1/remove", {
    method: "POST",
    // Reuse the same Idempotency-Key if you retry this POST.
    headers: { "x-api-key": KEY, "Idempotency-Key": randomUUID() },
    body: form,
  })
  if (res.status !== 202) return save(res, stem)

  const { id } = await res.json()
  const deadline = Date.now() + maxWaitMs
  while (Date.now() < deadline) {
    await sleep(2000)
    const result = await fetch(API + "/v1/jobs/" + id + "/result", {
      headers: { "x-api-key": KEY },
    })
    if (result.status === 409) {
      const body = await result.json()
      if (body.error && body.error.code === "not_ready") continue
      throw new Error("Job " + id + ": " + body.error.code)
    }
    return save(result, stem)
  }
  throw new Error("Job " + id + " is still running. Check /v1/jobs/" + id + " later.")
}

console.log(await removeBackground("photo.jpg"))

L'API accetta richieste CORS, utile per strumenti e test. Questo non rende sicuro chiamarla da una pagina web con la tua chiave al suo interno. Ne parliamo nella sezione sulla sicurezza più sotto.

Passo 4: Controlla l'output

La maggior parte delle app non vuole un ritaglio grezzo a piena risoluzione. Vuole un'immagine prodotto quadrata su bianco, una piccola anteprima o una maschera. Chiedere all'API il file finale ti risparmia un secondo passaggio di elaborazione. Queste sono le opzioni di /v1/remove:

Ogni opzione costa lo stesso 1 credito e i parametri sconosciuti vengono ignorati senza avvisi, quindi un errore di battitura non genera un errore. Un'immagine quadrata per marketplace con il prodotto centrato e un margine del 10% si ottiene così:

curl -X POST https://removebackground.dev/v1/remove \
  -H "x-api-key: $REMOVEBG_API_KEY" \
  -F 'image_file=@product.jpg' \
  -F 'crop=1:1' -F 'padding=10%' \
  -F 'width=1000' -F 'height=1000' \
  -F 'format=jpg' -F 'bg_color=white' \
  -o product-square.jpg

Una risposta riuscita contiene anche header utili. X-Credits-Remaining mostra il saldo dopo l'immagine. X-Matte-Confidence (da 0 a 1) indica quanto è netta la maschera, e X-Matte-Ambiguous-Ratio indica la quota di pixel morbidi come capelli, vetro o mosso. Registrando questi due valori puoi segnalare i ritagli poco affidabili per una revisione manuale invece di controllare ogni immagine.

Passo 5: Elabora immagini in blocco

Per importazioni di catalogo e rielaborazioni, non lanciare centinaia di richieste singole. POST /v1/batch mette in coda fino a 100 URL pubblici di immagini come un unico job, con le stesse opzioni di /v1/remove, e risponde subito 202:

import os
import time
import uuid
import requests

API = "https://removebackground.dev"
s = requests.Session()
s.headers["x-api-key"] = os.environ["REMOVEBG_API_KEY"]

urls = ["https://example.com/front.jpg", "https://example.com/back.jpg"]

job = s.post(f"{API}/v1/batch",
             json={"image_urls": urls, "format": "png", "size": "hd"},
             headers={"Idempotency-Key": str(uuid.uuid4())}, timeout=30)
job.raise_for_status()
job_id = job.json()["id"]  # save it: it's how you resume after a restart

while True:
    time.sleep(3)
    status = s.get(f"{API}/v1/jobs/{job_id}", timeout=30).json()
    if status["done"]:
        break

print(status["status"], "credits charged:", status["credits_charged"])
for item in status["items"]:
    if item["status"] != "succeeded":
        print("failed:", item["input"], item.get("error"))
        continue
    img = s.get(item["result_url"], timeout=60)
    with open(f"out-{item['position']}.{item['format']}", "wb") as f:
        f.write(img.content)

Alcune regole della documentazione da tenere presenti:

• Lo stato del job finisce come succeeded, partial (alcune immagini non sono riuscite) o failed. Ogni elemento di items ha il proprio stato e, in caso di errore, un codice di errore.
• Le voci che non sono URL http(s) e gli URL ripetuti vengono scartati e mai addebitati. Quando uno di questi conteggi è superiore a 0, abbina i risultati tramite input anziché per posizione.
• Puoi avere al massimo 3 job batch aperti per account. Un batch smette di contare quando done è true.
• Se i crediti finiscono a metà batch, le immagini completate restano pagate e le altre vengono segnate come saltate con out_of_credits, senza costi.
• L'API non ha un endpoint di annullamento, webhook o download ZIP, quindi lo schema è il polling. Leggere un job è gratuito e non è soggetto a rate limit.

Preferisci uno script da eseguire così com'è? La guida al batch con Python illustra un flusso completo da cartella a cartella.

Passo 6: Riprova in sicurezza e mantieni la fatturazione prevedibile

I timeout di rete sono l'origine dei doppi addebiti. Il tuo client si arrende, riprova, e ora esistono due job per un'immagine. La soluzione è un header Idempotency-Key: qualsiasi stringa univoca fino a 255 caratteri, come un UUID, una per immagine o batch. Se invii di nuovo la stessa richiesta con la stessa chiave, ricevi il job creato dalla prima, con l'header Idempotent-Replayed: true, e nessun nuovo addebito. Riutilizzare una chiave per un'immagine diversa restituisce 409 idempotency_key_reused.

La fatturazione segue una regola semplice: 1 credito quando un'immagine riesce, niente quando fallisce. Le richieste rifiutate prima dell'elaborazione, le immagini illeggibili e gli errori dopo i retry interni del provider sono gratuiti, e scaricare di nuovo un risultato completato è gratuito finché è conservato.

Limiti da considerare nella progettazione

Se ti servono più di 60 immagini al minuto, la soluzione è l'endpoint batch: una richiesta copre fino a 100 immagini. Salva i risultati nel tuo bucket appena li scarichi, perché dopo 48 ore i link dei risultati rispondono 410. Secondo la documentazione del provider, le immagini caricate non vengono usate per addestrare modelli.

Migrare dall'API di remove.bg

Il sito autonomo e l'API self-service di remove.bg terminano il 1° dicembre 2026 alle 09:00 CET. La sua API passa a Leonardo.Ai, il che richiede di modificare l'integrazione. Se preferisci non riscrivere nulla, removebackground.dev ha un endpoint compatibile con remove.bg e la migrazione è una riga:

Mantieni lo stesso header X-Api-Key (con una chiave removebackground.dev), gli stessi nomi dei parametri, gli stessi header di risposta e lo stesso formato degli errori:

curl -H "X-Api-Key: $REMOVEBG_API_KEY" \
  -F 'image_file=@photo.jpg' -F 'size=auto' \
  -F 'crop=true' -F 'crop_margin=10%' -F 'bg_color=ffffff' \
  -o no-bg.jpg https://removebackground.dev/v1.0/removebg

Conosci le differenze prima di passare:

• Niente 202. L'endpoint compatibile attende fino a 110 secondi, poi restituisce un timeout 503. Il job continua e viene addebitato se riesce, quindi riprovare quella richiesta alla cieca avvia un secondo job.
• Niente chiavi di idempotenza su questo endpoint. Se ti servono retry sicuri, passa gradualmente a /v1/remove.
• Alcune opzioni sono accettate ma ignorate: type e type_level (il soggetto viene rilevato automaticamente), semitransparency e le opzioni per le ombre (non vengono aggiunte ombre).
• Ogni dimensione costa 1 credito, compresa la piena risoluzione.

La guida alla migrazione contiene codice prima e dopo per cURL, Python, Node e PHP, oltre ai passaggi per Zapier, Make e n8n.

Tieni la chiave API lontana dal client

Questo è l'errore che costa soldi veri. Se la tua chiave si trova in una pagina web, in un'app mobile, in un repository pubblico o in un URL, chiunque può leggerla e spendere i tuoi crediti.

• Per permettere ai tuoi utenti di rimuovere sfondi, fai passare le loro immagini dal tuo backend e chiama l'API da lì.
• Aggiungi nel backend il tuo sistema di accesso e limiti di spesa per utente.
• Usa una chiave per ogni app o ambiente.
• Se una chiave trapela, revocala nella pagina dell'account. Smette di funzionare immediatamente. Il provider salva solo un hash di ogni chiave, quindi creane una nuova invece di provare a recuperare quella vecchia.

Esempio: ritagli per le miniature di YouTube

Se crei strumenti per creator, le miniature sono un uso ovvio. Una miniatura si vede soprattutto in piccolo, quindi il ritaglio deve reggerla: un volto o un prodotto, grande, con un bordo netto su uno sfondo semplice. YouTube consiglia 3840 x 2160 px in 16:9 con una larghezza minima di 640 px, e accetta JPG o PNG fino a 50 MB da computer, ma solo 2 MB dall'app mobile.

Lato API è una sola chiamata che restituisce un PNG trasparente ritagliato sul soggetto, pronto da posizionare su una tela 16:9:

curl -X POST https://removebackground.dev/v1/remove \
  -H "x-api-key: $REMOVEBG_API_KEY" \
  -F 'image_file=@me.jpg' \
  -F 'crop=true' -F 'padding=5%' \
  -o me-cutout.png

Scatta una foto vera per il ritaglio invece di prendere un fotogramma del video, perché i fotogrammi sono spesso mossi, e lascia libero l'angolo in basso a destra, dove YouTube mostra la durata del video. La pagina sulle miniature di YouTube copre l'aspetto grafico, e la nostra guida per ottenere i primi 1.000 iscritti spiega perché le miniature contano così tanto.

Rimuovere lo sfondo da ChatGPT, Claude o Cursor

Non tutti i lavori richiedono codice. removebackground.dev gestisce anche un server MCP all'indirizzo https://removebackground.dev/mcp, così puoi caricare una foto in ChatGPT, Claude, Cursor, VS Code o n8n e chiedere di rimuovere lo sfondo. In Claude Code basta un comando:

claude mcp add --transport http removebackground https://removebackground.dev/mcp

Poi digita /mcp in Claude Code per accedere. Il server offre tre strumenti: remove_background, get_job per le rimozioni che richiedono più di qualche secondo, e check_credits. Ogni immagine costa 1 credito, come con l'API.

Quanto costa

removebackground.dev è a consumo, senza abbonamento. I crediti non scadono mai, le immagini non riuscite sono gratuite e i nuovi account ricevono 50 crediti gratis. Tramite l'API, 1 credito corrisponde a una rimozione dello sfondo riuscita a piena risoluzione.

I prezzi sono in USD e i crediti non utilizzati sono rimborsabili entro 30 giorni. Prezzi per volumi superiori a Scale sono disponibili su richiesta. Consulta la pagina dei prezzi per i dettagli aggiornati.

In sintesi

Un'integrazione solida per rimuovere lo sfondo si riduce a poche abitudini: tieni la chiave sul tuo server, controlla lo stato prima di salvare il body, attendi il job invece di inviare di nuovo dopo un 202, invia un Idempotency-Key con ogni POST e usa l'endpoint batch per il lavoro in blocco.

Il riferimento completo, inclusa la specifica OpenAPI 3.1, si trova nella documentazione dell'API. Se lavori anche con i video oltre che con le immagini, il nostro confronto tra API per trascrizioni di YouTube e la nostra guida all'integrazione speech-to-text applicano gli stessi schemi di produzione al testo.