Sunucu API'si

Tüm API istekleri REST türü URL'lere yapılan standart HTTP istekleridir. Yanıtlar (sonucu getirirken) ya JSON ya da bir resimdir.

Kimlik Doğrulaması

API standart HTTP temel erişim kimlik doğrulaması kullanmaktadır. API'ye yapılan tüm isteklerin sizin kullanıcı olarak API kimliğinizi ve şifre olarak da API Anahtarı ile API Bilgilerinizi içermesi gerekmektedir. Unutmayın ClippingMagic.js size ait API Anahtarını kullanıcılarınıza göstermemek için yalnızca API kimliğinizi kullanmaktadır.

Güvenlik

Tüm istekler HTTPS üzerinden yapılmalıdır ve siz de tüm isteklerin kimlik doğrulamasını yapmalısınız.

Http istemci kitaplığınızın istekleri başarıyla gerçekleştirmesi için Sunucu Adı Belirtme (SNI) desteklemesi gerekmektedir. Eğer garip el sıkışma hatalarıyla karşılaşıyorsanız nedeni muhtemelen budur.

Arka Uç ile Ön Uç Karşılaştırılması

Unutmayın ki tüm yükleme ve indirme işlemleri arka uçta gerçekleşirken tüm gözden geçirme ve düzenleme işlemleri Akıllı Düzenleyicide gerçekleşir.

Bu bölme hem sizin API Anahtarınızı korur hem de internet sitenizde kusursuz son kullanıcı deneyimi sunmanıza olanak sağlar.

Hız Sınırı

API kullanım limitleri gayet bol tutulmuştur ve bu konudaki tek üst sınır sahip olduğunuz API kredileridir.

Normal son kullanıcı işlemlerinde herhangi bir hız sınırlamasına rastlamanız pek olası değildir. Zira o durumdaki kullanım inişli çıkışlı olma eğilimindedir ve servis de bunun altından gayet rahatlıkla kalkar.

Bununla birlikte, gruplu işlerde en fazla 5 iş parçacığı ile başlayıp, arzu edilen paralelliğe erişene kadar her 5 dakikada bir yeni iş parçacığı eklemenizi tavsiye ediyoruz. Eğer 100'den fazla eş zamanlı iş parçacığına ihtiyacınız olacaksa çalışmaya başlamadan önce lütfen bizimle iletişime geçin.

Eğer çok fazla istek girişi yaparsanız, 429 Too Many Requests yanıtları almaya başlarsınız. Bu olduğunda doğrusal geri çekilme uygulamalısınız: böyle bir yanıtı ilk aldığınızda, bir sonraki isteği girmeden önce 5 saniye bekleyin. İkinci ardışık 429 yanıtında, bir sonraki isteği girene kadar 2*5=10 saniye bekleyin. Üçüncüde 3*5=15 saniye bekleyin.

İsteğinizin başarılı olmasının ardından geri çekilme sayacını sıfırlayabilirsiniz. Geri çekilmeyi iş parçacığı başına olacak şekilde uygulamanız iyi olacaktır (Mesela iş parçacıkları birbirinden bağımsız olarak çalışmalıdır).

Hatalı JSON Nesnesi

API isteğinin başarılı veya başarısız olduğunu göstermek için geleneksel HTTP statüleri kullanılır ve hataya ilişkin önemli bilgiler dönen Hatalı JSON Nesnesinde bulunur.

Herhangi bir sorunlu istek olması durumunda Hatalı JSON Nesnesi yollamaya çalışıyoruz. Ancak teorik olarak JSON-dışı hata yanıtına neden olan dahili sunucu hatalarının olması her zaman mümkündür.

Özellikler

statusYanıtın HTTP durumu, hata ayıklaması işlemine yardımcı olmak için burada tekrar edilmiştir.
codeClipping Magic iç hata kodu.
messageOkunabilir hata mesajı, hata ayıklamasında yardımcı olma amaçlıdır.

