Server API

Semua permintaan API adalah permintaan HTTP standar ke URL bergaya REST. Responsnya bisa JSON, atau gambar (saat mengambil hasilnya).

Otentikasi

API menggunakan otentikasi akses dasar HTTP standar. Semua permintaan ke API perlu menyertakan Kredensial API Anda, dengan ID API sebagai pengguna dan Kunci API sebagai kata sandi. Perhatikan bahwa ClippingMagic.js hanya menggunakan ID API Anda, untuk tidak mengungkapkan Kunci API Anda kepada pengguna.

Keamanan

Semua permintaan harus dilakukan melalui HTTPS, dan Anda harus mengautentikasi semua permintaan.

Pustaka klien http Anda harus mendukung Server Name Indication (SNI) untuk mensukseskan permintaan. Jika Anda mendapatkan kesalahan jabat tangan yang aneh, kemungkinan besar inilah masalahnya.

Backend vs Frontend

Perhatikan bahwa semua operasi unggah dan unduh dilakukan di backend, tetapi semua operasi tinjauan dan pengeditan dilakukan di Editor Cerdas.

Pembagian tugas ini melindungi Kunci API Anda, sekaligus memungkinkan pengalaman pengguna akhir yang mulus di situs Anda.

Pembatasan Tarif

Tingkat penggunaan API dibatasi dengan tunjangan yang besar dan tidak ada batasan keras di luar kredit API Anda.

Selama operasi normal yang digerakkan oleh pengguna akhir, Anda tidak akan mengalami pembatasan kecepatan karena penggunaan cenderung surut dan mengalir dengan cara yang ditangani layanan dengan baik.

Namun, untuk pekerjaan batch kami sarankan untuk memulai dengan paling banyak 5 utas, menambahkan 1 utas baru setiap 5 menit hingga Anda mencapai tingkat paralelisme yang diinginkan. Harap hubungi sebelum memulai jika Anda membutuhkan lebih dari 100 rangkaian pesan bersamaan.

Jika Anda mengirimkan terlalu banyak permintaan, Anda akan mulai mendapatkan jawaban 429 Too Many Requests. Jika ini terjadi, Anda harus menerapkan linear back off: pada respons pertama seperti itu, tunggu 5 detik hingga mengirimkan permintaan berikutnya. Pada jawaban 429 kedua berturut-turut, tunggu 2*5=10 detik hingga mengirimkan permintaan berikutnya. Yang ketiga tunggu 3*5=15 detik, dan seterusnya.

Anda dapat mengatur ulang penghitung mundur setelah permintaan berhasil, dan Anda harus menerapkan mundur pada basis per utas (yaitu utas harus beroperasi secara independen satu sama lain).

Kesalahan Objek JSON

Kami menggunakan status HTTP konvensional untuk menunjukkan keberhasilan atau kegagalan permintaan API, dan menyertakan informasi kesalahan penting dalam Objek JSON Kesalahan yang dikembalikan.

Kami berusaha untuk selalu mengembalikan Objek JSON Kesalahan dengan permintaan apa pun yang bermasalah. Namun, secara teoritis selalu mungkin terjadi kegagalan server internal yang menyebabkan respons kesalahan non-JSON.

Atribut

statusStatus HTTP dari respons, diulang di sini untuk membantu proses debug.
codeKode kesalahan internal Clipping Magic.
messagePesan kesalahan yang dapat dibaca manusia, dimaksudkan untuk membantu dalam proses debug.

Jika status HTTP untuk permintaan Anda adalah 200, maka Objek JSON Kesalahan tidak akan dikembalikan, dan Anda dapat berasumsi bahwa permintaan secara umum berhasil.

Beberapa pustaka Klien HTTP meningkatkan pengecualian untuk status HTTP di rentang 400-599. Anda perlu menangkap pengecualian tersebut dan menanganinya dengan tepat.

HTTP StatusMakna
200-299

Sukses

400-499

Ada masalah dengan informasi yang diberikan dalam permintaan (mis., Ada parameter yang hilang). Harap tinjau pesan kesalahan untuk mencari tahu cara memperbaikinya.

500-599

Telah terjadi kesalahan internal Clipping Magic. Tunggu beberapa saat kemudian coba lagi, dan jika masalah tetap ada, silakan email kami.

Contoh Kesalahan Jawaban

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

