取得 API 金鑰

伺服器 API

所有 API 請求均爲發送至 REST 樣式 URL 的標準 HTTP 請求。 回應或者為 JSON，或者為圖像（正在擷取結果時）。

驗證

API 使用標準的 HTTP 基本存取驗證。 所有 API 請求均需要包含您的 API 憑證（使用者為 API ID，密碼為 API 機密）。 請注意，爲了不向您的使用者顯示您的 API 機密，ClippingMagic.js 僅使用您的 API ID。

安全性

所有請求必須使用 HTTP，並且您必須驗證所有請求。

您的 HTTP 用戶端程式庫必須支援伺服器名稱指示（SNI），方可成功提交要求。 若您收到奇怪的交握錯誤，很可能是這個原因。

後端 vs 前端

請注意，所有上傳和下載操作均在後端發生，但所有審閲和編輯操作在智慧編輯器中發生。

此分割可保護您的 API 金鑰，同時實現您網站上的無縫終端使用者體驗。

速率限制

API 使用速率限制寬鬆，無超出 API 點數的固定上限。

在標準終端使用者驅動型操作過程中，由於使用量呈服務可輕鬆應對的起伏傾向，您不太可能會遇到任何速率限制。

但我們建議您在批次工作時，最多以 5 個執行緒開始，每 5 分鐘增加 1 個新的執行緒，直至達到您想要的平行處理原則。 若您需要的並行執行緒超過 100 個，請在開始前與我們連絡。

若您提交的請求過多，會收到429 Too Many Requests的回應。 這種情況下，您應當應用線性停止：第一次收到此回應時，等待 5 秒鐘，再提交下一個請求。 連續第二次收到 429 回應時，等待 2*5=10 秒鐘，再提交下一個請求。 第三次等待 3*5=15 秒鐘，依此類推。

您可以在一個成功請求后重設停止計數器，並且應當應用以每個執行緒為基礎的停止（亦即各執行緒應當相互獨立運作）。

錯誤 JSON 物件

我們使用常設 HTTP 狀態標示 API 請求成功與否，並在傳回的錯誤 JSON 物件中包含重要的錯誤資訊。

我們力圖為所有有問題的請求均返回錯誤 JSON 物件。 但理論上總是有可能出現内部伺服器失敗，從而導致非 JSON 錯誤回應。

屬性
status在此處重複回應的 HTTP 狀態，以協助偵錯。
codeClipping Magic internal error code.
message人類看得懂的錯誤訊息，適合協助偵錯。

若您的請求的 HTTP 狀態為 200，則不會傳回錯誤 JSON 物件，並且您可安全無虞地假設此請求在廣義上已成功。

一些 HTTP 用戶端程式庫會為 400599 範圍内的 HTTP 狀態引發例外。 您需要捕捉此類例外，並適當地處理。

HTTP Status含義
200-299

成功
400-499

請求中提供的資訊有問題（例如缺失一個參數）。 請檢閲錯誤訊息，以瞭解如何修正此問題。

500-599

There's been a Clipping Magic internal error. 請稍後再重試，若問題持續，請向我們發送電郵。

最近的 API 錯誤會列在您的帳戶頁面上，以便進行調試。

錯誤回應範例

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

圖像 JSON 物件

圖像記錄以有 JSON 物件的統一方式代表，由數個 API 動作傳回。

屬性
id

圖像的唯一識別碼 用於讓使用者編輯圖像並下載結果。

secret

用 ClippingMagic.js 編輯此圖像所需的秘密金鑰
resultRevision

整數表示有可供下載的最新修訂（0 = 尚無結果）。

可讓您決定此圖像是否有比您已下載的結果更新的結果。

originalFilename

包含上傳原始圖像時提供的檔案名的字串。

test

true表示這是一個測試圖像，可免費處理，但結果會加上浮水印。

false表示這是一個正式圖像，處理需要點數，但結果不會加上浮水印。

範例

