Documentation de l'API de suppression d'arrière-plan

Description

Cette API cloud s'appuie sur la détection intelligente des objets saillants (SOD) pour automatiser la suppression d'arrière-plan avec une grande précision. Consultez la documentation ci-dessous pour les performances et l'intégration. Pour une vitesse optimale, nous recommandons des images source de moins de 5 Mo.

🥥 Remarques importantes

Conservation des données : les URL des images générées et les couches alpha (masques) ne restent valides qu'un jour. Téléchargez-les et stockez-les rapidement pour éviter toute perte.
Limites de débit : cet endpoint est limité par défaut à 2 QPS (requêtes par seconde). Pour davantage de concurrence ou de débit, contactez notre équipe commerciale.

Historique des versions

4.0 | Date de publication: 2025-03-20
4.0.1 | Date de publication: 2026-07-01 (Ajout de la prise en charge des résultats multiples)

Exigences relatives à l'image d'entrée

Format d'image	Résolution	Taille du fichier
jpg, jpeg, bmp, png, webp, bitmap, avif, tiff, heic, heif	Integer between [4096~4096]	Jusqu'à 10 Mo inclus

🥥 Remarques importantes

Les URL de sortie expirent après 24 heures.
La limite par défaut est de 2 QPS. Contactez-nous pour augmenter vos limites de concurrence.

URL de requête

🥥 https://coco-openapi.yezisheji.com/api/v1/segment/submit
https://coco-openapi.yezisheji.com/api/v1/segment/task_info

Méthodes de requête et exemples

# Créer une tâche

Plain Text|

curl -k 'https://coco-openapi.yezisheji.com/api/v1/segment/submit' \
-H 'X-API-KEY: YOUR_API_KEY' \
-F 'sync=1' \
-F 'image_file=@/path/of/image.jpg'

# Récupérer une tâche

Plain Text|

curl -k 'https://coco-openapi.yezisheji.com/api/v1/segment/task_info' \
-H 'X-API-KEY: YOUR_API_KEY' \
-F 'task_id={YOUR_TASK_ID}'

Authentification et autorisations

Une clé API doit être demandée avant d'utiliser ces services. Pour savoir comment l'obtenir, contactez notre équipe commerciale.
Authentification API : transmettez votre jeton secret dans le Header HTTP. Pour garantir la légitimité des requêtes et empêcher le vol d'identifiants, conservez votre clé API en lieu sûr.

Construire la requête

1、Suppression de l'arrière-plan d'une image

POST /api/v1/segment/submit

Paramètres de requête:

Nom du paramètre	Type	Valeur par défaut	Valeurs possibles	Description
image_url	String	None	-	URL de l'image dont supprimer l'arrière-plan (mutuellement exclusive avec image_file).
image_file	String($binary)	None	-	Fichier local dont supprimer l'arrière-plan (mutuellement exclusif avec image_url).
rsz_w	int	None	Integer between [0~4096]	Si la valeur est supérieure à 0, l'image renvoyée est redimensionnée proportionnellement à la largeur indiquée (rsz_w).
rsz_h	int	None	Integer between [0~4096]	Si la valeur est supérieure à 0, l'image renvoyée est redimensionnée proportionnellement à la hauteur indiquée (rsz_h).
crop_object	int	None	0、1	La valeur 1 active le recadrage sur la zone du sujet principal de l'image.
multi_result	int	None	0、1	Indique si plusieurs résultats de détourage doivent être renvoyés. Remarque : la facturation dépend du nombre de résultats renvoyés. Par exemple, 3 résultats consomment 3 tâches de détourage. Le nombre réel dépend de la prédiction du modèle et est normalement inférieur ou égal à 5.
sync	int	0	0、1	Indique si le mode synchrone est activé. 0, mode asynchrone : l'API renvoie immédiatement task_id sans attendre la fin ; récupérez ensuite le résultat via l'interface task_info. 1, mode synchrone : l'API attend la fin du détourage avant de renvoyer le résultat.
output_type	int	1	1、2、3	Résultat image et masque. 1 Renvoie uniquement l'image résultante. 2 Renvoie l'image résultante et le masque. 3 Renvoie uniquement le masque.
output_format	String	png	jpeg、png	Format de l'image renvoyée. png : arrière-plan transparent. jpeg : arrière-plan blanc par défaut, non transparent. Pour choisir une couleur, utilisez le paramètre bg_color.
bg_color	String	None	Hexadecimal color string starting with "#"	Définit une couleur d'arrière-plan unie. Disponible uniquement lorsque output_format vaut jpeg. Exemples : « #FFFFFF », « #000000 », etc.
output_mask_format	String	jpeg	jpeg、png	Format de l'image de masque renvoyée.
timeout	int	10	1-60	Durée maximale, en secondes, pendant laquelle l'API attend le traitement. Disponible uniquement lorsque sync=1 (mode synchrone).

