API server

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.

Sicurezza

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.

Backend e Frontend

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.

Limitazione di velocità

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).

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.

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

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.

Esempio di risposta di errore

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

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

image
Binario

Un file binario.

image.base64
Stringa

Stringa codificata base64.

image.url
Stringa

Un URL da recuperare.

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 maxPixels nel seguito. Dovresti pre-ridurre le tue immagini a queste ultime dimensioni o meno prima di caricarle.

test
Boleano
true, false

Passa in true per indicare che questa è un'immagine di prova.

Ometti o passa a false per le immagini di produzione.

Le immagini di prova possono essere elaborate gratuitamente, ma il risultato avrà una filigrana incorporata.

format
Enum
json, result, clipping_path_svg, alpha_mask_png

format=json (impostazione predefinita): non viene generato un risultato Auto-Clip e l'oggetto JSON immagine viene restituito. Da usare quando un operatore umano esamina e potenzialmente ritocca il risultato usando ClippingMagic.js

format=result genera e recupera il risultato Auto-Clip.

format=clipping_path_svg genera il risultato Auto-Clip e recupera il Percorso di ritaglio (SVG).

format=alpha_mask_png genera il risultato Auto-Clip e recupera la Maschera Alfa (PNG). La maschera Alfa ha le stesse dimensioni dell'immagine inserita. L'applicazione all'immagine inserita non produce il risultato, in quanto il Controllo bordi e lo Strumento di pulitura alone migliorano i colori limite.

Il id e secret sono restituiti nelle intestazioni x-amz-meta-id e x-amz-meta-secret durante il recupero di un risultato non JSON. Assicurati di memorizzarli in modo da poterli rivedere e modificare usando ClippingMagic.js. Controlla tutte le intestazioni incluse nella tua risposta

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

maxPixels
Intero
1000000 - 8388708

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

Ometti per usare uno sfondo trasparente.

Non dimenticarti di includere '#'.

Configura i parametri di elaborazione:

processing.mode
Enum
auto, photo, graphics

Controlla la modalità di elaborazione usata per la tua immagine.

Predefinito: auto

processing.autoClip
Boleano
true, false

Abilita (predefinito) o disabilita Auto-Clip nel modificare l'immagine nell'app web.

Disabilita se vuoi caricare immagini mediante l'API, ma quindi ritaglia in free-form qualcosa che non sia lo sfondo (se presente).

Predefinito: true

Configura i livelli di colore:

colors.auto
Boleano
true, false

Regola automaticamente i livelli di colore per migliorare il contrasto.

Predefinito: false

colors.brightness
Intero
-100 - 100

Regola la luminosità dell'immagine prodotta.

Predefinito: 0

colors.shadows
Intero
-100 - 100

Regola le ombre dell'immagine prodotta. Valori positivi corrispondono a ombre più scure.

Predefinito: 0

colors.highlights
Intero
-100 - 100

Regola i riflessi dell'immagine prodotta. Valori positivi corrispondono a ombre più chiare.

Predefinito: 0

colors.temperature
Intero
-100 - 100

Regola la temperatura dei colori dell'immagine prodotta. Valori positivi corrispondono a colori più caldi.

Predefinito: 0

colors.saturation
Intero
-100 - 100

Regola la saturazione dell'immagine prodotta. Valori positivi corrispondono a più saturazione.

Predefinito: 0

Configura la rimozione di un colore allo sfondo che è una dominante di colore nel primo piano, come con uno schermo verde:

colorCast.auto
Boleano
true, false

Determina automaticamente il colore dello sfondo da rimuovere dal primo piano.

Predefinito: false

colorCast.color
#RRGGBB
#A84400

Il colore di sfondo specificato manualmente da rimuovere dallo sfondo.

Ometti per rilevare automaticamente.

colorCast.foregroundGuard
Mobile
0.0 - 20.0

Valori maggiori riducono l'impatto della rimozione della dominante di colore su colori di primo piano genuini che sono simili alla dominante di colore ma più saturi di quelli rimossi.

Predefinito: 4.0

Configura il bilanciamento del bianco:

whiteBalance.auto
Boleano
true, false

Determina automaticamente il colore di riferimento da usare per il bilanciamento del bianco:

Predefinito: false

whiteBalance.color
#RRGGBB
#968386

Il colore per il bilanciamento del bianco specificato manualmente.

Ometti per rilevare automaticamente.

Configura gli ultimi ritocchi:

effects.dropShadow
[xOffsetPx:int] [yOffsetPx:int] [blurRadiusPx:int, 0 to 75] [opacity:float, 0 to 1]
30 30 25 0.75

Aggiungi un effetto di ombra sfalsata al risultato ritagliato.

effects.reflection
[yOffsetPx:int, 0 to 400] [heightPx:int, 0 to 800] [opacity:float, 0 to 1]
0 200 0.5

Aggiungi un effetto di riflesso al risultato ritagliato.

Configura i parametri bordo:

edges.corners
Boleano
true, false

Usa (predefinito) o disabilita il Controllo angoli.

edges.smoothing
Enum
smart, fixed

Usa smart (predefinito) o fixed arrotondamento.

edges.smoothingLevel
Mobile
0.0 - 5.0

Configura il livello di arrotondamento applicato al risultato.

Predefinito 1.0

edges.feathering
Enum
fixed, auto, local