Eğer isteğinizin HTTP statüsü 200 ise hiçbir hatalı JSON Nesnesi döndürülmeyecektir. İsteğin genel anlamda başarılı olduğunu düşünebilirsiniz.

Bazı HTTP İstemci kitaplıkları 400-599 aralığındaki HTTP statüleri için özel durum oluşturmaktadır. Bu özel durumları yakalayıp uygun bir şekilde işlem yapmanız gerekecektir.

HTTP StatusAnlamı
200-299

Başarı

400-499

İstekte verilen bilgide (örneğin eksik bir parametre gibi) bir sorun bulunmaktadır. Sorunu çözmek için lütfen hata mesajını gözden geçirin.

500-599

Clipping Magic iç hata kodu oluştu. Bir dakika bekleyip daha sonra tekrar deneyin. Sorunun hala devam etmesi halinde lütfen bize e-posta yollayın.

Örnek Hata Yanıtı

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

Resim JSON Nesnesi

Resim kayıtları pek çok API eylemi tarafından döndürülen bir JSON Nesnesi ile tek bir şekilde temsil edilmektedir.

Özellikler

id

Resme özel benzersiz tanıtıcı. Kullanıcıların resmi düzenleyip sonucunu indirmesine olanak vermek için gereklidir.

secret

Bu resmi ClippingMagic.js

koduyla düzenlemek için gizli anahtara ihtiyaç vardır
resultRevision

İndirilmeye hazır en son revizyonu belirten tam sayı (0 = henüz sonuç yok).

Bu resim için daha önce indirilmiş olandan daha yeni bir sonucun olup olmadığını anlamanızı sağlar.

originalFilename

Orjinal resmi yüklerken verilen ve dosya adını içeren bir dize.

test

true bunun işlem denemesi için ücretsiz olan bir test resmi olduğu ancak sonucun üstünde bir filigran olacağı manasına gelir.

false bunun işlem görmesi için kredi gerektiren bir prodüksiyon resmi olduğu ve sonuçta filigran bulunmayacağı manasına gelir.

Örnek

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

Yükleme POST https://clippingmagic.com/api/v1/images

Resim yüklemek için standart bir HTTP POST dosyası yüklemesi yapılır. Bu uç nokta arka ucunuzdan çağrılmalıdır, web sayfanızın javascriptinden çağrılamaz. Unutmayın ikili dosyaları yüklerken İçerik Türü multipart/form-data olmak zorundadır.

Parametreler

Girdi resmi bunlardan bir tanesi olmalıdır:

image
İkili

İkili bir dosya.

image.base64
Dize

base64-kodlu bir dize.

image.url
Dize

Getirilecek URL.

.bmp, .gif, .jpeg, .png, veya .tiff dosyası olmalıdır.

Maksimum resim yükleme boyutu (= en × yükseklik) 33.554.432pikseldir. Bu da aşağıdaki maxPixels ile geçersiz hale getirilmediği takdirde 4.194.404 piksel düzeyine küçültülür. Lütfen yükleme yapmadan önce resimlerinizi bu ikinci belirtilen boyuta veya ondan daha düşük bir boyuta küçültün.

test
Boole
true, false

Bunun bir test resmi olduğunu göstermek için true kodunu girin.

Prodüksiyon resimleri için atlayın veya false kodunu girin.

Test resimlerinde işlem yapmak ücretsizdir. Ancak sonuç üzerinde bir filigran bulunacaktır.

format
Numaralama
json, result, clipping_path_svg, alpha_mask_png

format=json (varsayılan): Otomatik Kırpma sonucu oluşturulmadı ve Resim JSON nesnesi döndürüldü. Bunu insan olan operatörün gözden geçirme yaptığı ve ClippingMagic.js kullanarak sonuçta rötuş yapma olasılığının olduğu zamanlarda kullanın.

format=result Otomatik Kırpma sonucunu oluşturur ve getirir.

