What's New

最近の更新内容をご紹介いたします。

2019-04-24

  • ガウシアンぼかしを行うblurパラメータが追加されました。

2019-04-10

  • unsharpパラメータを指定する際に+を用いるとエラーとなっていた不具合を修正しました。
  • fパラメータにautoのみを指定した場合にエラーとなっていた不具合を修正しました。

2019-04-03

  • アンシャープマスクを行うunsharpパラメータが追加されました。

2019-03-27

  • パラメータの区切り文字として、,に加えて、これをパーセントエンコードした%2C(および%2c)が使用可能になりました。

2019-02-28

  • Exif JPEGにおいて、Orientationが指定されていた場合に、その指定に対応するように自動的に画像を回転するパラメータr=autoを追加しました。

2019-02-21

  • オーバーレイ合成時に重ねる画像を変換することができるようになりました。また、複数の画像を重ねられるようになりました。詳細はOverlayの項をご確認ください。

2019-01-30

  • 完全透過ピクセルを含む画像を拡大縮小する際、そのピクセルと周囲の不透過ピクセルとの間で意図しない混色が発生することを防ぐため、背景色が適用されているとみなして混色を行うよう変更しました。
  • (2019-02-05追記) 上記の変更に伴い発生していた、a=3指定時に指定したサイズにならない場合があった不具合、および、透過PNGを背景色指定なしで変換した場合に白い背景色が適用されてしまっていた不具合をそれぞれ修正しました。
  • (2019-02-06追記) 出力フォーマットがJPEGの場合にも、入力画像に完全透過ピクセルが含まれる場合は、背景色が適用されているとみなして混色を行うよう修正しました。

Getting started

ImageFluxの概要

ImageFluxは画像変換とコンテンツキャッシュを備えたクラウドサービスです。 エンドユーザからのリクエストをプロキシし、取得した画像をキャッシュ、変換して配信します。

ImageFluxでは画像を取得するエンドポイント(HTTPまたはS3プロトコルをサポートしています)のことをオリジンと呼びます。 オリジンごとには一つのホスト名が割り当てられます。 ホスト名は.imageflux.jpで終わるランダムな英数字です。 Webアプリケーションではこのホスト名と変換パラメータ、そしてコンテンツのパスを指定することで変換後の画像を利用することができます。

オリジンの追加

オリジンの設定を追加するには、管理コンソールのを選択します。 オリジンから画像を取得する方法にはHTTPとS3プロトコルがあります。

HTTP

nginxやApache HTTP Serverなどすでに公開している一般的なWebサーバをオリジンとして使用することができます。 指定するパラメータは以下の3つです。

項目 説明
Scheme オリジンからの取得に試用するHTTPスキーム (httpまたはhttps)
Host オリジンとして使用するHTTPサーバのホスト名
PathPrefix オリジンから取得する際にパスの先頭につけるプレフィックス文字列
たとえば /imagesと指定すると、オリジンから取得する際すべてのURLのパスに /imagesをつけてリクエストします。

S3

S3プロトコルはHTTPで公開していないAmazon S3バケットからの画像配信に利用できます。

画像パラメータの指定

ImageFluxのURLには画像変換のパラメータを指定することができます。 パラメータはURLの先頭に/c/もしくは/c!/をつけて指定します。 たとえば、幅200x200ピクセルのサムネイルを配信するには以下のように指定します。 パラメータ間の区切りには,を使用しますが、代替として%2C(もしくは%2c)も使用可能です。

https://demo.imageflux.jp/c/w=200,h=200/demo.jpg

パス毎のデフォルトパラメータ

オリジンの設定ではパス毎にパラメータを予め指定することができます。 これを利用すると、たとえば `/small/` では予め決められたサイズに縮小したサムネイルを配信する、といったことが実現できます。

画像変換パラメータ

拡大縮小

指定したパラメータに画像を拡大・縮小します。

