API-Dokumentation

Alle API-Anfragen sind standardmäßige HTTP-Anfragen an REST-Style URLs. Die Antworten sind entweder JSON oder ein Bild (wenn das Ergebnis abgerufen wird).

Authentifizierung

Die API verwendet eine standardmäßige HTTP Basic Access Authentication. Alle Anfragen an die API müssen Ihre API-Zugangsdaten enthalten, wobei die API-ID als Benutzer und der API-Schlüssel als Kennwort fungieren. Beachten Sie, dass ClippingMagic.js nur Ihre API-ID verwendet, damit Ihr API-Schlüssel für Ihre Benutzer nicht sichtbar ist.

Sicherheit

Alle Anfragen müssen über HTTPS erfolgen, und Sie müssen alle Anfragen authentifizieren.

Ihre HTTP-Client-Bibliothek muss die Servernamensanzeige (Server Name Indication (SNI)) unterstützen, damit Anfragen erfolgreich gestellt werden können. Wenn seltsame Handshake-Fehler auftreten, ist dies wahrscheinlich die Ursache.

Backend i. Vgl. zu Frontend

Beachten Sie, dass sich alle Upload- und Download-Vorgänge auf dem Backend abspielen, aber alle Clipping-Vorgänge mit ClippingMagic.js im Web-Client (Frontend) ausgeführt werden.

Durch diese Trennung wird der API-Schlüssel geschützt, aber auch gleichzeitig auf Ihrer Website eine nahtlose Endbenutzererfahrung gewährleistet.

Geschwindigkeitsbegrenzung

Die Verwendung der API unterliegt einer Geschwindigkeitsbegrenzung mit großzügigen Limits und keiner festen Obergrenze über Ihre API-Punkte hinaus.

Während des normalen vom Endbenutzer gesteuerten Betriebs sind Geschwindigkeitsbegrenzungen sehr unwahrscheinlich, da die Nutzung graduell ab- und zunimmt, sodass der Dienst reibungslos ausgeführt werden kann.

Bei Stapelaufträgen empfehlen wir jedoch, mit höchstens 5 Threads zu beginnen und dann alle 5 Minuten 1 neuen Thread hinzuzufügen, bis der gewünschte Parallelitätsgrad erreicht ist. Lassen Sie uns bitte vor Beginn wissen, wenn Sie mehr als 100 gleichzeitige Threads benötigen.

Wenn zu viele Anfragen eingereicht werden, erhalten Sie in zunehmendem Maße die Antwort 429 Too Many Requests. In diesem Fall sollten Sie den Vorgang linear zurückfahren: nach der ersten dieser Antworten warten Sie 5 Sekunden, bis Sie die nächste Anfrage einreichen. Bei der zweiten aufeinanderfolgenden 429-Antwort warten Sie 2*5=10 Sekunden, bis Sie die nächste Anfrage einreichen. Bei der dritten Antwort warten Sie 3*5=15 Sekunden usw.

Sie können den Rückfahrzähler nach einer erfolgreichen Anfrage zurücksetzen und sollten das Rückfahren pro Thread vornehmen (d. h. die Threads sollten unabhängig voneinander ausgeführt werden).

Probieren Sie es

Alle API-Aktionen sind mit html-Formular-/Linkbeispielen verfügbar, die Sie direkt im Browser ausprobieren können. Die cURL-Beispiele verwenden Ihre API-Zugangsdaten, wenn Sie sich angemeldet haben. Dann müssen Sie sie lediglich kopieren und in Ihr Terminal einfügen und ausführen.

Fehler-JSON-Objekt

Wir verwenden herkömmliche HTTP-Status, um den Erfolg oder Fehlschlag einer API-Anfrage anzuzeigen, und stellen wichtige Fehlerinformationen im zurückgegebenen Fehler-JSON-Objekt bereit.

Wir versuchen, bei einer problematischen Anfrage immer ein Fehler-JSON-Objekt zurückzugeben. Es ist jedoch theoretisch möglich, dass interne Serverfehler auftreten, die zu Nicht-JSON-Fehlerantworten führen.

Attribute

statusDer HTTP-Status der Antwort, der hier zur Unterstützung des Debugging wiederholt wird.
codeInterner Fehlercode in Clipping Magic.
messageVisuell lesbare Fehlermeldung, die für das Debugging hilfreich sein soll.

Wenn der HTTP-Status für Ihre Anfrage 200 ist, wird kein Fehler-JSON-Objekt zurückgegeben, und Sie können mit großer Sicherheit davon ausgehen, dass die Anfrage generell erfolgreich war.

Manche HTTP-Client-Bibliotheken führen für HTTP-Status im Bereich 400-599 zu Ausnahmen. Diese Ausnahmen müssen erfasst und entsprechend behandelt werden.

