คำขอ API ทั้งหมดเป็นคำขอ HTTP แบบมาตรฐานถึง URL ในรูปแบบ REST ผลตอบรับจะเป็น JSON หรือภาพ (เมื่อดึงผลลัพธ์)
API ใช้ การรับรองความถูกต้องเบื้องต้นของการเข้าถึง HTTP แบบมาตรฐาน คำร้องขอทั้งหมดถึง API จำเป็นที่จะต้องมีข้อมูลประจำตัว API ของคุณ โดยมี API Id เป็นผู้ใช้ และรหัสลับ API เป็นรหัสผ่าน โปรดทราบว่า ClippingMagic.js
ใช้เฉพาะ API Id ของคุณ เพื่อที่จะไม่เปิดเผยรหัสลับ API ของคุณต่อผู้ใช้ของคุณ
คำขอทั้งหมดต้องกระทำผ่าน HTTPS และคุณต้องรับรองความถูกต้องของคำขอทั้งหมด
ไลบรารีไคลเอ็นต์ http ของคุณต้องรองรับ การบ่งชี้ชื่อเซิร์ฟเวอร์ (SNI) จึงจะส่งคำขอได้สำเร็จ หากคุณได้รับข้อผิดพลาดแฮนด์เชกที่แปลกประหลาด ก็น่าจะเป็นเพราะเหตุนี้มากที่สุด
โปรดทราบว่าการดำเนินการอัปโหลดและดาวน์โหลดทั้งหมดจะเกิดขึ้นทางฝั่งแบ็กเอนด์ แต่การดำเนินการตรวจสอบและแก้ไขทั้งหมดจะเกิดขึ้นในตัวแก้ไขแบบอัจฉริยะ
การแบ่งแบบนี้ช่วยป้องกันคีย์ API ของคุณ ขณะเดียวกันกับที่มอบประสบการณ์แบบไร้ที่ติแก่ผู้ใช้ปลายทางที่เว็บไซต์ของคุณ
การใช้งาน API มีอัตราที่จำกัด โดยเผื่อค่าไว้กว้างและไม่มีขอบเขตบนที่เคร่งครัดเกินกว่าเครดิต API ของคุณ
ในระหว่างการดำเนินการที่ผู้ใช้ปลายทางกระทำตามปกตินั้น มีโอกาสน้อยที่คุณจะประสบกับอัตราที่จำกัด เพราะการใช้งานมีแนวโน้มที่จะขึ้น ๆ ลง ๆ ในลักษณะที่บริการจัดการได้อย่างเรียบร้อย
อย่างไรก็ตาม ในกรณีของชุดงาน เราขอแนะนำให้เริ่มต้นด้วยชุดกิจกรรมสูงสุด 5 ชุด โดยเพิ่มใหม่ 1 ชุดทุก ๆ 5 นาที จนกว่าคุณจะไปถึงระดับการทำงานแบบขนานตามที่ต้องการ กรุณาแจ้งให้เราทราบก่อนที่คุณจะเริ่มงาน หากต้องการชุดกิจกรรมมากกว่า 100 ชุดพร้อมกัน
หากคุณส่งคำขอมากเกินไป คุณจะเริ่มได้รับผลตอบกลับ 429 Too Many Requests
เมื่อเกิดกรณีเช่นนี้ขึ้น คุณควรปรับใช้กลยุทธ์สุ่มรอเวลาแบบเส้นตรง : ในผลตอบกลับดังกล่าวครั้งแรก รอ 5 วินาที ก่อนส่งคำขอถัดไป ในผลตอบกลับ 429 ที่ต่อเนื่องกันครั้งที่สอง รอ 2*5=10 วินาที ก่อนส่งคำขอถัดไป ส่วนครั้งที่สาม จะรอ 3*5=15 วินาที ฯลฯ
คุณสามารถรีเซ็ตตัวนับการสุ่มรอเวลาหลังจากคำขอประสบผลสำเร็จ และคุณควรนำการสุ่มรอเวลาไปใช้กับแต่ละชุดกิจกรรม (กล่าวคือ ชุดกิจกรรมควรทำหน้าที่โดยอิสระไม่ขึ้นต่อกันและกัน)
เราใช้สถานะ HTTP แบบปกติ เพื่อบ่งชี้ความสำเร็จหรือความล้มเหลวของคำขอ API และรวมถึงรายละเอียดข้อผิดพลาดที่สำคัญในออบเจ็กต์ JSON ที่ผิดพลาดและถูกส่งคืน
เราพยายามอยู่เสมอที่จะส่งคืนออบเจ็กต์ JSON ที่ผิดพลาดพร้อมด้วยคำขอใด ๆ ที่เป็นปัญหา อย่างไรก็ตาม ในทางทฤษฎี มีความเป็นไปได้เสมอที่เซิร์ฟเวอร์จะเกิดความล้มเหลวภายใน ซึ่งนำไปสู่ผลตอบกลับข้อผิดพลาดที่ไม่ใช่ JSON
ลักษณะเฉพาะ |
|
---|---|
status | ในที่นี้ แสดงสถานะ HTTP ของผลตอบกลับซ้ำอีก เพื่อช่วยในการแก้จุดบกพร่อง |
code | รหัสข้อผิดพลาดภายในของ Clipping Magic |
message | ข้อความแสดงข้อผิดพลาดที่มนุษย์สามารถอ่านได้ มีจุดประสงค์เพื่อช่วยในการแก้จุดบกพร่อง |
หากสถานะ HTTP สำหรับคำขอของคุณคือ 200 แสดงว่าจะไม่มีการส่งคืนออบเจ็กต์ JSON ที่ผิดพลาด และคุณสามารถสรุปได้ว่า คำขอนั้นสื่อสารได้สำเร็จในวงกว้าง
ไลบรารีไคลเอ็นต์ HTTP บางส่วนทำให้เกิดข้อยกเว้นสำหรับสถานะ HTTP ในช่วง 400
-599
คุณจำเป็นจะต้องตรวจจับข้อยกเว้นเหล่านั้นและจัดการตามความเหมาะสม
HTTP Status | ความหมาย |
---|---|
200 -299
|
ความสำเร็จ |
400 -499
|
มีปัญหาเกิดขึ้นกับข้อมูลที่ให้ไว้ในคำขอ (เช่น พารามิเตอร์ขาดหายไป) กรุณาตรวจสอบข้อความแสดงข้อผิดพลาดเพื่อคิดหาวิธีที่จะจัดการแก้ไข |
500 -599
|
ตรวจพบข้อผิดพลาดภายใน Clipping Magic กรุณารอสักครู่แล้วลองใหม่อีกครั้ง หากปัญหายังคงมีอยู่ กรุณาส่งอีเมลถึงเรา |
ข้อผิดพลาด API ล่าสุดแสดงอยู่ในหน้าบัญชีของคุณ เพื่อช่วยให้คุณมีความสะดวกในการแก้จุดบกพร่อง
ตัวอย่างผลตอบกลับข้อผิดพลาด
{ "error" : { "status" : 400, "code" : 1006, "message" : "Failed to read the supplied image. " } }
การบันทึกภาพจะแสดงในรูปแบบเดียวกันกับออบเจ็กต์ JSON ซึ่งส่งคืนโดยการดำเนินการหลายอย่างของ API
ลักษณะเฉพาะ |
|
---|---|
id |
รหัสเฉพาะภาพ จำเป็นต้องอนุญาตให้ผู้ใช้แก้ไขภาพและเพื่อดาวน์โหลดผลลัพธ์ |
secret |
รหัสลับที่จำเป็นต้องใช้เพื่อแก้ไขภาพนี้ด้วย |
resultRevision |
ตัวเลขจำนวนเต็มที่ระบุการปรับปรุงแก้ไขล่าสุดที่มีให้ดาวน์โหลดได้ (0 = ยังไม่มีผลลัพธ์ให้ใช้ได้) อนุญาตให้คุณตัดสินว่า ภาพนี้มีผลลัพธ์ที่ใหม่กว่าที่คุณได้ดาวน์โหลดไว้ก่อนหน้านี้แล้วหรือไม่ |
originalFilename |
สตริงที่มีชื่อไฟล์ที่ให้ไว้เมื่ออัปโหลดภาพต้นฉบับ |
test |
|
ตัวอย่าง
{ "id" : 2346, "secret" : "image_secret1", "resultRevision" : 0, "originalFilename" : "example_image1.jpg", "imageCategoryUser" : "Photo", "imageCategoryAi" : "Photo", "test" : false }
POST https://clippingmagic.com/api/v1/images
ในการอัปโหลดภาพ คุณจะทำการอัปโหลดไฟล์ HTTP POST แบบมาตรฐาน แบ็กเอนด์จะต้องเรียกจุดสิ้นสุดนี้ ส่วนจาวาสคริปต์ที่หน้าเว็บของคุณจะเรียกไม่ได้ อย่าลืมว่า ประเภท-เนื้อหา ต้องเป็น multipart/form-data
เมื่ออัปโหลดไฟล์ไบนารี
พารามิเตอร์ |
|||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
ต้องป้อนภาพอินพุตในแบบใดแบบหนึ่งดังนี้ :
ต้องเป็นไฟล์ .bmp, .gif, .jpeg, .png, หรือ .tiff
ขนาดสูงสุดของภาพที่จะอัปโหลด (= ความกว้าง × ความสูง) คือ 33,554,432 พิกเซล, ซึ่งจะลดขนาดลงเป็น 4,194,404 พิกเซล เว้นแต่จะถูกแทนที่โดย |
|||||||||||||||
test
บูลีน true , false
|
ส่ง
ละเว้นหรือส่ง ภาพทดสอบจะดำเนินการได้ฟรี แต่ผลลัพธ์จะใส่ลายน้ำแทรกไว้ |
||||||||||||||
format
Enum json , result , clipping_path_svg , clipping_path_tiff , alpha_mask_png
|
การเรียกใช้ออบเจ็กต์ JSON ของภาพจะไม่เรียกเก็บเงินจากบัญชีของคุณ คุณจะต้องชำระเฉพาะเมื่อดาวน์โหลดผลลัพธ์สำหรับออกสื่อเท่านั้น |
||||||||||||||
maxPixels
จำนวนเต็ม 1000000 ถึง 26214400
|
เปลี่ยนขนาดสูงสุดของภาพ (= ความกว้าง × ความสูง) จะใช้เมื่อปรับขนาดภาพหลังจากการอัปโหลด ค่าเริ่มต้น : 4,194,404 พิกเซล |
||||||||||||||
background.color
#RRGGBB #0055FF
|
ละเว้นที่จะใช้พื้นหลังโปร่งใส และรับผลลัพธ์เป็น PNG รวมถึงการได้รับพื้นหลังทึบแสงของสีที่ระบุไว้และผลลัพธ์ที่เป็น output.opaqueFileFormat (ค่าเริ่มต้นคือ JPEG) อย่าลืมใส่ '#' |
||||||||||||||
กำหนดค่า พารามิเตอร์การประมวลผล:
|
|||||||||||||||
กำหนดค่า ระดับสี:
|
|||||||||||||||
กำหนดค่าการลบสีออกจากพื้นหลังที่เป็น สีเพี้ยนบนพื้นหน้า เช่นเดียวกับฉากเขียว :
|
|||||||||||||||
กำหนดค่า สมดุลสีขาว:
|
|||||||||||||||
กำหนดค่า การปรับแต่งขั้นสุดท้าย:
|
|||||||||||||||
กำหนดค่า พารามิเตอร์ขอบ:
|
|||||||||||||||
ใช้ผลลัพธ์ที่สมมาตรพอดีกับผลลัพธ์
|
|||||||||||||||
ควบคุม ขนาดผลลัพธ์และอัตราส่วนกว้างยาว:
|
|||||||||||||||
ควบคุม เอาต์พุตที่มีให้เลือก:
|
คุณสามารถอัปโหลดภาพในโหมดทดสอบได้โดยไม่ต้องสมัครเป็นสมาชิก แม้ว่าการอัปโหลดไม่ต้องใช้เครดิตก็ตาม แต่คุณจำเป็นต้องสมัครเป็นสมาชิก API ไว้อย่างถูกต้อง จึงจะสามารถใช้ API เพื่ออัปโหลดภาพสำหรับออกสื่อได้
ลองใช้ดู
ชื่อผู้ใช้ = API Id, รหัสผ่าน = รหัสลับ API
cURL
$ curl "https://clippingmagic.com/api/v1/images" \ -u 123:[secret] \ -F 'image=@example.jpg' \ -F 'test=true'
หาก 'example.jpg' มีอยู่จริง ให้ทดแทนตามความเหมาะสม สามารถเลือกใช้บรรทัดที่มี 'test=true' ได้
ตัวอย่างผลตอบกลับ
{ "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]
ในการดาวน์โหลดผลลัพธ์ คุณต้องทำ HTTP GET แบบมาตรฐาน อันดับแรก ต้องสร้างผลลัพธ์ขึ้นมาก่อน
ผลลัพธ์ทดสอบสามารถดาวน์โหลดได้ฟรี แต่จะมีลายน้ำอยู่ด้วย ส่วนผลลัพธ์สำหรับออกสื่อจะใช้หนึ่งเครดิตในการดาวน์โหลดครั้งแรก และฟรีเมื่อดาวน์โหลดซ้ำ
หากไม่มีผลลัพธ์ให้ใช้ได้ คุณจะได้รับผลตอบกลับที่เป็นข้อผิดพลาด
พารามิเตอร์ |
|
---|---|
imageId |
ผนวกรวมเข้าไปใน URL
คุณจะต้องใส่ค่า |
เลือกได้
format |
แต่
แต่
แต่
แต่ การเรียกใช้ออบเจ็กต์ JSON ของภาพจะไม่เรียกเก็บเงินจากบัญชีของคุณ คุณจะต้องชำระเฉพาะเมื่อดาวน์โหลดผลลัพธ์สำหรับออกสื่อเท่านั้น |
ส่วนหัวผลตอบกลับ
เมื่อ |
|
---|---|
x-amz-meta-id
Example: 2346
|
|
x-amz-meta-secret
Example: image_secret1
|
|
x-amz-meta-resultrevision
Example: 1
|
ทุกครั้งที่สร้างผลลัพธ์ใหม่ ตัวนับนี้จะเพิ่มขึ้น |
x-amz-meta-width
Example: 3200
(รวมไว้สำหรับ format=result เท่านั้น)
|
ความกว้างในหน่วยพิกเซลของผลลัพธ์ที่คุณกำลังดึงข้อมูลในคำขอนี้ |
x-amz-meta-height
Example: 2400
(รวมไว้สำหรับ format=result เท่านั้น)
|
ความยาวในหน่วยพิกเซลของผลลัพธ์ที่คุณกำลังดึงข้อมูลในคำขอนี้ |
Content-Disposition
Example: attachment; filename*=UTF-8''example_image1_clipped_rev_0.png
|
ชื่อไฟล์ของผลลัพธ์ รวมทั้งส่วนขยายด้วย |
ลองใช้ดู
ชื่อผู้ใช้ = API Id, รหัสผ่าน = รหัสลับ API
cURL
$ curl "https://clippingmagic.com/api/v1/images/2346" \ -u 123:[secret] \ -LOJ
ตัวอย่างผลตอบกลับ 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
ในการเรียกใช้รายการออปเจ็กต์ JSON ของภาพที่คุณต้องการ ให้ทำ HTTP GET แบบมาตรฐาน
พารามิเตอร์ |
|
---|---|
เลือกได้
limit |
จำนวนบันทึกที่จะเรียกใช้ ค่าเริ่มต้นคือ 20 (ต่ำสุด 1, สูงสุด 100) |
เลือกได้
offset |
ค่าออฟเซ็ตเพื่อใช้ในรายการบันทึก (ค่าเริ่มต้นคือ 0) |
ลักษณะเฉพาะผลตอบกลับ |
|
---|---|
images |
อาร์เรย์ออปเจ็กต์ JSON ของภาพ |
limit |
|
offset |
|
ลองใช้ดู
ชื่อผู้ใช้ = API Id, รหัสผ่าน = รหัสลับ API
cURL
$ curl "https://clippingmagic.com/api/v1/images?limit=2&offset=0" \ -u 123:[secret]
ตัวอย่างผลตอบกลับ
{ "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
หากต้องการลบภาพออก คุณต้องส่ง HTTP POST แบบมาตรฐานไปยัง URL เพื่อลบภาพออก
การทำเช่นนี้มีความแตกต่างเล็กน้อยเมื่อเทียบกับวิธีปฏิบัติ REST แบบมาตรฐานในการจัดการกับความเป็นจริงที่ว่าไลบรารีไคลเอ็นต์ HTTP จำนวนมากไม่รองรับคำกริยา HTTP DELETE ขณะที่หลีกเลี่ยงไม่ให้เกิดความสับสนเพราะมีหลายวิธีสำหรับทำสิ่งเดียวกัน
พารามิเตอร์ |
|
---|---|
imageId |
ผนวกรวมเข้าไปใน URL
คุณจะต้องใส่ค่า |
ลักษณะเฉพาะผลตอบกลับ |
|
---|---|
image |
ออบเจกต์ JSON ของภาพที่ลบแล้ว |
ลองใช้ดู
ชื่อผู้ใช้ = API Id, รหัสผ่าน = รหัสลับ API
cURL
$ curl "https://clippingmagic.com/api/v1/images/2346/delete" \ -u 123:[secret] \ -X POST
ตัวอย่างผลตอบกลับ
{ "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
ดึงข้อมูลพื้นฐานเกี่ยวกับบัญชีของคุณ เช่น สถานะการสมัครสมาชิกและจำนวนเครดิตที่เหลืออยู่
พารามิเตอร์ |
|
---|---|
ไม่มี |
ลักษณะเฉพาะผลตอบกลับ |
|
---|---|
subscriptionPlan |
แผนสมาชิกที่คุณมีอยู่ในขณะนี้ หรือ 'ไม่มี' |
subscriptionState |
สถานะการเป็นสมาชิกของคุณในขณะนี้ ('ใช้บริการ' หรือ 'ค้างชำระ') หรือ 'สิ้นสุดแล้ว' หากไม่ได้เป็นสมาชิก |
credits |
จำนวนเครดิต API ที่คงเหลือในบัญชีของคุณ ค่าเท่ากับ 0 ถ้าไม่ได้เป็นสมาชิกในขณะนี้ หรือเป็นสมาชิกแผนบริการที่ไม่ใช่ API |
ชื่อผู้ใช้ = API Id, รหัสผ่าน = รหัสลับ API
cURL
$ curl "https://clippingmagic.com/api/v1/account" \ -u 123:[secret]
ตัวอย่างผลตอบกลับ
{ "subscriptionPlan" : "none", "subscriptionState" : "ended", "credits" : 0 }