画像を変換して出す（大きさ、形式）

エントリーの画像は、URL にパラメーターを付けるだけで、大きさや形式を変えて出せます。変換した画像は保存され、2 回目からはすぐに返ります。

前提

• 画像のフィールドを持つエントリーを、API で取り出せること。取り出し方は エントリーを取り出す にあります
• 画像の URL を開くのに、API キーは要りません

画像の URL を取る

画像のフィールドは、次のように返ります。url が画像の URL です。

"eyecatch": {
  "url": "https://<メディアのホスト>/media/k2m9x0a1b2c3/hero.jpg",
  "width": 1600,
  "height": 900,
  "alt": "トップの写真"
}

<メディアのホスト> の部分は、環境によって決まります。URL は組み立てずに、返った url の値をそのまま使ってください。width、height、alt は、ないこともあります。

画像やファイルの URL は、知っていれば誰でも開けます。 エントリーを公開しているかどうかには関わりません。人に見せたくないファイルは、アップロードしないでください。

大きさと形式を変える

画像の URL にパラメーターを付けます。幅 800 px の AVIF にし、画質を 60 にします。<画像の URL> は、返った url の値に置き換えてください。

<画像の URL>?w=800&fm=avif&q=60

HTML では、次のように使います。

<img
  src="<画像の URL>?w=800&fm=avif&q=60"
  width="800"
  alt="トップの写真"
/>

使えるパラメーターは次のとおりです。

名前	値	既定	意味
w	1〜8192 の整数	元の大きさ	幅（px）
h	1〜8192 の整数	元の大きさ	高さ（px）
fit	clip max crop scale	clip	w と h の枠への合わせ方
q	1〜100 の整数	75	画質。JPEG、WebP、AVIF で効く
fm	jpg（jpeg も可）png webp avif	元の形式	出力の形式
dpr	1〜5 の数。小数も可	1	w と h に掛ける倍率

• w と h の片方だけを付けると、縦横の比を保って、もう片方が決まります
• dpr を掛けた大きさが 8192 を超えるときは、8192 になります
• 写真の向き（EXIF）は、変換の前に反映します。変換した画像からは、撮影の情報や位置の情報が消えます
• 知らないパラメーター（auto、blur など）は無視されます

名前と意味は imgix にそろえてあります。

枠に合わせる（fit）

w と h の両方を付けたときに、枠にどう合わせるかを fit で決めます。

値	合わせ方
clip（既定）	縦横の比を保ち、枠に収まるいちばん大きい大きさにする。元より大きくもする
max	clip と同じ。ただし元の大きさより大きくしない
crop	縦横の比を保って枠を埋め、はみ出たところを真ん中で切り取る
scale	縦横の比を気にせず、枠の大きさにする

一覧のサムネイルのように、同じ大きさの四角にそろえるときは crop を使います。

<画像の URL>?w=400&h=400&fit=crop

画面の細かさに合わせる（srcset）

高い解像度の画面には、dpr で大きい画像を出せます。

<img
  src="<画像の URL>?w=400"
  srcset="<画像の URL>?w=400&dpr=2 2x, <画像の URL>?w=400&dpr=3 3x"
  width="400"
  alt="トップの写真"
/>

?w=400&dpr=2 と ?w=800 のように、できあがる画像が同じなら、同じ画像が返ります。

出る形式

場合	出る形式
fm=jpg、fm=webp	その形式
fm=avif	AVIF。ただし、出る画像の 1 辺が 1,200 px を超えるときは WebP
fm=png	PNG。元が PNG のときだけ使える
fm なしで、元が JPEG、WebP、PNG	元と同じ形式
fm なしで、元が GIF	変換しない（元の画像が返る）

透明なところは、PNG、WebP、AVIF では残ります。JPEG にしたときは白になります。

次のときは、パラメーターを無視して、元の画像やファイルがそのまま返ります。

• JPEG、PNG、WebP、GIF ではないもの（SVG、AVIF、画像でないファイルなど）
• GIF に fm を付けていないとき

GIF に fm=jpg、fm=webp、fm=avif を付けると、最初のコマだけを変換します。動きはなくなります。

確かめる

ブラウザで、パラメーターを付けた URL を開きます。変えた大きさと形式の画像が表示されれば、変換できています。curl では、応答の Content-Type で出た形式を確かめられます。

curl -sI "<画像の URL>?w=800&fm=webp" | grep -i content-type

次のような行が表示されます。

content-type: image/webp

パラメーターが正しくないときは、400 と理由が返ります。

返ってきたもの	原因	直し方
400 w: must be an integer between 1 and 8192	値が範囲の外、または整数でない	表の範囲の値にします。ほかのパラメーターも同じ形の文が返ります
400 fm: png is only available for PNG images	PNG でない画像に fm=png を付けた	fm=webp などほかの形式にします
400 image is too large to transform	元の画像の画素の数が多すぎる	元の画像を小さくしてアップロードし直します。パラメーターを付けなければ、元の画像は出せます
404	画像が削除された、または URL が違う	エントリーを取り出し直して、url の値を使います

関連

• エントリーを取り出す
• Content API のリファレンス（メディアの一覧と返る値）
• メディアを上げる