format=clipping_path_svg Otomatik Kırpma sonucunu oluşturur ve Kırpma Yolunu (SVG) getirir.

format=alpha_mask_png Otomatik Kırpma sonucunu oluşturur ve Alfa Maskesini (PNG) getirir. Alfa Maskesi girdi resimle aynı boyuta sahiptir. Kenar Koruyucu ve Hale Silici sınır renklerini iyileştirir. Bu yüzden de bunu girdi resmine uygulamak size sonucu vermez.

JSON-dışı sonuç getirilirken id ve secret kodları x-amz-meta-id ve x-amz-meta-secret başlıkları içerisinde geri gönderilmektedir. ClippingMagic.js kullanarak sonucunuzu gözden geçirebilmek ve sonucunuzu düzenleyebilmek için bunları kaydettiğinizden emin olun. Yanıtta yer alan tüm başlıkları görün

Resim JSON Nesnesini getirme işlemi nedeniyle hesabınızdan ödeme alınmaz. Yalnızca prodüksiyon sonuçlarını indirirken ödeme yaparsınız.

maxPixels
Tam sayı
1000000'dan 8388708'a

Yüklemenin ardından resmi yeniden boyutlandırırken kullanılan maksimum boyutu (= en × boy) değiştirir.

Varsayılan: 4.194.404 piksel

background.color
#RRGGBB
#0055FF

Saydam bir arka plan kullanmak için atlayın.

'#' dahil etmeyi unutmayın.

işleme parametrelerinin ayarlarını yapın:

processing.mode
Numaralama
auto, photo, graphics

Resminiz için kullanılan işleme modunu kontrol edin.

Varsayılan: auto

processing.autoClip
Boole
true, false

İnternet uygulamasında resmi düzenlerken Otomatik Kırpma fonksiyonunu etkinleştirin (varsayılan) veya devre dışı bırakın.

API vasıtasıyla resimleri yüklemek isterseniz devre dışı bırakın ancak belirgin ön plan (eğer varsa) dışındaki şeyleri serbest biçimli kırpma yapın.

Varsayılan: true

Renk düzeylerinin ayarını yapın:

colors.auto
Boole
true, false

Kontrastı geliştirmek için renk düzeylerini otomatik olarak ayarlayın.

Varsayılan: false

colors.brightness
Tam sayı
-100'dan 100'a

Çıktı resminin parlaklığını ayarlayın.

Varsayılan: 0

colors.shadows
Tam sayı
-100'dan 100'a

Çıktı resminin gölgelerini ayarlayın. Pozitif değerler daha koyu gölge anlamına gelir.

Varsayılan: 0

colors.highlights
Tam sayı
-100'dan 100'a

Çıktı resmin parlak noktalarını ayarlayın. Pozitif değerler daha açık parlak noktalar anlamına gelir.

Varsayılan: 0

colors.temperature
Tam sayı
-100'dan 100'a

Çıktı resminin renk sıcaklığını ayarlayın. Pozitif değerler daha sıcak renkler anlamına gelir.

Varsayılan: 0

colors.saturation
Tam sayı
-100'dan 100'a

Çıktı resminin doygunluğunu ayarlayın. Pozitif değerler daha yüksek doygunluk anlamına gelir.

Varsayılan: 0

Mesela yeşil ekranla, ön plana düşen bir rengin arka plandan kaldırılması ayarlarını yapın.

colorCast.auto
Boole
true, false

Ön plandan kaldırmak için arka plan rengini otomatik olarak belirleyin.

Varsayılan: false

colorCast.color
#RRGGBB
#A84400

Ön plandan kaldırmak için elle belirlenmiş arka plan rengi.

Otomatik algılama için atlayın.

colorCast.foregroundGuard
Kayan
0.0'dan 20.0'a

Büyük değerler, üstün renge benzer olan ancak kaldırılanlardan daha doygun olan gerçek ön plan renkleri üzerindeki renk üstünlüğü kaldırma etkisini azaltır.

