すべての API リクエストは、REST スタイルの URL への標準 HTTP リクエストです。 応答は、JSON、または画像（結果を取得する場合）。
API は、標準の HTTP 基本アクセス認証を使用します。 API へのすべてのリクエストには、API Id をユーザーとして、API シークレットをパスワードとする API 資格情報を含める必要があります。 ClippingMagic.js は、API シークレットをユーザーに明かさないよう、API Id のみを使用します。
すべてのリクエストは HTTPS で行い、すべてのリクエストは認証しなければなりません。
リクエストを正しく行うには、http クライアントライブラリは、サーバー名表示（SNI） に対応している必要があります。 おかしなハンドシェークエラーが発生する場合、大抵これが原因となっています。
すべてのアップロードおよびダウンロード作業はバックエンドで行われますが、すべてのレビューおよび編集作業はスマートエディターで行われることに注意してください。
この分割は、API キーを保護すると共に、お客様のサイトにおけるシームレスなエンドユーザーエクスペリエンスを可能にします。
API の使用には帯域制限がありますが、割当量には余裕があり、API クレジット以外の固定された上限値があるわけではありません。
通常のエンドユーザー操作では使用方法に緩急があるのが常なので、ユーザー側で帯域制限を意識することはなく、サービスは円滑に処理されます。
ただし、バッチジョブでは最大 5 スレッドから始め、お望みの並列処理数に達するまで 5 分ごとに 1 新規スレッドを追加することをお奨めします。 100 同時スレッドを超える処理を必要とする場合は、作業開始前にご連絡ください。
あまりにも多くのリクエストを提出すると、429 Too Many Requestsのレスポンスが返されます。 これが発生したら、リニアバックオフを適用してください。すなわち、最初のレスポンスが返った後、次のリクエストの提出まで 5 秒間待ちます。 引き続き 2 回目の 429 レスポンス発生の場合、次のリクエストの提出まで 2*5=10 秒間待ちます。 3 回目は、 3*5=15 秒待ちます（以下同様）。
バックオフカウンターは、リクエストが正しく完了した後リセットできます。バックオフはスレッドごとに適用してください（すなわち、スレッドは相互に独立に操作する）。
当社は、API リクエストの成功または失敗を示すのに、従来の HTTP ステータスを使用し、返されるエラー JSON オブジェクトに重要なエラー情報を含めています。
当社は、問題のあるリクエストには、必ずエラー JSON オブジェクトを返すように努めています。 しかしながら、理論的には常に、内部サーバーの障害により、JSON 以外のエラーレスポンスが返される可能性があります。
|
属性 |
|
|---|---|
| status | 応答の HTTP ステータスをここに再掲されるのでデバッグに役立ててください。 |
| code | Clipping Magic 内部エラーコード。 |
| message | 人間が読みやすいエラーメッセージ、デバッグに役立ててください。 |
リクエストに対する HTTP ステータスが 200 の場合、JSON オブジェクトが返されず、リクエストは概して言えば正しく処理されたと想定することができます。
HTTP クライアントライブラリによっては、HTTP ステータスの例外を 400～599 の範囲で上げてきます。 それら例外を捕捉して、適切に処理する必要があります。
| HTTP Status | 意味 |
|---|---|
200-299
|
成功 |
400-499
|
リクエストで提供された情報に問題があります（パラメータの欠如など）。 エラーメッセージを確認して、修正方法を考えてください。 |
500-599
|
Clipping Magic 内部エラーが発生しました。 少し待ってやり直してください。問題が続くようでしたら、メールでお問い合わせください。 |
デバッグに役立てられるよう、最近の API エラーはアカウントページに記載されています。
エラー応答の例
{
"error" : {
"status" : 400,
"code" : 1006,
"message" : "Failed to read the supplied image. "
}
}
画像レコードは、JSON オブジェクトで統一的に表され、いくつかの API アクションによって返されます。
|
属性 |
|
|---|---|
| id |
画像の一意の識別子。 ユーザーが画像の編集およびその結果のダウンロードを行うのに必要なもの。 |
| secret |
この画像を |
| resultRevision |
ダウンロードできる最新版を示す整数（0 = まだ結果がない）。 この画像について、以前にダウンロードしたものより新しい結果があるかどうかを判断することができます。 |
| originalFilename |
元の画像をアップロードする場合に提供されるファイル名を含むストリング。 |
| test |
|
例
{
"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 でなければならないことに注意してください。
|
パラメータ |
|||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
入力画像は、以下のいずれかでなければなりません。
.bmp、.gif、.jpeg、.png または .tiff ファイルでなければなりません。
最大画像アップロードサイズ（= 幅 × 高さ）は、33,554,432 ピクセルで、以下の |
|||||||||||||||
|
test
ブーリアン true、false
|
これが試験用画像であることを示すため、
実際の画像向けには、省略するか、 試験画像は、自由に処理できますが、結果にはウォーターマークが組み込まれます。 |
||||||||||||||
|
format
列挙型 json、result、clipping_path_svg、clipping_path_tiff、alpha_mask_png
|
JSON 以外の結果を取得した場合、 画像 JSON オブジェクトの取得ではアカウントに課金されません。課金されるのは、運営用結果をダウンロードするときだけです。 |
||||||||||||||
|
maxPixels
整数 1000000 から 26214400
|
アップロード後に画像のサイズ変更をする場合、使用される最大画像サイズ（= 幅 × 高さ）を変更します。 デフォルト：4,194,404 ピクセル |
||||||||||||||
|
background.color
#RRGGBB #0055FF
|
透明の背景と PNG 結果を使用するには省略します。 指定色の不透明背景と output.opaqueFileFormat 結果（デフォルト JPEG）を使用するには含めてください。 「#」を含めてください。 |
||||||||||||||
|
処理パラメータを設定：
|
|||||||||||||||
|
色レベルを設定：
|
|||||||||||||||
|
緑のスクリーンなどにより、前景への色かぶりを発生させている色を背景から除去するよう設定：
|
|||||||||||||||
|
ホワイトバランスを設定：
|
|||||||||||||||
|
仕上げの設定： |
|||||||||||||||
|
エッジパラメータを設定：
|
|||||||||||||||
|
|||||||||||||||
|
結果のサイズとアスペクト比を制御：
|
|||||||||||||||
|
出力オプションを制御：
|
|||||||||||||||
サブスクリプションなしでも、試験モードで画像をアップロードすることができます。 ただし、アップロードにはクレジットを要しませんが、実際の運用画像を API 経由でアップロードするには、有効な API サブスクリプションが必要となります。
試してください
ユーザー名 = 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 を行います。 結果が、すでに生成されている必要があります。
試験結果は自由にダウンロードできますが、ウォーターマークが入っています。 運用版の結果をダウンロードするには、初回に 1 クレジットが課金されますが、その後のダウンロードは無料です。
結果がない場合、エラー応答が返されます。
|
パラメータ |
|
|---|---|
| imageId |
URL に組み込み
アップロード呼び出しで返された値を |
|
オプション
format |
その代わり、
その代わり、
その代わり、
画像 JSON オブジェクトの取得ではアカウントに課金されません。課金されるのは、運営用結果をダウンロードするときだけです。 |
|
応答ヘッダー
|
|
|---|---|
x-amz-meta-id
Example: 2346
|
画像の |
x-amz-meta-secret
Example: image_secret1
|
画像の |
x-amz-meta-resultrevision
Example: 1
|
このリクエストで取得する 新たな結果が生成される度にこのカウンターが増加します。 |
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 |
結果を生成する場合に実際に使われる |
| 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 を行います。
多くの HTTP クライアントライブラリが HTTP DELETE 動詞をサポートしていない現実の中、同じことを行うのに複数の方法を提供する混乱を避けるため、これは、標準 REST プラクティスから少し逸脱した方法です。
|
パラメータ |
|
|---|---|
| imageId |
URL に組み込み
アップロード呼び出しで返された値を |
|
応答属性 |
|
|---|---|
| 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
}