CodexPluginStats
← Files microCMSARCHIVED FILE

skills/microcms-guide/references/image-api.md

14 KB · Oct 3, 2026 · 06:35 UTC

↓ Download file

# 画像API ガイド

最終確認: 2026-09-08

このリファレンスは、microCMS の画像 API を使って画像表示を最適化し、データ転送量や表示負荷を抑えるための実践ガイド。パラメータ一覧の転載ではなく、ユーザーの目的に応じてどの最適化を優先するかを扱う。

## 目次

- [基本方針](#基本方針)
- [画像APIの前提](#画像apiの前提)
- [まずサイズを最適化する](#まずサイズを最適化する)
- [フォーマットを最適化する](#フォーマットを最適化する)
- [品質を調整する](#品質を調整する)
- [レスポンシブ画像](#レスポンシブ画像)
- [トリミングと fit](#トリミングと-fit)
- [複数パラメータを組み合わせる](#複数パラメータを組み合わせる)
- [データ転送量を減らす診断手順](#データ転送量を減らす診断手順)
- [リッチエディタ内の画像](#リッチエディタ内の画像)
- [一般的なWeb画像最適化との組み合わせ](#一般的なweb画像最適化との組み合わせ)
- [利用できない・注意が必要なケース](#利用できない注意が必要なケース)
- [判断ルール](#判断ルール)
- [メディアの公開範囲と削除](#メディアの公開範囲と削除)

- [公式情報](#公式情報)

## 基本方針

画像の最適化では、次の順序を基本とする。

1. 実際の表示サイズに対して元画像が大きすぎないか確認する。
2. `w` / `h` などで必要な寸法まで縮小する。
3. `fm=webp` や `fm=avif` など、利用環境に適したフォーマットを検討する。
4. 必要に応じて `q` で品質を調整する。
5. 画面幅・解像度が異なる場合は `srcset` / `sizes` または `dpr` を検討する。
6. 画像がビューポート外に多い場合は Lazy Loading など一般的な Web 側の対策も組み合わせる。

転送量削減の相談では、最初からキャッシュやアーキテクチャ変更に進まず、まず画像サイズを確認する。microCMS の公式ヘルプでも、データ転送量の多くを画像取得が占めるケースがあるとして画像最適化を案内している。

## 画像APIの前提

microCMS の画像 API は、取得した画像 URL の末尾にクエリパラメータを追加して適用する。

```ts
const optimizedImageUrl = `${image.url}?w=800&fm=webp`;
```

主な画像フィールドでは `url`, `width`, `height`, `alt` などの情報が返るため、元画像の寸法も判断材料にする。

画像処理には imgix の Rendering API が利用されているが、imgix の全機能がそのまま利用できるとは限らない。microCMS 公式ドキュメントで対応が確認できないパラメータを、利用可能と断定しない。

## まずサイズを最適化する

表示領域が幅 600px 程度なのに、2000px 以上の元画像をそのまま配信しない。

```text
?w=600
```

`w` は width、`h` は height を指定する。

画像の縦横比を維持しながら最大サイズ内に収めたい場合は、用途に応じて `fit=max` などを検討する。

### 推奨

- 一覧のサムネイルと記事詳細のメイン画像で、同じ大きな画像 URL をそのまま使い回さない。
- CSS で見た目だけ縮小しても、取得する画像ファイル自体が小さくなるわけではない。画像 API で配信サイズを縮小する。
- 元画像の `width` / `height` を確認し、不必要なアップスケールを避ける。
- 画像サイズの削減はフォーマットや品質調整より効果が大きい場合があるため、転送量削減では優先的に確認する。

microCMS 公式ヘルプの例では、1920px 幅の画像を `w=600` へ縮小することで、例示画像のファイルサイズが大幅に削減されている。具体的な削減率は画像内容によって変わるため、固定の削減率として説明しない。

## フォーマットを最適化する

### WebP

```text
?fm=webp
```

JPEG / PNG などから WebP へ変換できる。一般にファイルサイズ削減が期待できる。

### AVIF

```text
?fm=avif
```

AVIF への変換も可能。高い圧縮率を期待できる一方、利用対象ブラウザの対応状況を確認する。

### その他

`fm=jpg`, `fm=png` も利用できる。`fm=json` では画像メタデータを取得できる。

### 注意

`auto=format` は microCMS の画像 API ではサポートされていない。ユーザーが imgix の一般的な例をそのまま使おうとしている場合は修正する。

フォーマットは「常に AVIF が最善」などと固定しない。対象ブラウザ、画像内容、既存の画像最適化基盤を踏まえて選ぶ。

## 品質を調整する

`q` で画像の出力品質を 0〜100 の範囲で指定できる。

```text
?q=60
```

画像変換処理が行われる場合のデフォルト値は 75。パラメータを一切付与しない場合はオリジナル画像が表示される。

### 推奨

- 品質を下げるほどファイルサイズは小さくなりやすいが、視覚品質も落ちる。
- 固定値を「公式推奨値」として断定しない。画像の用途と見た目を確認して決める。
- サムネイルなど小さな画像と、商品・作品写真のように画質が重要な画像で同じ品質設定を機械的に適用しない。
- `q` だけを下げる前に、まず過剰な画像寸法を縮小できないか確認する。

## レスポンシブ画像

画面幅に応じて適切な画像サイズを取得する場合は、`srcset` と `sizes` の利用を検討する。

```html
<img
  srcset="
    https://example.microcms-assets.io/image.jpg?w=400 400w,
    https://example.microcms-assets.io/image.jpg?w=768 768w,
    https://example.microcms-assets.io/image.jpg?w=1024 1024w,
    https://example.microcms-assets.io/image.jpg?w=1536 1536w
  "
  sizes="(max-width: 1024px) 100vw, 1024px"
  src="https://example.microcms-assets.io/image.jpg?w=1024"
  alt=""
/>
```

`w` 幅記述子を使うと、ブラウザは表示幅だけでなくデバイスピクセル比も考慮して候補を選択できる。

画像 API には `dpr` もある。

```text
?dpr=2&w=300
```

`dpr` はデフォルト 1、最大 8。指定する場合は幅または高さも指定する。

### 判断

- HTML の `srcset` / `sizes` を使える一般的な Web サイトでは、複数の `w` 候補を生成する方法をまず検討する。
- フレームワークに専用の画像コンポーネントがある場合は、そのコンポーネントの画像選択・最適化機能との役割分担を確認する。
- Next.js の `next/image` 固有の設定は `microcms-nextjs` で扱う。

## トリミングと fit

`fit` では縦横比や切り取り方法を調整できる。

代表例:

- `fit=clip`: 縦横比を維持してリサイズする。デフォルト。
- `fit=crop`: 指定サイズに合わせて拡大・縮小し、はみ出す部分を切り取る。`w` と `h` が必要。
- `fit=max`: 指定サイズ内に縦横比を維持して最大限配置する。
- `fit=fill`: 指定サイズに収め、余白を指定色などで補う。

```text
?fit=crop&w=400&h=300
```

トリミングが必要ない画像に安易に `fit=crop` を使わない。人物や商品など重要部分が切れる可能性があるため、デザイン要件を確認する。

## 複数パラメータを組み合わせる

画像 API のパラメータは `&` で組み合わせられる。

```text
?w=800&fm=webp&q=70
```

固定比率のサムネイルなら、たとえば次のような構成を検討できる。

```text
?fit=crop&w=600&h=400&fm=webp&q=70
```

これは例であり、`600x400`, WebP, `q=70` を全サイト共通の推奨値として扱わない。実際の表示サイズとデザイン要件から決める。

## データ転送量を減らす診断手順

「データ転送量が多い」「画像が重い」と相談された場合は、次の順に確認する。

1. microCMS のデータログで転送量の状況を確認できるか確認する。
2. ページ内で取得している画像の枚数と実ファイルサイズを確認する。
3. 表示サイズより大幅に大きい画像を取得していないか確認する。
4. `w` / `h` で縮小できる画像を特定する。
5. WebP / AVIF などのフォーマット変換を検討する。
6. 必要に応じて `q` を調整する。
7. レスポンシブ画像を導入し、小さい画面へ巨大画像を送らない。
8. ファーストビュー外の画像が多い場合は Lazy Loading を検討する。
9. 動画など大容量メディアが主因なら、外部の動画配信・ストレージも検討する。
10. 画像以外も疑われる場合は `performance.md` と組み合わせ、JSON取得回数、`fields`、レンダリング方式、キャッシュなどを確認する。

重要: microCMS の CDN キャッシュから配信された画像・コンテンツであっても、microCMS のデータ転送量には含まれる。CDN キャッシュヒットだけを理由に「転送量は増えない」と説明しない。

画像 API で変換した画像は、変換後のファイルサイズを基準にデータ転送量が集計される。そのため画像 API によるファイルサイズ削減は、転送量削減に直接つながる。

## リッチエディタ内の画像

画像フィールドでは URL にそのままパラメータを付けられるが、リッチエディタの画像は HTML 内に `img` 要素として含まれるため扱いが異なる。

画像 API を適用する場合は、以下を検討する。

- 返却された HTML をパースして `img` の URL を書き換える。
- コンテンツ設計を変更できる場合は、画像を画像フィールドとして扱いやすい構造へ切り出す。

リッチエディタでは `w` / `h` を画像ごとに設定できる仕組みもある。既存コンテンツ量や編集運用を無視して大規模な構造変更を提案しない。

## 一般的なWeb画像最適化との組み合わせ

以下は microCMS 固有機能ではなく一般的な Web 最適化として扱う。

### Lazy Loading

ファーストビュー外の画像では `loading="lazy"` を検討する。

```html
<img
  src="https://example.microcms-assets.io/image.jpg?w=800"
  loading="lazy"
  width="800"
  height="600"
  alt=""
/>
```

レイアウトシフトを抑えるため、画像寸法を指定できる場合は `width` / `height` も設定する。

### フレームワークの画像最適化

Next.js などが独自の画像最適化機構を持つ場合、microCMS 画像 API と二重に何を処理するかを確認する。「両方使えば必ず速くなる」と説明しない。

## 利用できない・注意が必要なケース

- Amazon S3 連携を有効にしている場合、microCMS の画像 API は利用できない。
- SVG 形式では画像 API を利用できない。
- `auto=format` はサポートされていない。
- imgix のドキュメントに存在するパラメータでも、microCMS での利用可否が不明な場合は公式情報を確認する。
- 画像 URL にすでにクエリパラメータがある場合は `?` を重ねず、既存パラメータとの連結方法を確認する。
- フォーマット変換では対象ブラウザの対応状況を考慮する。

## 判断ルール

ユーザーの目的に応じて以下を優先する。

### 「画像を軽くしたい」

1. 表示サイズに合わせて `w` / `h` を調整する。
2. WebP / AVIF を検討する。
3. `q` を調整する。
4. レスポンシブ配信を検討する。

### 「データ転送量を減らしたい」

1. 画像が主因か確認する。
2. 画像が主因ならサイズ最適化を最優先する。
3. 画像以外も大きい場合は `performance.md` を読む。

### 「サムネイルを固定サイズで表示したい」

`fit=crop` + `w` + `h` を候補にする。ただし切り取り許容可否を確認する。

### 「Retinaでも鮮明にしたい」

`srcset` の幅候補または `dpr` を検討し、必要以上の大きな画像を全ユーザーへ送らない。

### 「Next.jsで画像を最適化したい」

このリファレンスでは microCMS 画像 API の原則だけを適用し、`next/image`, `remotePatterns`, Next.js Image Optimization の詳細は `microcms-nextjs` に委ねる。

## メディアの公開範囲と削除

microCMS標準のメディアはアップロード時からURLでアクセスでき、画像・ファイル単位の閲覧制限は提供されない。記事の下書き状態やContent APIキーで画像URLまで保護されると考えない。機密メディアには、アクセス制御を備えた別ストレージと拡張フィールドなどを検討する。[公式ヘルプ：メディアの閲覧制限](https://help.microcms.io/ja/knowledge/file-view-restrictions)

メディア削除時はCDNキャッシュも削除されるが、完了に時間がかかる場合がある。「削除操作直後にURLが必ず無効になる」とは約束しない。[公式ヘルプ：削除後もURLにアクセスできる場合](https://help.microcms.io/ja/knowledge/media-deletion-url-access)

## 公式情報

- [画像APIとは](https://document.microcms.io/image-api/introduction)
- [画像サイズ](https://document.microcms.io/image-api/size)
- [品質](https://document.microcms.io/image-api/quality)
- [解像度・画面サイズ](https://document.microcms.io/image-api/dpr)
- [フォーマット](https://document.microcms.io/image-api/format)
- [データ転送量](https://document.microcms.io/manual/data-amount)
- [データ転送量を節約する方法](https://help.microcms.io/ja/knowledge/reduce-data-costs)
- [リッチエディタ内の画像への画像API適用](https://help.microcms.io/ja/knowledge/apply-image-api-in-rich-editor)

SHA-256: 354c876c4fb612a1ceb8597c23958994cd548ae00c1aa8470bd91ebf018e5d47