画像の動的変換について

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

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

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

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

kio

画像最適化の挙動をキャンセルします。

種類	設定例
false固定	?kio=false

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

画像のキャンバスサイズを変更します。画像自体の大きさを変えず、周囲に枠を付けるのに使います。 bg-colorと組み合わせることで、枠の色を指定できます。

種類	内容	設定例
サイズ	キャンバスサイズをピクセルまたはパーセントで指定します。	?width=300&canvas=320,240
サイズ,ポジション	キャンバスサイズをピクセルまたはパーセント、ポジションでオフセットを指定します。	?width=300&canvas=320,240,x10,y10
サイズ,bg-color	キャンバスサイズを縦横1.1倍にしてグレーの枠を付与	?canvas=110p,110p&bg-color=c5c5c5

サイズ（canvas）

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

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

ポジション（canvas）

x、yを指定すると、画像の左上を基準としてオフセットします。
offset-x、offset-y で、オフセット値をパーセンテージで指定します。 サイズを: （コロン）を使用した比で指定した場合は、x、yでのポジション指定はできません。

また、x と offset-y 、 y と offset-x は一緒に利用できますが、 x と offset-x や、 y と offset-y を組み合わせることはできません。

種類	内容	設定例
x{数値},y{数値}	キャンバス内の画像位置をキャンバスの左上を基準として、XY座標で指定します。	?width=300&canvas=320,240,x10,y10
offset-x{数値},offset-y{数値}	キャンバス内の画像位置をXYのパーセンテージで指定します。	?canvas=1:1,offset-x25,offset-y25

contrast

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

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

crop

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

種類	内容	設定例
サイズ指定	画像サイズをピクセルまたはパーセントで指定します。	?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）

x、yを指定すると、画像の左上を基準としてオフセットします。
offset-x、offset-y で、オフセット値をパーセンテージで指定します。 サイズを: （コロン）を使用した比で指定した場合は、x、yでのポジション指定はできません。

また、x と offset-y 、 y と offset-x は一緒に利用できますが、 x と offset-x や、 y と offset-y を組み合わせることはできません。

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

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 パラメータで要求されるデコーダーの性能レベルを指定します。

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

種類	内容	設定例
レベル1	1.0〜1.3の範囲で指定します。	?format=mp4&profile=main&level=1.3
レベル2	2.0〜2.2の範囲で指定します。	?format=mp4&profile=main&level=2.0
レベル3	3.0〜3.2の範囲で指定します（3.0がデフォルト）。	?format=mp4&profile=main&level=3.0
レベル4	4.0〜4.2の範囲で指定します。	?format=mp4&profile=main&level=4.0
レベル5	5.0〜5.2の範囲で指定します。	?format=mp4&profile=main&level=5.1
レベル6	6.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 または lanczos	sinc関数を利用して最適化します。	?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