Gambar Objek JSON

Catatan gambar direpresentasikan secara seragam dengan Objek JSON, yang ditampilkan oleh beberapa tindakan API.

Atribut

id

Pengenal unik untuk gambar ini. Diperlukan untuk memungkinkan pengguna mengedit gambar dan mengunduh hasilnya.

secret

Kunci rahasia yang diperlukan untuk mengedit gambar ini ClippingMagic.js

resultRevision

Bilangan bulat yang menunjukkan revisi terbaru yang tersedia untuk diunduh (0 = belum ada hasil yang tersedia).

Memungkinkan Anda menentukan apakah ada hasil yang lebih baru tersedia untuk gambar ini daripada yang Anda unduh sebelumnya.

originalFilename

String berisi nama file yang diberikan saat mengupload gambar asli.

test

true artinya ini adalah gambar uji yang bebas untuk diproses tetapi hasilnya akan memiliki tanda air.

false artinya ini adalah gambar produksi yang memerlukan kredit untuk diproses, tetapi hasilnya tidak akan memiliki tanda air.

Contoh

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

Unggah POST https://clippingmagic.com/api/v1/images

Untuk mengupload gambar, Anda melakukan unggah file HTTP POST standar. Titik akhir ini harus dipanggil dari backend Anda, tidak dapat dipanggil dari javascript halaman web Anda. Harap diingat Jenis Isi harus multipart/form-data saat mengunggah file biner.

Parameter

Gambar masukan harus disediakan sebagai salah satu dari:

image
Biner

File biner.

image.base64
String

String berenkode base64. String bisa paling banyak 1 megabyte panjangnya.

image.url
String

URL untuk diberikan.

Harus berupa file .bmp, .gif, .jpeg, .png, atau .tiff.

Ukuran (=lebar × tinggi) maksimum gambar yang diunggah adalah 33.554.432pixels, yang diperkecil ke 4.194.404pixels kecuali diganti oleh maxPixels dibawah ini. Harap memperkecil gambar Anda terlebih dahulu ke ukuran terakhir atau lebih kecil sebelum mengunggah.

test
Boolean
true, false

Lulus dalam true untuk mengindikasikan bahwa ini adalah gambar tes.

Abaikan atau teruskan false untuk gambar produksi.

Gambar uji bebas untuk diproses, tetapi hasilnya akan memiliki tanda air yang disematkan.

format
Enum
json, result, clipping_path_svg, alpha_mask_png

format=json (default): tidak ada hasil Auto-Clip yang dibuat dan objek Image JSON dikembalikan. Gunakan ini ketika ada operator manusia yang meninjau dan berpotensi meningkatkan hasil menggunakan ClippingMagic.js.

format=result menghasilkan dan mengambil hasil Auto-Clip.

format=clipping_path_svg menghasilkan hasil Auto-Clip dan mengambil Clipping Path (SVG).

format=alpha_mask_png menghasilkan hasil Auto-Clip dan mengambil Alpha Mask (PNG). Alpha Mask memiliki ukuran yang sama dengan gambar masukan. Menerapkannya ke gambar masukan tidak memberi Anda hasil, karena Pelindung Tepi dan Halo Scrubber meningkatkan warna batas.

id dan secret dikembalikan dalam x-amz-meta-id dan x-amz-meta-secret header saat mengambil hasil non-JSON. Pastikan untuk menyimpan ini sehingga Anda dapat meninjau dan mengedit hasil Anda menggunakan ClippingMagic.js. Lihat semua tajuk yang disertakan dalam tanggapan

Mengambil Objek Gambar JSON tidak membebankan biaya ke akun Anda; Anda hanya dikenakan biaya saat mengunduh hasil produksi.

maxPixels
Bilangan Bulat
1000000 hingga 26214400

Mengganti ukuran gambar maksimum (= lebar × tinggi) digunakan saat mengubah ukuran gambar setelah diunggah.

Basis: 4.194.404pixels

background.color
#RRGGBB
#0055FF

Abaikan untuk menggunakan latar belakang transparan.

Pastikan untuk menyertakan '#'.

Konfigurasikan parameter pemrosesan:

processing.mode
Enum
auto, photo, graphics, scan

Kontrol mode proses yang digunakan untuk gambar Anda.

Basis: auto

processing.autoClip
Boolean
true, false

