API 文書

すべての API リクエストは、REST スタイルの URL への標準 HTTP リクエストです。 応答は、JSON、または画像(結果を取得する場合)。

認証

API は、標準の HTTP 基本アクセス認証を使用します。 API へのすべてのリクエストには、API Id をユーザーとして、API キーをパスワードとする API 資格情報を含める必要があります。 ClippingMagic.js は、API キーをユーザーに明かさないよう、API Id のみを使用します。

セキュリティ

すべてのリクエストは HTTPS で行い、すべてのリクエストは認証しなければなりません。

リクエストを正しく行うには、http クライアントライブラリは、サーバー名表示(SNI) に対応している必要があります。 おかしなハンドシェークエラーが発生する場合、大抵これが原因となっています。

バックエンド対フロントエンド

すべてのアップロードおよびダウンロード作業はバックエンドで行われますが、すべてのクリップ作業は ClippingMagic.js を使ってウェブクライアント(フロントエンド)で行われることに注意してください。

この分割は、API キーを保護すると共に、お客様のサイトにおけるシームレスなエンドユーザーエクスペリエンスを可能にします。

帯域制限

API の使用には帯域制限がありますが、割当量には余裕があり、API クレジット以外の固定された上限値があるわけではありません。

通常のエンドユーザー操作では使用方法に緩急があるのが常なので、ユーザー側で帯域制限を意識することはなく、サービスは円滑に処理されます。

ただし、バッチジョブでは最大 5 スレッドから始め、お望みの並列処理数に達するまで 5 分ごとに 1 新規スレッドを追加することをお奨めします。 100 同時スレッドを超える処理を必要とする場合は、作業開始前にご連絡ください。

あまりにも多くのリクエストを提出すると、429 Too Many Requestsのレスポンスが返されます。 これが発生したら、リニアバックオフを適用してください。すなわち、最初のレスポンスが返った後、次のリクエストの提出まで 5 秒間待ちます。 引き続き 2 回目の 429 レスポンス発生の場合、次のリクエストの提出まで 2*5=10 秒間待ちます。 3 回目は、 3*5=15 秒待ちます(以下同様)。

バックオフカウンターは、リクエストが正しく完了した後リセットできます。バックオフはスレッドごとに適用してください(すなわち、スレッドは相互に独立に操作する)。

試してください

すべての API アクションには html 形式 / リンク例が付いているので、ブラウザーからすぐに試してみることができます。cURL 例は、ユーザー自身の API 資格情報を使用するので、サインアップしている場合、ご自分のターミナルに単にコピー・ペーストして実行することができます。

エラー JSON オブジェクト

当社は、API リクエストの成功または失敗を示すのに、従来の HTTP ステータスを使用し、返されるエラー JSON オブジェクトに重要なエラー情報を含めています。

当社は、問題のあるリクエストには、必ずエラー JSON オブジェクトを返すように努めています。 しかしながら、理論的には常に、内部サーバーの障害により、JSON 以外のエラーレスポンスが返される可能性があります。

属性

status応答の HTTP ステータスをここに再掲されるのでデバッグに役立ててください。
codeClipping Magic 内部エラーコード。
message人間が読みやすいエラーメッセージ、デバッグに役立ててください。

リクエストに対する HTTP ステータスが 200 の場合、JSON オブジェクトが返されず、リクエストは概して言えば正しく処理されたと想定することができます。

HTTP クライアントライブラリによっては、HTTP ステータスの例外を 400599 の範囲で上げてきます。 それら例外を捕捉して、適切に処理する必要があります。

HTTP Status意味
200-299

成功

301-303

結果のダウンロード時:実際の結果ストレージ場所にリダイレクトされます。 エラー JSON オブジェクトが返されません。 結果をダウンロードする場合、HTTP クライアントライブラリを、リダイレクトに従うよう設定すべきです。

400-499

リクエストで提供された情報に問題があります(パラメータの欠如など)。 エラーメッセージを確認して、修正方法を考えてください。