{
  "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 文件上傳。 此端點必須從您的後端呼叫，無法從您的網頁 JavaScript 呼叫。 請記住，上傳二進位檔案時内容-類型必須爲multipart/form-data。

參數

輸入圖像必須以下列格式之一提供：

image
二進位

一個二進位檔案。

image.base64
字串

一個 Base64 編碼字串。 字串大小不得超過 1百萬像素。

image.url
字串

一個可擷取的 URL。

必須爲 .bmp、.gif、.jpeg、.png 或 .tiff 檔案。

上傳圖像大小的上限（=寬×高）為 33,554,432像素，會縮小為 4,194,404像素，除非由下方的maxPixels覆寫。 上傳之前，請先把您的圖像縮小為後一種大小或者更小。

test
布林值
true、false

傳入true來表示這是一個測試圖像。

為生產圖像省略或傳入false。

測試圖像可免費處理，但結果會内嵌浮水印。

format
列舉
json、result、clipping_path_svg、clipping_path_tiff、alpha_mask_png

format=json（預設）：不會產生自動剪裁結果，並傳回圖像 JSON 物件。 有人工檢閲並可能使用 ClippingMagic.js 修整裁剪時可使用此參數。

format=result會產生並擷取自動剪裁結果。

format=clipping_path_svg會產生自動剪裁結果，並擷取裁剪路徑（SVG）。

format=clipping_path_tiff會產生自動剪裁結果，並擷取裁剪路徑（TIFF）。

format=alpha_mask_png會產生自動剪裁結果，並擷取 Alpha 遮罩（PNG）。 Alpha 遮罩與輸入圖像大小相同。 由於邊緣防護和光環清除程式改進邊界色彩，將其應用於輸入圖像不會爲您取得結果。

擷取非 JSON 結果時，id 和secret會在 x-amz-meta-id 和 x-amz-meta-secret 標頭中傳回。 請務必對其加以儲存，以使用 ClippingMagic.js 檢視和編輯結果。 檢視回應中包含的所有標頭

擷取圖像 JSON 物件不會向您的帳戶收取費用；僅當下載正式結果時才會向您收費。

maxPixels
整數
1000000 至 26214400

上傳后調整圖像大小時變更使用的圖像大小上限（=寬×高）。

預設：4,194,404像素

background.color
#RRGGBB
#0055FF

省略以使用一個透明背景或者取得一個 PNG 結果。

包含以取得一個指定色彩的不透明背景和一個 output.opaqueFileFormat 結果（預設為 JPEG）。

請務必包含 '#'。

預設處理參數：

processing.mode
列舉
auto、photo、graphics、scan

控制爲您的圖像使用的處理模式。

預設：auto

processing.autoClip
布林值
true、false

在 Web 應用程式中編輯圖像時啟用（預設）或停用自動裁剪。

若想透過 API 上傳圖像則停用，但進行除了明顯的前景之外的任意格式裁剪（如有）。

預設：true

processing.autoHair
布林值
true、false

啟用（預設）或禁用自動頭髮遮罩。

預設：true

processing.allowGraphicsMode
布林值
true、false

啟用（預設）或禁用圖形模式的自動選中。

當format=json時此設定不適用。

預設：true

processing.allowScanMode
布林值
true、false

啟用（預設）或禁用掃描模式的自動選中。

當format=json時此設定不適用。

預設：true

預設色彩等級：

colors.auto
布林值
true、false

自動調整色彩等級以增強對比度。

預設：false

colors.brightness
整數
-100 至 100

調整輸出圖像的亮度。

預設：0

colors.shadows
整數
-100 至 100

調整輸出圖像的陰影。 正值表示較深的陰影。

預設：0

colors.highlights
整數
-100 至 100

調整輸出圖像的反白顯示。 正值表示較淺的反白顯示。

預設：0

colors.temperature
整數
-100 至 100

調整輸出圖像的色溫。 正值表示較暖的色彩。

預設：0

colors.saturation
整數
-100 至 100

調整輸出圖像的飽和度。 正值表示較多的飽和度。

預設：0

預設從背景投射到前景上的色彩移除，例如使用綠屏：

colorCast.auto
布林值
true、false

自動確定從前景移除的背景色彩。

預設：false

colorCast.color
#RRGGBB
#A84400

手動指定的從前景移除的背景色彩。

省略以自動偵測。

colorCast.foregroundGuard
浮點數
0.0 至 20.0

較大的值會降低色彩色調修正移除對與投射色彩相似、但較正被移除的色彩飽和度更高的真正前景色彩的影響。

預設：4.0

預設白平衡：

whiteBalance.auto
布林值
true、false

自動確定調整白平衡所使用的參照色彩。

預設：false

whiteBalance.color
#RRGGBB
#968386

手動指定的白平衡色彩。

省略以自動偵測。

預設最後修飾：

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

為裁剪結果新增一個延伸陰影。

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

為裁剪結果新增一個反射效果。

預設邊緣參數：

edges.corners
布林值
true、false

使用（預設）或停用角點防護。

edges.smoothing
列舉
smart、fixed

使用smart（預設）或fixed平滑化。

edges.smoothingLevel
浮點數
0.0 至 5.0

預設為結果應用的平滑化程度。

預設為 1.0

edges.feathering
列舉
fixed、auto、local

使用auto（預設）、local或fixed羽化。

edges.featheringRadiusPx
浮點數
0.0 至 6.0

預設為結果應用的羽化程度。

預設：1.0

edges.offsetPx
浮點數
0.0 至 10.0

預設為結果應用的邊界位移。

預設：0.0

將輸出調整成結果大小

fit.toResult
布林值
true、false

開啟或關閉（預設）調整成結果大小。

若爲關閉狀態，這部分的其他參數實際上會被忽略。

fit.paddingPercent
浮點數
0.0 至 35.0

在調整後的結果周圍應用的填充，是結果大小的一個百分數。

預設：5.0

fit.paddingPixels
整數
0 至 250

在調整後的結果周圍應用的像素填充。

若未加指定，則會使用百分數填充。

fit.objectSize
列舉
small、medium、large

您可以為物件指定一個合成大小。 這非常適合電子商務，因爲您可能想讓購物者瞭解產品相對其他產品的大致大小。

預設：large（=結果未調整大小）

fit.verticalAlignment
列舉
top、middle、bottom

指定您的結果在有多餘垂直空間的情況下應如何對齊。

還適用於強制外觀比例或目標大小時多餘空間的分散，詳情如下。

預設：middle

fit.shadows
列舉
ignore、pad、tight

您可以忽略陰影，在兩側均匀填充以符合陰影大小，或者僅在必要處新增填充，以避免截斷陰影。

預設：pad

fit.rotationDeg
浮點數
-360.0 至 360.0

旋轉圖像。 正值表示逆時針。

預設：0

控制結果大小和外觀比例：

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

確定結果具備提供的外觀比例。

fit.verticalAlignment控制多餘垂直空間的分散方式。

預設：不應用

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

確定結果具備提供的大小。

fit.verticalAlignment控制多餘垂直空間的分散方式。

預設：不應用

result.allowEnlarging
布林值
true、false

控制是否允許結果較輸入圖像更大。

預設：false

控制輸出選項：

output.dpi
整數
1 至 4000

設定結果中嵌入的 DPI 資訊。

若結果經過 Web 最佳化，則不包含 DPI 資訊。

預設：72

output.colorSpace
列舉
sRGB、AdobeRGB、AppleRGB、ColorMatchRGB

設定結果中嵌入的色彩空間資訊。

若結果經過 Web 最佳化，則不包含色彩空間資訊。

預設：sRGB

output.jpegQuality
整數
1 至 100

預設產生 JPEG 結果時使用的質量設定。

預設：75

output.pngOptimization
列舉
none、lossless、lossy

預設 PNG 結果的 Web 最佳化。

預設：lossless

output.jpegOptimization
列舉
none、enabled

預設 JPEG 結果的 Web 最佳化。

預設：enabled

output.opaqueFileFormat
列舉
jpeg、png

預設為不透明結果使用的檔案格式。

預設：jpeg

您無需訂閲，即可在測試模式中上傳圖像。 但儘管上傳無需點數，您仍然需要有效的 API 訂閲，方可透過 API 上傳正式圖像。

歡迎嘗試

格式：'#RRGGBB'
格式：'#RRGGBB'
格式：'#RRGGBB'

格式：'[xOffsetPx:int] [yOffsetPx:int] [blurRadiusPx:int, 0 to 75] [opacity:float, 0 to 1]'
範例：30 30 25 0.75

格式：'[yOffsetPx:int, 0 to 400] [heightPx:int, 0 to 800] [opacity:float, 0 to 1]'
範例：0 200 0.5

格式：'[width:float, >0]:[height:float, >0]'
範例：4:3

格式：'[width:int, >0] [height:int, >0]'
範例：400 300

使用者名稱 = 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

您需要插入此上傳呼叫傳回的 id 值。

可選
format

format=result（預設）擷取結果圖像。

format=clipping_path_svg 則會擷取裁剪路徑（SVG）。

format=clipping_path_tiff 則會擷取裁剪路徑（TIFF）。

format=alpha_mask_png 會擷取 Alpha 遮罩（PNG）。

format=json 會擷取圖像 JSON 物件。 您想檢查 resultRevision 或者丟失了圖像密碼時會很有用。

擷取圖像 JSON 物件不會向您的帳戶收取費用；僅當下載正式結果時才會向您收費。

回應標頭

當format不是json時，我們在這些 HTTP 回應標頭中提供重要資訊

x-amz-meta-id
Example: 2346

您的圖像的id。

x-amz-meta-secret
Example: image_secret1

您的圖像的secret。

x-amz-meta-resultrevision
Example: 1

您透過此要求正在擷取的resultRevision。

每次產生新結果時，此計數器均會遞增。

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

產生結果時實際使用的limit。

offset

產生結果時實際使用的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

如欲刪除圖像，您需要對圖像刪除 URL 執行標準 HTTP POST。

這稍微偏離標準 REST 作法，用於處理許多 HTTP 用戶端程式庫不支援 HTTP DELETE 動詞命令的現實，同時避免用多個方法做同一件事的問題。

參數
imageId

嵌入 URL

您需要插入此上傳呼叫傳回的 id 值。

回應屬性
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 積分數量。 如果目前尚未訂閱或訂閱非 API 計劃，則為 0。

歡迎嘗試

使用者名稱 = API ID，密碼 = API 秘密

cURL

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

範例回應

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