Documentazione API

Tutte le richieste API sono richieste HTTP standard agli URL stile REST. Le risposte sono JSON, oppure un'immagine (quando viene recuperato il risultato).

Autenticazione: L'API utilizza l'autenticazione di base HTTP standard. Tutte le richieste all'API devono includere le tue credenziali API, con l'ID API come utente e la chiave API come password. Tieni presente che ClippingMagic.js utilizza solo il tuo ID API, in modo da non svelare la tua chiave API ai tuoi utenti.

Protezione: Tutte le richieste devono essere fatte su HTTPS, e tu devi autenticare tutte le richieste. La tua libreria client HTTP deve supportare l'Indicazione nome server (SNI) per fare richieste con successo. Se ricevi strani errori di handshake, probabilmente dipende da questo.

Prova

Tutte le azioni API sono accompagnate da esempi di modulo / link html che puoi provare direttamente nel tuo browser. Gli esempi cURL usano le tue credenziali API se ti sei registrato, e tu puoi semplicemente copiarle-incollarle nel tuo terminale ed eseguirle.

Errore Oggetto JSON

Usiamo stati HTTP convenzionali per indicare se una richiesta API riesce o meno, includendo importanti informazioni di errore nell'Errore Oggetto JSON restituito.

Cerchiamo di restituire sempre un Errore Oggetto JSON con qualsiasi richiesta problematica. Tuttavia, in teoria è sempre possibile che vi siano errori interni del server che portano a una risposta non di errore JSON.

Attributi

statusLo status HTTP della risposta, ripetuto qui come ausilio per il debug.
codeCodice errore interno Clipping Magic.
messageMessaggio di errore leggibile, previsto per aiutare con il debug.

Esempio di risposta di errore

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

Se lo status HTTP per la tua richiesta è 200 non sarà restituito un Errore Oggetto JSON, e puoi presumere con sicurezza che la richiesta in senso lato è riuscita.

Alcune librerie client HTTP generano eccezioni per gli stati HTTP nel range 400-599. Dovrai catturare queste eccezioni e gestirle idoneamente.

HTTP StatusSignificato
200-299

Operazione riuscita

301-303

Durante lo scaricamento di risultati: vieni reindirizzato all'effettiva posizione di archiviazione dei risultati. Non sarà restituito un Errore Oggetto JSON. Dovresti configurare la tua libreria client HTTP per seguire i reindirizzamenti durante lo scaricamento di risultati.

400-499

Esiste un problema con le informazioni fornite nella richiesta (per esempio un parametro mancante). Controlla il messaggio di errore per determinare come risolverlo.

500-599

Si è verificato un errore interno Clipping Magic. Attendi un momento quindi riprova, e se il problema persiste inviaci una email.

Oggetto JSON Immagine

Record di immagini sono rappresentati in modo uniforme con un Oggetto JSON, restituito da diverse delle azioni API.

Attributi

id

Identificatore univoco per l'immagine. Necessario per consentire agli utenti di modificare l'immagine e per scaricarne i risultati.

secret

La chiave privata necessaria per modificare questa immagine con ClippingMagic.js

resultRevision

Il numero intero indica l'ultima revisione disponibile per lo scaricamento (0 = ancora nessun risultato disponibile).

Ti consente di determinare se è disponibile un risultato più recente di quello che hai già scaricato.

originalFilename

Una stringa contenente il nome file fornito durante il caricamento dell'immagine originale.

test

true significa che questa è un'immagine di prova, che si può elaborare gratuitamente, ma il risultato avrà una filigrana.

false significa che questa è un'immagine di produzione che costa crediti per l'elaborazione, ma il risultato non avrà una filigrana.

Esempio

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

Carica POST https://clippingmagic.com/api/v1/images

Per caricare un'immagine, devi eseguire un caricamento di file HTTP POST standard. Tieni presente che il Contenuto-Tipo deve essere multipart/form-data

Attributi

image

Il file immagine da caricare. Deve essere un file .bmp, .gif, .jpeg, .png, o .tiff.

Le dimensioni massime dell'immagine sono 8.388.608 pixel, che sono ridotte a 4.194.404 pixel. Dovresti pre-ridurre le tue immagini a queste ultime dimensioni o meno prima di caricarle.

Facoltativo
test

