API de suppression d’arrière-plan : une requête en entrée, un PNG final en sortie.

Envoyer votre image

POST /v1/remove accepte l’image de quatre façons. Utilisez-en une seule ; si une requête en contient plusieurs, image_file l’emporte, puis image_file_b64, puis image_url, puis le corps brut. Ces exemples lisent votre clé dans la variable d’environnement REMOVEBG_API_KEY (définissez-la avec export REMOVEBG_API_KEY=…) ; notez les guillemets doubles, qui permettent au shell de la remplacer.

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

Chaque exemple enregistre le corps de la réponse dans un fichier. Ce fichier n’est une image que si le statut est 200 ; voir Traiter la réponse.

Traiter la réponse

La plupart des images uniques reviennent terminées dans la même réponse. Quand la file est exceptionnellement chargée et qu’une image prend plus de 55 secondes environ, vous recevez à la place 202 Accepted avec un identifiant de tâche. La tâche continue de tourner : récupérez son résultat grâce à l’identifiant. Renvoyer l’image lancerait une deuxième tâche et pourrait coûter un deuxième crédit.

Un exemple complet

Gère l’image finale, un 202, une tâche en échec et un délai maximal côté client. L’image n’est envoyée qu’une fois, et seules les vérifications de statut, sans risque, sont relancées.

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

• Arrêter votre script n’arrête pas la tâche : elle peut quand même se terminer et être facturée. Son résultat apparaît dans votre Studio.
• Les délais sont à votre choix, pas une promesse de notre part ; la plupart des images sont traitées en quelques secondes.
• L’endpoint compatible remove.bg se comporte différemment : il ne répond jamais 202 (voir ci-dessous).

Les lots de A à Z

1. Envoyer

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

Jusqu’à 100 URL d’images publiques, avec n’importe quelle option de /v1/remove. Les deux URL d’exemple ci-dessus coûteraient jusqu’à 2 crédits s’il s’agissait de vraies images. La réponse arrive immédiatement :

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 compte les entrées qui ne sont pas des URL http(s) et duplicates les doublons ; les deux sont écartés et jamais facturés. Conservez l’id : il permet de reprendre la tâche après un redémarrage.

2. Interroger la tâche

GET /v1/jobs/:id toutes les quelques secondes jusqu’à ce que done vaille true. status passe de queued à processing, puis se termine en succeeded, partial (certaines images ont échoué) ou failed. Un élément en cours de nouvelle tentative affiche 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. Télécharger chaque résultat

GET /v1/jobs/:id/result?item=N pour chaque élément réussi (ou utilisez son result_url). item est la position, comptée à partir de zéro. Les positions suivent votre liste une fois les URL invalides et en double retirées : si l’un de ces compteurs est supérieur à 0, associez les résultats par input plutôt que par indice.

• Un lot ne compte plus dans la limite de 3 lots ouverts dès que done vaut true.
• L’API n’a ni endpoint d’annulation, ni webhooks, ni téléchargement ZIP. Les lots lancés depuis la page Bulk peuvent y être annulés ou téléchargés en ZIP.

Nouvelles tentatives, doublons et facturation

Envoyez une Idempotency-Key et les nouvelles tentatives ne peuvent pas facturer deux fois. Ajoutez un en-tête Idempotency-Key (n’importe quelle chaîne unique de 255 caractères maximum, comme un UUID) à POST /v1/remove ou POST /v1/batch, une clé 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 Idempotent-Replayed: true : aucune nouvelle tâche ni nouvelle facturation, même si la première requête est encore en cours. La même clé avec une image ou des options différentes répond 409 idempotency_key_reused. Les clés sont liées à votre compte et n’expirent pas.

Sans clé, chaque POST crée une nouvelle tâche, et chaque tâche réussie coûte 1 crédit (le POST /v1.0/removebg compatible remove.bg n’accepte pas de clés). La lecture d’une tâche (GET /v1/jobs/…) est toujours gratuite et peut être répétée sans risque.

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

Ce qui coûte un crédit

Quand réessayer

Limites et stockage

Durée de conservation des résultats

Chaque résultat est stocké de manière privée dans votre compte pendant 48 heures après sa création, puis supprimé. D’ici là, vous pouvez le télécharger à nouveau gratuitement avec GET /v1/jobs/:id/result ou depuis votre Studio. Ensuite, les liens de résultat répondent 410 result_unavailable ; traiter à nouveau l’image crée une nouvelle tâche. Les statuts des tâches restent consultables après la suppression de l’image. Consultez la politique de confidentialité pour savoir comment les fichiers importés sont traités ; nous n’utilisons pas vos images pour entraîner des modèles.

Sécurité

Gardez votre clé API sur un serveur que vous contrôlez. Ne la placez pas dans du code exécuté dans le navigateur, des applications mobiles, des dépôts publics ou des URL. Pour permettre à vos propres utilisateurs de supprimer des arrière-plans, faites transiter leurs images par votre backend, et ajoutez-y votre propre authentification et vos propres limites de dépenses.

• L’API autorise CORS pour fonctionner depuis des outils et du code côté serveur. Cela ne rend pas pour autant sûr le fait de placer une clé dans une page web : n’importe qui pourrait l’y lire.
• Toutes les clés d’un compte puisent dans le même solde de crédits. Créez une clé distincte par application ou par environnement sur votre page de compte, pour pouvoir en révoquer une sans casser les autres.
• Si une clé fuite, révoquez-la immédiatement sur la page de compte (elle cesse aussitôt de fonctionner) et créez-en une nouvelle. Nous ne conservons qu’une empreinte (hash) de chaque clé : nous ne pouvons donc pas vous la réafficher.

Dépannage