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).
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 geheime API-Schlüssel als Kennwort fungieren. Beachten Sie, dass ClippingMagic.js nur Ihre API-ID verwendet, damit Ihr geheimer API-Schlüssel für Ihre Benutzer nicht sichtbar ist.
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.
Beachten Sie, dass sich alle Upload- und Download-Vorgänge auf dem Backend abspielen, aber alle Prüf- und Bearbeitungsvorgänge im Smart-Editor ausgeführt werden.
Durch diese Trennung wird der API-Schlüssel geschützt, aber auch gleichzeitig auf Ihrer Website eine nahtlose Endbenutzererfahrung gewährleistet.
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).
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 |
|
|---|---|
| status | Der HTTP-Status der Antwort, der hier zur Unterstützung des Debugging wiederholt wird. |
| code | Clipping Magic – interner Fehlercode. |
| message | Visuell 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 Status | Bedeutung |
|---|---|
200-299
|
Erfolg |
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
|
Bei 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. |
Kürzlich aufgetretene API-Fehler sind auf Ihrer Kontoseite aufgeführt, sodass Sie sie leichter beheben können.
Beispiel für eine Fehlerantwort
{
"error" : {
"status" : 400,
"code" : 1006,
"message" : "Failed to read the supplied image. "
}
}
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 |
| 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 |
|
Beispiel
{
"id" : 2346,
"secret" : "image_secret1",
"resultRevision" : 0,
"originalFilename" : "example_image1.jpg",
"imageCategoryUser" : "Photo",
"imageCategoryAi" : "Photo",
"test" : false
}
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, wenn binäre Dateien hochgeladen werden.
|
Parameter |
|||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Das Eingabebild muss in einem der folgenden Formate bereitgestellt werden:
Muss eine .bmp-, .gif-, .jpeg-, .png-, oder .tiff-Datei sein.
Die maximale Upload-Größe für Bilder (= Breite × Höhe) ist 33.554.432 Pixel. Diese Größe wird auf 4.194.404 Pixel reduziert, sofern dies nicht von dem Wert für |
|||||||||||||||
|
test
Boolesch true, false
|
Übergeben Sie
Lassen Sie dies aus oder übergeben Sie Testbilder werden kostenlos verarbeitet, aber in das Ergebnis wird ein Wasserzeichen eingebettet. |
||||||||||||||
|
format
Enum json, result, clipping_path_svg, clipping_path_tiff, alpha_mask_png
|
Beim Abruf des Bild-JSON-Objekts wird Ihr Konto nicht belastet; Ihnen werden nur heruntergeladene Produktionsergebnisse in Rechnung gestellt. |
||||||||||||||
|
maxPixels
Ganzzahl 1000000 bis 26214400
|
Ändert die maximal verwendete Bildgröße (= Breite × Höhe), wenn die Größe des Bildes nach dem Hochladen geändert wird. Standardwert: 4.194.404 Pixel |
||||||||||||||
|
background.color
#RRGGBB #0055FF
|
Auslassen, um einen durchsichtigen Hintergrund zu verwenden und ein PNG-Ergebnis zu erhalten. Einschließen, um einen undurchsichtigen Hintergrund der angegebenen Farbe und ein output.opaqueFileFormat-Ergebnis zu erhalten (Standard-JPEG-Datei). Geben Sie auf jeden Fall „#“ mit ein. |
||||||||||||||
|
Konfigurieren Sie die Verarbeitungsparameter:
|
|||||||||||||||
|
Konfigurieren Sie die Farbintensität:
|
|||||||||||||||
|
Konfigurieren Sie das Entfernen einer Farbe aus dem Hintergrund, die einen Farbstich im Vordergrund erzeugt, z. B. bei Verwendung eines Green-Screens:
|
|||||||||||||||
|
Konfigurieren Sie den Weißabgleich:
|
|||||||||||||||
|
Konfigurieren Sie das Feilen:
|
|||||||||||||||
|
Konfigurieren Sie die Randparameter:
|
|||||||||||||||
|
Passen Sie die Ausgabe an das Ergebnis an
|
|||||||||||||||
|
Steuern Sie Ergebnisgröße und Seitenverhältnis:
|
|||||||||||||||
|
Steuern Sie die Ausgabeoptionen:
|
|||||||||||||||
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
Benutzername = API-ID, Kennwort = geheimer API-Schlüssel
cURL
$ curl "https://clippingmagic.com/api/v1/images" \ -u 123:[secret] \ -F 'image=@example.jpg' \ -F 'test=true'
Geht davon aus, dass 'example.jpg' vorhanden ist. Nach Bedarf ersetzen. Die Zeile mit 'test=true' ist optional.
Beispiel einer Antwort
{
"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]
Zum Herunterladen eines Ergebnisses verwenden Sie eine standardmäßige HTTP GET-Anfragemethode. Es muss zuerst ein Ergebnis erstellt worden sein.
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 kein Ergebnis zur Verfügung steht, erhalten Sie eine Fehlerantwort.
|
Parameter |
|
|---|---|
| imageId |
In die URL integriert
Sie müssen den |
|
Optional
format |
Beim Abruf des Bild-JSON-Objekts wird Ihr Konto nicht belastet; Ihnen werden nur heruntergeladene Produktionsergebnisse in Rechnung gestellt. |
|
Antwort-Kopfzeilen
Wenn |
|
|---|---|
x-amz-meta-id
Example: 2346
|
Die |
x-amz-meta-secret
Example: image_secret1
|
Die |
x-amz-meta-resultrevision
Example: 1
|
Die Jedes Mal, wenn ein neues Ergebnis generiert wird, wird dieser Zähler inkrementiert. |
x-amz-meta-width
Example: 3200
(nur eingeschlossen für format=result)
|
Die Breite des Ergebnisses, das Sie in dieser Anfrage abrufen, in Pixeln. |
x-amz-meta-height
Example: 2400
(nur eingeschlossen für format=result)
|
Die Höhe des Ergebnisses, das Sie in dieser Anfrage abrufen, in Pixeln. |
Content-Disposition
Example: attachment; filename*=UTF-8''example_image1_clipped_rev_0.png
|
Der Dateiname des Ergebnisses, einschließlich Erweiterung. |
Probieren Sie es
Benutzername = API-ID, Kennwort = geheimer API-Schlüssel
cURL
$ curl "https://clippingmagic.com/api/v1/images/2346" \ -u 123:[secret] \ -LOJ
Beispiel für eine JSON-Antwort
{
"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
Um eine Liste Ihrer Bild-JSON-Objekte herunterzuladen, verwenden Sie eine standardmäßige HTTP GET-Anfragemethode.
|
Parameter |
|
|---|---|
|
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 |
| offset |
Das beim Erstellen des Ergebnisses tatsächlich verwendete |
Probieren Sie es
Benutzername = API-ID, Kennwort = geheimer API-Schlüssel
cURL
$ curl "https://clippingmagic.com/api/v1/images?limit=2&offset=0" \ -u 123:[secret]
Beispiel einer Antwort
{
"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
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.
|
Parameter |
|
|---|---|
| imageId |
In die URL integriert
Sie müssen den |
|
Antwortattribute |
|
|---|---|
| image |
Das gelöschte Bild-JSON-Objekt. |
Probieren Sie es
Benutzername = API-ID, Kennwort = geheimer API-Schlüssel
cURL
$ curl "https://clippingmagic.com/api/v1/images/2346/delete" \ -u 123:[secret] \ -X POST
Beispiel einer Antwort
{
"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
Rufen Sie allgemeine Informationen über Ihr Konto auf, beispielsweise Abonnementstatus und Anzahl der verbliebenen Punkte.
|
Parameter |
|
|---|---|
| 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 API-Punkte. Ist 0, wenn derzeit kein Abonnement vorliegt oder wenn es sich um einen Plan ohne API handelt. |
Probieren Sie es
Benutzername = API-ID, Kennwort = geheimer API-Schlüssel
cURL
$ curl "https://clippingmagic.com/api/v1/account" \ -u 123:[secret]
Beispiel einer Antwort
{
"subscriptionPlan" : "none",
"subscriptionState" : "ended",
"credits" : 0
}