Passa in 'true' per indicare che questa è un'immagine di prova. Le immagini di prova possono essere elaborate gratuitamente, ma il risultato avrà una filigrana incorporata.

Attributi della risposta

image

l'Oggetto JSON Immagine

Puoi caricare immagini nella modalità di test anche senza abbonamento. Tuttavia, anche se i caricamenti non richiedono crediti, devi comunque avere un abbonamento API valido per caricare immagini di produzione attraverso l'API.

Prova

Username = API Id, Password = API Key

cURL

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

Presuppone che 'example.jpg' esiste. Sostituiscilo come dal caso.

Esempio di risposta

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

Scaricamento GET https://clippingmagic.com/api/v1/images/[image_id]

Per scaricare un risultato, devi eseguire una richiesta GET HTTP standard. Prima deve essere stato generato un risultato. In genere a questo fine devi lasciare che il tuo utente finale ritagli l'immagine sul tuo sito usando ClippingMagic.js

I risultati di prova, possono essere scaricati gratuitamente, ma includono una filigrana. I risultati di produzione costano un credito per lo scaricamento la prima volta che sono scaricati; scaricamenti ripetuti sono gratuiti.

Se c'è un risultato disponibile, sarai reindirizzato al risultato (i risultati sono archiviati in Amazon S3), per questo motivo devi assicurarti che la tua libreria client sia configurata in modo da seguire reindirizzamenti.

L'intestazione della risposta x-amz-meta-resultrevision indica il resultRevision del risultato scaricato, e l'intestazione Content-Disposition indica il nome file del risultato inclusa l'estensione: .jpeg per risultati con sfondi opachi, .png per risultati con sfondi trasparenti.

Se non c'è un risultato disponibile, riceverai una risposta di errore.

Argomenti

image_id

Incorporato nell'URL

Devi inserire il valore id che è stato restituito nella chiamata di caricamento.

Facoltativo
format

Come impostazione predefinita viene restituita l'immagine risultato. Tuttavia, se specifichi format=json riceverai invece l'Oggetto JSON Immagine. Utile se vuoi controllare resultRevision, o se hai perso la chiave dell'immagine.

Il tuo account non viene addebitato per il recupero dell'Oggetto JSON Immagine; vieni addebitato solamente quando scarichi risultati di produzione.

Username = API Id, Password = API Key

cURL

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

Esempio di risposta JSON

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

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

Per recuperare un elenco dei tuoi Oggetti JSON Immagini deve eseguire una richiesta standard GET HTTP.

Argomenti

Facoltativo
limit

Numero di record da recuperare. Il numero predefinito è 20 (Min 1, max 100).

Facoltativo
offset

Offset da usare nell'elenco di record (valore predefinito 0).

Attributi della risposta

images

Un array di Oggetti JSON Immagini.

limit

Il limit effettivamente usato quando si produce il risultato.

offset

Il offset effettivamente usato quando si produce il risultato.

Username = API Id, Password = API Key

cURL

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

Esempio di risposta

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

Elimina POST https://clippingmagic.com/api/v1/images/[image_id]/delete

Per eliminare un'immagine, devi eseguire una richiesta POST HTTP standard al suo URL-eliminazione.

Si tratta di una leggera deviazione dalla pratica REST standard per gestire il fatto che molte librerie client HTTP non supportano DELETE HTTP, evitando la complicazione di disporre di diversi modi di fare la stessa cosa.

Argomenti

image_id

Incorporato nell'URL

Devi inserire il valore id che è stato restituito nella chiamata di caricamento.

Attributi della risposta

image

L'Oggetto JSON Immagine eliminato.

Prova

Username = API Id, Password = API Key

cURL

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

Esempio di risposta

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

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

Ottieni informazioni di base sul tuo account, come lo status del tuo abbonamento e il numero di crediti rimanenti.

Argomenti

Nessuno

Attributi della risposta

subscriptionPlan

Il piano a cui sei attualmente abbonato, o 'nessuno'.

subscriptionState

Lo stato del tuo attuale abbonamento ('attivo' o 'scaduto') o 'terminato' se non sei abbonato.

credits

Il numero di crediti rimasti nel tuo account. 0 se non sei attualmente abbonato.

Username = API Id, Password = API Key

cURL

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

Esempio di risposta

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