Parameters
Key Value Type Default Description
w integer (なし) スケーリング後の幅を指定する(ピクセル単位)
h integer (なし) スケーリング後の高さを指定する(ピクセル単位)
u boolean 1 拡大することを許可する
u=0とした場合、オリジナル画像より高い解像度が指定されると、オリジナル画像と同じサイズで出力されます。
a integer 1 出力画像のアスペクトモードを設定します。
  • 0: (scale) 入力画像のアスペクト比に合わせ、出力画像の幅、高さにおさまるようにする
  • 1: (force-scale) 入力画像のアスペクト比を無視し、出力画像の幅、高さに合わせる
  • 2: (crop) 出力画像の幅、高さを満たすように縮小し、はみ出た領域をクロップする
  • 3: (pad) 入力画像のアスペクト比に合わせ、埋まらなかった部分を指定した背景色で埋める
c integer:integer:integer:integer (なし) 指定したサイズにクリップする (x1:y1:x2:y2)
cr float:float:float:float 0:0:1:1 指定したサイズにクリップする (割合で指定する)
例: 0.25:0.25:0.75:0.75=25%:25%:75%:75%
g integer 4 領域の原点を指定する
  • 1: 左上 (top-left)
  • 2: 中上 (top-center)
  • 3: 右上 (top-right)
  • 4: 左中 (middle-left)
  • 5: 中央 (middle-center)
  • 6: 右中 (middle-right)
  • 7: 左下 (bottom-left)
  • 8: 中下 (bottom-center)
  • 9: 右下 (bottom-right)
b string ffffff 背景色を指定する(16進数)
6桁で指定した場合は透過度0%として扱い、8桁で指定した場合は最終2桁を透過度として扱う
r integer / string 1 画像を回転/反転させる
  • 1: そのまま (top-left)
  • 2: 左右鏡像反転 (top-right)
  • 3: 180度回転 (bottom-right)
  • 4: 上下鏡像反転 (bottom-left)
  • 5: 1を斜め軸で鏡像回転 (left-top)
  • 6: 90度左回転 (right-top)
  • 7: 3を斜め軸で鏡像回転 (right-bottom)
  • 8: 90度右回転 (left-bottom)
  • auto: Exif情報のOrientation指定があれば、それを反映(逆変換)
through string (なし) 入力画像が指定されたフォーマットだった場合は一切の変換を行わない
jpg/png/gifのいずれか、またはこれらのうち複数を:区切りで並べる
例: png:gif
unsharp integerxfloat+float+float (なし) 拡大縮小後の画像に対してアンシャープマスクを適用する
radius x sigma + gain + threshold として指定する
例: 2x1.0+0.7+0.02
※blurと同時に指定することはできない
Name Value Type Default Description
radius integer 必須 ガウシアンぼかし半径(ピクセル単位)。0より大きい値
sigma float 必須 ガウシアンぼかしの標準偏差。0.0より大きい値
gain float 1.0 強調時の係数。thresholdを省略した場合のみ省略可
threshold float 0.05 強調時の閾値(比)。0.0より大きく1.0より小さい値
blur integerxfloat (なし) 拡大縮小後の画像に対してガウシアンぼかしを適用する
radius x sigma として指定する
例: 2x1.0
※unsharpと同時に指定することはできない
Name Value Type Default Description
radius integer 必須 ガウシアンぼかし半径(ピクセル単位)。0より大きい値
sigma float 必須 ガウシアンぼかしの標準偏差。0.0より大きい値

Overlay

指定した画像をオーバーレイ合成します。

Parameters (new style)

l=(パラメータ%2f重ねる画像のファイルパス)という形式で指定します。値はURLエンコードする必要があります。パラメータとしては拡大縮小で示したもの(throughを除く)に加えて、下記に示すものが使用可能です。,区切りでl=(...)指定を並べることにより、この順で複数の画像を重ねることができます。(後で指定されたものが上になります)

Key Value Type Default Description
x integer 0 横方向のオフセットを指定する
xr integer 0 横方向のオフセットを指定する(画像幅に対する割合)
y integer 0 縦方向のオフセットを指定する
yr integer 0 縦方向のオフセットを指定する(画像高さに対する割合)
lg integer 5 原点を指定する
  • 1: 左上 (top-left)
  • 2: 中上 (top-center)
  • 3: 右上 (top-right)
  • 4: 左中 (middle-left)
  • 5: 中央 (middle-center)
  • 6: 右中 (middle-right)
  • 7: 左下 (bottom-left)
  • 8: 中下 (bottom-center)
  • 9: 右下 (bottom-right)