Varsayılan: 4.0

Beyaz dengesi ayarı yapın:

whiteBalance.auto
Boole
true, false

Beyaz dengeleme işlemi yapmak için kullanılacak referans rengini otomatik olarak belirleyin.

Varsayılan: false

whiteBalance.color
#RRGGBB
#968386

Elle belirlenmiş beyaz dengesi rengi.

Otomatik algılama için atlayın.

Son rötuş ayarlarını yapın:

effects.dropShadow
[xOffsetPx:int] [yOffsetPx:int] [blurRadiusPx:int, 0 to 75] [opacity:float, 0 to 1]
30 30 25 0.75

Kırpılan sonuca gölge düşürme efekti ekleyin.

effects.reflection
[yOffsetPx:int, 0 to 400] [heightPx:int, 0 to 800] [opacity:float, 0 to 1]
0 200 0.5

Kırpılan sonuca yansıma efekti ekleyin.

Kenar parametre ayarlarını yapın:

edges.corners
Boole
true, false

Köşe Koruyucu kullanın (varsayılan) veya devre dışı bırakın.

edges.smoothing
Numaralama
smart, fixed

smart (varsayılan) veya fixed düzgünleştirme kullanın.

edges.smoothingLevel
Kayan
0.0'dan 5.0'a

Sonuca uygulanan düzgünleştirme miktar ayarlarını yapın.

Varsayılan 1.0

edges.feathering
Numaralama
fixed, auto, local

auto (varsayılan), local veya fixed yumuşatma kullanın.

edges.featheringRadiusPx
Kayan
0.0'dan 6.0'a

Sonuca uygulanan yumuşatma miktar ayarlarını yapın.

Varsayılan: 1.0

edges.offsetPx
Kayan
0.0'dan 10.0'a

Sonuca uygulanan sınır ofset ayarlarını yapın.

Varsayılan: 0.0

Çıktıyı sonuca sığdır

fit.toResult
Boole
true, false

Sonuca sığdır fonksiyonunu açın veya kapatın (varsayılan).

Kapalı olması halinde bu bölümde yer alan parametrelerin geri kalanı göz ardı edilmiş olmaktadır.

fit.paddingPercent
Kayan
0.0'dan 35.0'a

Sonucun boyutunun yüzdesi olarak sığdırılmış sonucun etrafına uygulanacak doldurma

Varsayılan: 5.0

fit.paddingPixels
Tam sayı
0'dan 250'a

Piksellerde sığdırılmış sonucun etrafına uygulanacak doldurma.

Eğer belirtilmemişse bunun yerine yüzde doldurma özelliği kullanılır.

fit.objectSize
Numaralama
small, medium, large

Nesneniz için sentetik bir boyut belirleyebilirsiniz. Bu size müşterilerinize ürününüzün diğer ürünlere oranla olan boyutuna dair bir fikir vermek isteyebileceğiniz eTicaret için faydalıdır.

Varsayılan: large (=sonuç yeniden boyutlandırılmamıştır)

fit.verticalAlignment
Numaralama
top, middle, bottom

Dikey alanda fazlalık olması halinde sonucunuzun nasıl hizalanacağını belirtin.

Bu ayrıca en boy oranı veya hedef boyut zorlamasına bağlı olarak ortaya çıkan fazla alanı dağıtırken de geçerlidir. Bakınız:

Varsayılan: middle

fit.shadows
Numaralama
ignore, pad, tight

Gölgeleri göz ardı edebilir, gölgeleri sığdırmak için her iki tarafa da eşit şekilde veya gölgeyi kesmemek için yalnızca gereken yerlere doldurma ekleyerek doldurabilirsiniz.

Varsayılan: pad

fit.rotationDeg
Kayan
-360.0'dan 360.0'a

Resmi döndürün. Pozitif değerler saat yönünün tersinedir.

