API Recraft de suppression d'arrière-plan : un exemple fonctionnel

La plupart des API de suppression d'arrière-plan vous obligent à choisir un modèle d'édition d'image générique, puis à le guider avec le bon prompt pour extraire le sujet. recraft/remove-background supprime cette étape : c'est un modèle dédié qui reçoit une URL d'image et renvoie un PNG transparent conservant les détails de bord au niveau des cheveux et des poils. Pas de prompt, pas de prompt négatif, pas de paramètre d'intensité — juste l'image source en entrée, le détourage en sortie.

Ce guide parcourt un appel complet et testé : la structure de la requête, la réponse que vous recevrez réellement, et les schémas de production qui empêchent un traitement par lots de se bloquer à cause d'un cas limite (callbacks, idempotence, gestion des erreurs).

Prérequis :

• Obtenir une clé API hiapi depuis votre console
• Python 3.9+ avec requests installé (pip install requests), ou utilisez directement curl
• Votre image source doit être accessible à une URL publique — l'API de tâches de hiapi récupère les images par URL, pas par téléversement de fichier. Formats PNG, JPG ou WEBP, 5 Mo maximum, 16 millions de pixels maximum, les deux dimensions entre 256 et 4096 pixels.

Requête

Comme tous les modèles de génération sur hiapi, recraft/remove-background fonctionne via l'API de tâches asynchrones partagée : POST /v1/tasks avec model et input, et vous recevez immédiatement un taskId, le détourage s'exécutant en arrière-plan. Le contrat complet — en-têtes de requête, clés d'idempotence, codes de statut — est documenté de façon centralisée dans Créer une tâche ; la partie spécifique au modèle est input, qui pour ce modèle ne contient qu'un seul champ :

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "recraft/remove-background",
  "input": {
    "image_url": "https://static.hiapi.ai/model-covers/recraft-remove-background/2026/09/01/golden-input-2048.jpg"
  }
}'

import requests

payload = {
    "model": "recraft/remove-background",
    "input": {
        "image_url": "https://static.hiapi.ai/model-covers/recraft-remove-background/2026/09/01/golden-input-2048.jpg",
    },
}

response = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json=payload,
)
print(response.json())
# {"code": 200, "data": {"taskId": "tk-hiapi-..."}, "message": "success"}

image_url est le seul champ accepté par ce modèle — pas de format, response_format ni paramètre de taille. Si vous envoyez autre chose, l'API rejette l'ensemble de la requête avec une erreur de schéma avant même d'atteindre le modèle (voir Erreurs ci-dessous). La sortie est toujours un PNG transparent.

Interroger le résultat

Prenez le taskId de la réponse ci-dessus, interrogez GET /v1/tasks/{taskId} jusqu'à ce que data.status atteigne un état terminal. L'énumération des statuts est identique sur tous les modèles de la plateforme : queued → handling → archiving → success (ou fail). L'exécution réelle de ce modèle se termine généralement en moins de 10 secondes :

import time

task_id = response.json()["data"]["taskId"]

while True:
    r = requests.get(
        f"https://api.hiapi.ai/v1/tasks/{task_id}",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
    )
    data = r.json()["data"]
    if data["status"] in ("success", "fail"):
        break
    time.sleep(2)

print(data)

Lorsque le statut est success, data.output est un tableau contenant un seul élément :

{
  "status": "success",
  "output": [
    {
      "artifactId": "119426",
      "type": "image",
      "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M1RYTHQ5F94S2405YSC65EWM-0.png",
      "expireAt": 1789222580
    }
  ]
}

url est un lien temporaire — expireAt est un horodatage Unix situé environ une semaine plus tard, et non une adresse CDN permanente. Dès que la tâche réussit, téléchargez les octets et stockez-les dans votre propre stockage :

image_bytes = requests.get(data["output"][0]["url"]).content
with open("cutout.png", "wb") as f:
    f.write(image_bytes)

Schémas de production