500-599

Clipping Magic-内部エラーがありました。 少し待ってやり直してください。問題が続くようでしたら、メールでお問い合わせください。

エラー応答の例

{
  "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" : 2345,
  "secret" : "image_secret",
  "resultRevision" : 0,
  "originalFilename" : "image.jpg",
  "test" : false
}

アップロード POST https://clippingmagic.com/api/v1/images

画像をアップロードするには、標準 HTTP POST ファイルのアップロードを行います。 このエンドポイントは、バックエンドからコールしなければなりません。ウェブページの javascript からはコールできません。 コンテンツタイプ は、multipart/form-data でなければならないことに注意してください

パラメータ

image

アップロードする画像ファイル。.bmp、.gif、.jpeg、.png または .tiff ファイルでなければなりません。

最最大画像アップロードサイズ(= 幅 × 高さ)は、33,554,432 ピクセルで、以下の maxPixels で上書きされない限り、4,194,404 ピクセルに圧縮されます。 アップロードする前に後者のサイズまたはより小さいサイズに画像を予め圧縮してください。

オプション
test

これが試験用画像であることを示すため、trueを渡します。 試験画像は、自由に処理できますが、結果にはウォーターマークが組み込まれます。

オプション
format

format=json(デフォルト):自動クリップ結果は生成されず、画像 JSON オブジェクトが返されます。 人が検証して ClippingMagic.js でクリップの微修正を行う可能性がある場合は、これを使用してください。

format=result によって自動クリップ結果を生成し、取得できます。

format=clipping_path_svg によって自動クリップ結果を生成し、クリッピングパス(SVG)を取得できます。

format=alpha_mask_png によって自動クリップ結果を生成し、アルファマスク(PNG)を取得できます。 アルファマスクは、入力画像と同じサイズです。 エッジガードとハロースクラバーが境界の色を改善するので、これを入力画像に適用しても、改善された結果は得られません。

JSON 以外の結果を取得した場合、id および secretx-amz-meta-id および x-amz-meta-secret ヘッダーに返されます。 これらを保存して、ClippingMagic.js を使用して結果を検証し、編集できるようにしてください。

画像 JSON オブジェクトの取得ではアカウントに課金されません。課金されるのは、運営用結果をダウンロードするときだけです。

オプション
maxPixels

整数、最小:1,000,000 ピクセル、最大:8,388,708 ピクセル、デフォルト:4,194,404ピクセル。

アップロード後に画像のサイズ変更をする場合、使用される最大画像サイズ(= 幅 × 高さ)を変更します。

サブスクリプションなしでも、試験モードで画像をアップロードすることができます。 ただし、アップロードにはクレジットを要しませんが、実際の運用画像を API 経由でアップロードするには、有効な API サブスクリプションが必要となります。

試してください

Username = API Id, Password = API Key

cURL

$ curl https://clippingmagic.com/api/v1/images \
 -u 123:[secret] \ 
 -F 'image=@example.jpg' \ 
 -F 'test=true'

「example.jpg」があることを想定しています。適当に置き換えてください。 「test=true」の行はオプションです。

応答の例

{
  "image" : {
    "id" : 2345,
    "secret" : "image_secret",
    "resultRevision" : 0,
    "originalFilename" : "image.jpg",
    "test" : false
  }
}

ダウンロード GET https://clippingmagic.com/api/v1/images/[imageId]

結果をダウンロードするには、標準の HTTP GET を行います。 結果が、すでに生成されている必要があります。 通常これは、エンドユーザーがお客様のサイトで ClippingMagic.js を使って画像をクリップすることによって行われます

試験結果は自由にダウンロードできますが、ウォーターマークが入っています。 運用版の結果をダウンロードするには、初回に 1 クレジットが課金されますが、その後のダウンロードは無料です。

結果があれば、そこにリダイレクトされる(結果は、Amazon S3 に保存されます)ので、クライアントライブラリがリダイレクトに従えるよう設定してください。

