Comment utiliser 851-labs/background-remover via l'API hiapi : curl, Python et requêtes exécutables

851-labs/background-remover transforme en un seul appel API une photo de produit, un portrait ou un animal en PNG transparent — sans prompt, sans masque, sans réglage de ratio d'aspect. Cet article présente la structure exacte de la requête, une commande curl exécutable, un script Python directement intégrable au backend, et l'erreur de schéma la plus fréquente.

Préparation

• Un compte hiapi et une clé API obtenue depuis la console.
• Une image hébergée sur une URL HTTPS publique. L'API de tâches reçoit une URL, et non un téléversement de fichier — si votre image source n'existe qu'en local, hébergez-la d'abord sur n'importe quel CDN ou stockage objet.

Toutes les requêtes sont envoyées au point de terminaison unifié de tâches :

POST https://api.hiapi.ai/v1/tasks
Authorization: Bearer sk-<your-key>
Content-Type: application/json

Structure de la requête (et la seule règle à retenir)

L'id du modèle est 851-labs/background-remover, à passer tel quel. Son schéma input ne comporte qu'un seul champ :

Champ	Type	Obligatoire	Description
image_url	string	Oui	Doit correspondre à ^https?://[^\s]+$ — une URL http(s) directement accessible.

C'est tout le schéma. Avant d'écrire du code, deux points méritent d'être connus :

1. Aucun champ prompt, mask, background-color ou aspect-ratio. Ce point de terminaison ne fait qu'une chose — la séparation premier plan/arrière-plan — et rien d'autre. Si vous avez ensuite besoin de recolorer ou de redimensionner, il faudra appeler un autre modèle.
2. Les champs superflus sont rejetés, et non ignorés. Si vous reprenez d'un payload d'un autre modèle un champ format ou size, la tâche renvoie 400 INVALID_REQUEST: <root>: additional properties 'format' not allowed avant même de démarrer.

Exemple minimal exécutable : curl

Créer une tâche :

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "851-labs/background-remover",
    "input": {
      "image_url": "https://your-cdn.example.com/product-shot.jpg"
    }
  }'

Une soumission réussie renvoie un id de tâche, situé dans data :

{"code": 200, "data": {"taskId": "tk-hiapi-..."}}

Interroger le résultat :

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-... \
  -H "Authorization: Bearer sk-<your-key>"

Pendant l'exécution, data.status passe successivement par queued → handling → archiving. Une fois terminé, il devient "success" et le PNG transparent apparaît dans data.output :

{
  "code": 200,
  "data": {
    "status": "success",
    "output": [{"url": "https://.../result.png", "expireAt": "..."}]
  }
}

L'URL de sortie a une durée de validité courte (voir expireAt). Téléchargez les octets du fichier dès que la tâche réussit — ne faites pas de hotlink et ne conservez pas l'URL brute.

Python prêt pour la production : soumission, interrogation, téléchargement

import time
import requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
API_KEY = "sk-<your-key>"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}


def remove_background(image_url: str) -> bytes:
    # 1. Créer la tâche
    resp = requests.post(API_BASE, headers=HEADERS, json={
        "model": "851-labs/background-remover",
        "input": {"image_url": image_url},
    }, timeout=60)
    body = resp.json()
    if resp.status_code != 200 or not (body.get("data") or {}).get("taskId"):
        raise RuntimeError(f"create failed [{resp.status_code}]: {body}")
    task_id = body["data"]["taskId"]

    # 2. Interroger jusqu'à l'état terminal
    deadline = time.time() + 300
    while time.time() < deadline:
        task = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS,
                            timeout=30).json().get("data") or {}
        if task.get("status") == "success":
            outputs = task.get("output") or []
            if not outputs or not outputs[0].get("url"):
                raise RuntimeError(f"task {task_id} succeeded but returned no output URL")
            # 3. Télécharger immédiatement — l'URL expire
            png = requests.get(outputs[0]["url"], timeout=120)
            png.raise_for_status()
            return png.content
        if task.get("status") == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        time.sleep(3)
    raise TimeoutError(f"task {task_id} still running after 300s")


if __name__ == "__main__":
    png = remove_background("https://your-cdn.example.com/product-shot.jpg")
    with open("cutout.png", "wb") as f:
        f.write(png)
    print(f"saved cutout.png ({len(png)} bytes)")

