開発者向けドキュメント

クイックスタート

30 秒で最初の画像を圧縮：コンソールで API キーを作成し、リクエストを送信します。

結果は、キーの保有者であるあなただけがアクセスできる暗号化されたプライベートリンクで返されます — 画像は今回の圧縮にのみ使用し、全体を通じて暗号化され、外部に漏れることはなく、学習やその他のいかなる用途にも一切使用しません。

認証

• HTTP Basic（主要な圧縮 API と互換）：ユーザー名は api 固定、パスワードはご自身の API キー — Authorization: Basic base64("api:KEY")
• Bearer（ネイティブレイヤーに推奨）：Authorization: Bearer KEY

キーのプレフィックスは mp_live_（本番）と mp_test_（サンドボックス）です。サーバーはキーのハッシュのみを保存し、完全なキーは作成時に一度だけ表示されます。アカウントごとに最大 5 個まで保持できます。認証失敗は原因を区別せず常に 401 を返します（列挙を防ぐため）。

POST /shrink 画像を圧縮

リクエストボディは次の 2 つのいずれかです：生のバイナリ画像（PNG / JPEG / WebP / HEIC / GIF / BMP / TIFF / AVIF）、またはソース URL を指定する JSON（公開された http/https のアドレスのみ、取得タイムアウトは 10 秒）。出力形式を指定しない場合は元の形式が維持されます：PNG / JPEG / WebP / GIF / TIFF / AVIF は元の形式で出力（AVIF→AVIF、TIFF→TIFF）、HEIC は JPEG に変換、そのままでは圧縮できない BMP は PNG に変換されます。GIF はデフォルトで可逆最適化（GIF のまま）され、さらに節約するために WebP に変換することもできます。

成功すると 201 Created を返し、レスポンスヘッダーには Location（結果のアドレス）と Compression-Count（今月の課金対象枚数）が含まれます：

GET /output/{id} 結果をダウンロード

認証が必要で、圧縮結果のバイナリを返します。結果は暗号化されたプライベートリンクで配信され、リンクの有効期限が切れると 404 OutputExpired を返すので、再圧縮して再取得できます。同じ結果の再ダウンロードには課金されません。

POST /output/{id} 派生操作

圧縮結果に対して resize / convert / preserve を実行します。各派生出力は 1 枚としてカウントされます：

• resize.method：scale（片側を基準に比率保持）/ fit（全体を収める）/ cover（切り抜いて埋める、現在は中央切り抜き）
• convert.type：image/webp、image/png、image/jpeg の間で変換
• preserve：copyright / creation / location のメタデータを保持

POST /v1/compress 同期圧縮（ネイティブレイヤー）

1 回のリクエストで圧縮結果のバイナリを直接返し、往復を省きます — CI に便利です：

• quality：smart（デフォルト）/ high / extreme / 1-100
• format：keep（元の形式を維持）/ webp
• レスポンスヘッダー：X-Input-Size / X-Output-Size / X-Ratio / Compression-Count

GET /v1/usage 利用状況の照会

今月の枚数、残りの無料枠、残りのリソースパック残高を返します — コンソールと同一です：

枠とレート制限

• レート：キーあたり 10 req/s、バースト 20（トークンバケット）。超過すると 429 + Retry-After を返します
• 同時実行：キーあたりの処理中タスク <= 20
• 毎月の無料枠：アカウントあたり 500 枚/月。使い切って支払い登録がない場合、429 AccountLimitReached を返します
• ファイルあたり：無料は 5 MB、有料は 80 MB、Enterprise はカスタマイズ可
• ピクセル：<= 1 億ピクセル。超過すると 422 ImageTooComplex を返します

すべての従量制エンドポイントのレスポンスヘッダー：Compression-Count、X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset。

課金

• POST /shrink 成功（201）：1 枚としてカウント
• POST /v1/compress 成功（200）：1 枚としてカウント
• GET /output/{id} 再ダウンロード：課金なし
• POST /output/{id} 派生操作の成功：1 回ごとに 1 枚としてカウント
• 4xx / 5xx、コンテンツ審査によるブロック、URL 取得失敗：課金なし。再試行が成功した場合は成功した呼び出しのみカウント