x-amz-meta-resultrevision 応答ヘッダーは、ダウンロードされた結果の resultRevision を示し、Content-Disposition ヘッダーは、不透明の背景の結果については、拡張子 .jpeg、透明の背景の結果については、拡張子 .png を含む結果ファイル名を示します。

結果がない場合、エラー応答が返されます。

パラメータ

imageId

URL に組み込み

アップロード呼び出しで返された値を id に挿入する必要があります。

オプション
format

デフォルトで、結果画像が返されます。

その代わり、format=clipping_path_svg によってクリッピングパス(SVG)を取得できます。

その代わり、format=alpha_mask_png によってアルファマスク(PNG)を取得できます。

format=json が代わりに画像 JSON オブジェクトを取得します。 resultRevision を確認したい場合、または画像シークレットを紛失した場合に便利です。

画像 JSON オブジェクトの取得ではアカウントに課金されません。課金されるのは、運営用結果をダウンロードするときだけです。

Username = API Id, Password = API Key

cURL

$ curl https://clippingmagic.com/api/v1/images/2345 \
 -u 123:[secret] \ 
 -LOJ

JSON 応答の例

{
  "image" : {
    "id" : 2345,
    "secret" : "image_secret",
    "resultRevision" : 0,
    "originalFilename" : "image.jpg",
    "test" : false
  }
}

リスト GET https://clippingmagic.com/api/v1/images

画像 JSON オブジェクトのリストを取得するには、標準の HTTP GET を行います。

パラメータ

オプション
limit

取得レコード数。デフォルトは、20(最小 1、最大 100)。

オプション
offset

レコードリストに使用されるオフセット(デフォルトは 0)。

応答属性

images

画像 JSON オブジェクトの配列。

limit

結果を生成する場合に実際に使われる limit

offset

結果を生成する場合に実際に使われる offset

Username = API Id, Password = API Key

cURL

$ curl "https://clippingmagic.com/api/v1/images?limit=2&offset=0" \
 -u 123:[secret]

応答の例

{
  "images" : [ {
    "id" : 2345,
    "secret" : "image_secret",
    "resultRevision" : 0,
    "originalFilename" : "image.jpg",
    "test" : false
  }, {
    "id" : 2346,
    "secret" : "image_secret2",
    "resultRevision" : 0,
    "originalFilename" : "image.jpg",
    "test" : false
  } ],
  "limit" : 2,
  "offset" : 0
}

削除 POST https://clippingmagic.com/api/v1/images/[imageId]/delete

画像を消去するには、消去する URL に対して標準の HTTP POST を行います。

多くの HTTP クライアントライブラリが HTTP DELETE 動詞をサポートしていない現実の中、同じことを行うのに複数の方法を提供する混乱を避けるため、これは、標準 REST プラクティスから少し逸脱した方法です。

パラメータ

imageId

URL に組み込み

アップロード呼び出しで返された値を id に挿入する必要があります。

応答属性

image

削除された画像 JSON オブジェクト。

試してください

Username = API Id, Password = API Key

cURL

$ curl https://clippingmagic.com/api/v1/images/2345/delete \
 -u 123:[secret] \ 
 -X POST

応答の例

{
  "image" : {
    "id" : 2345,
    "secret" : "image_secret",
    "resultRevision" : 0,
    "originalFilename" : "image.jpg",
    "test" : false
  }
}

アカウント GET https://clippingmagic.com/api/v1/account

サブスクリプション状況やクレジット残数などのアカウントに関する基本的な情報を取得してください。

パラメータ

なし

応答属性

subscriptionPlan

現在サブスクライブしているプランまたは「なし」。

subscriptionState

現在のサブスクリプション状態(「アクティブ」または「期限切れ」)あるいは、サブスクライブしていない場合は「終了」。

credits

アカウントのクレジット残数。現在サブスクライブしていない場合は 0。

Username = API Id, Password = API Key

cURL

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

応答の例

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