---
title: 画像の動的変換について
category: ファイル
weight: 90
---

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

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

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

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

| 種類 | 内容 | 設定例 |
|:------|:------|:------|
| [サイズ](#サイズcanvas) | キャンバスサイズをピクセルまたはパーセントで指定します。 | ?width=300&canvas=320,240 |
| [サイズ](#サイズcanvas),[ポジション](#ポジションcanvas) | キャンバスサイズをピクセルまたはパーセント、ポジションでオフセットを指定します。 |?width=300&canvas=320,240,x10,y10 |
| [サイズ](#サイズcanvas),[bg-color](#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) | 画像サイズをピクセルまたはパーセントで指定します。 | ?crop=150 |
| [サイズ指定](#サイズcrop),[オプション](#オプションcrop) | 画像サイズをピクセルまたはパーセント、オプションで切り抜き方を指定します。 | ?crop=150,smart |
| [サイズ指定](#サイズcrop),[ポジション](#ポジションcrop) | 画像サイズをピクセルまたはパーセント、ポジションでオフセットを指定します。 |?crop=150,100,x50,y50 |
| [サイズ指定](#サイズcrop),[ポジション](#ポジションcrop),[オプション](#オプションcrop) | 画像サイズをピクセルまたはパーセント、ポジションでオフセット、オプションで切り抜き方を指定します。 | ?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](#enable) パラメータで有効化します。[width](#width) パラメータなどと組み合わせて、元画像よりも大きな数値を指定されても拡大しないといった使い方をします。

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

## dpr

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

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

## enable

画像の拡大を有効にします。画像の拡大はデフォルトで禁止されているため、[width](#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) パラメータと併用します。[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](#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)と同じように画像を切り抜きます。違いは他の画像変換処理前に実行されるかです。指定できるパラメータは[crop](#crop)と同様です。

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


## profile

アニメーションGIFをMP4形式に変換する際、[level](#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](#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 |