Parameters (old style)

以下の形式でも指定可能ですが、上記の形式が推奨されます。

Key Value Type Default Description
l string (なし) 重ねる画像のファイルパス(URLエンコード形式)
lx integer 0 横方向のオフセットを指定する
lxr integer 0 横方向のオフセットを指定する(画像幅に対する割合)
ly integer 0 縦方向のオフセットを指定する
lyr integer 0 縦方向のオフセットを指定する(画像高さに対する割合)
lg integer 5 原点を指定する
  • 1: 左上 (top-left)
  • 2: 中上 (top-center)
  • 3: 右上 (top-right)
  • 4: 左中 (middle-left)
  • 5: 中央 (middle-center)
  • 6: 右中 (middle-right)
  • 7: 左下 (bottom-left)
  • 8: 中下 (bottom-center)
  • 9: 右下 (bottom-right)

Output

指定した形式で画像を出力します。

Parameters
Key Value Type Default Description
f string auto 出力フォーマットを指定する
  • auto : 入力画像と同じフォーマット
  • jpg : JPEG
  • png : PNG
  • gif : GIF
  • webp : WebP
  • webp:auto : WebPまたは入力画像と同じフォーマット(※1)
  • webp:jpg : WebPまたはJPEG(※1)
  • webp:png : WebPまたはPNG(※1)
  • webp:gif : WebPまたはGIF(※1)
※1 Acceptヘッダにimage/webpが含まれる場合はWebPで、そうでなければ : の後に指定した形式で出力される
q integer 75 クォリティパラメータ(0~100)
出力フォーマットがJPEGまたはWebPの場合に適用される。数値が大きい方が高画質となる。ただし0の場合はデフォルト値として扱われる
o boolean 1 出力フォーマットがJPEGの場合に、出力画像のハフマン符号化テーブルの最適化を行う

Signed URL

Signed URLはURLに署名パラメータを含めることで、外部のユーザによるパラメータの書き換えを防止する機能です。 署名パラメータはリクエストするURLから特定の方法で計算する必要があります。 この機能を利用することで、オーバーレイパラメータを除去してオリジナル画像を取り出すといったことを防ぐことができます。

設定方法

Signed URLはオリジンごとに設定できます。 オリジンの設定画面でにチェックを入れることでSigned URLが有効になります。 Signed URLが有効になっているオリジンでは署名パラメータを含まないURLでリクエストした場合、レスポンスはエラーになります。

署名パラメータの計算方法

署名パラメータによって署名されているURLをSinged URLと呼びます。 Signed URLを作成するには、次の方法で算出したハッシュ値をsigパラメーターの値としてURLの変換パラメーター部分に追加します。 署名パラメータはURLに含めるほかリクエストヘッダのX-ImageFlux-Signatureフィールドに設定することで、Signed URLと同様に署名パラメータを付与することができます。 署名パラメータ (signature) は以下の擬似コードで計算します。

version := "1"
value := BASE64URL(HMAC-SHA-256(SigningSecret, Path))
signature := version + "." + value
  • ここでBASE64URL関数はURLセーフな文字列を用いたBase64エンコードを行う関数です (詳細はRFC4648 Section 5を参照してください)。
  • HMAC-SHA-256関数はSHA-256ハッシュ関数を用いたHMACを計算する関数です。
  • Path変数はURLのパス(スキーム名とホスト名を除いたもの)を指します。
  • 正規化されていないパスが指定された場合は端末やブラウザによって正常に動作しない場合があります。ImageFluxではRFC-3986 Section 6.2.2による正規化を想定していますが、正規化されていないパスに対する動作は保証されていません。
Parameters
Key Value Type Default Description
sig string 署名パラメータ

サンプルURL (変換パラメータを含む場合)

画像変換パラメータと sigパラメータは任意の順で指定することができますが、sigパラメータ以外のパラメータ指定は署名計算時の順番を守る必要があります。