Remarque : si rsz_w et rsz_h sont tous deux définis, l'image est redimensionnée aux dimensions indiquées sans conserver ses proportions. Lorsque crop_object est activé, les proportions de l'image d'origine ne sont pas conservées.

# Exemple de réponse en mode asynchrone (sync=0)

JSON|

{
    "data": {
        "task_id": "67fcadf7b3b99f4447f9ddce"
    },
    "status": 200,
    "timestamp": 1744512855,
    "trace_id": "ae173819-6fb5-4e88-a587-ff654f2de9bf",
    "message": "ok"
}

# Exemple de réponse en mode synchrone (sync=1)

JSON|

{
    "data": {
        "created_at": 1744513021,
        "completed_at": 1744513022,
        "image": "{image oss url}",
        "mask": "{mask oss url}"
    },
    "status": 200,
    "timestamp": 1744513022,
    "trace_id": "3a2a0b4a-8b4a-4034-865a-8a5ebcc7e93c",
    "message": "ok"
}

2、Suppression de l'arrière-plan d'une image

POST /api/v1/segment/submit

Paramètres de requête:

# Exemple de réponse en mode asynchrone (sync=0)

JSON|

{
    "data": {
        "task_id": "67fcaec66b4a4af9c824fcd2",
        "created_at": 1744513062,
        "completed_at": 1744513063,
        "status": 2,
        "mask": "{mask oss url}",
        "image": "{image oss url}",
        "result_cnt": 2,
        "results": [
            {
                "task_id": "{task_id_1}",
                "created_at": 1744513062,
                "completed_at": 1744513063,
                "status": 2,
                "mask": "{mask oss url}",
                "image": "{image oss url}"
            },
            {
                "task_id": "{task_id_2}",
                "created_at": 1744513062,
                "completed_at": 1744513063,
                "status": 2,
                "mask": "{mask oss url}",
                "image": "{image oss url}"
            }
        ]
    },
    "status": 200,
    "timestamp": 1744513180,
    "trace_id": "952a636e-3a9d-4e72-b470-681c61fcd763",
    "message": "ok"
}

Nom du paramètre	Type	Description
result_cnt	Number	Nombre de résultats renvoyés (lorsque multi_result=1).

Nom du paramètre	Type	Valeur par défaut	Valeurs possibles	Description
task_id	String	None	Valid Task ID	task_id renvoyé par l'API de détourage (limité au mode asynchrone avec sync=0).

3、Consultation du quota d'utilisation

GET /api/v1/segment/quota

Paramètres de requête: Aucun

# Exemple de réponse

Plain Text|

{
    "data": {
        "used_tasks": 888,
        "remaining_tasks": 88888
    },
    "status": 200,
    "timestamp": 1778555905,
    "trace_id": "b9d83cd6-f220-436f-ac30-52fcd8d5b30a",
    "message": "ok"
}

Paramètres de réponse

Nom du paramètre	Type	Description
image	String	URL de l'image après suppression de l'arrière-plan.
mask	String($binary)	URL de l'image de masque.
results	Array	Tableau des résultats (lorsque multi_result=1).
result_cnt	Number	Nombre de résultats renvoyés (lorsque multi_result=1).
status	String	data.status, statut de la tâche : 2 Terminée 1 En cours -1 Échec -2 Délai d'attente dépassé
used_tasks	Number	Nombre de tâches de détourage utilisées.
remaining_tasks	Number	Nombre de tâches de détourage encore disponibles.

Codes de statut

Codes de statut de la réponse HTTP

Code de statut HTTP	Description
200	Requête réussie.
400	Erreur dans les paramètres client. Vérifiez que tous les paramètres sont présents et que leurs valeurs sont correctes.
401	Échec de l'authentification. Vérifiez la clé X-API-KEY et l'activation du service.
404	L'URL ou la ressource demandée n'existe pas. Vérifiez l'URL ou l'identifiant de tâche présent dans celle-ci.
412	Échec de la validation de l'URL ou du fichier image importé. Vérifiez l'URL ou le fichier.
413	Le fichier importé dépasse la taille autorisée. Vérifiez sa taille et la limite maximale du service.
429	La fréquence des requêtes dépasse la limite QPS (2 par défaut). Ralentissez les requêtes ou contactez l'équipe commerciale pour augmenter cette limite.
500	Exception serveur. Contactez l'équipe commerciale ou le support technique.