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.

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.

Beispiel für eine Fehlerantwort

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

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.

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

Wird als 'true' übergeben, um anzuzeigen, dass es sich um ein Testbild handelt. Testbilder werden kostenlos verarbeitet, aber in das Ergebnis wird ein Wasserzeichen eingebettet.

Antwortattribute

image

Das Bild-JSON-Objekt.

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. Wenn Sie jedoch format=json angeben, erhalten Sie statt dessen das Bild-JSON-Objekt zurück. 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
  }
}

Javascript-Fehler :-(


Helfen Sie uns bitte, dieses Problem zu beheben!