画像変換

画像URLのリサイズ・形式・品質指定と、変換されない条件。

メディアの画像URLにクエリを付けると、リサイズ・形式変換・品質調整ができます。元ファイルを管理画面で加工し直す必要はありません。URLは管理画面または配信APIから取得してください。

表示サイズに合わせる

SDKのbuildImageUrlでURLを組み立てられます。blogに画像フィールドeyecatchがある場合の例です。

import { buildImageUrl } from "@genko-me/sdk";
import { genko } from "@/lib/client";

const post = await genko.apis.blog.getOrNull("abcDEF123456");
const imageUrl = post?.eyecatch?.url
  ? buildImageUrl(post.eyecatch.url, { w: 800, format: "webp", q: 80 })
  : null;

この関数はURLを生成するだけで、画像を取得しません。表示側でimgなどに渡します。画像フィールドが未定義なら、先に追加してpullで型を同期してください。

パラメータ

名前	値	省略時
`w`	1〜2,000の整数。幅px	指定なし
`h`	1〜2,000の整数。高さpx	指定なし
`q`	1〜100の整数。出力品質	`80`
`format`	`webp`、`avif`、`jpeg`、`png`、`auto`	元形式を維持
`fit`	`cover`、`contain`、`inside`	幅・高さの両方ありならcover、それ以外はinside

qはWebP・AVIF・JPEGに適用し、PNGには適用しません。整数の範囲外や未知の値は400になります。buildImageUrlも値を検証し、不正な場合はURL生成時に例外を投げます。

用途別の指定

用途	指定例	結果
本文内の画像	`w=800`	比率を保って幅を調整
一覧のサムネイル	`w=640&h=360&fit=cover`	指定枠に合わせ、はみ出す部分を切り取る
全体を枠内に収める	`w=640&h=360&fit=contain`	全体を保ち、比率が違う場合は余白が付く
枠以内に縮小する	`w=640&h=360&fit=inside`	比率を保ち、出力寸法が枠より小さくなることがある

元画像より大きく拡大しません。指定した幅・高さが、常に実際の出力寸法になるとは限りません。

format=auto

Acceptヘッダーにimage/webpが含まれる場合はWebP、それ以外は元の形式を使います。自動でAVIFを選ぶ設定ではありません。AVIFが必要ならformat=avifを指定します。

実際に自動形式で変換した応答にはVary: Acceptが付きます。変換を行わず元ファイルを返す場合とは挙動が異なります。

変換されない場合

変換用のパラメータがない場合は元ファイルを返します。
元ファイルが25MBを超える場合は元ファイルを返します。
アニメーション画像でformatを省略すると元ファイルを返します。形式を指定した場合は先頭フレームだけを変換します。

アップロード可能なサイズと、変換可能なサイズは別です。Proで100MBまでアップロードできても、25MBを超える画像は変換されません。

JPEG・PNG・WebP・GIF・AVIF以外のファイルに変換指定を付けると415になります。PDFなどの配信には変換用パラメータを付けないでください。

キャッシュと差し替え

配信の応答にはCache-Control: public, max-age=31536000, immutableが設定されます。ブラウザなどが長期間同じURLを保持できる設定です。

メディアを差し替えたときは、配信APIから新しいURLを取得します。同じURLの内容がすぐに置き換わることを前提にしないでください。画像URL自体はAPIキーなしで取得できるため、公開範囲についてはメディア管理も参照してください。

想定どおりにならないとき

400なら指定値、415なら形式、変換されないなら25MB上限とアニメーションの条件を確認します。画像が小さいままなら元画像の寸法も確認してください。変換のタイムアウトは504になる場合があります。