Comment supprimer l'arrière-plan d'une image avec une API

Supprimer un arrière-plan à la main prend quelques minutes par photo. Le faire pour chaque produit importé, chaque photo de profil ou chaque miniature de votre application demande une API de suppression d'arrière-plan : une requête HTTP en entrée, un détourage terminé en sortie.

Ce guide montre comment l'intégrer correctement. Vous aurez du code cURL, Python et JavaScript fonctionnel, les options de sortie à connaître, la gestion des images lentes et des traitements en masse, et la façon de relancer sans payer deux fois. Les exemples utilisent removebackground.dev, notre produit frère, mais les principes s'appliquent à n'importe quel fournisseur.

Comment fonctionne une API de suppression d'arrière-plan

Vous envoyez une image, le fournisseur exécute un modèle de segmentation qui sépare le sujet de l'arrière-plan, et vous recevez une nouvelle image. Le cœur du résultat est un canal alpha : une valeur par pixel qui indique dans quelle mesure chaque pixel appartient au sujet. Les pixels totalement opaques sont le sujet, les pixels totalement transparents sont l'arrière-plan, et les valeurs intermédiaires gèrent les contours doux comme les cheveux, la fourrure et le verre.

À partir de ce masque, l'API peut renvoyer plusieurs choses :

• Un détourage transparent, généralement un PNG ou un WebP sans arrière-plan
• Le sujet sur une couleur unie, aplati en JPG pour les marketplaces qui exigent un fond blanc
• Le masque lui-même, une image en niveaux de gris que vous pouvez utiliser dans votre propre chaîne de composition
• Une version recadrée ou redimensionnée, ajustée au sujet et à une taille exacte

La requête est la partie facile. Une intégration en production doit aussi gérer les images plus longues que d'habitude, les gros lots, les limites de débit, les relances et la protection de la clé API face aux utilisateurs.

Ce qu'il faut vérifier dans une API de suppression d'arrière-plan

Avant d'écrire du code, vérifiez ces points avec vos propres images et votre propre trafic.

Étape 1 : Créer une clé API

Inscrivez-vous sur removebackground.dev et créez une clé sur la page de votre compte. Les nouveaux comptes reçoivent 50 crédits gratuits, de quoi exécuter les exemples ci-dessous et tester sur vos propres images.

Stockez la clé dans une variable d'environnement sur votre serveur :

export REMOVEBG_API_KEY="your_api_key"

Chaque appel envoie la clé dans l'en-tête x-api-key, et chaque appel consomme les crédits de ce compte. Créez une clé distincte par application ou environnement pour pouvoir en révoquer une sans casser les autres.

Étape 2 : Supprimer un arrière-plan avec cURL

L'endpoint en temps réel est POST https://removebackground.dev/v1/remove. Le test le plus rapide est un envoi de fichier :

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 plupart des images individuelles reviennent terminées dans la même réponse, en général en quelques secondes, sous forme de PNG transparent en pleine résolution.

L'endpoint accepte l'image de quatre façons. Envoyez-en une :

Si une requête en contient plusieurs, image_file l'emporte, puis image_file_b64, puis image_url, puis le corps brut. Les options peuvent être envoyées en champs de formulaire, en clés JSON ou en paramètres de query string.

Un point d'attention : -o enregistre le corps quel que soit le statut. Si la clé est fausse ou l'image invalide, votre « PNG » est en réalité une erreur JSON. Vérifiez le code de statut avant de faire confiance au fichier.

Étape 3 : Gérer 200, 202 et les erreurs en Python

Une API de suppression d'arrière-plan ne peut pas garantir que chaque image se termine en une seule requête HTTP. Quand la file est inhabituellement chargée et qu'une image prend plus d'environ 55 secondes, removebackground.dev répond 202 Accepted avec un identifiant de tâche au lieu de l'image. La tâche continue, et vous récupérez le résultat avec cet identifiant.

La règle essentielle : ne renvoyez jamais l'image après un 202. Cela lance une seconde tâche et peut coûter un second crédit. Voici une version Python complète qui envoie l'image une seule fois et ne relance que les appels sûrs :

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

Il faut Python 3 et requests (pip install requests). Deux détails passent facilement inaperçus. D'abord, arrêter votre script n'arrête pas la tâche : elle peut quand même se terminer et être facturée, et le résultat apparaît dans le Studio de votre compte. Ensuite, GET /v1/jobs/:id/result répond 409 not_ready tant que la tâche tourne : traitez-le comme « attendre », pas comme un échec.

