画像の動的変換について

画像はクエリストリングを追加することで、大きさや品質などを動的に変更できます。例えば次のように画像へリクエストすることで、幅200pxの画像を取得できます。 ファイルの拡張子がgif|png|jpe?g|webpの場合のみ適用されます。

https://xxxx.g.kuroco-img.app/files/user/example.jpg?width=200

パラメータは以下が指定できます。説明は各項目のリンク先を参照してください。

項目説明
autoWebPをサポートしている場合、自動的にフォーマットを変換します。(このパラメータはデフォルトで有効になっているので設定の必要はありません。)
bg-color背景色を設定します。
blurぼかしを設定します。
brightness輝度を設定します。
canvasキャンバスサイズを変更します。
contrastコントラストを設定します。
crop画像を切り抜きます。
disable画像の拡大を禁止します。
dprDPRを指定します。
enable画像の拡大を有効にします。
fitリサイズした際に、その画像をどう調整するかを指定します。
formatフォーマットを変更します。
frameアニメーションGIFから最初のフレームを抜き出します。
height画像の高さを指定します。
levelアニメーションGIFをMP4形式に変換する際に、 要求されるデコーダーの性能レベルを指定します。
optimize最適な品質を自動的に設定します。
orient画像の向きを変更します。
pad画像の枠にマージンを設けます。
precrop他の変更処理前に画像を切り抜きます。
profileビデオビットストリームを利用するアプリケーションレベルに応じて、ビデオエンコーダーの利用する機能を指定します。
quality変換後の画像品質を指定します。
resize-filterリサイズする際のフィルターを指定します。
saturation彩度を設定します。
sharpen画像内のエッジを鮮明にします。
trim画像を切り抜きます。
width画像の幅を指定します。

auto

WebブラウザがWebPに対応している場合、元画像をWebPフォーマットに変換して配信します。 (このパラメータはデフォルトで有効になっているので設定の必要はありません。)

種類設定例
webp固定?auto=webp

bg-color

画像の背景色をRGBで指定します。設定できる方法は全部で4つあります。

種類内容設定例
{6桁の文字列}000000〜FFFFFFの文字列?bg-color=c5c5c5
{3桁の文字列}000〜FFFの文字列?bg-color=000
{数値},{数値},{数値}0〜255の数字を3つをカンマ区切りで連結?bg-color=0,255,0
{数値},{数値},{数値},{数値}0〜255の数字を3つと、0〜1.0の透明度をカンマ区切りで連結?bg-color=0,255,0,0.5

blur

ぼかしは数値とパーセントの指定ができます。いずれもぼかしの半径を指定します。

種類内容設定例
{数値}ピクセルで指定?blur=50
{パーセント}画像の大きさに対するパーセントで指定?blur=0.5p

brightness

輝度は -100〜100の範囲で指定します。デフォルト値は0で、-100が真っ黒、100が真っ白になります。

種類内容設定例
{数値}-100〜100?brightness=50

canvas

画像のキャンバスサイズを変更します。画像自体の大きさを変えず、周囲に枠を付けるのに使います。

種類内容設定例
サイズ画像サイズをピクセルまたはパーセントで指定します。?canvas=320,240
サイズ,ポジション画像サイズをピクセルまたはパーセント、ポジションでオフセットを指定します。?crop=150,100,x50,y50

サイズ(canvas)

サイズはピクセルまたはパーセントで指定します。2つの値をカンマ、または : (コロン)で幅と高さに対して指定します。

種類内容設定例
{パーセント},{パーセント}数値にpを付けたものを2つ、カンマで繋ぎます。パーセント指定になります。?canvas=140p,120p
{数値},{数値}幅と高さをピクセル値で指定します。?canvas=320,240
{数値}:{数値}画像の割合を指定します?canvas=16:9

ポジション(canvas)

