Tutte le richieste API sono richieste HTTP standard agli URL stile REST. Le risposte sono JSON, oppure un'immagine (quando viene recuperato il risultato).
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 il segreto API come password. Tieni presente che ClippingMagic.js utilizza solo il tuo ID API, in modo da non svelare il tuo segreto API ai tuoi utenti.
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.
Tieni presente che tutte le operazioni di caricamento e scaricamento sono effettuate sul backend, ma tutte le operazioni di revisione e modifica sono effettuate nell'Editor intelligente.
Questa divisione protegge la tua chiave API, pur consentendo un'esperienza uniforme per l'utente finale sul tuo sito.
L'uso dell'API è a velocità limitata con concessioni generose e nessun limite superiore fisso oltre i tuoi crediti API.
Durante l'operazione normale gestita dall'utente finale non dovresti trovare limiti di velocità in quanto l'uso tende a fluire e rifluire in un modo che il servizio gestisce agilmente.
Tuttavia, per lavori in batch raccomandiamo di iniziare con almeno 5 thread, aggiungendo 1 nuovo thread ogni 5 minuti fino a raggiungere il livello di parallelismo desiderato. Ti pregheremmo di contattarci prima di iniziare se hai bisogno di oltre 100 thread simultanei.
Se inoltri troppe richieste inizierai a ricevere risposte 429 Too Many Requests. In tal caso dovresti applicare un backoff lineare: alla prima risposta di questo tipo, attendi 5 secondi prima di inoltrare la richiesta successiva. Alla seconda risposta 429 consecutiva, attendi 2*5=10 secondi prima di inoltrare la richiesta successiva. Alla terza attendi 3*5=15 secondi, ecc.
Puoi reimpostare il contatore di backoff dopo una richiesta riuscita, e dovresti applicare il backoff per thread (vale a dire i thread dovrebbero essere indipendenti l'uno dall'altro).
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 |
|
|---|---|
| status | Lo status HTTP della risposta, ripetuto qui come ausilio per il debug. |
| code | Codice errore interno Clipping Magic. |
| message | Messaggio di errore leggibile, previsto per aiutare con il debug. |
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 Status | Significato |
|---|---|
200-299
|
Operazione riuscita |
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 Clipping Magic interno. Attendi un momento quindi riprova, e se il problema persiste inviaci una email. |
I recenti errori API sono elencati nella pagina del tuo account per facilitare il debug.
Esempio di risposta di errore
{
"error" : {
"status" : 400,
"code" : 1006,
"message" : "Failed to read the supplied image. "
}
}
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 |
| 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 |
|
Esempio
{
"id" : 2346,
"secret" : "image_secret1",
"resultRevision" : 0,
"originalFilename" : "example_image1.jpg",
"imageCategoryUser" : "Photo",
"imageCategoryAi" : "Photo",
"test" : false
}
POST https://clippingmagic.com/api/v1/images
Per caricare un'immagine, devi eseguire un caricamento file POST HTTP standard. Questo endpoint deve essere chiamato dal tuo backend, non può essere chiamato dal javascript della tua pagina web. Tieni presente che il Contenuto-Tipo deve essere multipart/form-data quando carichi file binari.
|
Parametri |
|||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
L'immagine inserita deve essere fornita come:
Deve essere un file .bmp, .gif, .jpeg, .png, o .tiff.
Le dimensioni massime per il caricamento dell'immagine sono (= larghezza × altezza) sono 33.554.432 pixel, che sono ridotte a 4.194.404 pixel a meno che non siano sostituite da |
|||||||||||||||
|
test
Booleano true, false
|
Passa in
Ometti o passa a Le immagini di prova possono essere elaborate gratuitamente, ma il risultato avrà una filigrana incorporata. |
||||||||||||||
|
format
Enum json, result, clipping_path_svg, clipping_path_tiff, alpha_mask_png
|
Il Il tuo account non viene addebitato per il recupero dell'Oggetto JSON Immagine; vieni addebitato solamente quando scarichi risultati di produzione. |
||||||||||||||
|
maxPixels
Intero 1000000 - 26214400
|
Cambia le dimensioni massime (= larghezza × altezza) dell'immagine usate nel ridimensionamento dell'immagine dopo il caricamento. Predefinito: 4.194.404 pixel |
||||||||||||||
|
background.color
#RRGGBB #0055FF
|
Ottieni un risultato PNG anche senza usare uno sfondo trasparente. Includi per ottenere uno sfondo opaco del colore specifico e un risultato output.opaqueFileFormat (default JPEG). Non dimenticarti di includere '#'. |
||||||||||||||
|
Configura i parametri di elaborazione:
|
|||||||||||||||
|
Configura i livelli di colore:
|
|||||||||||||||
|
Configura la rimozione di un colore dallo sfondo che è una dominante di colore nel primo piano, come con uno schermo verde:
|
|||||||||||||||
|
Configura il bilanciamento del bianco:
|
|||||||||||||||
|
Configura gli ultimi ritocchi:
|
|||||||||||||||
|
Configura i parametri bordo:
|
|||||||||||||||
|
|||||||||||||||
|
Controlla dimensioni risultato e rapporto aspetto:
|
|||||||||||||||
|
Controlla le opzioni output:
|
|||||||||||||||
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
Nome utente = Id API, Password = Segreto API
cURL
$ curl "https://clippingmagic.com/api/v1/images" \ -u 123:[secret] \ -F 'image=@example.jpg' \ -F 'test=true'
Presuppone che 'example.jpg' esiste. Sostituiscilo come dal caso. Riga con'test=true' opzionale.
Esempio di risposta
{
"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]
Per scaricare un risultato, devi eseguire una richiesta GET HTTP standard. Prima deve essere stato generato un risultato.
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 non c'è un risultato disponibile, riceverai una risposta di errore.
|
Parametri |
|
|---|---|
| imageId |
Incorporato nell'URL
Devi inserire il valore |
|
Facoltativo
format |
Il tuo account non viene addebitato per il recupero dell'Oggetto JSON Immagine; vieni addebitato solamente quando scarichi risultati di produzione. |
|
Intestazioni risposta
Quando il |
|
|---|---|
x-amz-meta-id
Example: 2346
|
L' |
x-amz-meta-secret
Example: image_secret1
|
L' |
x-amz-meta-resultrevision
Example: 1
|
Il Ogni volta che un nuovo risultato viene generato questo contatore viene incrementato. |
x-amz-meta-width
Example: 3200
(solo incluso per format=result)
|
La larghezza in pixel del risultato che stai recuperando in questa richiesta. |
x-amz-meta-height
Example: 2400
(solo incluso per format=result)
|
L'altezza in pixel del risultato che stai recuperando in questa richiesta. |
Content-Disposition
Example: attachment; filename*=UTF-8''example_image1_clipped_rev_0.png
|
Il nome file del risultato, compresa l'estensione. |
Prova
Nome utente = Id API, Password = Segreto API
cURL
$ curl "https://clippingmagic.com/api/v1/images/2346" \ -u 123:[secret] \ -LOJ
Esempio di risposta 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
Per recuperare un elenco dei tuoi Oggetti JSON Immagini deve eseguire una richiesta standard GET HTTP.
|
Parametri |
|
|---|---|
|
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 |
| offset |
Il |
Prova
Nome utente = Id API, Password = Segreto API
cURL
$ curl "https://clippingmagic.com/api/v1/images?limit=2&offset=0" \ -u 123:[secret]
Esempio di risposta
{
"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
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.
|
Parametri |
|
|---|---|
| imageId |
Incorporato nell'URL
Devi inserire il valore |
|
Attributi della risposta |
|
|---|---|
| image |
L'Oggetto JSON Immagine eliminato. |
Prova
Nome utente = Id API, Password = Segreto API
cURL
$ curl "https://clippingmagic.com/api/v1/images/2346/delete" \ -u 123:[secret] \ -X POST
Esempio di risposta
{
"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
Ottieni informazioni di base sul tuo account, come lo status del tuo abbonamento e il numero di crediti rimanenti.
|
Parametri |
|
|---|---|
| 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 API rimasti nel tuo account. 0 se non sei attualmente abbonato, o sei abbonato a un piano non-API. |
Nome utente = Id API, Password = Segreto API
cURL
$ curl "https://clippingmagic.com/api/v1/account" \ -u 123:[secret]
Esempio di risposta
{
"subscriptionPlan" : "none",
"subscriptionState" : "ended",
"credits" : 0
}