API de serveur

Toutes les requêtes API sont des requêtes HTTP standard pour URL de type REST. Les réponses sont soit JSON, soit une image (pour la récupération du résultat).

Authentification

L'API utilise une authentification d'accès de base HTTP standard. Toutes les requêtes vers l'API doivent inclure vos identifiants API, l'identifiant API étant l'utilisateur et le secret API étant le mot de passe. Veuillez noter que ClippingMagic.js utilise uniquement votre identifiant API mais ne révèle pas votre secret API à vos utilisateurs.

Sécurité

Toutes les requêtes doivent être passées via HTTPS et vous devez authentifier toutes les requêtes.

Votre bibliothèque des clients http doit prendre en charge le SNI (Server Name Indication) pour que les requêtes puissent être adressées. Si vous recevez d'étranges erreurs de protocole d'accord (handshake), c'est très probablement le cas.

Dorsal/Frontal

Veuillez noter que toutes les opérations de téléchargement en amont et en aval se produisent sur le serveur dorsal, mais que toutes les opérations de visualisation et d'édition ont lieu dans l'Éditeur intelligent.

Cette distinction protège votre clé API, tout en offrant à l'utilisateur final un déroulement fluide des opérations.

Taux limité

Le taux d'utilisation de l'API est limité avec des allocations généreuses et aucune limite supérieure stricte au-delà de vos crédits API.

Au cours d'un fonctionnement normal axé sur l'utilisateur final, il est peu probable que vous rencontriez une limitation de débit, car l'utilisation a alors tendance à refluer et à s'écouler d'une manière que le service gère avec fluidité.

Cependant, pour les travaux par lots, nous vous recommandons de commencer avec au plus 5 fils, en ajoutant 1 nouveau fil toutes les 5 minutes jusqu'à ce que vous ayez atteint le niveau de parallélisme souhaité. Veuillez nous contacter avant de commencer si vous avez besoin de plus de 100 fils simultanés.

Si vous soumettez trop de requêtes, vous commencerez à recevoir des réponses 429 Too Many Requests. Dans ce cas, vous devrez appliquer un retrait linéaire : lorsque vous recevez la première réponse de ce type, attendez 5 secondes avant de soumettre la requête suivante. Lorsque vous recevez la deuxième réponse 429 consécutive, attendez 2*5=10 secondes avant de soumettre la requête suivante. À la troisième réponse, attendez 3*5=15 secondes, et ainsi de suite.

