画像変換API#
Snapkitの画像変換APIを使用して、URLパラメータによるリアルタイム画像変換を実行できます。高性能処理のためのSharp↗ライブラリとCloudFront CDNをベースに、世界中で高速な画像配信を提供します。
クイックスタート#
基本的な使用方法#
アップロードされた画像URLにクエリパラメータを追加してリアルタイム変換：
GET https://{organization}-cdn.snapkit.studio
/{project}
/{path}
/{filename}
?w=800&h=600&fit=cover&flip=true&grayscale=true&dpr=2URLコンポーネント：
{organization}: 組織名（例：acme-corp）{project}: プロジェクト名{path}: フォルダパス{filename}: 画像ファイル名- クエリパラメータ: 変換オプション（
w、h、fitなど）
主要機能#
- リアルタイム変換: URLパラメータによる瞬時の画像変換
- CDNキャッシュ: 初回変換後のCloudFrontからの高速画像配信
- 自動最適化: ブラウザ機能に基づく自動フォーマット選択
- 高解像度サポート: DPR（Device Pixel Ratio）ベースのレスポンシブ画像生成
変換パラメータ リファレンス#
サイズ & レイアウト#
パラメータ | タイプ | 説明 | デフォルト | 制限 |
|---|---|---|---|---|
w | number | 幅（ピクセル） | 最大4,096px | |
h | number | 高さ（ピクセル） | 最大4,096px | |
fit | string | フィッティングモード： | cover | |
dpr | number | Device Pixel Ratio | 1.0 | 1.0-4.0 |
変換 & エフェクト#
パラメータ | タイプ | 説明 | 制限 |
|---|---|---|---|
rotation | number | 回転角度（0-360度、自動正規化） | |
flip | boolean | 垂直反転 | |
flop | boolean | 水平反転 | |
blur | number | ブラー強度 | 最大20 |
grayscale | boolean | グレースケール変換 |
領域 & フォーマット#
パラメータ | タイプ | 説明 | 制限 |
|---|---|---|---|
extract | string | 領域抽出： | 最大4,096x4,096 |
format | string | 出力フォーマット： |
実用的な使用例#
レスポンシブ画像最適化#
デスクトップ高解像度
?w=800&h=600&dpr=2.0&format=webp&fit=cover
モバイル最適化
?w=375&dpr=3&format=auto&fit=cover
サムネイル生成
?w=200&h=200&fit=cover
高度な変換組み合わせ#
ポートフォリオギャラリー
?w=400&h=300&grayscale=true&blur=1&format=webp
商品画像
?w=600&h=600&fit=contain&format=auto
画像プレビュー
?extract=25,25,50,50&w=300&format=jpeg
基本変換オプション#
リサイズ
?w=800&h=600&fit=cover
回転と反転
?rotation=90&flip=true
ブラーとグレースケール効果
?blur=2&grayscale=true
リサイズ適用 (w=300&h=200&fit=cover)
変換効果の可視化#
リサイズ + 高解像度 (w=300&h=200&fit=cover&dpr=2.0)
Device Pixel Ratio（DPR）の使用#
高解像度ディスプレイサポートのために実際の画像サイズを調整します。指定されたサイズにDPR値を掛けて実際の画像サイズを計算します。
DPRの動作原理#
w=300&dpr=1.0→ 実際の画像サイズ：300px（300 × 1.0）w=300&dpr=1.5→ 実際の画像サイズ：450px（300 × 1.5）w=300&dpr=2.0→ 実際の画像サイズ：600px（300 × 2.0）
ブラウザは依然として指定されたサイズ（300px）で表示しますが、鮮明なレンダリングのために大きな画像をダウンロードします。
使用例#
デスクトップ標準解像度
?w=400&h=300&dpr=2
高解像度Retinaモバイル
?w=400&h=300&dpr=3
変換処理順序#
画像変換は以下の順序で処理されます：
- Resize（サイズ調整） - DPR適用
- Rotation（回転）
- Flip/Flop（反転）
- Blur（ブラー効果）
- Grayscale（グレースケール変換）
- Extract（領域抽出）
- Format（フォーマット変換）
複合変換例#
複数の変換を組み合わせることができます：
サイズ調整 + グレースケール + ブラー
?w=400&h=300&grayscale=true&blur=2
領域抽出 + 回転
?extract=25,25,50,50&rotation=90
高解像度ディスプレイ最適化
?w=400&h=300&dpr=2.0&format=webp
モバイルレスポンシブ画像
?w=375&dpr=1.5&format=auto&fit=cover
回転と反転の組み合わせ
?rotation=45&flip=true&blur=1
パフォーマンス & キャッシュ#
CloudFront CDN#
すべての変換された画像は高速配信のためにCloudFront CDNにキャッシュされます：
- 初回リクエスト：元画像を変換してキャッシュ
- 後続リクエスト：キャッシュからの瞬時配信
- キャッシュ期間：1年
Accept ヘッダーベース最適化#
formatパラメータがautoの場合、ブラウザのAcceptヘッダーに基づいて最適なフォーマットが自動選択されます：
- AVIF対応ブラウザ：AVIF形式に変換
- WebP対応ブラウザ：WebP形式に変換
- 標準ブラウザ：JPEG/PNG形式に変換
システム制限と保護機能#
処理制限#
- 最大画像サイズ：4,096 x 4,096ピクセル
- 入力ピクセル制限：268,402,689ピクセル（約16K x 16K）
- ブラー強度：最大20（CPU保護）
- DPR範囲：1.0-4.0
自動フォールバックシステム#
変換中に問題が発生した場合の自動処理：
- パラメータエラー：無効な値の自動修正
- 変換失敗：元画像を返す
- メモリ不足：処理制限でシステム安全性を確保
- フォーマットエラー：デフォルトJPEG形式に変換
メモリ最適化#
- キャッシュ無効：Sharpメモリキャッシュ不使用
- 自動クリーンアップ：処理完了後のSharpライブラリインスタンス自動解放
- 単一処理：メモリ保護のための並行性制限
統合 & 使用#
Next.js統合（近日公開）#
現在開発中です。近日利用可能になります。
最新情報を入手：
- Discord コミュニティ↗に参加
- GitHub リポジトリ↗にスターと フォロー
- ブログで更新をチェック
import { Image } from "@snapkit/nextjs";
<Image
src="https://{organization}-<your-org>-cdn.snapkit.studio/{project}/images/hero.jpg"
alt="Hero"
width={800}
height={600}
transforms={{
blur: 0,
format: "auto",
dpr: 2.0,
}}
/>;レスポンシブ画像実装#
const getResponsiveUrl = (src: string, width: number, mobile = false) => {
const dpr = mobile ? 1.5 : 3.0;
return `${src}?w=${width}&dpr=${dpr}&fit=cover&format=auto`;
};
// 使用例
<picture>
<source media="(min-width: 768px)" srcSet={getResponsiveUrl(baseUrl, 800)} />
<img src={getResponsiveUrl(baseUrl, 400, true)} alt="Responsive" />
</picture>;次のステップ#
- Next.js統合ガイド - @snapkit/nextjsを使用したウェブアプリケーション統合
- Figmaプラグインの使用 - デザインワークフローからの直接画像最適化
- パフォーマンス最適化のヒント - ウェブサイトの読み込み速度を向上させるための戦略