消費の順序：プランの月次枠 → リソースパック（購入が早いものから、有効期限なし）。前払い制で、従量制の月次請求はありません — 枠を使い切ると一時停止し、リソースパックを購入すると再開します。

AI / Skill 連携

MiniPic は公式の Agent Skill（minipic-compress）を提供しています。インストールすれば、Anthropic Agent Skills オープン標準に対応した任意の AI エージェント（Claude Code / Cursor / Codex CLI / Copilot CLI など）に「このフォルダの画像を圧縮して」のように伝えるだけで、自動的に MiniPic API を呼び出して圧縮、WebP への変換、バッチ処理を行い、圧縮率を報告します — curl やリトライ処理を手書きする必要はありません。

インストール

次のいずれかを選んでください（3 つの方法）：

Agent Skills 標準に対応する他のエージェント（Cursor / Codex CLI / Copilot CLI など）では、各ドキュメントに従って minipic-compress/ ディレクトリを対応する skills のパスに配置してください。

API キーを設定

キューは環境変数からのみ読み取られ、ハードコードもエコーも一切されません。コンソールでキーを作成したら、環境に設定してください：

範囲とトリガーの例

次のような意図を伝えると、Skill が自動的にトリガーされます：

• 「この画像 / このフォルダの画像を圧縮して」
• 「hero.png を WebP に変換して、できるだけ小さくして」
• 「これらの画像は大きすぎる — パッケージ化の前にまとめて最適化して、どれだけ削減できたか教えて」

機能：単一ファイル / フォルダのバッチ / リモート URL の圧縮、PNG・JPEG・WebP・GIF 間の変換、品質プリセット（smart / high / extreme）の選択、削減率の自動計算と報告、429 レート制限時の自動バックオフ再試行。

VS Code 拡張機能

公式の MiniPic Image Compression 拡張機能を使えば、curl を手書きすることなく、エディター内でワークスペースの画像を直接圧縮できます。MiniPic の自社開発エンジン搭載です。PNG / JPEG / WebP / GIF / AVIF / TIFF に対応し、圧縮しながら形式を変換（WebP / AVIF などに変換してさらに節約）でき、VS Code、Cursor などの互換エディターで動作します。

インストール

次のいずれかを選んでください：

• VS Code の拡張機能パネル（⇧⌘X）で MiniPic を検索してインストールをクリック。
• またはコマンドパレットから ext install minipic.minipic-vscode を実行。
• または Visual Studio Marketplace の拡張機能ページを開いてインストールをクリック。

API キーを設定

コンソールでキー（mp_live_ で始まる）を作成したら、コマンドパレット（⇧⌘P）から MiniPic: Set API Key を実行して貼り付けます。キーは VS Code の SecretStorage に安全に保存され、平文の設定に書き込まれることも settings.json で同期されることも一切ありません。

使い方

• 右クリックで圧縮：エクスプローラーで画像やフォルダを選び（単一、複数選択、またはディレクトリ全体を再帰的に）→ 右クリックして MiniPic: Compress Images で、現在の品質と形式の設定を使ってその場で圧縮します。
• WebP に変換して参照を更新：右クリックして MiniPic: Convert to WebP and Update References で WebP に変換し、ワークスペース全体のその画像への参照を自動で更新します。
• 自動圧縮：有効にすると、ワークスペースの新規 / 変更された画像を監視して自動で圧縮します（枠を消費するためデフォルトはオフ）。ステータスバーまたは MiniPic: Toggle Auto-Compress で切り替えます。
• 利用状況を表示：MiniPic: View Usage を実行すると、今月の圧縮枚数、無料残高、利用見積もりが見られます — コンソールと同一です。

主な設定

エラーコード

エラーボディは主要な圧縮 API の慣例に従います：{"error": "code", "message": "人間が読める説明"}。フィールドは追加のみで、削除されることはありません。