Tüm API istekleri REST türü URL'lere yapılan standart HTTP istekleridir. Yanıtlar (sonucu getirirken) ya JSON ya da bir resimdir.
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 Parolası ile API Bilgilerinizi içermesi gerekmektedir. Unutmayın ClippingMagic.js size ait API Parolasını kullanıcılarınıza göstermemek için yalnızca API kimliğinizi kullanmaktadır.
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.
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.
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).
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 |
|
|---|---|
| status | Yanıtın HTTP durumu, hata ayıklaması işlemine yardımcı olmak için burada tekrar edilmiştir. |
| code | Clipping Magic iç hata kodu. |
| message | Okunabilir 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 Status | Anlamı |
|---|---|
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. |
Hata ayıklama yapabilmeniz için Son zamanlardaki API hataları hesabınız sayfasında listelenmiştir.
Örnek Hata Yanıtı
{
"error" : {
"status" : 400,
"code" : 1006,
"message" : "Failed to read the supplied image. "
}
}
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 |
| 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 |
|
Örnek
{
"id" : 2346,
"secret" : "image_secret1",
"resultRevision" : 0,
"originalFilename" : "example_image1.jpg",
"imageCategoryUser" : "Photo",
"imageCategoryAi" : "Photo",
"test" : false
}
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:
.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 |
|||||||||||||||
|
test
Boole true, false
|
Bunun bir test resmi olduğunu göstermek için
Prodüksiyon resimleri için atlayın veya Test resimlerinde işlem yapmak ücretsizdir. Ancak sonuç üzerinde bir filigran bulunacaktır. |
||||||||||||||
|
format
Numaralama json, result, clipping_path_svg, clipping_path_tiff, alpha_mask_png
|
JSON-dışı sonuç getirilirken 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 26214400'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 kullanıp PNG sonucu almak için atlayın. Belirlenen rengin ve bir output.opaqueFileFormat sonucunun (varsayılan JPEG) opak bir arka planını elde etmek için dahil edin. '#' dahil etmeyi unutmayın. |
||||||||||||||
|
İşleme parametrelerinin ayarlarını yapın:
|
|||||||||||||||
|
Renk düzeyleri ayarını yapın:
|
|||||||||||||||
|
Mesela yeşil ekranla, ön plana düşen bir rengin arka plandan kaldırılması ayarlarını yapın:
|
|||||||||||||||
|
Beyaz dengesi ayarı yapın:
|
|||||||||||||||
|
Son rötuş ayarlarını yapın:
|
|||||||||||||||
|
Kenar parametre ayarlarını yapın:
|
|||||||||||||||
|
|||||||||||||||
|
Sonuç boyutunu ve en boy oranını kontrol edin:
|
|||||||||||||||
|
Çıktı seçeneklerini kontrol edin:
|
|||||||||||||||
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
Kullanıcı adı= API kimliği, Şifre= API Parolası
cURL
$ curl "https://clippingmagic.com/api/v1/images" \ -u 123:[secret] \ -F 'image=@example.jpg' \ -F 'test=true'
'example.jpg' var olduğu varsayılmaktadır. Uygun durumlarda değiştirin. 'deneme=gerçek' satırı isteğe bağlıdır.
Örnek Yanıt
{
"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]
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 |
|
İsteğe bağlı
format |
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ı
|
|
|---|---|
x-amz-meta-id
Example: 2346
|
Resminizin |
x-amz-meta-secret
Example: image_secret1
|
Resminizin |
x-amz-meta-resultrevision
Example: 1
|
Bu istekte getirdiğiniz 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''example_image1_clipped_rev_0.png
|
Sonuç dosya adı, uzantı dahildir. |
Deneyin
Kullanıcı adı= API kimliği, Şifre= API Parolası
cURL
$ curl "https://clippingmagic.com/api/v1/images/2346" \ -u 123:[secret] \ -LOJ
Örnek JSON Yanıtı
{
"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
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 |
|
| offset |
|
Deneyin
Kullanıcı adı= API kimliği, Şifre= API Parolası
cURL
$ curl "https://clippingmagic.com/api/v1/images?limit=2&offset=0" \ -u 123:[secret]
Örnek Yanıt
{
"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
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 |
|
Yanıt Özellikleri |
|
|---|---|
| image |
Silinen Resim JSON Nesnesi. |
Deneyin
Kullanıcı adı= API kimliği, Şifre= API Parolası
cURL
$ curl "https://clippingmagic.com/api/v1/images/2346/delete" \ -u 123:[secret] \ -X POST
Örnek Yanıt
{
"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
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 API kredisi sayısı. Halihazırda üyü değilseniz veya API-dışı bir plana üyeyseniz. |
Kullanıcı adı= API kimliği, Şifre= API Parolası
cURL
$ curl "https://clippingmagic.com/api/v1/account" \ -u 123:[secret]
Örnek Yanıt
{
"subscriptionPlan" : "none",
"subscriptionState" : "ended",
"credits" : 0
}