Documentation API

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 de base HTTP standard. Toutes les requêtes vers l'API doivent inclure vos identifiants API, l'identifiant de l'API étant l'utilisateur et la clé API le mot de passe. Veuillez noter que ClippingMagic.js utilise uniquement votre identifiant API mais ne révèle pas votre clé API à vos utilisateurs.

Securité : Toutes les requêtes doivent être passées via HTTPS et être authentifiées. 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.

Faites un essai

Toutes les actions API sont en format html/exemples de liens que vous pouvez directement essayer dans votre navigateur. Les exemples cURL utilisent vos identifiants API si vous êtes enregistré, de sorte que vous pouvez les copier-coller dans votre terminal pour les exécuter.

Erreur d'objet JSON

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'erreur dans l'Erreur d'objet JSON retournée.

Nous nous efforçons de toujours renvoyer une erreur d'objet JSON 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.

Exemple de message d'erreur

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

Si le statut HTTP de votre requête est 200, aucune erreur d'objet JSON ne sera retournée, 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 statuts HTTP dans la classe 400599. Vous devez repérer ces exceptions et les traiter adéquatement.

HTTP StatusSignification
200-299

Succès

301-303

Lors du téléchargement des résultats : vous êtes redirigé vers l'emplacement de stockage de résultats actuels. Aucune erreur d'objet JSON ne sera retournée. Vous devriez configurer votre bibliothèque de clients HTTP pour suivre les redirections lors du téléchargement des résultats.

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.

Image d'objet JSON

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 d'essai 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" : 2345,
  "secret" : "image_secret",
  "resultRevision" : 0,
  "originalFilename" : "image.jpg",
  "test" : false
}

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

Pour télécharger une image, effectuez un téléchargement de fichier HTTP POST standard. N'oubliez pas que le type de contenu doit être multipart/form-data.

Attributs

image

Fichier image à télécharger. Doit être un fichier .bmp, .gif, .jpeg, .png ou .tiff.

La dimension maximum des images est 8 388 608 pixels, qui est réduite à 4 194 404 pixels. Veuillez réduire vos images à cette dimension ou à une dimension inférieure avant de les télécharger.

Facultatif
test

Passez « true » pour indiquer qu'il s'agit d'une image d'essai. Les images d'essai sont traitées gratuitement mais comporteront un tatouage numérique.

Attributs de réponse

image

L'image en objet JSON.

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

Username = API Id, Password = API Key

cURL

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

Présume que « exemple.jpg » existe. Remplacez adéquatement.

Exemple de réponse

{
  "image" : {
    "id" : 2345,
    "secret" : "image_secret",
    "resultRevision" : 0,
    "originalFilename" : "image.jpg",
    "test" : false
  }
}

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

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é. Ceci se fait généralement en laissant l'utilisateur final découper l'image sur votre site en utilisant ClippingMagic.js

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 un résultat est disponible, vous serez redirigé vers le résultat (les résultats sont stockés sur Amazon S3). Assurez-vous donc que votre bibliothèque de clients est configurée de manière à suivre les redirections.

L'en-tête de réponse x-amz-meta-resultrevision indique le resultRevision du résultat téléchargé, et l'en-tête Content-Disposition indique le nom de fichier du résultat et son extension : .jpeg pour les résultats avec arrière-plan opaque, .png pour les résultats avec arrière-plan transparent.

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

Arguments

image_id

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

Par défaut, l'image du résultat est retournée. Toutefois, si vous spécifiez format=json, vous recevrez l'image de l'objet 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'image de l'objet JSON ne débite pas votre compte. Vous n'êtes facturé que lorsque vous téléchargez les résultats en production.

Username = API Id, Password = API Key

cURL

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

Exemple de réponse JSON

{
  "image" : {
    "id" : 2345,
    "secret" : "image_secret",
    "resultRevision" : 0,
    "originalFilename" : "image.jpg",
    "test" : false
  }
}

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

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

Arguments

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 images des objets JSON.

limit

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

offset

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

Username = API Id, Password = API Key

cURL

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

Exemple de réponse

{
  "images" : [ {
    "id" : 2345,
    "secret" : "image_secret",
    "resultRevision" : 0,
    "originalFilename" : "image.jpg",
    "test" : false
  }, {
    "id" : 2346,
    "secret" : "image_secret2",
    "resultRevision" : 0,
    "originalFilename" : "image.jpg",
    "test" : false
  } ],
  "limit" : 2,
  "offset" : 0
}

Suppression POST https://clippingmagic.com/api/v1/images/[image_id]/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.

Arguments

image_id

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'image de l'objet JSON supprimée.

Faites un essai

Username = API Id, Password = API Key

cURL

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

Exemple de réponse

{
  "image" : {
    "id" : 2345,
    "secret" : "image_secret",
    "resultRevision" : 0,
    "originalFilename" : "image.jpg",
    "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.

Arguments

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 restant sur votre compte. 0 si vous n'êtes pas actuellement abonné(e).

Username = API Id, Password = API Key

cURL

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

Exemple de réponse

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