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).
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.
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.
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.
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).
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 |
|
|---|---|
| status | Le statut HTTP de la réponse, répété ici pour faciliter l'élimination des erreurs. |
| code | Code d'erreur interne Clipping Magic. |
| message | Message 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 Status | Signification |
|---|---|
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. "
}
}
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 |
| 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 |
|
Exemple
{
"id" : 2346,
"secret" : "image_secret1",
"resultRevision" : 0,
"originalFilename" : "example_image1.jpg",
"imageCategoryUser" : "Photo",
"imageCategoryAi" : "Photo",
"test" : false
}
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 :
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 |
|||||||||||||||
|
test
Booléen true, false
|
Indiquez
Omettez ou passez 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
|
L' 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 :
|
|||||||||||||||
|
Configurez les niveaux de couleur :
|
|||||||||||||||
|
Configurez la suppression d'une couleur de l'arrière-plan qui est projetée sur l'avant-plan, comme avec un écran vert :
|
|||||||||||||||
|
Configurez l'équilibre des blancs :
|
|||||||||||||||
|
Configurez les touches de finition :
|
|||||||||||||||
|
Configurer les paramètres du bord :
|
|||||||||||||||
|
|||||||||||||||
|
Contrôlez les dimensions et proportions du résultat :
|
|||||||||||||||
|
Contrôlez les options de sortie :
|
|||||||||||||||
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
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
}
}
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 |
|
Facultatif
format |
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 |
|
|---|---|
x-amz-meta-id
Example: 2346
|
L' |
x-amz-meta-secret
Example: image_secret1
|
L' |
x-amz-meta-resultrevision
Example: 1
|
Le 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. |
Faites un essai
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
}
}
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 |
| offset |
La |
Faites un essai
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
}
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 |
|
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
}
}
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. |
Faites un essai
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
}