Aktifkan (basis) atau nonaktifkan Auto-Clip saat mengedit gambar di aplikasi web.

Nonaktifkan jika ingin mengunggah gambar melalui API, tetapi kemudian lakukan pemotongan bentuk bebas pada sesuatu selain latar depan yang jelas (jika ada).

Basis: true

processing.autoHair
Boolean
true, false

Aktifkan (default) atau nonaktifkan aplikasi masker rambut otomatis.

Basis: true

processing.allowGraphicsMode
Boolean
true, false

Aktifkan (default) atau nonaktifkan pemilihan otomatis Mode Grafik.

Pengaturan ini tidak berlaku jika format=json.

Basis: true

processing.allowScanMode
Boolean
true, false

Aktifkan (default) atau nonaktifkan pemilihan otomatis Mode Pindai.

Pengaturan ini tidak berlaku jika format=json.

Basis: true

Konfigurasi level warna:

colors.auto
Boolean
true, false

Secara otomatis menyesuaikan tingkat warna untuk meningkatkan kontras.

Basis: false

colors.brightness
Bilangan Bulat
-100 hingga 100

Sesuaikan kecerahan gambar output.

Basis: 0

colors.shadows
Bilangan Bulat
-100 hingga 100

Sesuaikan bayangan dari gambar keluaran. Nilai positif berarti bayangan yang lebih gelap.

Basis: 0

colors.highlights
Bilangan Bulat
-100 hingga 100

Sesuaikan sorotan dari gambar keluaran. Nilai positif berarti sorotan yang lebih ringan.

Basis: 0

colors.temperature
Bilangan Bulat
-100 hingga 100

Sesuaikan suhu warna dari gambar keluaran. Nilai positif berarti warna yang lebih hangat.

Basis: 0

colors.saturation
Bilangan Bulat
-100 hingga 100

Sesuaikan saturasi gambar keluaran. Nilai positif berarti lebih saturasi.

Basis: 0

Konfigurasikan penghapusan warna dari latar belakang yang dilemparkan di latar depan, seperti dengan layar hijau:

colorCast.auto
Boolean
true, false

Secara otomatis menentukan warna latar belakang yang akan dihapus dari latar depan.

Basis: false

colorCast.color
#RRGGBB
#A84400

Warna latar belakang yang ditentukan secara manual untuk dihapus dari latar depan.

Abaikan untuk mendeteksi secara otomatis.

colorCast.foregroundGuard
Bilangan Desimal
0.0 hingga 20.0

Nilai yang lebih besar mengurangi dampak penghilangan cor warna pada warna latar depan asli yang mirip dengan warna cor tetapi lebih jenuh daripada warna yang dihilangkan.

Basis: 4.0

Konfigurasi keseimbangan putih:

whiteBalance.auto
Boolean
true, false

Secara otomatis menentukan warna referensi yang akan digunakan untuk melakukan keseimbangan putih.

Basis: false

whiteBalance.color
#RRGGBB
#968386

Warna keseimbangan putih yang ditentukan secara manual.

Abaikan untuk mendeteksi secara otomatis.

Konfigurasi sentuhan akhir:

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

Tambahkan efek drop shadow ke hasil yang dipotong.

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

Tambahkan efek refleksi ke hasil yang dipotong.

Konfigurasikan parameter tepi:

edges.corners
Boolean
true, false

Gunakan (basis) atau nonaktifkan Pelindung Sudut.

edges.smoothing
Enum
smart, fixed

Gunakan smart (basis) atau fixed penghalusan.

edges.smoothingLevel
Bilangan Desimal
0.0 hingga 5.0

Konfigurasi jumlah penghalusan yang diterapkan pada hasil.

Basis 1.0

edges.feathering
Enum
fixed, auto, local

Gunakan auto (basis), local, atau fixed penghalusan.

edges.featheringRadiusPx
Bilangan Desimal
0.0 hingga 6.0

Konfigurasikan jumlah feathering yang diterapkan pada hasil.

Basis: 1.0

edges.offsetPx
Bilangan Desimal
0.0 hingga 10.0

Konfigurasikan offset batas yang diterapkan ke hasil.

Basis: 0.0

Sesuaikan output dengan hasil

fit.toResult
Boolean
true, false

Aktifkan atau nonaktifkan paskan dengan hasil (basis).