Usa auto (predefinito), local, o fixed sfumatura.

edges.featheringRadiusPx
Mobile
0.0 - 6.0

Configura il livello di sfumatura applicato al risultato.

Predefinito: 1.0

edges.offsetPx
Mobile
0.0 - 10.0

Configura l'offset limite applicato al risultato.

Predefinito: 0.0

Adatta l'output al risultato

fit.toResult
Boleano
true, false

Attiva o disattiva adatta al risultato (predefinito).

Se è disattivato il resto dei parametri in questa sezione saranno ignorati.

fit.paddingPercent
Mobile
0.0 - 35.0

Il riempimento da applicare attorno al risultato adattato, come percentuale delle dimensioni del risultato.

Predefinito: 5.0

fit.paddingPixels
Intero
0 - 250

Il riempimento in pixel da applicare attorno al risultato adattato.

Se non specificato, viene usato un riempimento percentuale.

fit.objectSize
Enum
small, medium, large

Puoi specificare dimensioni sintetiche per il tuo oggetto. Ciò è utile per eCommerce nel caso tu voglia dare al tuo acquirente una vaga idea delle dimensioni del prodotto relativamente ad altri prodotti.

Predefinito : large (= il risultato non viene ridimensionato)

fit.verticalAlignment
Enum
top, middle, bottom

Specifica come il tuo risultato dovrebbe essere allineato in presenza di spazio verticale eccessivo.

Inoltre, applica quando distribuire spazio in eccesso in seguito al rapporto aspetto o all'imposizione delle dimensioni target, vedi qui sotto.

Predefinito: middle

fit.shadows
Enum
ignore, pad, tight

Puoi ignorare le ombreggiature, riempire uniformemente entrambi i lati per adattare le ombreggiature, o riempire solamente dove necessario per non tagliare l'ombreggiatura.

Predefinito: pad

fit.rotationDeg
Mobile
-360.0 - 360.0

Ruota l'immagine. I valori positivi sono in senso antiorario.

Predefinito: 0

Controlla dimensioni risultato e rapporto aspetto:

result.aspectRatio
[width:float, >0]:[height:float, >0]
4:3

Assicura che il risultato abbia il rapporto aspetto fornito.

fit.verticalAlignment controlla come viene distribuito lo spazio verticale in eccesso.

Predefinito: non applicato

result.targetSize
[width:int, >0] [height:int, >0]
400 300

Assicura che il risultato sia delle dimensioni fornite.

fit.verticalAlignment controlla come viene distribuito lo spazio verticale in eccesso.

Predefinito: non applicato

result.allowEnlarging
Boleano
true, false

Controlla se il risultato può essere o meno di dimensioni maggiore dell'immagine di input.

Predefinito: false

Controlla le opzioni output:

output.dpi
Intero
1 - 4000

Imposta le informazioni DPI incorporate nel risultato.

Le informazioni DPI non sono incluse se il risultato non è ottimizzato per il web.

Predefinito: 72

output.colorSpace
Enum
sRGB, AdobeRGB, AppleRGB, ColorMatchRGB

Imposta le informazioni sullo spazio di colore incorporate nel risultato.

Le informazioni sullo spazio di colore non sono incluse se il risultato non è ottimizzato per il web.

Predefinito: sRGB

output.jpegQuality
Intero
1 - 100

Configura le impostazioni della qualità usate quando si produce un risultato JPEG.

Predefinito: 75

output.pngOptimization
Enum
none, lossless, lossy

Configura l'ottimizzazione web dei risultati PNG.

Predefinito: lossless

output.jpegOptimization
Enum
none, enabled

Configura l'ottimizzazione web dei risultati JPEG.

Predefinito: enabled

output.opaqueFileFormat
Enum
jpeg, png

Configura il formato del file da usare per i risultati opachi.

Predefinito: jpeg

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


Formato: '#RRGGBB'



Formato: '#RRGGBB'

Formato: '#RRGGBB'


Formato: '[xOffsetPx:int] [yOffsetPx:int] [blurRadiusPx:int, 0 to 75] [opacity:float, 0 to 1]'
Esempio: 30 30 25 0.75

Formato: '[yOffsetPx:int, 0 to 400] [heightPx:int, 0 to 800] [opacity:float, 0 to 1]'
Esempio: 0 200 0.5




Formato: '[width:float, >0]:[height:float, >0]'
Esempio: 4:3

Formato: '[width:int, >0] [height:int, >0]'
Esempio: 400 300

Username = API Id, Password = API Key

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

Scaricamento 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 id che è stato restituito nella chiamata di caricamento.

Facoltativo
format

format=result Per impostazione predefinita viene recuperata l'immagine risultato.

format=clipping_path_svg invece recupera il Percorso di ritaglio (SVG).

format=alpha_mask_png invece recupera la Maschera Alfa (PNG).

format=json invece recupera 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.

Intestazioni risposta

Quando il format non è json forniamo informazioni chiave in queste intestazioni risposta HTTP

x-amz-meta-id
Example: 2345

L' id della tua immagine.

x-amz-meta-secret
Example: image_secret

L' secret della tua immagine.

x-amz-meta-resultrevision
Example: 1

Il resultRevision che stai recuperando in questa richiesta.

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''image_clipped_rev_0.png

Il nome file del risultato, compresa l'estensione.

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.

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 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/[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 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.

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