Le même flux en JavaScript (Node.js)

Le même flux en Node.js 18 ou plus récent, avec fetch, FormData et Blob intégrés, et l'envoi d'un fichier local :

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 accepte les requêtes CORS, ce qui est pratique pour les outils et les tests. Cela ne rend pas sûr un appel depuis une page web contenant votre clé. Plus de détails dans la section sécurité ci-dessous.

Étape 4 : Contrôler la sortie

La plupart des applications ne veulent pas d'un détourage brut en pleine résolution. Elles veulent une image produit carrée sur fond blanc, un petit aperçu ou un masque. Demander directement le fichier final à l'API vous évite une seconde étape de traitement. Voici les options de /v1/remove :

Chaque option coûte le même 1 crédit, et les paramètres inconnus sont ignorés sans avertissement : une faute de frappe ne déclenchera pas d'erreur. Une image carrée pour marketplace, avec le produit centré et 10 % de marge, ressemble à ceci :

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

Une réponse réussie contient aussi des en-têtes utiles. X-Credits-Remaining indique votre solde après l'image. X-Matte-Confidence (de 0 à 1) indique à quel point le masque est net, et X-Matte-Ambiguous-Ratio donne la part de pixels doux comme les cheveux, le verre ou le flou de mouvement. Journaliser ces deux valeurs vous permet de signaler les détourages peu fiables pour une vérification humaine au lieu de contrôler chaque image.

Étape 5 : Traiter des images en masse

Pour les imports de catalogue et les rattrapages, n'envoyez pas des centaines de requêtes individuelles. POST /v1/batch met en file jusqu'à 100 URL d'images publiques en une seule tâche, avec les mêmes options que /v1/remove, et répond 202 immédiatement :

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)

Quelques règles de la documentation à prendre en compte :

• Le statut de la tâche finit en succeeded, partial (certaines images ont échoué) ou failed. Chaque élément de items a son propre statut et, en cas d'échec, un code d'erreur.
• Les entrées qui ne sont pas des URL http(s) et les URL en double sont écartées et jamais facturées. Quand l'un de ces nombres est supérieur à 0, associez les résultats par input plutôt que par position.
• Vous pouvez avoir au maximum 3 tâches de lot ouvertes par compte. Un lot cesse de compter dès que done vaut true.
• Si les crédits s'épuisent en cours de lot, les images terminées restent payées et les autres sont marquées comme ignorées avec out_of_credits, sans frais.
• L'API n'a ni endpoint d'annulation, ni webhooks, ni téléchargement ZIP : le modèle est donc l'interrogation périodique. La lecture d'une tâche est gratuite et n'est pas soumise à la limite de débit.

Vous préférez un script à lancer tel quel ? Le guide de traitement par lots avec Python détaille un flux complet de dossier à dossier.

Étape 6 : Relancer en toute sécurité et garder une facturation prévisible

Les timeouts réseau sont à l'origine des doubles facturations. Votre client abandonne, relance, et il existe maintenant deux tâches pour une seule image. La solution est un en-tête Idempotency-Key : n'importe quelle chaîne unique de 255 caractères maximum, comme un UUID, une par image ou par lot. Si vous renvoyez la même requête avec la même clé, vous obtenez la tâche créée par la première, avec l'en-tête Idempotent-Replayed: true, et sans nouvelle facturation. Réutiliser une clé pour une autre image renvoie 409 idempotency_key_reused.

La facturation suit une règle simple : 1 crédit quand une image réussit, rien quand elle échoue. Les requêtes rejetées avant traitement, les images illisibles et les échecs après les propres relances du fournisseur sont gratuits, et retélécharger un résultat terminé est gratuit tant qu'il est conservé.

Les limites à prévoir

Si vous avez besoin de plus de 60 images par minute, l'endpoint de lot est la solution : une requête couvre jusqu'à 100 images. Stockez les résultats dans votre propre bucket dès que vous les téléchargez, car après 48 heures les liens de résultat renvoient 410. Selon la documentation du fournisseur, les images envoyées ne servent pas à entraîner des modèles.

Migrer depuis l'API remove.bg

Le site autonome et l'API en libre-service de remove.bg prennent fin le 1er décembre 2026 à 09:00 CET. Son API passe chez Leonardo.Ai, ce qui impose de modifier votre intégration. Si vous préférez ne rien réécrire, removebackground.dev propose un endpoint compatible remove.bg, et la migration tient en une ligne :

Vous gardez le même en-tête X-Api-Key (avec une clé removebackground.dev), les mêmes noms de paramètres, les mêmes en-têtes de réponse et le même format d'erreurs :

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