La suppression d'arrière-plan est une tâche d'image légère, qui se termine généralement bien avant le délai limite de 300 secondes — ce timeout n'est qu'un filet de sécurité, pas une durée d'exécution attendue.

Utiliser un callback au lieu de l'interrogation

Pour un backend Web, il est recommandé d'enregistrer un callback lors de la création de la tâche plutôt que d'interroger dans le gestionnaire de requête. L'objet callback se trouve à la racine, au même niveau que model :

{
  "model": "851-labs/background-remover",
  "input": { "image_url": "https://your-cdn.example.com/product-shot.jpg" },
  "callback": {
    "url": "https://your-app.example.com/hooks/hiapi",
    "when": "final"
  }
}

callback.when ne prend en charge que "final" — vous recevez exactement un POST lorsque la tâche passe à success ou fail, et aucun événement de progression. Le gestionnaire doit utiliser taskId comme clé pour éviter de traiter deux fois un webhook livré en double, et doit balayer régulièrement GET /v1/tasks/<id> pour vérifier les ids que votre point de terminaison n'a jamais confirmés.

Gestion des erreurs : celles qui comptent vraiment

400 INVALID_REQUEST à la création — le message d'erreur indique le champ exact :

Message	Cause
invalid input: image_url: missing required field "image_url"	input est vide, ou le nom de clé est mal orthographié
image_url: 'not-a-url' does not match pattern '^https?://[^\s]+$'	La valeur n'est pas une URL http(s) bien formée
<root>: additional properties 'format' not allowed	Vous avez envoyé un champ que ce modèle n'accepte pas

Ces erreurs sont définitives — réessayer avec le même payload échouera toujours. Corrigez le champ puis renvoyez la requête.

401 permission_denied à la création — le problème vient de la clé elle-même, pas du corps de la requête :

{"error": {"code": "permission_denied", "message": "...", "request_id": "...", "type": "hiapi_error"}}

Vérifiez les autorisations de modèle de cette clé dans la console.

La tâche renvoie status: "fail" — la création a réussi mais l'exécution elle-même a échoué (généralement parce que le backend n'a pas pu récupérer image_url). Lisez data.error.code / message ; ce type d'échec peut être réessayé en toute sécurité une fois avec un backoff.

Un GET sur un id de tâche inconnu ou expiré renvoie 404 avec {"code": 404, "data": null, "message": "task not found"} — dans tout balayage de réconciliation, considérez-le comme un état terminal, et non comme « toujours en attente ».

Étapes suivantes

• Page du modèle 851-labs/background-remover — exemples en direct et tarif actuel.
• Supprimer l'arrière-plan d'une image avec une édition basée sur prompt — une alternative basée sur Seedream, adaptée aux cas où vous voulez non seulement supprimer l'arrière-plan mais aussi le modifier.
• Documentation de l'API de tâches asynchrones hiapi — référence complète création/interrogation/callback.
• Documentation d'authentification hiapi — configuration de la clé API et format de l'en-tête de requête.
• Tarifs — tarif actuel par image.

Questions fréquentes

Ai-je besoin d'un prompt ? Non. Fournissez uniquement un image_url ; le modèle sépare lui-même le premier plan de l'arrière-plan.

La sortie est-elle vraiment transparente ? Oui — le résultat est un PNG avec canal alpha, directement compositeable sur n'importe quel arrière-plan.

Puis-je modifier le ratio d'aspect, la couleur ou l'arrière-plan dans le même appel ? Non. Ce point de terminaison ne fait que supprimer l'arrière-plan. Pour recolorer, redimensionner ou remplacer l'arrière-plan, utilisez ce PNG transparent comme entrée et enchaînez avec un modèle d'édition d'image.

Pourquoi est-ce que je reçois « additional properties '...' not allowed » ? Le schéma n'accepte qu'un seul champ, image_url. Tout champ repris d'un payload d'un autre modèle — format, size, background_color, n'importe lequel — est directement rejeté, et non silencieusement ignoré.

Comment dois-je enregistrer le résultat ? Téléchargez-le dès que la tâche atteint status: "success". L'URL de sortie est une URL signée avec expireAt ; elle ne convient pas au hotlink à long terme.

Combien cela coûte-t-il ? La facturation se fait à l'usage, par image. Consultez le tarif actuel sur la page des tarifs.