Jika tidak aktif, sisa parameter di bagian ini akan diabaikan secara efektif.

fit.paddingPercent
Bilangan Desimal
0.0 hingga 35.0

Padding yang akan diterapkan di sekitar hasil yang disesuaikan, sebagai persentase dari ukuran hasil.

Basis: 5.0

fit.paddingPixels
Bilangan Bulat
0 hingga 250

Padding dalam piksel untuk diterapkan di sekitar hasil yang disesuaikan.

Jika tidak ditentukan, padding persen digunakan sebagai gantinya.

fit.objectSize
Enum
small, medium, large

Anda dapat menentukan ukuran sintetis untuk objek Anda. Ini berguna untuk eCommerce di mana Anda mungkin ingin memberikan gambaran awal kepada pembeli tentang ukuran produk relatif terhadap produk lain.

Basis: large (= hasilnya tidak diubah ukurannya)

fit.verticalAlignment
Enum
top, middle, bottom

Tentukan bagaimana hasil Anda harus diratakan jika ada ruang vertikal berlebih.

Juga berlaku saat mendistribusikan ruang berlebih karena rasio aspek atau penegakan ukuran target, lihat di bawah.

Basis: middle

fit.shadows
Enum
ignore, pad, tight

Anda dapat mengabaikan bayangan, pad secara merata di kedua sisi agar sesuai dengan bayangan, atau hanya menambahkan padding di tempat yang diperlukan untuk tidak memotong bayangan.

Basis: pad

fit.rotationDeg
Bilangan Desimal
-360.0 hingga 360.0

Rotasikan gambar. Nilai positif berlawanan arah jarum jam.

Basis: 0

Kontrol ukuran hasil dan rasio aspek:

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

Pastikan hasilnya memiliki rasio aspek yang disediakan.

fit.verticalAlignment mengatur distribusi ruang vertikal berlebih.

Basis: tidak diterapkan

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

Pastikan hasil memiliki ukuran yang disediakan.

fit.verticalAlignment mengatur distribusi ruang vertikal berlebih.

Basis: tidak diterapkan

result.allowEnlarging
Boolean
true, false

Mengatur apakah hasil dibiarkan menjadi lebih besar dari gambar input atau tidak.

Basis: false

Atur opsi keluaran:

output.dpi
Bilangan Bulat
1 hingga 4000

Atur informasi DPI yang disematkan dalam hasil.

Informasi DPI tidak disertakan jika hasilnya dioptimalkan web.

Basis: 72

output.colorSpace
Enum
sRGB, AdobeRGB, AppleRGB, ColorMatchRGB

Atur informasi ruang warna yang disematkan dalam hasil.

Informasi ruang warna tidak disertakan jika hasilnya dioptimalkan untuk web.

Basis: sRGB

output.jpegQuality
Bilangan Bulat
1 hingga 100

Konfigurasikan pengaturan kualitas yang digunakan saat menghasilkan hasil JPEG.

Basis: 75

output.pngOptimization
Enum
none, lossless, lossy

Konfigurasikan pengoptimalan web untuk hasil PNG.

Basis: lossless

output.jpegOptimization
Enum
none, enabled

Konfigurasikan pengoptimalan web dari hasil JPEG.

Basis: enabled

output.opaqueFileFormat
Enum
jpeg, png

Konfigurasi format file yang akan digunakan untuk hasil buram.

Basis: jpeg

Anda dapat mengunggah gambar dalam mode uji tanpa berlangganan. Namun, meskipun mengunggah tidak memerlukan kredit, Anda tetap memerlukan langganan API yang sah untuk mengunggah gambar produksi melalui API.

Silakan mencoba


Format: '#RRGGBB'



Format: '#RRGGBB'

Format: '#RRGGBB'


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

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




Format: '[width:float, >0]:[height:float, >0]'
Contoh: 4:3

Format: '[width:int, >0] [height:int, >0]'
Contoh: 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'

Asumsikan 'example.jpg' tersedia. Gantikan sebagimana mestinya. Baris dengan pilihan 'test=true'.

Conotoh Jawaban

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

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

Untuk mengunduh hasil, Anda melakukan HTTP GET standar. Hasil harus sudah dibuat terlebih dahulu.

Hasil tes dapat diunduh gratis, tetapi menyertakan tanda air. Hasil produksi memerlukan satu kredit untuk diunduh saat pertama kali diunduh; unduhan berulang gratis.