Vous pouvez réinitialiser le compteur de recul après une requête réussie et vous devez appliquer le recul fil par fil (c'est-à-dire que les fils doivent fonctionner indépendamment les uns des autres).

Objet JSON d'erreur

Nous utilisons des statuts HTTP classiques pour indiquer le succès ou l'échec d'une requête API, et incluons d'importantes informations sur l'Objet JSON d'erreur retourné.

Nous nous efforçons de toujours renvoyer un Objet JSON d'erreur en cas de requête problématique. Des erreurs de serveur internes pouvant causer des messages d'erreur non JSON sont toutefois théoriquement possibles.

Attributs

statusLe statut HTTP de la réponse, répété ici pour faciliter l'élimination des erreurs.
codeCode d'erreur interne Clipping Magic.
messageMessage d'erreur interprétable par l'utilisateur, destiné à faciliter l'élimination des erreurs.

Si le statut HTTP de votre requête est 200, aucun Objet JSON d'erreur ne sera retourné, et vous pouvez présumer que la requête dans son ensemble a réussi.

Certaines bibliothèques de clients HTTP déclenchent des exceptions pour les états HTTP dans la plage 400599. Vous devez repérer ces exceptions et les traiter adéquatement.

HTTP StatusSignification
200-299

Succès

400-499

Un problème est survenu avec les informations fournies dans la requête (un paramètre peut être manquant, par exemple). Veuillez revoir le message d'erreur pour déterminer la manière de le résoudre.

500-599

Une erreur interne Clipping Magic s'est produite. Patientez un instant puis réessayez. Veuillez nous envoyer un e-mail si le problème persiste.

Les erreurs API récentes sont répertoriées sur la page de votre compte pour faciliter le débogage.

Exemple de message d'erreur

{
  "error" : {
    "status" : 400,
    "code" : 1006,
    "message" : "Failed to read the supplied image. "
  }
}

Objet JSON d'image

Les enregistrements d'images sont représentés de manière uniforme avec un Objet JSON, retourné par plusieurs actions API.

Attributs

id

Identifiant unique pour l'image. Requis pour permettre aux utilisateurs de modifier l'image et de télécharger ses résultats.

secret

La clé secrète requise pour modifier cette image avec ClippingMagic.js

resultRevision

Nombre entier indiquant la révision la plus récente disponible pour le téléchargement (0 = pas de résultat disponible pour l'instant).

Vous permet de déterminer si un résultat plus récent est disponible pour cette image que vous avez antérieurement téléchargée.

originalFilename

Une chaîne contenant le nom de fichier fourni lors du téléchargement de l'image originale.

test

true signifie qu'il s'agit d'une image-test qui peut être traitée gratuitement, mais dont le résultat comportera un tatouage numérique.

false signifie qu'il s'agit d'une image en production qui nécessite des crédits pour être traitée, mais le résultat ne comportera pas de tatouage numérique.

Exemple

{
  "id" : 2346,
  "secret" : "image_secret1",
  "resultRevision" : 0,
  "originalFilename" : "example_image1.jpg",
  "imageCategoryUser" : "Photo",
  "imageCategoryAi" : "Photo",
  "test" : false
}

Téléchargement en amont POST https://clippingmagic.com/api/v1/images

Pour télécharger une image, vous effectuez le téléchargement d'un fichier HTTP POST standard. Ce point d'extrémité doit être appelé de votre application dorsale. Il ne peut pas être appelé depuis le javascript de votre page Web. N'oubliez pas que le type de contenu doit être multipart/form-data pour le téléchargement en amont de fichiers binaires.

Paramètres

L'image source doit être fournie de l'une des manières suivantes :

image
Binaire

Fichier binaire.

image.base64
Chaîne

Chaîne encodée base64. La taille de la chaîne doit être de 1mégaoctet maximum.

image.url
Chaîne

URL à récupérer.

Doit être un fichier .bmp, .gif, .jpeg, .png ou .tiff.

La taille de téléchargement maximale des images (= width × height) est 33 554 432 pixels, qui est réduite à 4 194 404 pixels, à moins d'être remplacée par maxPixels ci-dessous. Veuillez réduire vos images à cette dimension ou à une dimension inférieure avant de les télécharger.

test
Booléen
true, false

Indiquez true pour indiquer qu'il s'agit d'une image d'essai.

Omettez ou passez false pour les images de production.

Les images-tests sont traitées gratuitement mais comporteront un tatouage numérique.

format
Énuméré
json, result, clipping_path_svg, clipping_path_tiff, alpha_mask_png

format=json (default): Aucun résultat de découpage automatique n'est généré et l'objet Image JSON est renvoyé. Utilisez ce mode lorsqu'un opérateur humain examine et retouche potentiellement le résultat à l'aide de ClippingMagic.js.

format=result génère et récupère le résultat du découpage automatique.

format=clipping_path_svg génère le résultat du découpage automatique et récupère le chemin de découpage (SVG).

format=clipping_path_tiff génère le résultat du découpage automatique et récupère le chemin de découpage (TIFF).

format=alpha_mask_png génère le résultat du découpage automatique et récupère le masque alpha (PNG). Le masque alpha a la même taille que l'image source. Le fait de l'appliquer à l'image source ne donne pas le résultat, car les fonctionnalités Protection des bords et Nettoyeur de halo améliorent les couleurs du contour.

L'id et le secret sont retournés dans les en-têtes x-amz-meta-id et x-amz-meta-secret lors de la récupération d'un résultat non JSON. Veillez donc à les enregistrer afin de pouvoir examiner et modifier votre résultat avec ClippingMagic.js. Voir tous les en-têtes inclus dans la réponse

La récupération de l'Objet JSON d'image ne débite pas votre compte. Vous n'êtes facturé(e) que lorsque vous téléchargez les résultats en production.

maxPixels
Entier
1000000 à 26214400

Change la taille d'image maximale (= width × height) utilisée lors du redimensionnement de l'image après le téléchargement.

Défaut : 4 194 404 pixels

background.color
#RRGGBB
#0055FF

Omettez pour utiliser un arrière-plan transparent et obtenez un résultat PNG.

Incluez pour obtenir un arrière-plan opaque de la couleur spécifiée et un résultat output.opaqueFileFormat (JPEG par défaut).

Veillez à inclure le « # ».

Configurez les paramètres de traitement :

processing.mode
Énuméré
auto, photo, graphics, scan

Contrôlez le mode de traitement utilisé pour l'image.

Défaut : auto

processing.autoClip
Booléen
true, false

Activez (défaut) ou désactivez le découpage automatique lorsque l'image est éditée dans l'application Web.

Désactivez pour télécharger des images via l'API, puis procédez à un détourage de forme libre à un endroit autre que l'avant-plan évident (le cas échéant).

Défaut : true

processing.autoHair
Booléen
true, false

Activez (défaut) ou désactivez l'application d'un masque automatique pour les cheveux.

Défaut : true

processing.allowGraphicsMode
Booléen
true, false

Activez (défaut) ou désactivez la sélection automatique du mode Graphiques.

Ce réglage ne s'applique pas lorsque format=json.

Défaut : true

processing.allowScanMode
Booléen
true, false

Activez (défaut) ou désactivez la sélection automatique du mode Numérisation.

Ce réglage ne s'applique pas lorsque format=json.

Défaut : true

Configurez les niveaux de couleur :

colors.auto
Booléen
true, false

Réglez automatiquement les niveaux de couleur pour améliorer le contraste.

Défaut : false

colors.brightness
Entier
-100 à 100

Réglez la luminosité de l'image de sortie.

Défaut : 0

colors.shadows
Entier
-100 à 100

Ajustez les ombres de l'image de sortie. Les valeurs positives correspondent à des ombres plus sombres.

Défaut : 0

colors.highlights
Entier
-100 à 100

Ajustez les hautes lumières de l'image de sortie. Les valeurs positives correspondent à des hautes lumières plus claires.

Défaut : 0

colors.temperature
Entier
-100 à 100

Ajustez la température des couleurs de l'image de sortie. Les valeurs positives correspondent à des couleurs plus chaudes.

Défaut : 0

colors.saturation
Entier
-100 à 100

Ajustez la saturation de l'image de sortie. Les valeurs positives correspondent à plus de saturation.

Défaut : 0

Configurez la suppression d'une couleur de l'arrière-plan qui est projetée sur l'avant-plan, comme avec un écran vert :

colorCast.auto
Booléen
true, false

Déterminez automatiquement la couleur de l'arrière-plan à supprimer de l'avant-plan.

Défaut : false

colorCast.color
#RRGGBB
#A84400

La couleur d'arrière-plan spécifiée manuellement à supprimer de l'avant-plan.

Omettez pour détecter automatiquement.

colorCast.foregroundGuard
Flottant
0.0 à 20.0

Des valeurs plus élevées réduisent l'impact de la suppression de la dominante de couleur sur les couleurs de premier plan authentiques similaires à la couleur de dominante mais plus saturées que celles supprimées.

Défaut : 4.0

Configurez l'équilibre des blancs :

whiteBalance.auto
Booléen
true, false

Déterminez automatiquement la couleur de référence à utiliser pour l'équilibre des blancs.

Défaut : false

whiteBalance.color
#RRGGBB
#968386

La couleur de l'équilibre des blancs spécifiée manuellement.

Omettez pour détecter automatiquement.

Configurez les touches de finition :

effects.dropShadow
[xOffsetPx:int] [yOffsetPx:int] [blurRadiusPx:int, 0 to 75] [opacity:float, 0 to 1]
30 30 25 0.75

Ajoutez un effet d'ombre portée sur le résultat découpé.

effects.reflection
[yOffsetPx:int, 0 to 400] [heightPx:int, 0 to 800] [opacity:float, 0 to 1]
0 200 0.5

Ajoutez un effet de reflet au résultat découpé.

Configurer les paramètres du bord :

edges.corners
Booléen
true, false

Utilisez (défaut) ou désactivez la protection des coins.

edges.smoothing
Énuméré
smart, fixed

Utilisez le lissage smart (défaut) ou fixed.

edges.smoothingLevel
Flottant
0.0 à 10.0

Configurez la quantité de lissage appliqué au résultat.

Défaut 1.0

edges.feathering
Énuméré
fixed, auto, local

Utilisez auto (défaut), local ou estompage fixed.

edges.featheringRadiusPx
Flottant
0.0 à 6.0

Configurez la quantité d'estompage appliqué au résultat.

Défaut : 1.0

edges.offsetPx
Flottant
0.0 à 10.0

Configurez le décalage du contour appliqué au résultat.

Défaut : 0.0

Adaptez la sortie au résultat

fit.toResult
Booléen
true, false

Activez ou désactivez (défaut) ajuster au résultat.

Si désactivé, le reste des paramètres de cette section sont effectivement ignorés.

fit.paddingPercent
Flottant
0.0 à 35.0

Le remplissage à appliquer autour du résultat ajusté, en tant que pourcentage de la dimension du résultat.

Défaut : 5.0

fit.paddingPixels
Entier
0 à 250

Le remplissage en pixels à appliquer autour du résultat ajusté.

Si non spécifié, un pourcentage de remplissage est utilisé à la place.

fit.objectSize
Énuméré
small, medium, large

Vous pouvez spécifier une dimension synthétique de l'objet. Ceci est utile pour le commerce électronique pour donner à l'acheteur une idée générale de la taille du produit par rapport aux autres produits.

Défaut : large (= le résultat n'est pas redimensionné)

fit.verticalAlignment
Énuméré
top, middle, bottom

Spécifiez comment aligner le résultat s'il y a un excès d'espace vertical.

S'applique également lors de la distribution de l'espace excédentaire en raison de l'application du format d'image ou de la taille cible, voir ci-dessous.

Défaut : middle

fit.shadows
Énuméré
ignore, pad, tight

Vous pouvez ignorer les ombres, ou remplir uniformément des deux côtés pour préserver les ombres ou asymétriquement aux endroits requis pour ne pas couper l'ombre.

Défaut : pad

fit.rotationDeg
Flottant
-360.0 à 360.0

Faites tourner l'image. Les valeurs positives sont le sens antihoraire.

Défaut : 0

Contrôlez les dimensions et proportions du résultat :

result.aspectRatio
[width:float, >0]:[height:float, >0]
4:3

Assurez-vous que le résultat utilise les proportions fournies.

fit.verticalAlignment contrôle la distribution de l'espace vertical en excès.

Défaut : non appliqué

result.targetSize
[width:int, >0] [height:int, >0]
400 300

Assurez-vous que le résultat utilise la les dimensions fournies.

fit.verticalAlignment contrôle la distribution de l'espace vertical en excès.

Défaut : non appliqué

result.allowEnlarging
Booléen
true, false

Contrôle si le résultat est autorisé à devenir plus grand que l'image d'entrée ou non.

Défaut : false

Contrôlez les options de sortie :

output.dpi
Entier
1 à 4000

Définissez les informations DPI intégrées dans le résultat.

Les informations DPI ne sont pas incluses si le résultat est optimisé Web.

Défaut : 72

output.colorSpace
Énuméré
sRGB, AdobeRGB, AppleRGB, ColorMatchRGB

Définissez les informations d'espace colorimétrique intégrées dans le résultat.

Les informations d'espace colorimétrique ne sont pas incluses si le résultat est optimisé Web.

Défaut : sRGB

output.jpegQuality
Entier
1 à 100

Configurez le réglage de qualité utilisé lors de la production d'un résultat JPEG.

Défaut : 75

output.pngOptimization
Énuméré
none, lossless, lossy

Configurez l'optimisation Web des résultats PNG.

Défaut : lossless

output.jpegOptimization
Énuméré
none, enabled

Configurez l'optimisation Web des résultats JPEG.

Défaut : enabled

output.opaqueFileFormat
Énuméré
jpeg, png

Configurez le format de fichier à utiliser pour les résultats opaques.

Défaut : jpeg

Vous pouvez télécharger des images en mode d'essai sans abonnement. Toutefois, même si ces téléchargements n'utilisent pas de crédits, une inscription API valide est requise pour télécharger des images en production via l'API.

Faites un essai


Format : '#RRGGBB'



Format : '#RRGGBB'

Format : '#RRGGBB'


Format : '[xOffsetPx:int] [yOffsetPx:int] [blurRadiusPx:int, 0 to 75] [opacity:float, 0 to 1]'
Exemple : 30 30 25 0.75

Format : '[yOffsetPx:int, 0 to 400] [heightPx:int, 0 to 800] [opacity:float, 0 to 1]'
Exemple : 0 200 0.5




Format : '[width:float, >0]:[height:float, >0]'
Exemple : 4:3

Format : '[width:int, >0] [height:int, >0]'
Exemple : 400 300

Nom d'utilisateur = Id API, Mot de passe = Secret API

cURL

$ curl "https://clippingmagic.com/api/v1/images" \
 -u 123:[secret] \ 
 -F 'image=@example.jpg' \ 
 -F 'test=true'

Présume que « exemple.jpg » existe. Remplacez adéquatement. La ligne avec « test=vrai » est facultative.

Exemple de réponse

{
  "image" : {
    "id" : 2346,
    "secret" : "image_secret1",
    "resultRevision" : 0,
    "originalFilename" : "example_image1.jpg",
    "imageCategoryUser" : "Photo",
    "imageCategoryAi" : "Photo",
    "test" : false
  }
}

Téléchargement en aval GET https://clippingmagic.com/api/v1/images/[imageId]

Pour télécharger un résultat, vous faites une requête HTTP GET standard. Un résultat doit d'abord avoir été généré.

Les résultats des essais peuvent être téléchargés gratuitement, mais ils comporteront un tatouage numérique. Les résultats en production coûtent un crédit pour le premier téléchargement. Les téléchargements ultérieurs sont gratuits.

Si aucun résultat n'est disponible, vous recevrez un message d'erreur.

Paramètres

imageId

Inclus dans l'URL

Vous devrez insérer la valeur id qui a été renvoyée dans l'appel de téléchargement.

Facultatif
format

format=result (défaut) récupère l'image résultat.

format=clipping_path_svg récupère le chemin de découpage (SVG) à la place.

format=clipping_path_tiff récupère le chemin de découpage (TIFF) à la place.

format=alpha_mask_png récupère le masque alpha (PNG) à la place.

format=json récupère l'objet image JSON à la place. Utile si vous voulez consulter le nombre resultRevision ou si vous avez perdu la clé secrète de l'image.

La récupération de l'Objet JSON d'image ne débite pas votre compte. Vous n'êtes facturé(e) que lorsque vous téléchargez les résultats en production.

En-têtes de réponse

Lorsque format n'est pas json, nous fournissons des informations critiques dans les en-têtes de ces réponses HTTP.

x-amz-meta-id
Example: 2346

L'id de votre image.

x-amz-meta-secret
Example: image_secret1

L'secret de votre image.

x-amz-meta-resultrevision
Example: 1

Le resultRevision que vous récupérez dans cette requête.

Ce compteur augmente à chaque fois qu'un nouveau résultat est généré.

x-amz-meta-width
Example: 3200
(uniquement inclus pour format=result)

La largeur en pixels du résultat récupéré dans cette requête.

x-amz-meta-height
Example: 2400
(uniquement inclus pour format=result)

La longueur en pixels du résultat récupéré dans cette requête.

Content-Disposition
Example: attachment; filename*=UTF-8''example_image1_clipped_rev_0.png

Le nom de fichier du résultat, y compris l'extension.

Nom d'utilisateur = Id API, Mot de passe = Secret API

cURL

$ curl "https://clippingmagic.com/api/v1/images/2346" \
 -u 123:[secret] \ 
 -LOJ

Exemple de réponse JSON

{
  "image" : {
    "id" : 2346,
    "secret" : "image_secret1",
    "resultRevision" : 0,
    "originalFilename" : "example_image1.jpg",
    "imageCategoryUser" : "Photo",
    "imageCategoryAi" : "Photo",
    "test" : false
  }
}

Liste GET https://clippingmagic.com/api/v1/images

Pour récupérer une liste de vos Objets JSON d'image, vous faites une requête HTTP GET standard.

Paramètres

Facultatif
limit

Nombre de résultats à récupérer. 20 par défaut (1 minimum, 100 maximum).

Facultatif
offset

Décalage à utiliser dans la liste des résultats (0 par défaut).

Attributs de réponse

images

Un tableau des Objets JSON d'image.

limit

La limit effectivement utilisée pour produire le résultat.

offset

La offset effectivement utilisée pour produire le résultat.

Nom d'utilisateur = Id API, Mot de passe = Secret API

cURL

$ curl "https://clippingmagic.com/api/v1/images?limit=2&offset=0" \
 -u 123:[secret]

Exemple de réponse

{
  "images" : [ {
    "id" : 2346,
    "secret" : "image_secret1",
    "resultRevision" : 0,
    "originalFilename" : "example_image1.jpg",
    "imageCategoryUser" : "Photo",
    "imageCategoryAi" : "Photo",
    "test" : false
  }, {
    "id" : 2347,
    "secret" : "image_secret2",
    "resultRevision" : 0,
    "originalFilename" : "example_image2.jpg",
    "imageCategoryUser" : "Photo",
    "imageCategoryAi" : "Photo",
    "test" : false
  } ],
  "limit" : 2,
  "offset" : 0
}

Suppression POST https://clippingmagic.com/api/v1/images/[imageId]/delete

Pour supprimer une image, vous faites une requête HTTP POST standard vers l'URL de l'image à supprimer.

Il s'agit d'une légère déviation de la méthode REST standard qui permet de gérer le fait que de nombreuses bibliothèques de clients HTTP ne prennent pas en charge le verbe HTTP DELETE, ainsi que d'éviter les méthodes redondantes.

Paramètres

imageId

Inclus dans l'URL

Vous devrez insérer la valeur id qui a été renvoyée dans l'appel de téléchargement.

Attributs de réponse

image

L'objet JSON d'image supprimé.

Faites un essai

Nom d'utilisateur = Id API, Mot de passe = Secret API

cURL

$ curl "https://clippingmagic.com/api/v1/images/2346/delete" \
 -u 123:[secret] \ 
 -X POST

Exemple de réponse

{
  "image" : {
    "id" : 2346,
    "secret" : "image_secret1",
    "resultRevision" : 0,
    "originalFilename" : "example_image1.jpg",
    "imageCategoryUser" : "Photo",
    "imageCategoryAi" : "Photo",
    "test" : false
  }
}

Compte GET https://clippingmagic.com/api/v1/account

Récupérez des informations de base sur votre compte, telles que le statut de votre abonnement et le nombre de crédits restants.

Paramètres

Aucun

Attributs de réponse

subscriptionPlan

Le plan d'abonnement auquel vous êtes actuellement abonné(e) ou « aucun ».

subscriptionState

Le statut de votre abonnement actuel (« actif » ou « échu ») ou « terminé » si vous n'êtes pas abonné(e).

credits

Le nombre de crédits API restants sur votre compte. 0 si vous n'êtes pas actuellement abonné(e), ou si vous êtes abonné(e) à un plan non API.

Nom d'utilisateur = Id API, Mot de passe = Secret API

cURL

$ curl "https://clippingmagic.com/api/v1/account" \
 -u 123:[secret]

Exemple de réponse

{
  "subscriptionPlan" : "none",
  "subscriptionState" : "ended",
  "credits" : 0
}