HTTP StatusBedeutung
200-299

Erfolg

301-303

Beim Herunterladen von Ergebnissen: Sie werden zum eigentlichen Speicherort der Ergebnisse umgeleitet. Es wird kein Fehler-JSON-Objekt zurückgegeben. Sie sollten Ihre HTTP-Client-Bibliothek so konfigurieren, dass sie beim Herunterladen von Ergebnissen der Umleitung folgt.

400-499

Es gibt ein Problem bei den in der Anfrage angegebenen Informationen (es fehlt z. B. ein Parameter). Prüfen Sie bitte die Fehlermeldung, um eine Methode zu finden, den Fehler zu beheben.

500-599

In Clipping Magic ist ein interner Fehler aufgetreten. Warten Sie einen Moment und versuchen Sie es erneut. Wenn das Problem immer noch auftritt, schicken Sie uns eine E-Mail.

Beispiel für eine Fehlerantwort

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

Bild-JSON-Objekt

Bilddatensätze werden mit einem JSON-Objekt, das von mehreren der API-Aktionen zurückgegeben wird, einheitlich dargestellt.

Attribute

id

Für das Bild eindeutiger Bezeichner. Wird vom Benutzer zum Bearbeiten des Bildes und Herunterladen des Ergebnisses benötigt.

secret

Der geheime Schlüssel, der zur Bearbeitung dieses Bildes mit ClippingMagic.js

erforderlich ist
resultRevision

Ganzzahl, die die neueste Version angibt, die heruntergeladen werden kann (0 = noch kein Ergebnis erhältlich).

Damit können Sie feststellen, ob es für dieses Bild ein neueres Ergebnis gibt als das zuvor heruntergeladene.

originalFilename

Eine Zeichenfolge, die den Dateinamen enthält, der beim Hochladen des Originalbildes angegeben wurde.

test

true bedeutet, dass es sich um ein Testbild handelt, das kostenlos verarbeitet werden kann, dessen Ergebnis jedoch ein Wasserzeichen enthalten wird.

false bedeutet, dass es sich um ein Produktionsbild handelt, dessen Verarbeitung Punkte kostet, dessen Ergebnis jedoch kein Wasserzeichen enthalten wird.

Beispiel

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

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

Zum Hochladen eines Bildes führen Sie einen standardmäßigen HTTP POST-Dateiupload durch. Dieser Endpunkt muss von Ihrem Backend abgerufen werden. Er kann nicht von Ihrem Webseiten-Javascript abgerufen werden. Denken Sie daran, dass der Inhaltstyp als multipart/form-data vorliegen muss

Attribute

image

Die hochzuladende Bilddatei. Es muss sich um eine .bmp-, .gif-, .jpeg-, .png- oder .tiff-Datei handeln.

Die maximale Bildgröße ist 16.777.216 Pixel, wobei diese auf 4.194.404 Pixel verkleinert wird. Verkleinern Sie Ihre Bilder bitte auf die letztgenannte oder eine kleinere Größe, bevor Sie sie hochladen.

Optional
test

Übergeben Sie true, um anzuzeigen, dass es sich um ein Testbild handelt. Testbilder werden kostenlos verarbeitet, aber in das Ergebnis wird ein Wasserzeichen eingebettet.

Optional
format

Standardmäßig wird kein automatisches Beschneideergebnis erzeugt, und das Bild-JSON-Objekt wird zurückgegeben. Dies ist der typische Betriebsmodus, wenn eine Prüfung durch einen menschlichen Bediener erfolgt und das beschnittene Bild möglicherweise mit ClippingMagic.js nachgebessert wird.

format=result erzeugt stattdessen das automatische Beschneideergebnis und ruft es ab.

format=clipping_path_svg erzeugt stattdessen das automatische Beschneideergebnis und ruft den Clipping-Pfad (SVG) ab.

format=alpha_mask_png erzeugt stattdessen das automatische Beschneideergebnis und ruft die Alphamaske (PNG) ab.

id und secret werden in den Kopfzeilen x-amz-meta-id und x-amz-meta-secret zurückgegeben, wenn ein Nicht-JSON-Ergebnis abgerufen wird.

Beim Abruf des Bild-JSON-Objekts wird Ihr Konto nicht belastet; Ihnen werden nur heruntergeladene Produktionsergebnisse in Rechnung gestellt.

Sie können Bilder ohne Abonnement im Testmodus hochladen. Uploads kosten zwar keine Punkte, aber Sie benötigen dennoch ein gültiges API-Abonnement, um Produktionsbilder über die API hochzuladen.

Probieren Sie es

Username = API Id, Password = API Key

cURL

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

Geht davon aus, dass 'example.jpg' vorhanden ist. Nach Bedarf ersetzen.