Utilisez un callback plutôt qu'une boucle d'interrogation. Passez callback.url à la création ; hiapi vous enverra le résultat final par POST dès que la tâche sera terminée, au lieu de consommer des requêtes dans une boucle d'interrogation :

payload = {
    "model": "recraft/remove-background",
    "callback": {"url": "https://example.com/hiapi/callback", "when": "final"},
    "input": {"image_url": "https://your-cdn.example.com/product-01.jpg"},
}

when: "final" signifie que vous ne recevez qu'un seul callback, déclenché à l'état terminal (success ou fail), et non un par état intermédiaire. Pour un lot de photos de produits, c'est le réglage par défaut approprié : vous n'avez pas à maintenir une boucle d'interrogation pour chaque image.

Idempotence. Si la requête expire de votre côté mais a en réalité atteint hiapi, réessayer avec le même en-tête Idempotency-Key (documenté dans Créer une tâche) renvoie la tâche d'origine, sans facturer un second détourage. Cela vaut la peine d'être configuré pour tout traitement par lots qui réessaie en cas d'erreur réseau.

Erreurs — deux formes, pas une. Les requêtes mal formées et les échecs d'authentification sont renvoyés avec des enveloppes différentes ; un code qui ne vérifie que l'une d'elles ignore silencieusement l'autre :

// Erreur d'entrée (validation de schéma) — HTTP 400
{"code": 400, "data": null, "error_code": "INVALID_REQUEST", "message": "invalid input: image_url: missing required field \"image_url\""}

// Clé API invalide ou expirée — HTTP 401
{"error": {"code": "permission_denied", "message": "This API key is invalid...", "request_id": "...", "type": "hiapi_error"}}

Vérifiez d'abord error_code, puis revenez à error.code — ne partez pas du principe que tous les échecs ont les mêmes clés de premier niveau.

Tarification. 0,01 $ par image (20 crédits), quel que soit la résolution d'entrée, tarification uniforme. Les prix actuels figurent toujours sur la page de tarification.

Quand vous devez remplacer l'arrière-plan, pas seulement le détourer

recraft/remove-background ne produit qu'un détourage transparent — pas de remplissage, pas de scène. Si l'objectif est de remplacer par un fond de studio ou une scène lifestyle dans le même appel, c'est une autre tâche : utilisez un modèle image-vers-image et demandez-lui de régénérer l'arrière-plan autour du sujet conservé. Consultez Supprimer l'arrière-plan d'une image avec l'API : édition par prompt pour découvrir cette méthode et quand cela vaut la peine de payer plus cher qu'un simple détourage.

Questions fréquentes

recraft/remove-background accepte-t-il des prompts ou des paramètres d'intensité ? Non. Le schéma est strict — image_url est le seul champ accepté. L'envoi de champs supplémentaires comme format ou response_format renvoie un 400 avec le message "additional properties not allowed".

Quels formats et tailles d'image sont pris en charge ? Entrée : PNG, JPG ou WEBP, 5 Mo maximum, 16 millions de pixels maximum, les deux dimensions entre 256 et 4096 pixels. La sortie est toujours un PNG avec canal alpha.

Puis-je téléverser un fichier local au lieu d'une URL ? Non — image_url doit être une URL publique http(s):// que les serveurs hiapi peuvent récupérer. Téléversez d'abord vers un stockage objet ou un CDN.

Combien de temps l'URL de sortie reste-t-elle valide ? Le champ expireAt de chaque entrée de sortie est un horodatage Unix, généralement environ une semaine plus tard. Traitez-la comme un lien temporaire et copiez les octets dans votre propre stockage dès que la tâche réussit — ne conservez pas les liens temp.hiapi.ai à long terme.

Cela convient-il au traitement par lots de centaines de photos de produits ? Oui — soumettez une tâche par image, partagez un callback.url et laissez hiapi vous pousser les résultats au lieu d'interroger un par un. À 0,01 $/image, le traitement d'un catalogue de 1 000 images coûte 10 $ en génération.