サーバー API

すべての 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 秒待ちます(以下同様)。

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

エラー JSON オブジェクト

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

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

属性

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

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

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

HTTP Status意味
200-299

成功

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
バイナリ

バイナリファイル。

image.base64
文字列

base64 でエンコードされた文字列。

image.url
文字列

フェッチするための URL。

.bmp、.gif、.jpeg、.png または .tiff ファイルでなければなりません。

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

test
ブーリアン
truefalse

これが試験用画像であることを示すため、trueを渡します。

実際の画像向けには、省略するか、falseを渡してください。

試験画像は、自由に処理できますが、結果にはウォーターマークが組み込まれます。

format
列挙型
jsonresultclipping_path_svgalpha_mask_png

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
整数
1000000 から 8388708

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

デフォルト:4,194,404 ピクセル

background.color
#RRGGBB
#0055FF

透明の背景を使用するには省略します。

「#」を含めてください。

処理パラメータを設定:

processing.mode
列挙型
autophotographics

画像に使用される処理モードを制御。

デフォルト:auto

processing.autoClip
ブーリアン
truefalse

ウェブアプリで画像を編集する際の自動クリップを有効化(デフォルト)または無効化。

API 経由で画像をアップロードした後、明白な前景(該当する場合)以外を自由形式でトリミングしたい場合に無効化してください。

デフォルト:true

色レベルを設定:

colors.auto
ブーリアン
truefalse

色レベルを時戸津的に調整し、コントラストを強化します。

デフォルト: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
ブーリアン
truefalse

前景から除去するため、背景色を自動的に決定。

デフォルト:false

colorCast.color
#RRGGBB
#A84400

前景から除去するため、背景色を手動で指定。

自動検出の場合は省略。

colorCast.foregroundGuard
浮動
0.0 から 20.0

値を大きくすると、かぶり色に近い真正の前景色からの色かぶり除去効果を低減しますが、除去された色より彩度が高くなります。

デフォルト:4.0

ホワイトバランスを設定:

whiteBalance.auto
ブーリアン
truefalse

ホワイトバランスを実施するために使用する基準色を自動的に決定します。

デフォルト: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
ブーリアン
truefalse

コーナーガードを使用(デフォルト)または無効化。

edges.smoothing
列挙型
smartfixed

smart(デフォルト)またはfixedスムージングを使用。

edges.smoothingLevel
浮動
0.0 から 5.0

結果に適用されるスムージング量を設定。

デフォルト 1.0

edges.feathering
列挙型
fixedautolocal

auto(デフォルト)、local、または fixedフェザリングを使用。

edges.featheringRadiusPx
浮動
0.0 から 6.0

結果に適用されるフェザリング量を設定。

デフォルト:1.0

edges.offsetPx
浮動
0.0 から 10.0

結果に適用される境界オフセットを設定。

デフォルト:0.0

出力を結果に適応させる

fit.toResult
ブーリアン
truefalse

結果に適応をオンまたはオフ(デフォルト)にします。

オフの場合、このセクションの残りのパラメータは実質的に無効となります。

fit.paddingPercent
浮動
0.0 から 35.0

結果サイズのパーセンテージとして適用される適応結果周囲の隙間。

デフォルト:5.0

fit.paddingPixels
整数
0 から 250

適応結果周囲に適用されるピクセルで表示される隙間。

指定されない場合、パーセントによる隙間が使用されます。

fit.objectSize
列挙型
smallmediumlarge

オブジェクトの合成サイズを指定することができます。 これは、買い物客に製品の大まかなサイズを他の製品との比較で示したい E コマースなどでは便利です。

デフォルト:large(= 結果にはサイズ調整が含まれません)

fit.verticalAlignment
列挙型
topmiddlebottom

縦のスペースが超過している場合、結果をどのように調整するかを指定します。

また、アスペクト比または強制的ターゲットサイズなどにより超過スペースを分散させる場合も適用されます。以下を参照してください。

デフォルト:middle

fit.shadows
列挙型
ignorepadtight

影を無視すること、影に合わせて両側に均等にパッドを設定すること、あるいは、影を切り取らないよう必要な場所にのみパッドを当てがいタイトに設定することもできます。

デフォルト: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
ブーリアン
truefalse

結果が入力画像より大きくなっても良いかどうかを制御します。

デフォルト:false

出力オプションを制御:

output.dpi
整数
1 から 4000

結果に組み込まれる DPI 情報を設定。

結果がウェブ最適化されている場合、DPI 情報は含まれません。

デフォルト:72

output.colorSpace
列挙型
sRGBAdobeRGBAppleRGBColorMatchRGB

結果に組み込まれる色スペース情報を設定。

結果がウェブ最適化されている場合、色スペース情報は含まれません。

デフォルト:sRGB

output.jpegQuality
整数
1 から 100

JPEG 結果を生成する場合に使われる品質設定を指定します。

デフォルト:75

output.pngOptimization
列挙型
nonelosslesslossy

PNG 結果のウェブ最適化を設定。

デフォルト:lossless

output.jpegOptimization
列挙型
noneenabled

JPEG 結果のウェブ最適化を設定。

デフォルト:enabled

output.opaqueFileFormat
列挙型
jpegpng

不透明な結果に使用されるファイルフォーマットを設定。

デフォルト: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

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 を行います。 結果が、すでに生成されている必要があります。

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

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

パラメータ

imageId

URL に組み込み

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

オプション
format

format=result(デフォルト)結果画像を取得します。

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

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

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

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

応答ヘッダー

formatjson でない場合、これら HTTP 応答ヘッダーに主要情報を提供します。

x-amz-meta-id
Example: 2345

画像の id

x-amz-meta-secret
Example: image_secret

画像の 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''image_clipped_rev_0.png

拡張子を含む結果ファイル名。

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
}