画像の左上を基準として、xy でオフセット値を指定します。 offset-xoffset-y は画像の中心を基準とします。なお、 xoffset-x や、 yoffset-y を組み合わせることはできません。 xoffset-yyoffset-x は一緒に利用できます。

種類内容設定例
x{数値},y{数値}画像の左上を基準として、キャンバスをXY座標で指定します。?canvas=150,100,x50,y50
offset-x{数値},offset-y{数値}画像の中心を基準として、キャンバスをXY座標で指定します。?canvas=1:1,offset-x25,offset-y50
x{数値},offset-y{数値}X軸は画像の左上、Y軸は画像の中心を基準としてキャンバスを指定します。?canvas=1:1,x250,offset-y50
offset-x{数値},y{数値}X軸は画像の中心、Y軸は画像の左上を基準としてキャンバスを指定します。?canvas=1:1,x50,offset-y250

contrast

コントラストは -100〜100の範囲で指定します。デフォルト値は0で、-100がグレースケールになります。

種類内容設定例
{数値}-100〜100の範囲で指定します。?contrast=50

crop

画像を切り抜きます。サイズと位置、さらに smartsafe パラメータによって切り抜き方を指定できます。

種類内容設定例
サイズ指定画像サイズをピクセルまたはパーセントで指定します。?crop=150
サイズ指定,オプション画像サイズをピクセルまたはパーセント、オプションで切り抜き方を指定します。?crop=150,smart
サイズ指定,ポジション画像サイズをピクセルまたはパーセント、ポジションでオフセットを指定します。?crop=150,100,x50,y50
サイズ指定,ポジション,オプション画像サイズをピクセルまたはパーセント、ポジションでオフセット、オプションで切り抜き方を指定します。?crop=150,100,x50,y50,smart

サイズ(crop)

サイズはピクセルまたはパーセントで指定します。また、カンマで幅と高さを区切って指定することや、: (コロン)で区切って比率による指定も可能です。

種類内容設定例
{数値}指定した数値で縦横を切り取ります。?crop=150
{数値},{数値}0.01〜0.99の数値2つをカンマで繋ぎます。パーセント指定になります。?crop=0.2,0.4
{数値},{数値}幅と高さをピクセル値で指定します。?crop=200,400
{数値}:{数値}画像の割合を指定します?crop=16:9

オプション(crop)

オプションは smart または safe を指定できます。

smart

コンテンツを意識したアルゴリズムにより、顔など重要なコンテンツを重視しながら画像を切り抜きます。

safe

通常、画像の領域外の範囲で切り抜きを行おうとすると Invalid transformation for requested image エラーになります。 safe オプションを付けることで回避できるようになりますが、生成される画像は指定したサイズではない可能性があります。

ポジション(crop)

画像の左上を基準として、xy でオフセット値を指定します。 offset-xoffset-y は画像の中心を基準とします。なお、 xoffset-x や、 yoffset-y を組み合わせることはできません。 xoffset-yyoffset-x は一緒に利用できます。

種類内容設定例
x{数値},y{数値}画像の左上を基準として、切り抜く基準値をXY座標で指定します。?crop=150,100,x50,y50
offset-x{数値},offset-y{数値}画像の中心を基準として、切り抜く基準値をXY座標で指定します。?crop=1:1,offset-x25,offset-y50
x{数値},offset-y{数値}X軸は画像の左上、Y軸は画像の中心を基準として切り抜く基準値を指定します。?crop=1:1,x250,offset-y50
offset-x{数値},y{数値}X軸は画像の中心、Y軸は画像の左上を基準として切り抜く基準値を指定します。?crop=1:1,x50,offset-y250

disable

画像の拡大を禁止します。画像の拡大はデフォルトで禁止されているため、有効にするためには enable パラメータで有効化します。width パラメータなどと組み合わせて、元画像よりも大きな数値を指定されても拡大しないといった使い方をします。

種類設定例
upscale固定?width=2560&disable=upscale

dpr

