API 文書

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

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

セキュリティ:すべてのリクエストは HTTPS で行い、すべてのリクエストは認証しなければなりません。 リクエストを正しく行うには、http クライアントライブラリは、サーバー名表示(SNI) に対応している必要があります。 おかしなハンドシェークエラーが発生する場合、大抵これが原因となっています。

試してください

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

エラー JSON オブジェクト

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

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

属性

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

エラー応答の例

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

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

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

HTTP Status意味
200-299

成功

301-303

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

400-499

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

500-599

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

画像 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 ファイルアップロードを行います。コンテンツタイプmultipart/form-data でなければならないことに注意してください

属性

image

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

最大画像サイズは、8,388,608ピクセルで、4,194,404ピクセルに圧縮されます。 アップロードする前に後者のサイズまたはより小さいサイズに画像を予め圧縮してください。

オプション
test

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

応答属性

image

画像 JSON オブジェクト。

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

試してください

Username = API Id, Password = API Key

cURL

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

「example.jpg」があることを想定しています。適当に置き換えてください。

応答の例

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

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

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

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

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

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

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

引数

image_id

URL に組み込み

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

オプション
format

デフォルトで、結果画像が返されます。しかしながら、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/[image_id]/delete

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

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

引数

image_id

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
}