Wszystkie żądania interfejsu API to standardowe żądania HTTP do adresów URL typu REST. Odpowiedzi mają formę JSON albo obrazu (przy pobieraniu rezultatu).
Interfejs API używa standardowego podstawowego uwierzytelniania dostępu HTTP. Wszystkie żądania do interfejsu API będą wymagały poświadczeń API z identyfikatorem API jako użytkownikiem i kluczem tajnym API jako hasłem. Zwróć uwagę, że ClippingMagic.js używa tylko twojego identyfikatora interfejsu API, żeby nie ujawniać twojego klucza tajnego API twoim użytkownikom.
Wszystkie żądania muszą być kierowane przez HTTPS i wymagają uwierzytelnienia.
Aby z powodzeniem wykonywać żądania, twoja biblioteka klienta HTTP musi obsługiwać oznaczanie nazwy serwera (SNI). Jeśli otrzymujesz dziwne błędy uzgadniania, to prawdopodobnie z tego powodu.
Zwróć uwagę, że wszystkie operacje przekazywania i pobierania odbywają się na zapleczu, natomiast wszystkie operacje przeglądania i edytowania odbywają się w Inteligentnym edytorze.
Te podział zabezpiecza twój klucz API, umożliwiając jednocześnie użytkownikowi końcowemu bezproblemowe korzystanie z twojej witryny.
Używanie interfejsu API podlega ograniczeniu przepustowości z wysokimi przydziałami i bez stałej górnej granicy przekroczenia posiadanych środków interfejsu API.
Prawdopodobieństwo napotkania na ograniczenie szybkości w zwykłym trybie działania sterowanym przez użytkownika końcowego jest małe, jako że usługa płynnie obsługuje tego rodzaju tryb użycia.
W przypadku zadań wsadowych zalecamy jednak, żeby zacząć od nie więcej niż 5 wątków, dodając 1 nowy wątek co 5 minut aż do osiągnięcia oczekiwanego poziomu równoległości. W razie potrzeby więcej niż 100 współbieżnych wątków, prosimy o kontakt przed rozpoczęciem procesu.
Przesłanie zbyt wielu żądań spowoduje otrzymanie odpowiedzi 429 Too Many Requests. W takim wypadku należy zastosować wycofanie liniowe: po otrzymaniu pierwszej takiej odpowiedzi odczekaj 5 sekund przed przesłaniem kolejnego żądania. Po drugiej kolejnej odpowiedzi 429 odczekaj 2*5=10 sekund przed przesłaniem kolejnych żądań. Po trzeciej odpowiedzi odczekaj 3*5=15 sekund, itd.
Po pomyślnie wykonanym żądaniu możesz zresetować licznik wycofania i stosować wycofanie dla poszczególnych wątków (tzn. wątki powinny działać niezależnie od siebie).
Aby określić czy dane żądanie API zakończyło się pomyślnie czy niepomyślnie używamy konwencjonalnych statusów HTTP, uwzględniając istotne informacje o błędzie w zwróconym obiekcie JSON błędu.
Staramy się zawsze zwrócić obiekt JSON błędu dla każdego problematycznego żądania. Zawsze istnieje jednak teoretyczna możliwość wewnętrznych awarii serwera skutkujących odpowiedzią na błąd inną niż JSON.
|
Atrybuty |
|
|---|---|
| status | Status HTTP odpowiedzi, powtórzony tutaj żeby pomóc z debugowaniem. |
| code | Clipping Magic internal error code. |
| message | Czytelny dla użytkownika komunikat o błędzie, który ma pomóc w debugowaniu. |
Jeżeli status HTTP dla żądania wynosi 200, obiekt JSON błędu nie zostanie zwrócony i można bezpiecznie założyć, że żądanie zasadniczo się powiodło.
Niektóre biblioteki klienta HTTP zgłaszają wyjątki dla statusów HTTP w zakresie 400-599. Wyjątki te trzeba przechwycić i odpowiednio obsłużyć.
| HTTP Status | Znaczenie |
|---|---|
200-299
|
Powodzenie |
400-499
|
Wystąpił problem z informacją przekazaną w żądaniu (np. brakowało parametru). Przejrzyj komunikat o błędzie aby ustalić jak go rozwiązać. |
500-599
|
There's been a Clipping Magic internal error. Zaczekaj chwilę i spróbuj ponownie, a jeśli problem nie zniknie, skontaktuj się z nami e-mailem. |
Ostatnie błędy interfejsu API są wyświetlane na stronie konta dla wygody debugowania.
Przykładowa odpowiedź na błąd
{
"error" : {
"status" : 400,
"code" : 1006,
"message" : "Failed to read the supplied image. "
}
}
Rekordy obrazu są reprezentowane w jednolity sposób za pomocą obiektu JSON zwracanego przez kilka działań interfejsu API.
|
Atrybuty |
|
|---|---|
| id |
Unikatowy identyfikator dla obrazu. Wymagany w celu umożliwienia użytkownikom edytowania obrazu i pobrania rezultatu. |
| secret |
Klucz tajny wymagany do edytowania tego obrazu za pomocą |
| resultRevision |
Liczba całkowita wskazująca najnowszą wersję dostępną do pobrania (0 = rezultat nie jest jeszcze dostępny). Pozwala stwierdzić, czy dostępny jest nowszy rezultat obrazu niż poprzednio pobrany. |
| originalFilename |
Ciąg zawierający nazwę pliku dostarczany w momencie przekazywania oryginalnego obrazu. |
| test |
|
Przykład
{
"id" : 2346,
"secret" : "image_secret1",
"resultRevision" : 0,
"originalFilename" : "example_image1.jpg",
"imageCategoryUser" : "Photo",
"imageCategoryAi" : "Photo",
"test" : false
}
POST https://clippingmagic.com/api/v1/images
Aby przekazać obraz, wykonaj standardowe przekazywanie pliku HTTP POST. Punkt końcowy musi zostać wywołany z zaplecza, nie można wywołać go z języka javascript twojej witryny internetowej. Pamiętaj, że przy przekazywaniu plików binarnych wymagany typ zawartości to multipart/form-data.
|
Parametry |
|||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Obraz wejściowy musi zostać podany jako jeden z poniższych:
Musi być plikiem .bmp, .gif, .jpeg, .png, lub .tiff.
Maksymalny rozmiar przekazywanego obrazu (= szerokość × wysokość) wynosi 33 554 432 piksele i zostanie zmniejszony do 4 194 404 pikseli o ile nie zostanie zastąpiony przez |
|||||||||||||||
|
test
Wartość logiczna true, false
|
Przekaż
W przypadku obrazów produkcyjnych pomiń albo przekaż Obrazy testowe można przetwarzać bezpłatnie, ale rezultat będzie opatrzony znakiem wodnym. |
||||||||||||||
|
format
Enum json, result, clipping_path_svg, clipping_path_tiff, alpha_mask_png
|
Przy pobieraniu rezultatu innego niż JSON w nagłówkach Pobranie obiektu JSON obrazu nie powoduje obciążenia konta; opłata jest naliczana dopiero w momencie pobrania rezultatów produkcyjnych. |
||||||||||||||
|
maxPixels
Liczba całkowita 1000000 do 26214400
|
Zmienia maksymalny rozmiar obrazu (= szerokość × wysokość) używany przy zmianie rozmiaru obrazu po przekazaniu. Wartość domyślna: 4 194 404 piksele |
||||||||||||||
|
background.color
#RRGGBB #0055FF
|
Pomiń żeby użyć przezroczystego tła i uzyskać rezultat PNG. Uwzględnij żeby uzyskać nieprzezroczyste tło w określonym kolorze i rezultat output.opaqueFileFormat (domyślnie JPEG). Pamiętaj, żeby dołączyć "#". |
||||||||||||||
|
Konfiguruj parametry przetwarzania:
|
|||||||||||||||
|
Konfiguruj poziomy kolorów:
|
|||||||||||||||
|
Skonfiguruj usunięcie z tła koloru tworzącego przebarwienie pierwszego planu, tak jak za pomocą zielonego ekranu:
|
|||||||||||||||
|
Konfiguruj balans bieli:
|
|||||||||||||||
|
Konfiguruj wykończenia:
|
|||||||||||||||
|
Konfiguruj parametry krawędzi:
|
|||||||||||||||
|
Dopasuj produkt wyjściowy do rezultatu
|
|||||||||||||||
|
Kontroluj rozmiar rezultatu i współczynnik proporcji:
|
|||||||||||||||
|
Kontroluj opcje pliku wyjściowego:
|
|||||||||||||||
Obrazy można przekazywać w trybie testowym bez subskrypcji. Ale mimo że przekazania nie wiążą się z płatnością środkami, przekazywanie obrazów produkcyjnych za pomocą interfejsu API nadal wymaga prawidłowej subskrypcji API.
Wypróbuj to
Nazwa użytkownika = Identyfikator API, Hasło = Tajne API
cURL
$ curl "https://clippingmagic.com/api/v1/images" \ -u 123:[secret] \ -F 'image=@example.jpg' \ -F 'test=true'
Zakłada, że 'example.jpg' istnieje. Zamień w odpowiednich przypadkach. Linia zawierająca 'test=true' jest opcjonalna.
Przykładowa odpowiedź
{
"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]
Aby pobrać rezultat wykonujesz standardową operację HTTP GET. Najpierw musiał zostać wygenerowany rezultat.
Rezultaty testowe można pobierać bezpłatnie, ale zawierają one znak wodny. Koszt pobrania rezultatu produkcyjnego to jeden środek w momencie pierwszego pobrania; powtórne pobrania są bezpłatne.
Jeżeli rezultat nie jest dostępny, otrzymasz odpowiedź na błąd.
|
Parametry |
|
|---|---|
| imageId |
Utrwalone w URL
Musisz wstawić wartość |
|
Opcjonalne
format |
Pobranie obiektu JSON obrazu nie powoduje obciążenia konta; opłata jest naliczana dopiero w momencie pobrania rezultatów produkcyjnych. |
|
Nagłówki odpowiedzi
W przypadku |
|
|---|---|
x-amz-meta-id
Example: 2346
|
|
x-amz-meta-secret
Example: image_secret1
|
|
x-amz-meta-resultrevision
Example: 1
|
Każde wygenerowanie nowego rezultatu powoduje zwiększenie licznika. |
x-amz-meta-width
Example: 3200
(uwzględnione tylko dla format=result)
|
Podana w pikselach szerokość obrazu, który pobierasz w tym żądaniu. |
x-amz-meta-height
Example: 2400
(uwzględnione tylko dla format=result)
|
Podana w pikselach wysokość rezultatu, który pobierasz w tym żądaniu. |
Content-Disposition
Example: attachment; filename*=UTF-8''example_image1_clipped_rev_0.png
|
Nazwa pliku rezultatu, łącznie z rozszerzeniem. |
Wypróbuj to
Nazwa użytkownika = Identyfikator API, Hasło = Tajne API
cURL
$ curl "https://clippingmagic.com/api/v1/images/2346" \ -u 123:[secret] \ -LOJ
Przykładowa odpowiedź JSON
{
"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
Aby pobrać listę obiektów JSON obrazu, wykonujesz standardową operację HTTP GET.
|
Parametry |
|
|---|---|
|
Opcjonalne
limit |
Liczba rekordów do pobrania. Wartość domyślna to 20 (minimum 1, maksimum 100). |
|
Opcjonalne
offset |
Przesunięcie używane dla listy rekordów (wartość domyślna to 0). |
|
Atrybuty odpowiedzi |
|
|---|---|
| images |
Ciąg obiektów JSON obrazu. |
| limit |
|
| offset |
|
Wypróbuj to
Nazwa użytkownika = Identyfikator API, Hasło = Tajne API
cURL
$ curl "https://clippingmagic.com/api/v1/images?limit=2&offset=0" \ -u 123:[secret]
Przykładowa odpowiedź
{
"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
Aby usunąć obraz, wyślij żądanie HTTP POST do jego URL usunięcia.
Jest to drobne odchylenie od standardowej praktyki REST przyjęte ze względu na to, że wiele bibliotek klientów HTTP nie obsługuje zlecenia HTTP USUŃ i pozwalające uniknąć zamieszania wynikającego z istnienia różnych sposobów wykonania tego samego działania.
|
Parametry |
|
|---|---|
| imageId |
Utrwalone w URL
Musisz wstawić wartość |
|
Atrybuty odpowiedzi |
|
|---|---|
| image |
Usunięty objekt JSON obrazu. |
Wypróbuj to
Nazwa użytkownika = Identyfikator API, Hasło = Tajne API
cURL
$ curl "https://clippingmagic.com/api/v1/images/2346/delete" \ -u 123:[secret] \ -X POST
Przykładowa odpowiedź
{
"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
Pobierz ogólne informacje o swoim koncie, takie jak status subskrypcji i ilość posiadanych środków.
|
Parametry |
|
|---|---|
| Brak | |
|
Atrybuty odpowiedzi |
|
|---|---|
| subscriptionPlan |
Plan subskrypcji, z którego obecnie korzystasz, albo "brak". |
| subscriptionState |
Status twojej aktualnej subskrypcji ("aktywna" albo "zaległa") lub jeżeli subskrypcja nie istnieje - "zakończono". |
| credits |
Liczba kredytów API pozostałych na Twoim koncie. 0, jeśli nie jest aktualnie subskrybowany lub subskrybowany do planu innego niż API. |
Wypróbuj to
Nazwa użytkownika = Identyfikator API, Hasło = Tajne API
cURL
$ curl "https://clippingmagic.com/api/v1/account" \ -u 123:[secret]
Przykładowa odpowiedź
{
"subscriptionPlan" : "none",
"subscriptionState" : "ended",
"credits" : 0
}