Beispiel einer Antwort

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

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

Zum Herunterladen eines Ergebnisses verwenden Sie eine standardmäßige HTTP GET-Anfragemethode. Es muss zuerst ein Ergebnis erstellt worden sein. In der Regel lassen Sie dazu Ihren Endbenutzer das Bild auf Ihrer Website mit ClippingMagic.js beschneiden

Die Testergebnisse können kostenlos heruntergeladen werden, enthalten allerdings ein Wasserzeichen. Die Produktionsergebnisse kosten beim ersten Herunterladen jeweils einen Punkt; wiederholte Downloads sind kostenlos.

Wenn ein Ergebnis zur Verfügung steht, werden Sie zu ihm umgeleitet (die Ergebnisse werden auf Amazon S3 gespeichert). Sie müssen also sicherstellen, dass Ihre Client-Bibliothek so konfiguriert ist, dass sie der Umleitung folgt.

Die Antwortkopfzeile x-amz-meta-resultrevision gibt die resultRevision des heruntergeladenen Ergebnisses an, und die Kopfzeile Content-Disposition weist auf den Dateinamen des Ergebnisses einschließlich Erweiterung hin: .jpeg für Ergebnisse mit undurchsichtigen Hintergründen, .png für Ergebnisse mit durchsichtigen Hintergründen.

Wenn kein Ergebnis zur Verfügung steht, erhalten Sie eine Fehlerantwort.

Argumente

image_id

In die URL integriert

Sie müssen den id-Wert einfügen, der im Upload-Aufruf zurückgegeben wurde.

Optional
format

Standardmäßig wird das Ergebnisbild zurückgegeben.

format=clipping_path_svg ruft stattdessen den Clipping-Pfad (SVG) ab.

format=alpha_mask_png ruft stattdessen die Alphamaske (PNG) ab.

format=json ruft stattdessen das Bild-JSON-Objekt ab. Dies ist dann nützlich, wenn Sie die resultRevision prüfen möchten oder wenn der geheime Schlüssel des Bildes verloren gegangen ist.

Beim Abruf des Bild-JSON-Objekts wird Ihr Konto nicht belastet; Ihnen werden nur heruntergeladene Produktionsergebnisse in Rechnung gestellt.

Username = API Id, Password = API Key

cURL

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

Beispiel für eine JSON-Antwort

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

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

Um eine Liste Ihrer Bild-JSON-Objekte herunterzuladen, verwenden Sie eine standardmäßige HTTP GET-Anfragemethode.

Argumente

Optional
limit

Anzahl der abzurufenden Datensätze. Der Standardwert betrögt 20 (Min 1, Max 100).

Optional
offset

In der Liste der Datensätze zu verwendender Offset-Wert (Standardeinstellung 0).

Antwortattribute

images

Ein Array mit Bild-JSON-Objekten.

limit

Das beim Erstellen des Ergebnisses tatsächlich verwendete limit.

offset

Das beim Erstellen des Ergebnisses tatsächlich verwendete offset.

Username = API Id, Password = API Key

cURL

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

Beispiel einer Antwort

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

Löschen POST https://clippingmagic.com/api/v1/images/[image_id]/delete

Zum Löschen eines Bildes verwenden Sie eine standardmäßige HTTP POST-Anfrage, die an die entsprechende URL geleitet wird.

Damit wird geringfügig von standardmäßigen REST-Praktiken abgewichen, um der Tatsache Rechnung zu tragen, dass zahlreiche HTTP-Client-Bibliotheken das HTTP DELETE-Verb nicht unterstützen. Gleichzeitig wird vermieden, dass mehrere Methoden zur Durchführung einer Aktion bereitgestellt werden.

Argumente

image_id

In die URL integriert

Sie müssen den id-Wert einfügen, der im Upload-Aufruf zurückgegeben wurde.

Antwortattribute

image

Das gelöschte Bild-JSON-Objekt.

Probieren Sie es

Username = API Id, Password = API Key

cURL

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

Beispiel einer Antwort

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

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

Rufen Sie allgemeine Informationen über Ihr Konto auf, beispielsweise Abonnementstatus und Anzahl der verbliebenen Punkte.

Argumente

Keine

Antwortattribute

subscriptionPlan

Der Plan, den Sie derzeit abonniert haben, bzw. „Keine“.

subscriptionState

Der Status Ihres aktuellen Abonnements („aktiv“ oder „überfällig“) oder „abgelaufen“, wenn kein Abonnement vorliegt.

credits

Die Anzahl der in Ihrem Konto verbliebenen Punkte. Ist 0, wenn derzeit kein Abonnement vorliegt.

Username = API Id, Password = API Key

cURL

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

Beispiel einer Antwort

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