デバイスピクセル比を指定します。Retinaディスプレイなどの解像度の高いディスプレイへの対応に利用します。width パラメータなどと組み合わせて利用します。

種類内容設定例
{数値}DPRを数字で指定します。?width=200&dpr=2

enable

画像の拡大を有効にします。画像の拡大はデフォルトで禁止されているため、width パラメータなどと組み合わせて、元画像よりも大きな数値を指定された場合に拡大するといった指定をします。

種類設定例
upscale固定?width=2560&enable=upscale

fit

画像をリサイズした際に、その画像をどう調整するかを指定します。

種類内容設定例
bounds指定した領域内に画像が収まるようにします。縦横いずれかを小さな値にします。?width=150&height=150&fit=bounds
cover指定した領域内に画像が収まるようにします。縦横いずれかを大きな値にします。?width=150&height=150&fit=cover
crop指定した領域に合うように、画像を中心にリサイズします。?width=150&height=150&fit=crop

format

画像のフォーマットを変更します。指定できるのは次の通りです。

  • gif
  • png
  • png8
  • jpg
  • pjpg
  • bjpg
  • webp
  • webpll
  • webply
  • mp4

設定の例は次の通りです。

?format=png

frame

アニメーションGIFから最初のフレームを抜き出します。

種類設定例
1のみ?frame=1

height

画像の高さを指定します。絶対値または相対値(パーセント)で指定します。

種類内容設定例
{数値}1〜8192の範囲でピクセル数を指定します。?height=200
{数値}0〜0.99で縮小するパーセントを指定します。?height=0.5
{パーセント}150p(150%)といった指定をします。?height=150p

level

アニメーションGIFをMP4形式に変換する際に、profile パラメータと併用します。profile パラメータで要求されるデコーダーの性能レベルを指定します。

指定できる値は次の通りです。

種類内容設定例
レベル11.0〜1.3の範囲で指定します。?format=mp4&profile=main&level=1.3
レベル22.0〜2.2の範囲で指定します。?format=mp4&profile=main&level=2.0
レベル33.0〜3.2の範囲で指定します(3.0がデフォルト)。?format=mp4&profile=main&level=3.0
レベル44.0〜4.2の範囲で指定します。?format=mp4&profile=main&level=4.0
レベル55.0〜5.2の範囲で指定します。?format=mp4&profile=main&level=5.1
レベル66.0〜6.2の範囲で指定します。?format=mp4&profile=main&level=5.1

optimize

最適な品質を自動的に設定します。指定できる値は次の通りです。

  • low
  • medium
  • high

設定の例は次の通りです。

?optimize=low

orient

画像の向きを変更します。

種類内容設定例
r画像を右に回転します。?orient=r
l画像を左に回転します。?orient=l
h水平方向に反転します。?orient=h
v垂直方向に反転します。?orient=v
hv または vh画像を垂直、水平方向に反転します。?orient=vh
1デフォルト値。何もしません。?orient=1
2水平方向に反転します。hと同じです。?orient=2
3画像を垂直、水平方向に反転します。?orient=3
4垂直方向に反転します。vと同じです。?orient=4
5水平方向に反転します。その後左に回転します。?orient=5
6画像を右に回転します。?orient=6
7水平方向に反転します。その後右に回転します。?orient=7
8画像を左に回転します。?orient=8

pad

画像の枠にマージンを設けます。 bg-colorと組み合わせることで、枠に色を付けられます。数値は整数の場合はピクセル数、1.0以下の小数点を含む数値の場合はパーセント指定になります。

種類内容設定例
{数値}上下左右同じ幅の枠を付けます。?pad=20
{数値},{数値}1つ目の数字が上下、2つ目の数字が左右の幅を指定します。?pad=25,100
{数値},{数値},{数値}1つ目の数字が上、2つ目の数字が左右、3つ目の数字が下の幅を指定します。?pad=25,50,100
{数値},{数値},{数値},{数値}1つ目の数字が上、2つ目の数字が右、3つ目の数字が左、4つ目の数字が下の幅を指定します。?pad=25,50,75,100

