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.

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.

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.

Exemple de message d'erreur

{
  "error" : {
    "status" : 400,
    "code" : 1006,
    "message" : "Failed to read the supplied image. "
  }
}
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
}

Pour télécharger une image, vous réalisez le téléchargement d'un fichier HTTP POST.

N'oubliez pas que le type de contenu doit être multipart/form-data

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.

Arguments

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.

test

Facultatif

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.

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
  }
}

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.

format

Facultatif

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.

Faites un essai

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
  }
}

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

Arguments

limit

Facultatif

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

offset

Facultatif

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.

Faites un essai

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
}

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
  }
}

Erreur Javascript :-(


Merci de nous aider à régler ce problème !