Jika tidak ada hasil yang tersedia, maka Anda akan mendapatkan respon kesalahan.

Parameter

imageId

Disatukan ke URL

Anda harus memasukkan nilai id yang dikembalikan dalam panggilan Unggah.

Pilihan
format

format=result (basis) mengambil gambar hasil.

format=clipping_path_svg sebagai gantinya mengambil Clipping Path (SVG).

format=alpha_mask_png sebagai gantinya mengambil Alpha Mask (PNG).

format=json sebagai gantinya mengambil Image JSON Object. Berguna jika Anda ingin memeriksa resultRevisi, atau jika Anda kehilangan rahasia gambar.

Mengambil Objek Gambar JSON tidak membebankan biaya ke akun Anda; Anda hanya dikenakan biaya saat mengunduh hasil produksi.

Contoh Jawaban

Jika format bukan json kami memberikan informasi penting dalam tajuk tanggapan HTTP ini

x-amz-meta-id
Example: 2345

id gambar Anda.

x-amz-meta-secret
Example: image_secret

secret gambar Anda.

x-amz-meta-resultrevision
Example: 1

resultRevision Anda untuk permintaan ini.

Setiap kali hasil baru dibuat, penghitung ini bertambah.

x-amz-meta-width
Example: 3200
(hanya disertakan untuk format=result)

Lebar dalam piksel dari hasil yang Anda ambil dalam permintaan ini.

x-amz-meta-height
Example: 2400
(hanya disertakan untuk format=result)

Tinggi dalam piksel dari hasil yang Anda ambil dalam permintaan ini.

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

Nama file hasil, termasuk ekstensi.

Username = API Id, Password = API Key

cURL

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

Contoh Kesalahan Jawaban

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

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

Untuk mengambil daftar Objek Gambar JSON Anda, Anda melakukan HTTP GET standar.

Parameter

Pilihan
limit

Jumlah catatan yang akan diambil. Basisnya 20 (Min 1, maks 100).

Pilihan
offset

Offset untuk digunakan dalam daftar catatan (basis ke 0).

Atribut Jawaban

images

Barisan Objek Gambar JSON.

limit

limit sebenarnya digunakan saat membuat hasil.

offset

offset sebenarnya digunakan saat membuat hasil.

Username = API Id, Password = API Key

cURL

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

Conotoh Jawaban

{
  "images" : [ {
    "id" : 2345,
    "secret" : "image_secret",
    "resultRevision" : 0,
    "originalFilename" : "image.jpg",
    "imageCategoryUser" : "Photo",
    "imageCategoryAi" : "Photo",
    "test" : false
  }, {
    "id" : 2346,
    "secret" : "image_secret2",
    "resultRevision" : 0,
    "originalFilename" : "image.jpg",
    "imageCategoryUser" : "Photo",
    "imageCategoryAi" : "Photo",
    "test" : false
  } ],
  "limit" : 2,
  "offset" : 0
}

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

Untuk menghapus gambar, Anda melakukan HTTP POST standar ke delete-URL-nya.

Ini adalah sedikit penyimpangan dari praktik REST standar untuk menangani kenyataan bahwa banyak pustaka klien HTTP tidak mendukung kata kerja HTTP DELETE, untuk menghindari kekacauan karena memiliki banyak cara untuk melakukan hal yang sama.

Parameter

imageId

Disatukan ke URL

Anda harus memasukkan nilai id yang dikembalikan dalam panggilan Unggah.

Atribut Jawaban

image

Objek Gambar JSON yang dihapus.

Silakan mencoba

Username = API Id, Password = API Key

cURL

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

Conotoh Jawaban

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

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

Dapatkan informasi dasar tentang akun Anda, seperti status langganan Anda dan jumlah kredit yang tersisa.

Parameter

Tiada

Atribut Jawaban

subscriptionPlan

Paket langganan Anda saat ini berlangganan, atau 'tidak ada'.

subscriptionState

Status langganan Anda saat ini ('aktif' atau 'terlambatBayar') atau 'berakhir' jika tidak berlangganan.

credits

Jumlah kredit yang tersisa di akun Anda. 0 jika saat ini tidak berlangganan.

Username = API Id, Password = API Key

cURL

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

Conotoh Jawaban

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