precrop

cropと同じように画像を切り抜きます。違いは他の画像変換処理前に実行されるかどうかです。指定できるパラメータはcropと同様です。

種類内容設定例
サイズ指定画像サイズをピクセルまたはパーセントで指定します。?precrop=150
サイズ指定,オプション画像サイズをピクセルまたはパーセント、オプションで切り抜き方を指定します。?precrop=150,smart
サイズ指定,ポジション画像サイズをピクセルまたはパーセント、ポジションでオフセットを指定します。?precrop=150,100,x50,y50
サイズ指定,ポジション,オプション画像サイズをピクセルまたはパーセント、ポジションでオフセット、オプションで切り抜き方を指定します。?precrop=150,100,x50,y50,smart

profile

アニメーションGIFをMP4形式に変換する際、level パラメータと共に指定します。ビデオビットストリームを利用するアプリケーションレベルに応じて、ビデオエンコーダーの利用する機能を指定します。

種類内容設定例
baselineビデオ会議やモバイルアプリ向きの指定です(デフォルト)。?format=mp4&profile=baseline&level=5.0
main標準画質の指定です。?format=mp4&profile=main&level=5.0
high高画質の指定です。?format=mp4&profile=high&level=5.0

quality

変換後の画像品質を指定します。WebPが表示できるWebブラウザ向けに出力する際に、2つ目の数値でWebP向けの品質を指定できます。2つ目の数値を使う場合は autoパラメータと併用してください。

種類内容設定例
{数値}出力する画像の品質。100以下の数値を指定します。?quality=85
{数値},{数値}1つ目の数値が通常の画像品質、2つ目の数値がWebP向けの画像品質になります。?format=pjpg&auto=webp&quality=85,75

resize-filter

リサイズする際のフィルターを指定します。

種類内容設定例
nearest付近にあるピクセル情報を利用します。?resize-filter=nearest
bilinear または linear画素の2x2平均値を利用します。?resize-filter=bilinear
bicubic または cubic画素の4x4平均値を利用し、内側の値をより高く評価します。?resize-filter=bicubic
lanczos2ランチョスフィルタによって、可能な限り再構成を試みます。?resize-filter=lanczos2
lanczos3 または lanczossinc関数を利用して最適化します。?resize-filter=lanczos3

saturation

彩度は -100〜100の範囲で指定します。デフォルト値は0で、-100がグレースケールになります。

種類内容設定例
{数値}-100〜100の範囲で指定します。?saturation=50

sharpen

画像内のエッジを鮮明にします。

種類内容設定例
a{数値},r{数値},t{数値}aは量、rは半径、tはしきい値を設定します。?sharpen=a5,r2,t0

trim

画像を切り抜きます。数値は整数の場合はピクセル数、1.0以下の小数点を含む数値の場合はパーセント指定になります。

種類内容設定例
{数値}上下左右同じ幅で切り抜きます。?trim=20
{数値},{数値}1つ目の数字が上下、2つ目の数字が左右の切り抜き幅を指定します。?trim=25,100
{数値},{数値},{数値}1つ目の数字が上、2つ目の数字が左右、3つ目の数字が下の切り抜き幅を指定します。?trim=25,50,100
{数値},{数値},{数値},{数値}1つ目の数字が上、2つ目の数字が右、3つ目の数字が左、4つ目の数字が下の切り抜き幅を指定します。?trim=25,50,75,100

width

画像の幅を指定します。絶対値または相対値(パーセント)で指定します。

種類内容設定例
{数値}1〜8192の範囲でピクセル数を指定します。?width=200
{数値}0〜0.99で縮小するパーセントを指定します。?width=0.5
{パーセント}150pで150%といった指定をします。?width=250p