Varsayılan: 0

Sonuç boyutunu ve en boy oranını kontrol edin:

result.aspectRatio
[width:float, >0]:[height:float, >0]
4:3

Sonucun istenilen en boy oranında olduğundan emin olun.

fit.verticalAlignment, dikey alanın fazlasının nasıl dağıtılacağını kontrol eder.

Varsayılan: uygulanmadı

result.targetSize
[width:int, >0] [height:int, >0]
400 300

Sonucun istenilen boyutta olduğundan emin olun.

fit.verticalAlignment, dikey alanın fazlasının nasıl dağıtılacağını kontrol eder.

Varsayılan: uygulanmadı

result.allowEnlarging
Boole
true, false

Sonucun girdi resminden daha büyük hale gelmesine izin verilip verilmeyeceğini kontrol eder.

Varsayılan: false

Çıktı seçeneklerini kontrol edin:

output.dpi
Tam sayı
1'dan 4000'a

Sonuca gömülü DPI bilgilerini ayarlayın.

Sonucun internette optimize edilmiş olması durumunda DPI bilgileri dahil edilmez.

Varsayılan: 72

output.colorSpace
Numaralama
sRGB, AdobeRGB, AppleRGB, ColorMatchRGB

Sonuca gömülü renk alanı bilgilerini ayarlayın.

Sonucun internette optimize edilmiş olması durumunda renk alanı bilgileri dahil edilmez.

Varsayılan: sRGB

output.jpegQuality
Tam sayı
1'dan 100'a

JPEG sonucu oluştururken kullanılan kalite ayarlarını belirleyin.

Varsayılan: 75

output.pngOptimization
Numaralama
none, lossless, lossy

PNG sonuçlarının internet optimizasyon ayarlarını yapın.

Varsayılan: lossless

output.jpegOptimization
Numaralama
none, enabled

JPEG sonuçlarının internet optimizasyon ayarlarını yapın.

Varsayılan: enabled

output.opaqueFileFormat
Numaralama
jpeg, png

Opak sonuçlar için kullanılacak dosya formatı ayarlarını yapın.

Varsayılan: jpeg

Test modunda resimleri abonelik olmadan yükleyebilirsiniz. Yükleme yapmak kredi harcamaz ancak prodüksiyon resimlerini API vasıtasıyla yüklemek için geçerli bir API aboneliğine ihtiyacınız olacaktır.

Deneyin


Formatı: '#RRGGBB'



Formatı: '#RRGGBB'

Formatı: '#RRGGBB'


Formatı: '[xOffsetPx:int] [yOffsetPx:int] [blurRadiusPx:int, 0 to 75] [opacity:float, 0 to 1]'
Örnek: 30 30 25 0.75

Formatı: '[yOffsetPx:int, 0 to 400] [heightPx:int, 0 to 800] [opacity:float, 0 to 1]'
Örnek: 0 200 0.5




Formatı: '[width:float, >0]:[height:float, >0]'
Örnek: 4:3

Formatı: '[width:int, >0] [height:int, >0]'
Örnek: 400 300

Username = API Id, Password = API Key

cURL

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

'example.jpg' var olduğunu varsaymaktadır. Uygun durumlarda değiştirin. 'deneme=gerçek' satırı isteğe bağlıdır.

Örnek Yanıt

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

İndir GET https://clippingmagic.com/api/v1/images/[imageId]

Sonucu indirmek için standart bir HTTP GET yapın. Önce bir sonuç oluşturulmuş olması gerekir.

Test sonuçlarının indirilmesi ücretsizdir. Ancak bu sonuçlarda filigran bulunacaktır. Prodüksiyon sonuçlarının indirilmesi ilk kez indirildiklerinde bir kredi tutarındadır. Aynı sonuç için daha sonra yapılacak indirme işlemleri ücretsizdir.

Eğer mevcut bir sonuç yoksa o zaman bir hata yanıtı alırsınız.

Parametreler

