Semua permintaan API adalah permintaan HTTP standar ke URL bergaya REST. Responsnya bisa JSON, atau gambar (saat mengambil hasilnya).
API menggunakan otentikasi akses dasar HTTP standar. Semua permintaan ke API harus menyertakan Kredensial API Anda, dengan ID API sebagai pengguna dan Rahasia API sebagai kata sandi. Perhatikan bahwa ClippingMagic.js hanya menggunakan ID API Anda, untuk tidak mengungkapkan Rahasia API Anda kepada pengguna.
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.
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.
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).
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 |
|
|---|---|
| status | Status HTTP dari respons, diulang di sini untuk membantu proses debug. |
| code | Clipping Magic kode kesalahan internal. |
| message | Pesan 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 Status | Makna |
|---|---|
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
|
Terjadi Clipping Magic kesalahan internal. Tunggu beberapa saat kemudian coba lagi, dan jika masalah tetap ada, silakan email kami. |
Kesalahan API terbaru tercantum di laman akun Anda untuk kenyamanan proses debug Anda.
Contoh Kesalahan Jawaban
{
"error" : {
"status" : 400,
"code" : 1006,
"message" : "Failed to read the supplied image. "
}
}
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 |
| 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 |
|
Contoh
{
"id" : 2346,
"secret" : "image_secret1",
"resultRevision" : 0,
"originalFilename" : "example_image1.jpg",
"imageCategoryUser" : "Photo",
"imageCategoryAi" : "Photo",
"test" : false
}
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:
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 |
|||||||||||||||
|
test
Boolean true, false
|
Lulus dalam
Abaikan atau teruskan Gambar uji bebas untuk diproses, tetapi hasilnya akan memiliki tanda air yang disematkan. |
||||||||||||||
|
format
Enum json, result, clipping_path_svg, clipping_path_tiff, alpha_mask_png
|
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 dan dapatkan hasil PNG. Sertakan untuk mendapatkan latar belakang buram dari warna yang ditentukan dan hasil output.opaqueFileFormat (JPEG default). Pastikan untuk menyertakan '#'. |
||||||||||||||
|
Konfigurasikan parameter pemrosesan:
|
|||||||||||||||
|
Konfigurasi level warna:
|
|||||||||||||||
|
Konfigurasikan penghapusan warna dari latar belakang yang dilemparkan di latar depan, seperti dengan layar hijau:
|
|||||||||||||||
|
Konfigurasi keseimbangan putih:
|
|||||||||||||||
|
Konfigurasi sentuhan akhir:
|
|||||||||||||||
|
Konfigurasikan parameter tepi:
|
|||||||||||||||
|
|||||||||||||||
|
Kontrol ukuran hasil dan rasio aspek:
|
|||||||||||||||
|
Atur opsi keluaran:
|
|||||||||||||||
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
Nama Pengguna = Id API, Kata Sandi = Rahasia API
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" : 2346,
"secret" : "image_secret1",
"resultRevision" : 0,
"originalFilename" : "example_image1.jpg",
"imageCategoryUser" : "Photo",
"imageCategoryAi" : "Photo",
"test" : false
}
}
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 |
|
Pilihan
format |
Mengambil Objek Gambar JSON tidak membebankan biaya ke akun Anda; Anda hanya dikenakan biaya saat mengunduh hasil produksi. |
|
Contoh Jawaban
Jika |
|
|---|---|
x-amz-meta-id
Example: 2346
|
|
x-amz-meta-secret
Example: image_secret1
|
|
x-amz-meta-resultrevision
Example: 1
|
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''example_image1_clipped_rev_0.png
|
Nama file hasil, termasuk ekstensi. |
Silakan mencoba
Nama Pengguna = Id API, Kata Sandi = Rahasia API
cURL
$ curl "https://clippingmagic.com/api/v1/images/2346" \ -u 123:[secret] \ -LOJ
Contoh Kesalahan Jawaban
{
"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
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 |
|
| offset |
|
Silakan mencoba
Nama Pengguna = Id API, Kata Sandi = Rahasia API
cURL
$ curl "https://clippingmagic.com/api/v1/images?limit=2&offset=0" \ -u 123:[secret]
Conotoh Jawaban
{
"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
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 |
|
Atribut Jawaban |
|
|---|---|
| image |
Objek Gambar JSON yang dihapus. |
Silakan mencoba
Nama Pengguna = Id API, Kata Sandi = Rahasia API
cURL
$ curl "https://clippingmagic.com/api/v1/images/2346/delete" \ -u 123:[secret] \ -X POST
Conotoh Jawaban
{
"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
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 API yang tersisa di akun Anda. 0 jika saat ini tidak berlangganan, atau berlangganan paket non-API. |
Silakan mencoba
Nama Pengguna = Id API, Kata Sandi = Rahasia API
cURL
$ curl "https://clippingmagic.com/api/v1/account" \ -u 123:[secret]
Conotoh Jawaban
{
"subscriptionPlan" : "none",
"subscriptionState" : "ended",
"credits" : 0
}