元のURL https://p1-47e91401.imageflux.jp/c/w=200/images/1.jpg
Signing Secret testsigningsecret
署名パラメータ 1.tiKX5u2kw6wp9zDgl1tLiOIi8IsoRIBw8fVgVc0yrNg=
Signed URL https://p1-47e91401.imageflux.jp/c/sig=1.tiKX5u2kw6wp9zDgl1tLiOIi8IsoRIBw8fVgVc0yrNg=,w=200/images/1.jpg

サンプルURL (変換パラメータを含まない場合)

元のURL https://p1-47e91401.imageflux.jp/images/1.jpg
Signing Secret testsigningsecret
署名パラメータ 1.-Yd8m-5pXPihiZdlDATcwkkgjzPIC9gFHmmZ3JMxwS0=
Signed URL https://p1-47e91401.imageflux.jp/c/sig=1.-Yd8m-5pXPihiZdlDATcwkkgjzPIC9gFHmmZ3JMxwS0=/images/1.jpg

署名パラメータを算出するサンプルコマンド

PHP
$ php -r '
  $hash = hash_hmac("sha256", "/images/1.jpg", "testsigningsecret", true);
  echo "1.".strtr(base64_encode($hash), "+/", "-_");
'

出力結果

1.-Yd8m-5pXPihiZdlDATcwkkgjzPIC9gFHmmZ3JMxwS0=
Ruby
$ ruby -rbase64 -ropenssl -e '
  hash = OpenSSL::HMAC.digest("sha256", "testsigningsecret", "/images/1.jpg")
  puts "1." + Base64.urlsafe_encode64(hash)
'

出力結果

1.-Yd8m-5pXPihiZdlDATcwkkgjzPIC9gFHmmZ3JMxwS0=

署名パラメータをリクエストヘッダフィールドX-ImageFlux-Signatureを用いて指定するサンプルコマンド

$ curl -H'X-ImageFlux-Signature: 1.tiKX5u2kw6wp9zDgl1tLiOIi8IsoRIBw8fVgVc0yrNg=' \
    https://p1-47e91401.imageflux.jp/c/w=200/images/1.jpg

HTTP API

HTTP RPCスタイルのシンプルなAPIを提供しています。現在のところ、キャッシュ管理APIのみをサポートしています。

Basics

リクエストとレスポンス

リクエストはすべてPOSTメソッドである必要があります。例えば、cache.lookupをcURLコマンドで実行する場合、次のコマンドを実行します。

$ curl -XPOST https://console.imageflux.jp/api/cache.lookup \
  -d token=ffff... \
  -d url=http://...

レスポンスはJSON形式です。

{
  "ok": true,
  "urls": [ ... ]
}

全てのレスポンスはok属性を含んでいます。APIの実行が成功した場合、ok属性はtrueを返します。 ok属性は、APIが成功したかどうかを示しており、実行結果自体には関係ありません。 例えば、cache.deleteはキャッシュを削除するAPIですが、キャッシュが削除されたかどうかにかかわらず、APIの呼び出しが成功すれば常にtrueになります。

APIトークン

ユーザ認証はtokenパラメータによって行われます。APIトークンはユーザごとに生成されたSHA256ハッシュ文字列です。

Cache Management

cache.lookup キャッシュされているか確認する

指定したURLがキャッシュされているか確認します。 URLのコンテントがキャッシュされている場合、キャッシュされているURLの一覧がレスポンスに含まれます。

Parameters
Argument Example Required Description
token fffff... yes APIトークン
url http://... yes コンテントのURL
Response
{
  "ok": true,
  "urls": [
    "http://...",
  ]
}

cache.delete キャッシュを削除する

指定したURLのキャッシュを削除します。 URLのコンテントが正常にキャッシュされた場合、キャッシュが削除されたURLの一覧がレスポンスに含まれます。

Request parameters
Argument Example Required Description
token fffff... yes APIトークン
url http://... yes コンテントのURL
Response
{
  "ok": true,
  "urls": [
    "http://...",
  ]
}