imageId

URL'ye yerleştirilmiştir

Yükle çağrısında geri döndürülen id değerini girmeniz gerekecektir.

İsteğe bağlı
format

format=result (varsayılan) sonuç resmini getirir.

format=clipping_path_svg bunun yerine Kırpma Yolunu (SVG) getirir.

format=alpha_mask_png bunun yerine Alfa Maskesini (PNG) getirir.

format=json bunun yerine Resim JSON Nesnesini getirir. SonuçRevizyonunu kontrol etmek isterseniz veya resim parolasını kaybettiyseniz faydalıdır.

Resim JSON Nesnesini getirme işlemi nedeniyle hesabınızdan ödeme alınmaz. Yalnızca prodüksiyon sonuçlarını indirirken ödeme yaparsınız.

Yanıt Başlıkları

format json olmadığı zaman kilit bilgileri bu HTTP yanıt başlıklarıyla veriyoruz

x-amz-meta-id
Example: 2345

Resminizin id.

x-amz-meta-secret
Example: image_secret

Resminizin secret.

x-amz-meta-resultrevision
Example: 1

Bu istekte getirdiğiniz resultRevision.

Her yeni sonuç oluşturma işleminde bu sayaçta artış olur.

x-amz-meta-width
Example: 3200
(yalnızca format=result için dahildir)

Bu istekle getirdiğiniz sonucun piksellerinin eni.

x-amz-meta-height
Example: 2400
(yalnızca format=result için dahildir)

Bu istekle getirdiğiniz sonucun piksellerinin yüksekliği.

Content-Disposition
Example: attachment; filename*=UTF-8''image_clipped_rev_0.png

Sonuç dosya adı, uzantı dahildir.

Username = API Id, Password = API Key

cURL

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

Örnek JSON Yanıtı

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

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

Resim JSON Nesnelerinizin bir listesini getirmek için, standart bir HTTP GET yapın.

Parametreler

İsteğe bağlı
limit

Getirilecek kayıtların sayısı. Varsayılan 20 (Minimum 1, maksimum 100).

İsteğe bağlı
offset

Kayıtların listesinde kullanılacak ofset (varsayılan 0).

Yanıt Özellikleri

images

Resim JSON Nesnesi dizisi.

limit

limit kodu sonuç oluşturulurken gerçekten kullanıldı.

offset

offset kodu sonuç oluşturulurken gerçekten kullanıldı.

Username = API Id, Password = API Key

cURL

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

Örnek Yanıt

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

Silme POST https://clippingmagic.com/api/v1/images/[imageId]/delete

Bir resmi silmek için onun URL-silmesine standart bir HTTP POST yaparsınız.

Bu da pek çok HTTP istemci kitaplığının HTTP SİL eylemini desteklemediği gerçeğinin üstesinden gelmek için, standart REST uygulamasında az bir sapmayla gerçekleştirilir. Böylece aynı şeyi yapmak için pek çok yolla uğraşmak zorunda kalınmaz.

Parametreler

imageId

URL'ye yerleştirilmiştir

Yükle çağrısında geri döndürülen id değerini girmeniz gerekecektir.

Yanıt Özellikleri

image

Silinen Resim JSON Nesnesi.

Deneyin

Username = API Id, Password = API Key

cURL

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

Örnek Yanıt

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

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

Hesabınıza ilişkin abonelik statüsü ve kalan kredi sayısı gibi temel bilgileri getirin.

Parametreler

Yok

Yanıt Özellikleri

subscriptionPlan

Şu anda abone olduğunuz plan veya 'hiç'.

subscriptionState

Mevcut aboneliğinizin statüsü ('aktif' veya 'ödemesi gecikmiş') veya abone değilseniz 'sona erdi'.

credits

Hesabınızda kalan kredi sayısı. Eğer şu anda abone değilseniz 0.

Username = API Id, Password = API Key

cURL

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

Örnek Yanıt

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