托管智慧編輯器

將 Clipping Magic 智慧編輯器整合入您的自設工作流程的最便捷的方式。

整合步驟

請務必首先閲讀快速啟動

  1. 使用伺服器 API 上傳一個圖像。

  2. 建立一個托管智慧編輯器 URL,並將其提供給裁剪您指定的圖像的真人操作者。

  3. 裁剪所有圖像後,您的真人操作者的瀏覽器將巡覽至指定的傳回 URL,並顯示一個包含裁剪工作階段相關資訊的 HTTP POST。

如果您需要一個白標解決方案或每個已裁剪圖像的回呼,請參閱白標智慧編輯器

托管智慧編輯器 URL https://clippingmagic.com/api/v1/hosted/[apiId]

您可以建立一個簡單的 URL,供您的真人操作者在其瀏覽器中開啟,以審閲並編輯您的一個或多個圖像。

托管智慧編輯器 URL 支援以下參數:

images
id1:secret1,id2:secret2,...
123:abc,456:def
必要項

供剪裁的圖像。 以逗號分隔的 id:secret組清單。 適用於您使用伺服器 API 上傳圖像的情況。

returnUrl
字串
必要項

您的真人操作者完成了剪裁後,其瀏覽器會發出 HTTP POST 至此 URL。 請參閲下方細節。

useStickySettings
布林值
truefalse

若您傳入 useStickySettings=true,編輯器將使用其 API 金鑰用於上傳該圖像的使用者的當前自設自黏設定。

如此您就可以自設基本剪裁設定一次,然後將其套用到您編輯的所有圖像。

Read about how to configure the sticky settings

預裁剪在 API 中無法使用,但您可以在 API 的上傳呼叫中設定圖像大小限制。

locale
字串

編輯器使用的顯示語言。若省略,預設為英文。有效值為:

代碼顯示語言
en-US English (英文)
de-DE Deutsch (德文)
es-ES Español (西班牙文)
fr-FR Français (法文)
hi-IN हिन्दी (印地文)
id-ID Indonesia (印尼文)
it-IT Italiano (義大利文)
ja-JP 日本語 (日文)
ko-KR 한국어 (韓文)
pl-PL Polski (波蘭文)
pt-BR Português (葡萄牙文)
ru-RU Русский (俄文)
th-TH ไทย (泰文)
tr-TR Türkçe (土耳其文)
vi-VN Tiếng Việt (越南文)
zh-Hans-CN 简体中文 (中文)
zh-Hant-TW 繁體中文 (中文)

新式瀏覽器允許很長的 URL,但若您需要支援舊版瀏覽器並在一個工作階段中剪裁超過 30 個圖像,則可以透過 POST 而非直接連結進行提交。

單圖像 URL 範例


https://clippingmagic.com/api/v1/hosted/123?images=2345:image_secret&returnUrl=https%3A%2F%2Fclippingmagic.com%2Fapi%2FreturnUrlExample

指定單個圖像時,編輯器沒有「跳過」按鈕,並且不會顯示剩餘的待剪裁圖像數。

多圖像 URL 範例


https://clippingmagic.com/api/v1/hosted/123?images=2345:image_secret,2346:image_secret2&returnUrl=https%3A%2F%2Fclippingmagic.com%2Fapi%2FreturnUrlExample

指定多個圖像時,編輯器有「跳過」按鈕,並且顯示剩餘的待剪裁圖像數。

傳回 URL

您的真人操作者完成剪裁後,其瀏覽器會發出 HTTP POST 至您指定的傳回 URL。 該 POST 會包含一個單一參數:clippingMagicJson。 當您解析該參數的内容時,其會拆包至一個包含哪些圖像已剪裁的資訊的 JSON 物件。 您即可透過使用,下載現在可用的結果。

event
列舉
editor-exiterror

editor-exit表示裁剪工作階段成功結束。

error表示出現錯誤,並且下方的error被填充。

images
[{"id":1,"secret":"secret1"},{"id":2,"secret":"secret2"},{"id":3,"secret":"secret3"},{"id":4,"secret":"secret4"}]
含托管智慧編輯器 URL 中所提供圖像的陣列。
clipped
[{"id":1,"secret":"secret1"},{"id":2,"secret":"secret2"}]
含此工作階段中實際剪裁圖像的陣列,即真人操作者在編輯器中按下了「完成」的圖像。
skipped
[{"id":3,"secret":"secret3"},{"id":4,"secret":"secret4"}]
含此工作階段中跳過的圖像的陣列,即真人操作者在編輯器中按下了「跳過」的圖像。

event=error,則將有使用以下填充的error成員物件:

error.status
整數
類似 HTTP 狀態的代碼。 4xx表示一個呼叫端錯誤。 5xx表示一個内部伺服器錯誤。
error.code
整數
發生錯誤的唯一識別數字。
error.message
字串
描述發生的錯誤的人類看得懂的錯誤訊息。

您將需要停用所有 CSRF 檢查,或者將 CSRF 權杖添加至傳回 URL,POST 方可成功。

若您的真人操作者關閉其瀏覽器,或者您使用一個不可解析的托管智慧編輯器 URL,則您的傳回 URL 不會被呼叫。

成功範例 clippingMagicJson解碼至:
{
  "event" : "editor-exit",
  "images" : [ {
    "id" : 2345,
    "secret" : "image_secret"
  }, {
    "id" : 2346,
    "secret" : "image_secret2"
  } ],
  "clipped" : [ {
    "id" : 2345,
    "secret" : "image_secret"
  }, {
    "id" : 2346,
    "secret" : "image_secret2"
  } ],
  "skipped" : [ ]
}
測試您的傳回 URL
錯誤範例 clippingMagicJson解碼至:
{
  "event" : "error",
  "error" : {
    "status" : 400,
    "code" : 1234,
    "message" : "Example error"
  },
  "images" : [ {
    "id" : 2345,
    "secret" : "image_secret"
  }, {
    "id" : 2346,
    "secret" : "image_secret2"
  } ],
  "clipped" : [ ],
  "skipped" : [ {
    "id" : 2345,
    "secret" : "image_secret"
  }, {
    "id" : 2346,
    "secret" : "image_secret2"
  } ]
}
測試您的傳回 URL