Connaissez les différences avant de basculer :

• Pas de 202. L'endpoint compatible attend jusqu'à 110 secondes, puis renvoie un timeout 503. La tâche continue et est facturée si elle réussit : relancer cette requête à l'aveugle lance donc une seconde tâche.
• Pas de clés d'idempotence sur cet endpoint. Si vous avez besoin de relances sûres, passez progressivement à /v1/remove.
• Certaines options sont acceptées mais ignorées : type et type_level (le sujet est détecté automatiquement), semitransparency et les options d'ombre (aucune ombre n'est ajoutée).
• La taille coûte toujours 1 crédit, y compris en pleine résolution.

Le guide de migration fournit du code avant et après pour cURL, Python, Node et PHP, ainsi que les étapes pour Zapier, Make et n8n.

Gardez votre clé API hors du client

C'est l'erreur qui coûte de l'argent réel. Si votre clé se trouve dans une page web, une application mobile, un dépôt public ou une URL, n'importe qui peut la lire et dépenser vos crédits.

• Pour permettre à vos utilisateurs de supprimer des arrière-plans, faites passer leurs images par votre backend et appelez l'API depuis celui-ci.
• Ajoutez votre propre connexion et des limites de dépenses par utilisateur dans ce backend.
• Utilisez une clé par application ou environnement.
• Si une clé fuite, révoquez-la sur la page du compte. Elle cesse de fonctionner immédiatement. Le fournisseur ne stocke qu'un hash de chaque clé : créez-en une nouvelle plutôt que d'essayer de récupérer l'ancienne.

Exemple : détourages pour les miniatures YouTube

Si vous créez des outils pour les créateurs, les miniatures sont un usage évident. Une miniature est surtout vue en petit format, donc le détourage doit la porter : un visage ou un produit, en grand, avec un contour net sur un arrière-plan simple. YouTube recommande 3840 x 2160 px en 16:9 avec une largeur minimale de 640 px, et accepte le JPG ou le PNG jusqu'à 50 Mo depuis un ordinateur, mais seulement 2 Mo depuis l'application mobile.

Côté API, il suffit d'un appel qui renvoie un PNG transparent recadré sur le sujet, prêt à être posé sur un canevas 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

Prenez une vraie photo pour le détourage plutôt qu'une image extraite d'une vidéo, souvent floue à cause du mouvement, et laissez le coin inférieur droit libre, car YouTube y affiche la durée de la vidéo. La page sur les miniatures YouTube couvre l'aspect design, et notre guide pour obtenir vos 1 000 premiers abonnés explique pourquoi les miniatures comptent autant.

Supprimer des arrière-plans depuis ChatGPT, Claude ou Cursor

Tous les besoins ne demandent pas de code. removebackground.dev fait aussi tourner un serveur MCP à l'adresse https://removebackground.dev/mcp : vous pouvez envoyer une photo dans ChatGPT, Claude, Cursor, VS Code ou n8n et demander la suppression de l'arrière-plan. Dans Claude Code, une seule commande suffit :

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

Tapez ensuite /mcp dans Claude Code pour vous connecter. Le serveur expose trois outils : remove_background, get_job pour les suppressions qui prennent plus de quelques secondes, et check_credits. Chaque image coûte 1 crédit, comme avec l'API.

Combien ça coûte

removebackground.dev fonctionne au paiement à l'usage, sans abonnement. Les crédits n'expirent jamais, les images en échec sont gratuites et les nouveaux comptes reçoivent 50 crédits gratuits. Via l'API, 1 crédit correspond à une suppression d'arrière-plan réussie en pleine résolution.

Les prix sont en USD, et les crédits non utilisés sont remboursables sous 30 jours. Des tarifs de volume au-delà de Scale sont disponibles sur demande. Consultez la page des tarifs pour les détails à jour.

En résumé

Une intégration solide de suppression d'arrière-plan repose sur quelques habitudes : gardez la clé sur votre serveur, vérifiez le statut avant d'enregistrer le corps, attendez la tâche au lieu de renvoyer l'image après un 202, envoyez un Idempotency-Key avec chaque POST et utilisez l'endpoint de lot pour les traitements en masse.

La référence complète, y compris la spécification OpenAPI 3.1, se trouve dans la documentation de l'API. Si vous travaillez aussi avec de la vidéo, notre comparatif des API de transcription YouTube et notre guide d'intégration de la reconnaissance vocale appliquent les mêmes principes de production au texte.