Tất cả các yêu cầu API là những yêu cầu HTTP tiêu chuẩn cho các URL kiểu REST. Các phản hồi là JSON hoặc một hình ảnh (khi tải kết quả).
API sử dụng xác thực truy cập cơ bản HTTP tiêu chuẩn. Tất cả các yêu cầu đối với API sẽ cần có Thông Tin Đăng Nhập API của bạn, cùng với Mã Định Danh API như là người dùng và API Bí Mật như là mật khẩu. Lưu ý rằng ClippingMagic.js chỉ sử dụng Mã Định Danh API của bạn, không tiết lộ API Bí Mật của bạn cho những người dùng.
Tất cả yêu cầu phải được thực hiện qua HTTPS và bạn phải xác thực tất cả yêu cầu đó.
Thư viện khách hàng http của bạn phải hỗ trợ Chỉ Định Tên Máy Chủ (SNI) để thực hiện thành công các yêu cầu. Nếu bạn nhận được các lỗi giao tiếp lạ, việc thiếu hỗ trợ SNI có thể chính là lý do.
Lưu ý rằng tất cả hoạt động tải lên và tải về tiến hành trên máy chủ, nhưng tất cả hoạt động xem xét và chỉnh sửa thực hiện ở Phần Mềm Chỉnh Sửa Thông Minh (Smart Editor).
Việc phân chia này bảo vệ Khoá API của bạn, đồng thời cho phép trải nghiệm người dùng cuối có tính liền mạch trên trang web của bạn.
Việc sử dụng API được giới hạn tốc độ với các hạn mức cho phép mang tính hào phóng và không có giới hạn trần vượt qua điểm API của bạn.
Trong quá trình hoạt động thông thường do người dùng cuối điều khiển, bạn sẽ ít gặp phải bất kỳ giới hạn tốc độ nào vì việc sử dụng có xu hướng tăng giảm theo cách mà dịch vụ xử lý một cách ổn thoả.
Dù vậy, đối với các công việc hàng loạt chúng tôi khuyến khích bắt đầu nhiều nhất là 5 chuỗi, tăng thêm 1 chuỗi mới mỗi 5 phút cho đến khi bạn đạt đến mức độ song song mong muốn. Nếu bạn cần hơn 100 chuỗi cùng lúc, vui lòng liên hệ trước khi bắt đầu.
Nếu bạn gửi quá nhiều yêu cầu thì bạn sẽ bắt đầu nhận các phản hồi 429 Too Many Requests. Khi điều này xảy ra, bạn nên áp dụng linear back off//: trước phản hồi đầu tiên đó, đợi 5 giây cho đến khi gửi yêu cầu tiếp theo. Đối với 429 phản hồi liên tục thứ hai/, hãy đợi 2*5= 10 giây cho đến khi gửi yêu cầu tiếp theo. Đối với thứ bạ, đợi 3*5=15 giây, v.v.
Bạn có thể đặt lại bộ đếm back off sau khi yêu cầu thành công và bạn nên sử dụng back off trên cơ sở mỗi chuỗi (chẳng hạn các chuỗi nên hoạt động độc lập với nhau).
Chúng tôi sử dụng nguyên trạng HTTP quy ước để cho thấy sự thành công hay thất bại của một yêu cầu API và bao gồm những thông tin lỗi quan trọng trong Đối tượng Lỗi JSON (Error JSON Object) được trả về.
Chúng tôi luôn cố gắng trả về Đối tượng Lỗi JSON (Error JSON Object) với bất kỳ yêu nào có vấn đề. Tuy nhiên, có những thất bại của máy chủ nội bộ luôn luôn có thể về mặt lý thuyết mà việc đó dẫn đến phản hồi không không phải do lỗi JSON.
|
Các Thuộc Tính |
|
|---|---|
| status | Trạng thái phản hồi của HTTP được lập lại ở đây để giúp cho việc gỡ lỗi. |
| code | Clipping Magic mã lỗi nội bộ. |
| message | Tin nhắn lỗi người có thể đọc được, dự định có ích trong việc gỡ lỗi. |
Nếu trạng thái HTTP đối với yêu cầu của bạn là 200 thì sẽ không có Đối Tượng Lỗi JSON (Error JSON Object) nào được trả về và bạn có thể giả định một cách an toàn nói chung là yêu cầu đã thành công/.
Một số Thư Viện Khách Hàng HTTP đưa ra các lỗi/ về nguyên trạng HTTP/ trong phạm vi 400-599. Bạn sẽ cần nắm lấy các lỗi này và xử lý chúng phù hợp.
| HTTP Status | Ý nghĩa |
|---|---|
200-299
|
Thành Công |
400-499
|
Có vấn đề với thông tin được cung cấp trong yêu cầu (chẳng hạn đã mất một tham số). Vui lòng xem xét tin nhắn lỗi để tìm ra cách sửa nó. |
500-599
|
Đã có Clipping Magic mã lỗi nội bộ. Đợi 1 chút rồi thử lại và nếu sự cố cứ tiếp tục tồn tại, vui lòng email cho chúng tôi. |
Lỗi API gần đây được liệt kê trên trang tài khoản của bạn để tiện cho bạn gỡ lỗi.
Example Error Response
{
"error" : {
"status" : 400,
"code" : 1006,
"message" : "Failed to read the supplied image. "
}
}
Các ghi nhận hình ảnh được thể hiện theo cách đồng nhất với một JSON Object, được trả về bởi nhiều tác vụ API.
|
Các Thuộc Tính |
|
|---|---|
| id |
Mã định danh duy nhất cho hình ảnh. Cần để người dùng chỉnh sửa hình ảnh và tải về kết quả hình ảnh. |
| secret |
Cần khóa bí mật để chỉnh sửa hình ảnh này bằng |
| resultRevision |
Sống nguyên cho thấy đa số sửa đổi gần đây có sẵn để tải về (0 = chưa cung cấp kết quả). Cho phép bạn xác định xem có cung cấp kết quả cho hình ảnh này mới hơn hình ảnh được tải về trước đó. |
| originalFilename |
Chuỗi chứa tên tập tin được cung cấp khi tải hình ảnh gốc lên. |
| test |
|
Ví Dụ
{
"id" : 2346,
"secret" : "image_secret1",
"resultRevision" : 0,
"originalFilename" : "example_image1.jpg",
"imageCategoryUser" : "Photo",
"imageCategoryAi" : "Photo",
"test" : false
}
POST https://clippingmagic.com/api/v1/images
Để tải hình ảnh lên, bạn tải tệp HTTP POST chuẩn. Phải gọi đểm cuối này từ phía máy chủ, không thể gọi nó từ javascript của trang web. Hãy ghi nhớ rằng Loại-Nội Dung phải là multipart/form-data khi tải các tệp nhị phân lên.
|
Các tham số |
|||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Phải cung cấp hình ảnh đầu vào là hình ảnh của:
Phải là tệp .bmp, .gif, .jpeg, .png, hoặc .tiff.
Kích thước tải lên hình ảnh tối đa (= chiều rộng × chiều cao) là 33.554.432 pixels, mà trở nên co nhỏ lại thành 4.194.404 pixels trừ khi ghi đè lên bởi |
|||||||||||||||
|
test
Boolean Boolean true, false
|
Gửi
Loại bỏ hoặc gửi Hình ảnh kiểm thử được tự do xử lý nhưng kết quả sẽ có hình nền mờ được nhúng. |
||||||||||||||
|
format
Bộ đếm json, result, clipping_path_svg, clipping_path_tiff, alpha_mask_png
|
Trả về Lấy Image JSON Object không tính tiền tài khoản của bạn; bạn chỉ có thể bị tính tiền khi tải kết quả sản phẩm xuống. |
||||||||||||||
|
maxPixels
Số nguyên 1000000 to 26214400
|
Thay đổi kích thước hình ảnh tối đa (=chiều rộng × chiều cao) được dùng khi đưa hình ảnh trở lại kích thước yêu cầu sau khi tải lên. Mặc định: 4.194.404 pixels |
||||||||||||||
|
background.color
#RRGGBB #0055FF
|
Bỏ sự dụng phông nền trong suốt và nhận kết quả PNG. Kèm để nhận nền không trong suốt theo một màu được chỉ định và kết quả output.opaqueFileFormat (mặc định là JPEG). Chắc chắn đưa '#' vào. |
||||||||||||||
|
Cấu hình các tham số xử lý:
|
|||||||||||||||
|
Tùy chỉnh các mức màu:
|
|||||||||||||||
|
Tùy chỉnh gỡ bỏ màu ở phông nền mà truyền từ tiền cảnh, như với mành hình màu xanh lá cây.
|
|||||||||||||||
|
Tùy chỉnh cân bằng màu trắng:
|
|||||||||||||||
|
Tùy chỉnh cảm ứng hoàn thiện:
|
|||||||||||||||
|
Tùy chỉnh các tham số xử lý:
|
|||||||||||||||
|
Làm cho phù hợp kết quả xuất ra
|
|||||||||||||||
|
Kiểm soát kích cỡ kết quả và tỷ lệ khung ảnh ratio:
|
|||||||||||||||
|
Kiểm soát các tùy chọn xuất ra:
|
|||||||||||||||
Bạn có thể tải lên các hình ảnh trong chế độ kiểm thử mà không cần đăng ký. Tuy nhiên, cho dù việc tải lên không mất điểm, bạn cũng cần đăng ký API hợp lệ để tải lên các hình ảnh sản xuất qua API.
Hãy dùng thử
Người dùng = id API, Hộ chiếu = Bí mật API
cURL
$ curl "https://clippingmagic.com/api/v1/images" \ -u 123:[secret] \ -F 'image=@example.jpg' \ -F 'test=true'
Giả định 'example.jpg' tồn tại. Hãy thay thế khi phù hợp. Sắp xếp với tùy chọn'test=true'.
Example Response
{
"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]
Để tải về kết quả, bạn thực hiện HTTP GET tiêu chuẩn. Phải chắc chắn đã tạo kết quả trước.
Các kết quả kiểm thử được tự do tải về nhưng bao gồm hình nền mờ. Các kết quả sản xuất mất một điểm để tải về lần đầu tải chúng về; những lần tải về lập lại miễn phí.
Nếu không có sẵn kết quả thì bạn sẽ nhận được một phản hồi lỗi.
|
Các tham số |
|
|---|---|
| imageId |
Được đính kèm trong URL
Bạn sẽ cần phải chèn giá trị |
|
Không bắt buộc
format |
Lấy Image JSON Object không tính tiền tài khoản của bạn; bạn chỉ có thể bị tính tiền khi tải kết quả sản phẩm xuống. |
|
Các Tiêu Đề Phản Hồi
Khi |
|
|---|---|
x-amz-meta-id
Example: 2346
|
Hình ảnh của bạn là |
x-amz-meta-secret
Example: image_secret1
|
Hình ảnh của bạn là |
x-amz-meta-resultrevision
Example: 1
|
Mỗi lần tạo một kết quả mới, bộ đếm này được tăng dần. |
x-amz-meta-width
Example: 3200
(chỉ được đưa vào cho format=result)
|
Chiều rông trong các điểm ảnh của kết quả mà bạn đang tải theo yêu cầu này. |
x-amz-meta-height
Example: 2400
(chỉ được đưa vào cho format=result)
|
Chiều cao trong các điểm ảnh của kết quả mà bạn đang tải theo yêu cầu này. |
Content-Disposition
Example: attachment; filename*=UTF-8''example_image1_clipped_rev_0.png
|
Tên tệp kết quả, bao gồm mở rộng. |
Hãy dùng thử
Người dùng = id API, Hộ chiếu = Bí mật API
cURL
$ curl "https://clippingmagic.com/api/v1/images/2346" \ -u 123:[secret] \ -LOJ
Example JSON Response
{
"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
Để tải danh sách các Image JSON Object của bạn, bạn thực hiện HTTP GET tiêu chuẩn.
|
Các tham số |
|
|---|---|
|
Không bắt buộc
limit |
Số bản ghi cần tải. Các mặc định cho 20 (Tối thiểu 1, tối đa 100). |
|
Không bắt buộc
offset |
Offset sử dụng trong danh sách các ghi nhận (mặc định đến 0) |
|
Các Thuộc Tính Phản Hồi |
|
|---|---|
| images |
Một mảng Image JSON Objects. |
| limit |
|
| offset |
|
Hãy dùng thử
Người dùng = id API, Hộ chiếu = Bí mật API
cURL
$ curl "https://clippingmagic.com/api/v1/images?limit=2&offset=0" \ -u 123:[secret]
Example Response
{
"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
Để xóa hình ảnh, bạn làm phương pháp HTTP POST tiêu chuân để xóa URL.
Đây là sự lệch nhẹ từ thực hành REST tiêu chuẩn để xử lý thực tế mà nhiều thư viện khách hàng HTTP không hỗ trợ động từ HTTP DELETE trong khi tránh sự lộn xộn có nhiều cách làm cùng một việc.
|
Các tham số |
|
|---|---|
| imageId |
Được đính kèm trong URL
Bạn sẽ cần phải chèn giá trị |
|
Các Thuộc Tính Phản Hồi |
|
|---|---|
| image |
Image JSON Object bị xóa. |
Hãy dùng thử
Người dùng = id API, Hộ chiếu = Bí mật API
cURL
$ curl "https://clippingmagic.com/api/v1/images/2346/delete" \ -u 123:[secret] \ -X POST
Example Response
{
"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
Lấy thông tin cơ bản về tài khoản của bạn như tình trạng đăng ký và số điểm còn lại của bạn.
|
Các tham số |
|
|---|---|
| Không Có | |
|
Các Thuộc Tính Phản Hồi |
|
|---|---|
| subscriptionPlan |
Gói đăng hiện mà hiện nay bạn được đăng ký cho hoặc 'không'/. |
| subscriptionState |
Tình trạng đăng ký hiện nay của bạn ('hoạt động hoặc 'Quá hạn') hoặc đã kết thúc nếu không có đăng ký. |
| credits |
Số điểm API còn lại trong tài khoản của bạn. 0 nếu hiện tại không có đăng ký hoặc đã đăng ký chương trình không phải API. |
Hãy dùng thử
Người dùng = id API, Hộ chiếu = Bí mật API
cURL
$ curl "https://clippingmagic.com/api/v1/account" \ -u 123:[secret]
Example Response
{
"subscriptionPlan" : "none",
"subscriptionState" : "ended",
"credits" : 0
}