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.

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.

Attribute

status
Der HTTP-Status der Antwort, der hier zur Unterstützung des Debugging wiederholt wird.
code
Interner Fehlercode in Clipping Magic.
message
Visuell 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. "
  }
}
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
}

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

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.

Argumente

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.

test

Optional

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.

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

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.

format

Optional

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.

Probieren Sie es

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

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

Argumente

limit

Optional

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

offset

Optional

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.

Probieren Sie es

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
}

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!