---
url: https://docs.snapotter.com/ja/api/rest.md
description: 完全な REST API リファレンス。ツールエンドポイント、バッチ処理、パイプライン、ファイルライブラリ、認証、チーム、管理者操作。
---

# REST API リファレンス

リクエスト/レスポンスの例を含むインタラクティブな API ドキュメントは <http://localhost:1349/api/docs> で利用できます。

機械可読な仕様:

* `/api/v1/openapi.yaml` - OpenAPI 3.1 仕様
* `/llms.txt` - LLM 向けのサマリー
* `/llms-full.txt` - LLM 向けの完全なドキュメント

## 認証

`AUTH_ENABLED=false`でない限り、すべてのエンドポイントは認証を必要とします。

### セッショントークン

新規インストールでは、以下のツール呼び出しが動作する前に、デフォルトの `admin` アカウントのパスワードを変更する必要があります。[初回ログイン](#first-login)を参照してください。

```bash
# Login
curl -X POST http://localhost:1349/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin"}'
# Returns: {"token":"<session-token>"}

# Use token (tool routes are POST multipart)
curl -X POST http://localhost:1349/api/v1/tools/image/resize \
  -H "Authorization: Bearer <session-token>" \
  -F "file=@photo.jpg" \
  -F 'settings={"width":800}'
```

セッションは 7 日後に期限切れになります（`SESSION_DURATION_HOURS` で設定可能）。

### 初回ログイン

デフォルトの `admin` アカウントがパスワードを変更するまで、そのセッショントークンはほとんどのエンドポイント（ツール呼び出しや API キーの作成を含む）から、エラーコード `MUST_CHANGE_PASSWORD` とともに `403` を受け取ります。管理者がパスワードをリセットしたアカウントも同様です。ログインのレスポンスでは `user.mustChangePassword: true` でこれが示されます。ログインで得たセッショントークンを使ってパスワードを変更します:

```bash
curl -X POST http://localhost:1349/api/auth/change-password \
  -H "Authorization: Bearer <session-token>" \
  -H "Content-Type: application/json" \
  -d '{"currentPassword":"admin","newPassword":"<new-password>"}'
```

リクエストを送信したセッションは有効なままです。そのアカウントの他のセッションはすべてサインアウトされ、API キーもすべて失効します。`SKIP_MUST_CHANGE_PASSWORD=true` を設定するとこの要件は無効になります。CI と開発向けの設定です。

### API キー

```bash
# Create a key (returns key once - store it)
curl -X POST http://localhost:1349/api/v1/api-keys \
  -H "Authorization: Bearer <session-token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-script"}'
# Returns: {"key":"si_<96 hex chars>","id":"...","name":"my-script"}

# Use the key
curl -X POST http://localhost:1349/api/v1/tools/image/resize \
  -H "Authorization: Bearer si_<your-key>" \
  -F "file=@photo.jpg" \
  -F 'settings={"width":800}'
```

キーには `si_` というプレフィックスが付き、scrypt ハッシュとして保存されます。生のキーは一度だけ表示され、二度と取得できません。

### 認証エンドポイント

| メソッド | パス | アクセス | 説明 |
|--------|------|--------|-------------|
| `POST` | `/api/auth/login` | Public | ログインしてセッショントークンを取得 |
| `POST` | `/api/auth/logout` | Auth | 現在のセッションを破棄 |
| `GET` | `/api/auth/session` | Auth | 現在のセッションを検証 |
| `POST` | `/api/auth/change-password` | Auth | 自分のパスワードを変更（他のすべてのセッションと API キーを無効化） |
| `GET` | `/api/auth/users` | Admin | すべてのユーザーを一覧表示 |
| `POST` | `/api/auth/register` | Admin（`users:manage`；提案ロールの権限） | 新しいユーザーを作成 |
| `PUT` | `/api/auth/users/:id` | Admin（`users:manage`；対象への権限） | ユーザーのロールまたはチームを更新 |
| `POST` | `/api/auth/users/:id/reset-password` | Admin（`users:manage`；対象への権限） | ユーザーのパスワードをリセット |
| `DELETE` | `/api/auth/users/:id` | Admin（`users:manage`；対象への権限） | ユーザーを削除 |
| `GET` | `/api/v1/config/auth` | Public | 認証が有効かどうかを確認（`{ authEnabled: bool }`） |
| `POST` | `/api/auth/mfa/enroll` | Auth | TOTP MFA 登録を開始。エンタープライズの `mfa` 機能が必要 |
| `POST` | `/api/auth/mfa/verify` | Auth | TOTP コードで MFA 登録を確定 |
| `POST` | `/api/auth/mfa/complete` | Public | 保留中の MFA ログインチャレンジを完了 |
| `POST` | `/api/auth/mfa/disable` | Auth | 現在のユーザーの MFA を無効化 |
| `POST` | `/api/auth/users/:id/mfa/reset` | Admin（`users:manage`；対象への権限） | ユーザーの MFA をリセット |
| `GET` | `/api/auth/oidc/login` | Public | OIDC が有効なとき OIDC ログインを開始 |
| `GET` | `/api/auth/oidc/callback` | Public | OIDC 認可コールバック |
| `GET` | `/api/auth/saml/metadata` | Public | SAML が有効なときの SAML SP メタデータ XML |
| `GET` | `/api/auth/saml/login` | Public | SAML ログインを開始 |
| `POST` | `/api/auth/saml/callback` | Public | SAML アサーションコンシューマーサービス |

ユーザーに対して MFA が有効な場合、`POST /api/auth/login` はセッショントークンの代わりに `{"requiresMfa":true,"mfaToken":"..."}` を返します。その `mfaToken` と TOTP またはリカバリコードを `/api/auth/mfa/complete` に送信してください。

### パーミッション

| パーミッション | Admin | User |
|-----------|:-----:|:----:|
| ツールを使用 | ✓ | ✓ |
| 自分のファイル/パイプライン/API キー | ✓ | ✓ |
| 全ユーザーのファイル/パイプライン/キーを閲覧 | ✓ | - |
| 設定の書き込み | ✓ | - |
| ユーザーとチームの管理 | ✓ | - |
| ブランディングの管理 | ✓ | - |

## ヘルスチェック

| メソッド | パス | アクセス | 説明 |
|--------|------|--------|-------------|
| `GET` | `/api/v1/health` | Public | 基本的なヘルスチェック。200 で `{"status":"healthy","version":"..."}` を返し、データベースに到達できない場合は 503 で `{"status":"unhealthy"}` を返します。 |
| `GET` | `/api/v1/readyz` | Public | レディネスプローブ。PostgreSQL、Redis、ディスク容量、および設定されている場合は S3 をチェックします。インスタンスがトラフィックを受け取るべきでない場合は 503 を返します。 |
| `GET` | `/api/v1/admin/health` | Admin（`system:health`） | 稼働時間、ストレージモード、データベースステータス、キューの状態、GPU の可用性を含む詳細な診断。 |

## ツールの使用

すべてのツールは同じパターンに従います:

```bash
# Single file
curl -X POST http://localhost:1349/api/v1/tools/<section>/<toolId> \
  -H "Authorization: Bearer <token>" \
  -F "file=@input.jpg" \
  -F 'settings={"width":800,"height":600}'

# Batch (returns ZIP)
curl -X POST http://localhost:1349/api/v1/tools/<section>/<toolId>/batch \
  -H "Authorization: Bearer <token>" \
  -F "files=@a.jpg" \
  -F "files=@b.jpg" \
  -F 'settings={...}'
```

`<section>` は `image`、`video`、`audio`、`pdf`、`files` のいずれかです。

* アップロードは `multipart/form-data` です。
* `settings` はツール固有のオプションを含む JSON 文字列です。
* `clientJobId` は、呼び出し元が指定する進捗相関のためのオプションのフォームフィールドです。
* `fileId` は、既存のファイルライブラリ項目を参照するオプションのフォームフィールドです。存在する場合、処理された出力は新しいバージョンとして保存され、レスポンスに `savedFileId` が含まれます。
* **高速ツール** は通常 200 JSON を返します: `{"jobId":"...","downloadUrl":"/api/v1/download/<jobId>/<filename>","originalSize":1234,"processedSize":567}`。処理されたファイルは `downloadUrl` から取得します。
* **キューに入るツール** は、長時間実行される場合や同期待機ウィンドウを超える場合、202 JSON を返すことがあります: `{"jobId":"...","async":true}`。進捗のために SSE に接続し、完了したらダウンロードします（[進捗トラッキング](#progress-tracking) を参照）。
* **バッチ** ルートは、汎用バッチレジストリに登録されたツールについて、ZIP アーカイブを直接ストリーミングして返します（`X-Job-Id` ヘッダー付き）。

## ツールリファレンス

### 変換プリセット

共有カタログには、`jpg-to-png`、`mov-to-mp4`、`m4a-to-mp3`、`pdf-to-jpg`、`excel-to-csv` など、121 個の専用変換プリセットエンドポイントが含まれています。プリセットはファーストクラスのツールルートです:

`POST /api/v1/tools/<section>/<presetId>`

各プリセットは出力形式を固定し、`convert`、`convert-video`、`extract-audio`、`convert-audio`、`image-to-pdf`、`pdf-to-image`、`svg-to-raster`、`convert-spreadsheet` などのベースツールに委譲します。完全なルートテーブルとオプション設定については、[変換プリセット](/ja/tools/conversion-presets) を参照してください。

圧縮プリセットも同じ仕組みです。`compress-image-to-20kb`、`compress-image-to-50kb`、`compress-image-to-100kb`、`compress-image-to-200kb`、`compress-image-to-500kb` は `compress` を実行し、`compress-pdf-to-100kb`、`compress-pdf-to-200kb`、`compress-pdf-to-500kb`、`compress-pdf-to-1mb`、`compress-pdf-to-2mb` は `compress-pdf` を実行します。どのプリセットも `mode` を `targetSize` に固定し、`targetSizeKb` を名前に含まれるサイズに固定します。

### 基本ツール

| ツール ID | 名前 | 主な設定 |
|---------|------|-------------|
| `resize` | リサイズ | `width`, `height`, `fit`（cover/contain/fill/inside/outside）, `percentage`, `withoutEnlargement`, 加えて 23 種類のソーシャルメディアプリセット |
| `crop` | クロップ | `left`, `top`, `width`, `height`, `unit`（px/percent） |
| `rotate` | 回転と反転 | `angle`, `horizontal`（bool）, `vertical`（bool） |
| `convert` | 変換 | `format`（jpg/png/webp/avif/tiff/gif/heic/heif）, `quality` |
| `compress` | 圧縮 | `mode`（quality/targetSize）, `quality`（1–100）, `targetSizeKb` |

### 最適化

| ツール ID | 名前 | 主な設定 |
|---------|------|-------------|
| `optimize-for-web` | Web 向け最適化 | `format`（webp/jpeg/avif/png）, `quality`, `maxWidth`, `maxHeight`, `progressive`, `stripMetadata` |
| `strip-metadata` | メタデータ削除 | - |
| `edit-metadata` | メタデータ編集 | `title`, `description`, `author`, `copyright`, `keywords`, `gps`（lat/lon）, `dateTime` |
| `bulk-rename` | 一括リネーム | `pattern`（`{n}`, `{date}`, `{original}` に対応）, `startIndex`, `padding` |
| `image-to-pdf` | 画像から PDF | `pageSize`（A4/Letter/...）, `orientation`, `margin`, `targetSize`（{value, unit}） |
| `favicon` | ファビコンジェネレーター | `padding`, `backgroundColor`, `borderRadius` - 標準サイズをすべて生成 |

### 調整

| ツール ID | 名前 | 主な設定 |
|---------|------|-------------|
| `adjust-colors` | 色の調整 | `brightness`, `contrast`, `exposure`, `saturation`, `temperature`, `tint`, `hue`, `sharpness`, `red`, `green`, `blue`, `effect`（none/grayscale/sepia/invert） |
| `sharpening` | シャープニング | `method`（adaptive/unsharp-mask/high-pass）, `sigma`, `m1`, `m2`, `x1`, `y2`, `y3`, `amount`, `radius`, `threshold`, `strength`, `kernelSize`（3/5）, `denoise`（off/light/medium/strong） |
| `replace-color` | 色の置換 | `sourceColor`, `targetColor`（置換色）, `makeTransparent`, `tolerance` |
| `color-blindness` | 色覚異常シミュレーション | `simulationType`（protanopia/deuteranopia/tritanopia/protanomaly/deuteranomaly/tritanomaly/achromatopsia/blueConeMonochromacy、デフォルト "deuteranomaly"） |
| `duotone` | デュオトーン | `shadow`（hex）, `highlight`（hex）, `intensity`（0-100） |
| `pixelate` | ピクセレート | `blockSize`（2-128）, `region`（部分的なピクセレートのための {left, top, width, height}） |
| `vignette` | ビネット | `strength`（0.1-1）, `color`（hex）, `radius`, `softness`, `roundness`, `centerX`, `centerY` |

### AI ツール

すべての AI ツールはお使いのハードウェア上で動作します。デフォルトでは CPU、サポートされている NVIDIA GPU が利用可能な場合は NVIDIA CUDA を使用します。VA-API、Quick Sync、OpenCL による Intel/AMD iGPU アクセラレーションは、現在 AI 推論ではサポートされていません。インターネット接続は不要です。

| ツール ID | 名前 | AI モデル | 主な設定 |
|---------|------|---------|-------------|
| `remove-background` | 背景の削除 | rembg（BiRefNet / U2-Net） | フェーズ 1: `model`, `edgeRefine`（0-3）, `decontaminate`。フェーズ 2（`/api/v1/tools/image/remove-background/effects`）、`/batch`、およびパイプライン: `backgroundType`（transparent/color/gradient/blur、`/effects` ではさらに image）, `backgroundColor`, `gradientColor1`, `gradientColor2`, `gradientAngle`, `blurEnabled`, `blurIntensity`, `shadowEnabled`, `shadowOpacity`, `outputFormat`（png/webp/avif） |
| `remove-gif-background` | GIF 背景の削除 | rembg（フレームごと） | `model`, `outputFormat`（webp/gif/apng）, `backgroundType`（transparent/color/gradient/blur/image）, `backgroundColor`, `gradientColor1`, `gradientColor2`, `gradientAngle`, `blurIntensity`（0-100）, `shadowEnabled`, `shadowOpacity`（0-100）, `edgeRefine`（0-3）, `decontaminate` |
| `upscale` | 画像のアップスケール | RealESRGAN | `scale`（2/4）, `model`, `faceEnhance`, `denoise`, `format`, `quality` |
| `erase-object` | オブジェクト消しゴム | LaMa（ONNX） | マスクは 2 番目のファイルパートとして送信（フィールド名 `mask`）, `format`, `quality` |
| `ocr` | OCR / テキスト抽出 | Tesseract (高速); RapidOCR + PP-OCR ONNX (バランス/ベスト) | `quality` (高速/バランス/最高)、`language`、`enhance` |
| `blur-faces` | 顔 / PII ぼかし | MediaPipe | `blurRadius`, `sensitivity` |
| `smart-crop` | スマートクロップ | MediaPipe + Sharp | `mode`（subject/face/trim）, `strategy`（attention/entropy）, `width`, `height`, `padding`, `facePreset`（closeup/head-shoulders/upper-body/half-body）, `sensitivity`, `threshold`, `padToSquare`, `padColor`, `targetSize`, `quality` |
| `image-enhancement` | 画像の強調 | 解析ベース | `mode`（auto/exposure/contrast/color/sharpness）, `strength` |
| `enhance-faces` | 顔の強調 | GFPGAN / CodeFormer | `model`（gfpgan/codeformer）, `strength`, `sensitivity`, `centerFace` |
| `colorize` | AI カラー化 | DDColor | `intensity`, `model` |
| `noise-removal` | ノイズ除去 | 段階的デノイズ | `tier`（quick/balanced/quality/maximum）, `strength`, `detailPreservation`, `colorNoise`, `format`, `quality` |
| `red-eye-removal` | 赤目除去 | 顔ランドマーク + 色解析 | `sensitivity`, `strength` |
| `restore-photo` | 写真復元 | 複数ステップのパイプライン | `mode`（auto/light/heavy）, `scratchRemoval`, `faceEnhancement`, `fidelity`, `denoise`, `denoiseStrength`, `colorize` |
| `passport-photo` | パスポート写真 | MediaPipe ランドマーク | 2 フェーズフロー。解析はマルチパート `file` を使用。生成は `countryCode`, `bgColor`, `printLayout`（none/4x6/a4）, ランドマーク, 画像寸法を含む JSON を使用 |
| `content-aware-resize` | コンテンツ認識リサイズ | シームカービング（caire） | `width`, `height`, `protectFaces`, `blurRadius`, `sobelThreshold`, `square` |
| `transparency-fixer` | PNG 透明度フィクサー | BiRefNet HR-matting | `defringe`（0-100）, `outputFormat`（png/webp） |
| `background-replace` | 背景の置き換え | rembg（BiRefNet） | `backgroundType`（color/gradient）, `color`（hex）, `gradientColor1`, `gradientColor2`, `gradientAngle`, `feather`（0-20）, `format`（png/webp） |
| `blur-background` | 背景ぼかし | rembg（BiRefNet） | `intensity`（1-100）, `feather`（0-20）, `format`（png/webp） |
| `ai-canvas-expand` | AI キャンバス拡張 | LaMa（アウトペインティング） | `extendTop`, `extendRight`, `extendBottom`, `extendLeft`（px）, `tier`（fast/balanced/high）, `format`, `quality` |

### ウォーターマークとオーバーレイ

| ツール ID | 名前 | 主な設定 |
|---------|------|-------------|
| `watermark-text` | テキストウォーターマーク | `text`, `font`, `fontSize`, `color`, `opacity`, `position`, `rotation`, `tile` |
| `watermark-image` | 画像ウォーターマーク | `opacity`, `position`, `scale` - 2 番目のファイルがウォーターマーク |
| `text-overlay` | テキストオーバーレイ | `text`, `font`, `fontSize`, `color`, `x`, `y`, `background`, `padding`, `borderRadius` |
| `compose` | 画像合成 | `x`, `y`, `opacity`, `blend` - 2 番目のファイルが上にレイヤーされる |
| `meme-generator` | ミームジェネレーター | `templateId`, `textLayout`（top-bottom/top-only/bottom-only/center/side-by-side）, `textBoxes`（\[{id, text}]）, `fontFamily`（anton/arial-black/comic-sans/montserrat/bebas-neue/permanent-marker/roboto）, `fontSize`, `textColor`, `strokeColor`, `textAlign`, `allCaps`。テンプレートモード（`templateId` を含む JSON ボディ）またはカスタム画像モード（ファイル付きマルチパート）に対応。 |

### ユーティリティ

| ツール ID | 名前 | 主な設定 |
|---------|------|-------------|
| `info` | 画像情報 | -（width, height, format, size, channels, hasAlpha, DPI, EXIF を返す） |
| `compare` | 画像比較 | `mode`（side-by-side/overlay/diff）, `diffThreshold` - 2 番目のファイルが比較対象 |
| `find-duplicates` | 重複の検出 | `threshold`（知覚ハッシュ距離、デフォルト 8） - 複数ファイル |
| `color-palette` | カラーパレット | `count`（主要色の数）, `format`（hex/rgb） |
| `qr-generate` | QR コードジェネレーター | `data`, `size`, `margin`, `colorDark`, `colorLight`, `errorCorrectionLevel`, `dotStyle`, `cornerStyle`, `logo`（オプションのファイル） |
| `barcode-read` | バーコードリーダー | -（QR, EAN, Code128, DataMatrix などを自動検出） |
| `image-to-base64` | 画像から Base64 | `format`（data-uri/plain）, `mimeType` |
| `html-to-image` | HTML から画像 | `url`, `format`（png/jpg/webp）, `quality`, `fullPage`, `devicePreset`（desktop/tablet/mobile/custom）, `viewportWidth`, `viewportHeight` |
| `histogram` | ヒストグラム | `scale`（linear/log） - RGB ヒストグラムチャートとチャンネルごとの統計を返す |
| `lqip-placeholder` | LQIP プレースホルダー | `width`（4-64）, `blur`, `strategy`（blur/pixelate/solid）, `format`（webp/png/jpeg）, `quality` |
| `barcode-generate` | バーコードジェネレーター | `text`, `type`（code128/ean13/upca/code39/itf14/datamatrix）, `scale`（1-8）, `includeText`（bool）。JSON ボディ、ファイルアップロードなし。 |
| `aspect-ratio-calculator` | アスペクト比計算機 | `width`, `height`, `newWidth`, `newHeight`, `round`（bool）。JSON ボディ、ファイルアップロードなし。不明な値を返します。 |

### レイアウトと構成

| ツール ID | 名前 | 主な設定 |
|---------|------|-------------|
| `collage` | コラージュ / グリッド | `template`（25 以上のレイアウト）, `gap`, `backgroundColor`, `borderRadius` - 複数ファイル |
| `stitch` | 連結 / 結合 | `direction`（horizontal/vertical/grid）, `gap`, `backgroundColor`, `alignment` - 複数ファイル |
| `split` | 画像分割 | `mode`（grid/rows/cols）, `rows`, `cols`, `tileWidth`, `tileHeight` |
| `border` | ボーダーとフレーム | `width`, `color`, `style`（solid/gradient/pattern）, `borderRadius`, `padding`, `shadow` |
| `beautify` | スクリーンショットの装飾 | `backgroundType`（solid/linear-gradient/radial-gradient/image/transparent）, `gradientStops`, `padding`, `borderRadius`, `shadowPreset`, `frame`（none/macos-light/macos-dark/windows-light/windows-dark/browser-light/browser-dark/iphone/macbook/ipad/...）, `socialPreset`（none/twitter/linkedin/instagram-square/instagram-story/facebook/producthunt）, `watermarkText`, `outputFormat` |
| `circle-crop` | 円形クロップ | `zoom`（1-5）, `offsetX`, `offsetY`, `borderWidth`, `borderColor`, `background`（transparent/hex）, `outputSize` |
| `rounded-crop` | 角丸クロップ | `shape`（rounded-square/squircle）, `cornerRadius`（0-50、短辺に対する割合）, `zoom`（1-5）, `offsetX`, `offsetY`, `borderWidth`, `borderColor`, `background`（transparent/hex）, `outputSize` |
| `image-pad` | 画像パディング | `target`（16:9/9:16/1:1/4:3/3:4/custom）, `ratioW`, `ratioH`, `background`（color/transparent/blur）, `color`（hex）, `padding`（0-50%） |
| `sprite-sheet` | スプライトシート | `columns`（1-16）, `padding`, `background`（hex）, `format`（png/webp/jpeg）, `quality` - 複数ファイル（2-64 枚の画像） |

### 形式と変換

| ツール ID | 名前 | 主な設定 |
|---------|------|-------------|
| `svg-to-raster` | SVG からラスター | `format`（png/jpeg/webp/avif/tiff/gif/heif）, `width`, `height`, `scale`, `dpi`, `background` |
| `vectorize` | 画像から SVG | `colorMode`（bw/color）, `threshold`, `colorPrecision`, `filterSpeckle`, `pathMode`（none/polygon/spline） |
| `gif-tools` | GIF ツール | `mode`（resize/optimize/speed/reverse/extract/rotate）, `width`, `height`, `percentage`, `colors`（2/4/16/256）, `dither`, `effort`, `speedFactor`, `extractMode`（single/range/all）, `frameNumber`, `frameStart`, `frameEnd`, `extractFormat`（png/webp）, `angle`（90/180/270）, `flipH`, `flipV`, `loop` |
| `gif-webp` | GIF/WebP コンバーター | `quality`（1-100）, `lossless`（bool）, `resizePercent`（10-100） |

### 動画ツール

| ツール ID | 名前 | 主な設定 |
|---------|------|-------------|
| `convert-video` | 動画の変換 | `format`（mp4/mov/webm/avi/mkv）, `quality`（high/balanced/small） |
| `compress-video` | 動画の圧縮 | `quality`（light/balanced/strong）, `resolution`（original/1080p/720p/480p） |
| `trim-video` | 動画のトリミング | `mode`（range/ends）, `startS`, `endS`, `cutStartS`, `cutEndS`, `precise`（bool、フレーム精度のカット） |
| `mute-video` | 動画のミュート | - |
| `video-to-gif` | 動画から GIF | `fps`（1-30）, `width`, `startS`, `durationS`（最大 60 秒） |
| `resize-video` | 動画のリサイズ | `width`, `height`, `preset`（custom/2160p/1440p/1080p/720p/480p/360p） |
| `crop-video` | 動画のクロップ | `width`, `height`, `x`, `y` |
| `rotate-video` | 動画の回転 | `transform`（cw90/ccw90/180/hflip/vflip） |
| `change-fps` | FPS の変更 | `fps`（1-120） |
| `video-color` | 動画の色調整 | `brightness`, `contrast`, `saturation`, `gamma` |
| `video-speed` | 動画の速度 | `factor`（0.25-4）, `keepPitch`（bool） |
| `reverse-video` | 動画の逆再生 | -（最大 5 分） |
| `video-loudnorm` | 音声のノーマライズ | -（EBU R128） |
| `aspect-pad` | アスペクトパディング | `target`（16:9/9:16/1:1/4:3/3:4）, `color`（hex） |
| `blur-pad` | ぼかしパディング | `target`（16:9/9:16/1:1/4:3/3:4）, `blur`（2-50） |
| `watermark-video` | 動画のウォーターマーク | `text`, `position`, `fontSize`, `opacity`, `color` |
| `stabilize-video` | 動画の手ぶれ補正 | `smoothing`（5-60、フレーム単位） |
| `gif-to-video` | GIF から動画 | `format`（mp4/webm/mov） |
| `video-to-webp` | 動画から WebP | `fps`, `width`, `quality`, `loop`（bool） |
| `video-to-avif` | 動画を AVIF に変換 | `fps`（1-30）, `width`（64-1280）, `startS`, `durationS`（最大 60 秒）, `quality`（1-100）, `loop`（bool） |
| `video-to-frames` | 動画からフレーム | `mode`（all/nth/timestamps）, `n`, `timestamps`, `format`（png/jpg） |
| `merge-videos` | 動画の結合 | -（複数ファイル、最初の動画の解像度にノーマライズ） |
| `replace-audio` | 音声の置き換え | -（動画 + 音声ファイル、2 ファイル） |
| `burn-subtitles` | 字幕の焼き込み | `fontSize`（8-72） - 動画 + 字幕ファイル |
| `embed-subtitles` | 字幕の埋め込み | `language`（ISO 639-2/B コード） - 動画 + 字幕ファイル |
| `extract-subtitles` | 字幕の抽出 | -（SRT を出力） |
| `convert-subtitles` | 字幕変換 | `format`（srt/vtt/ass）, `encoding`（auto/utf-8/windows-1252/windows-1250/windows-1251/windows-1256/iso-8859-2/gb18030/big5/shift_jis/euc-kr） |
| `images-to-video` | 画像から動画 | `secondsPerImage`（0.5-10）, `resolution`（1080p/720p/square）, `fps` - 複数ファイル |
| `video-metadata` | 動画メタデータのクリーン | - |
| `auto-subtitles` | 自動字幕（AI） | `language`（auto/en/de/fr/es/zh/ja/ko/id/th/vi）, `format`（srt/vtt） |
| `extract-audio` | 音声の抽出 | `format`（mp3/wav/m4a/ogg） |

### 音声ツール

| ツール ID | 名前 | 主な設定 |
|---------|------|-------------|
| `convert-audio` | 音声の変換 | `format`（mp3/wav/ogg/flac/m4a）, `bitrateKbps`（32-320） |
| `trim-audio` | 音声のトリミング | `mode`（range/ends）, `startS`, `endS`, `cutStartS`, `cutEndS` |
| `volume-adjust` | 音量調整 | `gainDb`（-30 から 30） |
| `normalize-audio` | 音声のノーマライズ | -（EBU R128、-16 LUFS） |
| `fade-audio` | 音声のフェード | `fadeInS`（0-30）, `fadeOutS`（0-30） |
| `reverse-audio` | 音声の逆再生 | - |
| `audio-speed` | 音声の速度 | `factor`（0.25-4） |
| `pitch-shift` | ピッチシフト | `semitones`（-12 から 12） |
| `audio-channels` | 音声チャンネル | `mode`（stereo-to-mono/mono-to-stereo/swap） |
| `silence-removal` | 無音の除去 | `thresholdDb`（-80 から -20）, `minSilenceS`（0.1-5） |
| `noise-reduction` | ノイズ低減 | `strength`（light/medium/strong） |
| `merge-audio` | 音声の結合 | `format`（mp3/wav/flac/m4a） - 複数ファイル |
| `split-audio` | 音声の分割 | `mode`（time/parts/silence）, `segmentS`, `parts`, `thresholdDb`, `minSilenceS` |
| `ringtone-maker` | 着信音メーカー | `startS`, `durationS`（1-30） |
| `waveform-image` | 波形画像 | `width`, `height`, `color`（hex） |
| `audio-metadata` | 音声メタデータ | `strip`（bool）, `title`, `artist`, `album` |
| `transcribe-audio` | 音声の文字起こし（AI） | `language`（auto/en/de/fr/es/zh/ja/ko/id/th/vi）, `outputFormat`（txt/srt/vtt） |

### ドキュメントツール

| ツール ID | 名前 | 主な設定 |
|---------|------|-------------|
| `merge-pdf` | PDF の結合 | -（複数ファイル、最大 20 個の PDF） |
| `split-pdf` | PDF の分割 | `mode`（range/every）, `range`, `everyN`（1-500） |
| `compress-pdf` | PDF の圧縮 | `mode`（quality/targetSize）, `quality`（1-100）, `targetSizeKb` |
| `rotate-pdf` | PDF の回転 | `angle`（90/180/270）, `range`（ページ範囲） |
| `extract-pages` | ページの抽出 | `range`（qpdf 構文、例 "1-5,8,10-z"） |
| `remove-pages` | ページの削除 | `pages`（削除する qpdf 範囲） |
| `organize-pdf` | PDF の整理 | `order`（qpdf ページ順、例 "3,1,2,5-z"） |
| `multi-tool-pdf` | PDF マルチツール | `items`（ページ構成、`[{doc, page, rot}]`、最大 1200 ページ）, `pageCounts` - 複数ファイル（最大 20 個の PDF） |
| `protect-pdf` | PDF の保護 | `userPassword`, `ownerPassword`（AES-256） |
| `unlock-pdf` | PDF のロック解除 | `password` |
| `repair-pdf` | PDF の修復 | - |
| `linearize-pdf` | PDF の Web 最適化 | -（高速な Web 表示のためにリニアライズ） |
| `grayscale-pdf` | PDF のグレースケール化 | - |
| `pdfa-convert` | PDF/A 変換 | -（アーカイブ用 PDF/A-2） |
| `crop-pdf` | PDF のクロップ | `margin`（0-2000 ポイント） |
| `resize-pdf-pages` | PDF ページサイズ変更 | `pageSize` (`4x6in`, `100x150mm`, `a4`, `a5`, `a6`, `letter`, `legal`, `custom`), `width`, `height`, `unit` (`in`, `mm`), `keepOrientation` |
| `nup-pdf` | N-up PDF | `perSheet`（2/3/4/8/9/12/16） |
| `booklet-pdf` | ブックレット PDF | `perSheet`（2/4/6/8） |
| `watermark-pdf` | PDF のウォーターマーク | `text`, `position`, `fontSize`, `opacity`, `rotation` |
| `pdf-page-numbers` | PDF ページ番号 | `position`（bl/bc/br/tl/tc/tr）, `fontSize` |
| `flatten-pdf` | PDF のフラット化 | -（フォームと注釈を焼き込む） |
| `redact-pdf` | PDF の墨消し | `terms`（string\[]）, `caseSensitive`（bool） |
| `sign-pdf` | PDF の署名 | PDF `file`、署名ファイル `sig0`、`sig1`、`placements` JSON 配列を含むカスタムマルチパートルート |
| `pdf-to-text` | PDF からテキスト | - |
| `pdf-to-word` | PDF から Word | - |
| `pdf-to-markdown` | PDF から Markdown | -（`.md` ファイルを出力） |
| `pdf-metadata` | PDF メタデータ | `title`, `author`, `subject`, `keywords`, `stripAll` |
| `convert-document` | ドキュメントの変換 | `format`（docx/odt/rtf/txt） |
| `convert-presentation` | プレゼンテーションの変換 | `format`（pptx/odp） |
| `convert-spreadsheet` | スプレッドシートの変換 | `format`（xlsx/ods/csv） |
| `excel-to-pdf` | Excel から PDF | - |
| `word-to-pdf` | Word から PDF | - |
| `powerpoint-to-pdf` | PowerPoint から PDF | - |
| `html-to-pdf` | HTML から PDF | -（リモートリソースは無効） |
| `markdown-to-docx` | Markdown から Word | - |
| `markdown-to-html` | Markdown から HTML | - |
| `markdown-to-pdf` | Markdown から PDF | -（リモートリソースは無効） |
| `epub-convert` | EPUB の変換 | `format`（pdf/docx/html/md） |
| `to-epub` | EPUB への変換 | -（.docx, .md, .html, .txt を受け付け） |
| `ocr-pdf` | PDF OCR（AI） | `quality`（fast/balanced/best）, `language`（auto/en/de/fr/es/zh/ja/ko）, `pages` |
| `pdf-to-image` | PDF から画像 | `pages`（all/range）, `format`, `dpi`, `quality` |
| `pdf-to-jpg` | PDF から JPG | `pages`, `dpi`, `quality`, `colorMode` |
| `pdf-to-png` | PDF から PNG | `pages`, `dpi`, `quality`, `colorMode` |
| `pdf-to-tiff` | PDF から TIFF | `pages`, `dpi`, `quality`, `colorMode` |

### ファイルツール

| ツール ID | 名前 | 主な設定 |
|---------|------|-------------|
| `chart-maker` | チャートメーカー | `kind`（bar/line/pie）, `title`, `width`, `height` |
| `csv-excel` | CSV から Excel | `sheet`（XLSX 入力のワークシート番号） - 双方向 |
| `csv-json` | CSV から JSON | `pretty`（bool） - 双方向 |
| `json-xml` | JSON から XML | `pretty`（bool） - 双方向 |
| `split-csv` | CSV の分割 | `rowsPerFile`（1-1000000）, `keepHeader`（bool） |
| `merge-csvs` | CSV の結合 | -（複数ファイル、列が一致するもの） |
| `merge-text` | テキストファイル結合 | `separator`（blank-line/rule/filename-heading） - 複数ファイル、2-50 ファイル |
| `yaml-json` | YAML / JSON | -（双方向） |
| `xml-to-csv` | XML から CSV | -（繰り返し要素を自動検出） |
| `convert-font` | フォント変換 | `format` (ttf, otf, woff, woff2) |
| `convert-case` | 大文字・小文字変換 | `text`, `mode`（upper/lower/sentence/title/capitalized/inverse/alternating/camel/pascal/snake/kebab）, `locale`（BCP 47 タグ）。JSON ボディ、ファイルアップロードなし。変換後のテキストを返します。 |
| `proportion-calculator` | 比例計算機 | `a`, `b`, `c`, `mode`（direct/inverse）。JSON ボディ、ファイルアップロードなし。不明な値を返します。 |
| `base64` | Base64 エンコード / デコード | `text`, `mode`（encode/decode）, `urlSafe`（bool）。JSON ボディ、ファイルアップロードなし。変換後のテキストを返します。 |
| `excel-to-csv` | Excel から CSV | `convert-spreadsheet` を基盤とする専用の変換プリセット |
| `otf-to-ttf` | OTF から TTF | `convert-font` を基盤とする専用の変換プリセット |
| `woff-to-ttf` | WOFF から TTF | `convert-font` を基盤とする専用の変換プリセット |
| `woff2-to-ttf` | WOFF2 から TTF | `convert-font` を基盤とする専用の変換プリセット |
| `ttf-to-woff2` | TTF から WOFF2 | `convert-font` を基盤とする専用の変換プリセット |
| `create-zip` | ZIP の作成 | -（複数ファイル、2-50 ファイル） |
| `extract-zip` | ZIP の展開 | -（ボム対策済み） |

### HTML から画像

Web ページを画像としてキャプチャします。他のツールと異なり、このエンドポイントはマルチパートフォームデータの代わりに `application/json` を受け付けます（ファイルアップロードは不要）。

**エンドポイント:** `POST /api/v1/tools/image/html-to-image`

**Content-Type:** `application/json`

| パラメータ | 型 | デフォルト | 説明 |
|-----------|------|---------|-------------|
| `url` | string | （必須） | キャプチャする URL（http/https のみ） |
| `format` | string | `"png"` | 出力形式: `jpg`, `png`, `webp` |
| `quality` | number | `90` | 品質 1-100（JPG/WebP のみ） |
| `fullPage` | boolean | `false` | スクロール可能なページ全体をキャプチャ |
| `devicePreset` | string | `"desktop"` | `desktop`, `tablet`, `mobile`, `custom` |
| `viewportWidth` | number | `1280` | カスタムビューポート幅 320-3840 |
| `viewportHeight` | number | `720` | カスタムビューポート高さ 320-2160 |
| `clientJobId` | string | （自動生成） | 独自のジョブ ID。レスポンスが届く前に進捗ストリームを開けます |

**例:**

```bash
curl -X POST http://localhost:1349/api/v1/tools/image/html-to-image \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://snapotter.com", "format": "png", "devicePreset": "desktop"}'
```

**レスポンス:**

```json
{
  "jobId": "uuid",
  "downloadUrl": "/api/v1/download/{jobId}/screenshot.png",
  "originalSize": 0,
  "processedSize": 54321
}
```

キャプチャはキューに入ったジョブとして実行されます。同期待機時間内に完了すると、上記の結果が `200` で返ります。時間のかかるキャプチャは `{"jobId":"...","async":true}` とともに `202` を返します。[進捗トラッキング](#progress-tracking) の説明に従って追跡してください。2.3.0 まではこのエンドポイントは常に完了を待って `200` を返していたため、`200` だけを処理するスクリプトは `202` も処理する必要があります。

### ツールのサブルート

一部のツールは、標準の `POST /api/v1/tools/<section>/<toolId>` 以外に追加のエンドポイントを公開します:

| メソッド | パス | 説明 |
|--------|------|-------------|
| `GET` | `/api/v1/tools/popular` | 人気のツール ID を返す。使用データが乏しい場合はキュレーションされたデフォルトリストにフォールバック |
| `POST` | `/api/v1/tools/image/remove-background/effects` | AI を再実行せずに背景エフェクト（color/gradient/blur/shadow）を適用。初回削除時のキャッシュされたマスクを使用。 |
| `POST` | `/api/v1/tools/image/edit-metadata/inspect` | 画像から既存の EXIF/IPTC/XMP メタデータを読み取る |
| `POST` | `/api/v1/tools/image/strip-metadata/inspect` | 削除前にメタデータフィールドを確認 |
| `POST` | `/api/v1/tools/image/passport-photo/analyze` | フェーズ 1: AI 顔検出 + 背景削除。顔ランドマークとキャッシュデータを返す。 |
| `POST` | `/api/v1/tools/image/passport-photo/generate` | フェーズ 2: キャッシュされた解析を使ってクロップ、リサイズ、タイル化。AI の再実行なし。 |
| `POST` | `/api/v1/tools/image/gif-tools/info` | GIF メタデータ（フレーム数、寸法、再生時間）を取得 |
| `POST` | `/api/v1/tools/pdf/pdf-to-image/info` | PDF メタデータ（ページ数、寸法）を取得 |
| `POST` | `/api/v1/tools/pdf/pdf-to-image/preview` | 特定の PDF ページのプレビューを生成 |
| `POST` | `/api/v1/tools/pdf/pdf-to-jpg/info` | 専用の JPG プリセット向けの PDF メタデータを取得 |
| `POST` | `/api/v1/tools/pdf/pdf-to-jpg/preview` | JPG プリセットの PDF ページプレビューを生成 |
| `POST` | `/api/v1/tools/pdf/pdf-to-png/info` | 専用の PNG プリセット向けの PDF メタデータを取得 |
| `POST` | `/api/v1/tools/pdf/pdf-to-png/preview` | PNG プリセットの PDF ページプレビューを生成 |
| `POST` | `/api/v1/tools/pdf/pdf-to-tiff/info` | 専用の TIFF プリセット向けの PDF メタデータを取得 |
| `POST` | `/api/v1/tools/pdf/pdf-to-tiff/preview` | TIFF プリセットの PDF ページプレビューを生成 |
| `POST` | `/api/v1/tools/image/svg-to-raster/batch` | 複数の SVG を一括でラスターに変換 |
| `POST` | `/api/v1/tools/image/image-enhancement/analyze` | 画像品質を解析し、強調の推奨事項を返す |
| `POST` | `/api/v1/tools/image/optimize-for-web/preview` | ライブパラメータ調整のための軽量プレビュー。サイズヘッダー付きの最適化された画像を返す。 |

## バッチ処理

汎用のバッチ対応ツールを複数のファイルに一度に適用します。ZIP アーカイブを返します。PDF 署名や PDF から画像へのプリセットルートなど、カスタムの複数ファイルまたは複数ステップのルートは、汎用の `/batch` ルートの代わりに独自のエンドポイント契約を使用します。

`ocr-pdf` ツールは、この汎用 `/batch` ルートをサポートします。

```bash
curl -X POST http://localhost:1349/api/v1/tools/image/compress/batch \
  -H "Authorization: Bearer <token>" \
  -F "files=@a.jpg" \
  -F "files=@b.jpg" \
  -F "files=@c.jpg" \
  -F 'settings={"quality":80}'
```

並列度は `CONCURRENT_JOBS` で制御されます（デフォルト: CPU コアから自動検出）。`MAX_BATCH_SIZE` はバッチあたりのファイル数を制限します（デフォルト: 100、無制限にするには 0 を設定）。

## パイプライン

### パイプラインの実行

```bash
# Single file
curl -X POST http://localhost:1349/api/v1/pipeline/execute \
  -H "Authorization: Bearer <token>" \
  -F "file=@input.jpg" \
  -F 'pipeline={"steps":[
    {"toolId":"resize","settings":{"width":1200}},
    {"toolId":"compress","settings":{"quality":80}},
    {"toolId":"watermark-text","settings":{"text":"© 2025"}}
  ]}'

# Batch (multiple files → ZIP)
curl -X POST http://localhost:1349/api/v1/pipeline/batch \
  -H "Authorization: Bearer <token>" \
  -F "files=@a.jpg" \
  -F "files=@b.jpg" \
  -F 'pipeline={"steps":[{"toolId":"resize","settings":{"width":800}}]}'
```

各ステップの出力が次のステップの入力になります。パイプラインはデフォルトで 20 ステップまで許可され、`MAX_PIPELINE_STEPS` で設定可能です。`MAX_PIPELINE_STEPS=0` を設定すると制限が解除されます。

### パイプラインの保存と管理

| メソッド | パス | 説明 |
|--------|------|-------------|
| `POST` | `/api/v1/pipeline/save` | 名前付きパイプラインを保存（`name`, `description`, `steps[]`） |
| `GET` | `/api/v1/pipeline/list` | 保存済みパイプラインを一覧表示（管理者はすべて、ユーザーは自分のものを閲覧） |
| `DELETE` | `/api/v1/pipeline/:id` | 削除（所有者または管理者） |
| `GET` | `/api/v1/pipeline/tools` | パイプラインステップに有効なツール ID を一覧表示 |

## 進捗トラッキング

長時間実行されるジョブ、キューに入るツール、バッチジョブ、パイプラインは、Server-Sent Events を介してリアルタイムの進捗を送信します。このストリームには他のエンドポイントと同様に認証が必要です。`Authorization` ヘッダーでセッショントークンまたは API キーを送信してください（ブラウザーはセッション Cookie を利用できます）。読み取れるのは、ジョブの所有者、`files:all` を持つユーザー、および機能インストールジョブの場合は `features:manage` を持つユーザーだけです。それ以外の呼び出し元には `404` が返ります。

```bash
# Connect to the SSE stream (jobId is in the JSON response body from the tool endpoint)
curl -N http://localhost:1349/api/v1/jobs/<jobId>/progress \
  -H "Authorization: Bearer <token>"
```

イベント形式:

```
data: {"jobId":"...","type":"single","phase":"processing","stage":"Upscaling","percent":42}
data: {"jobId":"...","type":"single","phase":"complete","percent":100,"result":{"downloadUrl":"/api/v1/download/..."}}
data: {"jobId":"...","type":"batch","status":"processing","completedFiles":2,"totalFiles":5,"failedFiles":0,"errors":[]}
```

`POST /api/v1/jobs/:jobId/cancel` を使って、キューに入っているまたは実行中のジョブのキャンセルをリクエストできます。レスポンスは `{"canceled":true|false}` です。

### ジョブのステータス

`GET /api/v1/jobs/:jobId` は、接続を開いたままにせずにジョブの保存済みの状態を返します。`202` レスポンスの後にポーリングするか、ストリームが切れたときの代替手段として使ってください。アクセスルールは進捗ストリームと同じです。

```bash
curl http://localhost:1349/api/v1/jobs/<jobId> \
  -H "Authorization: Bearer <token>"
# Returns: {"jobId":"...","status":"completed","createdAt":"...","progress":{"percent":100},"result":{"downloadUrl":"/api/v1/download/..."},"progressUrl":"/api/v1/jobs/.../progress"}
```

`status` は `queued`、`processing`、`completed`、`failed`、`canceled` のいずれかです。失敗したジョブには `error.message` が含まれ、ある場合は `error.code` も含まれます。キャンセルされたジョブでも、完了したファイルの ZIP などの部分的な `result` を持つことがあるため、`result` が存在する場合は常に読み取ってください。

## ファイルライブラリ

バージョン履歴付きの永続的なファイルストレージ。

| メソッド | パス | 説明 |
|--------|------|-------------|
| `POST` | `/api/v1/upload` | ワークスペースにファイルをアップロード（一時的な処理用） |
| `POST` | `/api/v1/files/upload` | 永続的なファイルライブラリにファイルをアップロード |
| `POST` | `/api/v1/files/save-result` | ツール処理の結果を新しいファイルバージョンとして保存 |
| `GET` | `/api/v1/files` | 保存済みファイルを一覧表示（ページネーション、検索付き） |
| `GET` | `/api/v1/files/:id` | ファイルメタデータ + バージョンチェーンを取得 |
| `GET` | `/api/v1/files/:id/download` | ファイルをダウンロード |
| `GET` | `/api/v1/files/:id/thumbnail` | 300px の JPEG サムネイルを取得 |
| `DELETE` | `/api/v1/files` | ファイルとそのバージョンチェーンを一括削除（ボディ: `{ ids: [...] }`） |
| `POST` | `/api/v1/files/download` | 複数のファイルを 1 つの ZIP でダウンロード（ボディ: `{ ids: [...] }`） |
| `POST` | `/api/v1/fetch-urls` | URL ベースのインポートのためにリモート URL をワークスペースに取得 |
| `POST` | `/api/v1/preview` | ブラウザ互換の WebP プレビューを生成（HEIC/HEIF/RAW 形式向け） |
| `GET` | `/api/v1/files/:id/preview` | 保存済みの PDF、Office ドキュメント、動画、音声ファイルについて、キャッシュされたまたは生成されたブラウザ互換プレビューをストリーミング |
| `POST` | `/api/v1/preview/generate` | アップロードされたメディアファイルを先に保存せずに、オンデマンドで MP4 または MP3 プレビューを生成 |
| `GET` | `/api/v1/download/:jobId/:filename` | ワークスペースから処理済みファイルをダウンロード |

ツールの結果をライブラリに自動保存するには、既存のライブラリファイルを参照する `fileId` をマルチパートフォームフィールドとして含めます。処理結果は新しいバージョンとして保存されます。

## API キー管理

| メソッド | パス | アクセス | 説明 |
|--------|------|--------|-------------|
| `POST` | `/api/v1/api-keys` | Auth | 新しいキーを生成 - 一度だけ表示 |
| `GET` | `/api/v1/api-keys` | Auth | キーを一覧表示（name, id, lastUsedAt - 生のキーは含まない） |
| `DELETE` | `/api/v1/api-keys/:id` | Auth | キーを削除 |

## チーム

| メソッド | パス | アクセス | 説明 |
|--------|------|--------|-------------|
| `GET` | `/api/v1/teams` | Admin（`teams:manage`） | チームを一覧表示 |
| `POST` | `/api/v1/teams` | Admin（`teams:manage`） | チームを作成 |
| `PUT` | `/api/v1/teams/:id` | Admin（`teams:manage`） | チームを更新（少なくとも 1 つのフィールドが必要） |
| `DELETE` | `/api/v1/teams/:id` | Admin（`teams:manage`） | チームを削除（デフォルトチームやメンバーがいるチームは削除不可） |

## 設定

ランタイム設定では、認識済みキーの閉じた集合を使用します。読み取りには `settings:read`、書き込みには `settings:write` が必要です。また、セキュリティおよびコンプライアンスのキーには、それぞれ `security:manage` または `compliance:manage` も必要です。秘密の設定には完全な管理者権限が必要で、専用エンドポイントが管理する認証情報と状態は、ここでは読み取り専用です。一括更新は、いずれかの値が書き込まれる前に検証されます。

| メソッド | パス | 説明 |
|--------|------|-------------|
| `GET` | `/api/v1/settings` | すべての設定を取得 |
| `PUT` | `/api/v1/settings` | 設定を一括更新（キー・バリューのペアを含む JSON ボディ） |
| `GET` | `/api/v1/settings/:key` | キーで特定の設定を取得 |

代表的なキー: `disabledTools`（ツール ID の JSON 配列）、`enableExperimentalTools`（ブール値）、`loginAttemptLimit`（セキュリティポリシー）、`auditRetentionDays`（コンプライアンスポリシー）。認識されていないキーは拒否されます。

## 環境設定

ユーザーごとの環境設定は、インスタンス設定とは別です。認証済みユーザーは誰でも自分の環境設定マップを読み取り、更新できます。

| メソッド | パス | 説明 |
|--------|------|-------------|
| `GET` | `/api/v1/preferences` | 現在のユーザーの環境設定を `{ "preferences": { ... } }` として取得 |
| `PUT` | `/api/v1/preferences` | 現在のユーザーの 1 つ以上の環境設定キーをアップサート |

## ロール

細分化されたパーミッションを持つカスタムロール管理。

ロールの作成と変更には権限包含の制約が適用されます。提案されたロールや現在のロールは、操作主体の階層を上回ること、実効パーミッションを超えること、またはツールスコープを広げることはできません。API キーのスコープもこの検証の対象となります。カスタムロールの削除には、所属メンバーのフォールバックとして使用される組み込みの `user` ロールを割り当てる権限も必要です。

| メソッド | パス | アクセス | 説明 |
|--------|------|--------|-------------|
| `GET` | `/api/v1/roles` | Admin（`audit:read`） | ユーザー数付きですべてのロールを一覧表示 |
| `POST` | `/api/v1/roles` | Admin（`security:manage`） | カスタムロールを作成（`name`, `description`, `permissions`） |
| `PUT` | `/api/v1/roles/:id` | Admin（`security:manage`） | カスタムロールを更新（組み込みロールは変更不可） |
| `DELETE` | `/api/v1/roles/:id` | Admin（`security:manage`） | カスタムロールを削除（組み込みロールは削除不可。影響を受けるユーザーは `user` ロールに戻る） |

利用可能なパーミッション（17）: `tools:use`, `files:own`, `files:all`, `apikeys:own`, `apikeys:all`, `pipelines:own`, `pipelines:all`, `settings:read`, `settings:write`, `users:manage`, `teams:manage`, `features:manage`, `system:health`, `audit:read`, `compliance:manage`, `webhooks:manage`, `security:manage`。

## 監査ログ

セキュリティ関連のアクションを確認するための管理者専用エンドポイント。

| メソッド | パス | アクセス | 説明 |
|--------|------|--------|-------------|
| `GET` | `/api/v1/audit-log` | Admin（`audit:read`） | オプションのフィルタ付きのページネーションされた監査ログ |

クエリパラメータ:

| パラメータ | 説明 |
|-----------|-------------|
| `page` | ページ番号（デフォルト: 1） |
| `limit` | ページあたりのエントリ数（デフォルト: 50、最大: 100） |
| `action` | アクションタイプでフィルタ（例 `ROLE_CREATED`, `ROLE_DELETED`） |
| `ip` | ソース IP アドレスでフィルタ |
| `from` | この ISO 8601 日付より後のエントリでフィルタ |
| `to` | この ISO 8601 日付より前のエントリでフィルタ |

## アナリティクス

| メソッド | パス | アクセス | 説明 |
|--------|------|--------|-------------|
| `GET` | `/api/v1/config/analytics` | Public | 有効なアナリティクス設定（PostHog キー、Sentry DSN、サンプルレート）を取得。アナリティクスがオフの場合（コンパイル時のベイクまたはインスタンスの `analyticsEnabled` 設定のいずれか）、キー、DSN、インスタンス ID は空白になります。 |
| `POST` | `/api/v1/feedback` | Auth | 明示的なユーザーフィードバックを、設定された PostHog プロジェクトに `feedback_submitted` として送信。このルートはアナリティクスゲートを尊重し、送信をレート制限し、`contactOk` が true でない限り連絡先フィールドを取り除き、ファイルの内容、ファイル名、アップロードパス、生のプライベートエラーテキストを一切受け付けません。アナリティクスが無効な場合、`{ "ok": true, "accepted": false }` を返します。 |
| `PUT` | `/api/v1/settings` | Admin（`settings:write`） | インスタンス全体のオプトアウトを設定。全員のアナリティクスをオフにするには JSON ボディ `{ "analyticsEnabled": "false" }` を、再びオンにするには `"true"` を送信します。 |

## 機能 / AI バンドル

AI 機能バンドル（Docker 環境での AI モデルパッケージのインストール/アンインストール）を管理します。カスタム自動化からツールを有効化する場合は、ツールレベルのインストールエンドポイントを推奨します。一部の AI ツールは複数の共有バンドルを必要とし、このエンドポイントはインストール済みのバンドルをスキップして、不足しているものだけをキューに入れます。

OCR は、厳密な依存関係ではなく、オプションの拡張機能です。 `fast` Tesseract 層はパックなしで機能します。 `POST /api/v1/admin/features/ocr/install` は、`balanced` および `best` の署名付き RapidOCR パックを Linux amd64 または arm64 にインストールします。 正確な OCR ランタイムは、CPU のみおよび NVIDIA ホストで CPU を使用し、少なくとも 4 GiB の有効メモリ (構成されたコンテナーの cgroup 制限、それ以外の場合はホスト メモリ) を必要とします。 SnapOtter は、`requiredMemoryBytes`、`effectiveMemoryBytes`、および `insufficient-memory` 互換性理由を報告し、ダウンロード前に互換性のないインストールを拒否します。 このメモリ要件は、`fast` には適用されません。 このパックは、ターゲットに応じて、ダウンロードに 208 ～ 234 の MiB、インストールに 409 ～ 488 の MiB があります。 署名付きインデックスは、インストール中に適用される正確なサイズをバインドします。

| メソッド | パス | アクセス | 説明 |
|--------|------|--------|-------------|
| `GET` | `/api/v1/features` | Auth | すべての機能バンドルとそのインストール状況を一覧表示 |
| `POST` | `/api/v1/admin/features/:bundleId/install` | Admin（`features:manage`） | 機能バンドルをインストール（非同期、進捗トラッキング用の `jobId` を返す） |
| `POST` | `/api/v1/admin/tools/:toolId/features/install` | Admin（`features:manage`） | ツールが必要とするすべてのバンドルをインストール。バンドルごとの queued/skipped ステータスを返す |
| `POST` | `/api/v1/admin/features/:bundleId/uninstall` | Admin（`features:manage`） | 機能バンドルをアンインストールし、モデルファイルをクリーンアップ |
| `GET` | `/api/v1/admin/features/disk-usage` | Admin（`features:manage`） | AI モデルの合計ディスク使用量を取得 |
| `POST` | `/api/v1/admin/features/import` | 管理者 (`features:manage`) | レガシー AI バンドル (`file`) または署名済みオフライン OCR リリース (`index` プラス `archive`) をインポートします。 |

エアギャップされた OCR インポートには、リリースの署名付き `ocr-runtime-index.json` と一致するプラットフォーム アーカイブが含まれている必要があります。 SnapOtter は、オンライン インストールで使用されるものと同じ Ed25519 署名、アーティファクト ハッシュ、互換性、抽出、およびスモーク テスト チェックを適用します。

```bash
curl -X POST http://localhost:1349/api/v1/admin/features/import \
  -H "Authorization: Bearer <admin-token>" \
  -F "index=@ocr-runtime-index.json" \
  -F "archive=@ocr-linux-amd64-cpu-py312.tar.gz"
```

arm64 の `linux-arm64-cpu-py311` アーカイブを使用します。別のターゲットの署名付きアーティファクトはインストールされずに拒否されます。

## 管理者操作

オブザーバビリティ、サポート、使用状況レポート、バックアップステータスのための運用エンドポイント。

| メソッド | パス | アクセス | 説明 |
|--------|------|--------|-------------|
| `GET` | `/api/v1/admin/log-level` | Admin（`settings:write`） | 現在のランタイムログレベルを読み取る |
| `POST` | `/api/v1/admin/log-level` | Admin（`settings:write`） | ランタイムログレベルを変更（`fatal`, `error`, `warn`, `info`, `debug`, `trace`, `silent` のいずれか） |
| `GET` | `/api/v1/metrics` | Admin（`system:health`） | テキスト形式の Prometheus メトリクス |
| `GET` | `/api/v1/admin/support-bundle` | Admin（`system:health`） | 秘匿化された診断サポートバンドル ZIP をダウンロード |
| `GET` | `/api/v1/admin/usage` | Admin（`audit:read`） | 使用状況ダッシュボードデータ（オプションの `days` クエリパラメータ付き） |
| `GET` | `/api/v1/admin/backup-status` | Admin（`system:health`） | 最新のバックアップメタデータと鮮度ステータスを読み取る |
| `POST` | `/api/v1/admin/backup-status` | Admin（`system:health`） | 完了したバックアップを記録（`type`, オプションの `sizeBytes`, オプションの `notes`） |

## エンタープライズ API

これらのルートは、関連するエンタープライズ機能によってライセンスゲートされています。それでも、記載された SnapOtter のパーミッションを必要とします。

**完全な組み込み管理者**とは、認証された主体が `admin` ロールを持ち、管理者権限の完全かつ実効的なセットを保持していることを意味します。管理者権限が一つでも欠ける API キーのスコープは対象外です。

| メソッド | パス | アクセス | 説明 |
|--------|------|--------|-------------|
| `GET` | `/api/v1/enterprise/audit/export` | Admin（`audit:read`） | 監査エントリをフィルタ付きで JSON または CSV としてエクスポート |
| `GET` | `/api/v1/enterprise/config/export` | 完全な組み込み管理者 | 秘匿化されたインスタンス設定、カスタムロール、チームをエクスポート |
| `POST` | `/api/v1/enterprise/config/import` | 完全な組み込み管理者 | 設定をインポート（オプションのドライラン付き） |
| `GET` | `/api/v1/enterprise/ip-allowlist` | Admin（`security:manage`） | 設定された CIDR 許可リストを読み取る |
| `PUT` | `/api/v1/enterprise/ip-allowlist` | Admin（`security:manage`） | 自己ロックアウト防止付きで CIDR 許可リストを更新 |
| `GET` | `/api/v1/enterprise/legal-hold` | Admin（`compliance:manage`） | ユーザーおよびチームのリーガルホールドを一覧表示 |
| `PUT` | `/api/v1/enterprise/legal-hold` | Admin（`compliance:manage`） | ユーザーまたはチームにリーガルホールドを適用または解除 |
| `POST` | `/api/v1/enterprise/scim/token` | 完全な組み込み管理者 | SCIM ベアラートークンを生成（一度だけ返される） |
| `DELETE` | `/api/v1/enterprise/scim/token` | 完全な組み込み管理者 | 現在の SCIM ベアラートークンを失効 |
| `GET` | `/api/v1/enterprise/siem/config` | Admin（`webhooks:manage`） | SIEM 転送設定を読み取る |
| `PUT` | `/api/v1/enterprise/siem/config` | Admin（`webhooks:manage`） | SIEM 転送設定を更新 |
| `GET` | `/api/v1/enterprise/webhooks` | Admin（`webhooks:manage`） | Webhook の宛先を一覧表示 |
| `POST` | `/api/v1/enterprise/webhooks` | Admin（`webhooks:manage`） | Webhook の宛先を作成 |
| `PUT` | `/api/v1/enterprise/webhooks/:index` | Admin（`webhooks:manage`） | Webhook の宛先を更新 |
| `DELETE` | `/api/v1/enterprise/webhooks/:index` | Admin（`webhooks:manage`） | Webhook の宛先を削除 |
| `POST` | `/api/v1/enterprise/webhooks/:index/test` | Admin（`webhooks:manage`） | テスト用の Webhook ペイロードを送信 |
| `POST` | `/api/v1/enterprise/users/:id/export` | Admin（`compliance:manage`） | GDPR ユーザーエクスポートジョブを開始 |
| `GET` | `/api/v1/enterprise/users/:id/export/:jobId` | Admin（`compliance:manage`） | GDPR エクスポートのステータスとダウンロード URL を読み取る |
| `DELETE` | `/api/v1/enterprise/users/:id/purge` | Admin（`compliance:manage`；対象への権限） | 確認後にユーザーのデータを完全に消去 |
| `DELETE` | `/api/v1/enterprise/teams/:id/purge` | Admin（`compliance:manage`；全メンバーへの権限） | 確認後にチームのデータを完全に消去 |
| `GET` | `/api/v1/admin/version` | Admin（`system:health`） | アプリ、ビルド、Node、スキーマのバージョンメタデータを読み取る |
| `GET` | `/api/v1/admin/migrations/pending` | Admin（`system:health`） | パッケージされたマイグレーションと適用済みマイグレーションを比較 |
| `GET` | `/api/v1/admin/upgrade-check` | Admin（`system:health`） | アップグレードのレディネスチェックを実行 |

### SCIM 2.0

SCIM のディスカバリエンドポイントは公開されています。ユーザーおよびグループのエンドポイントには、上で生成した SCIM ベアラートークンが必要です。従来のバージョンなしトークンは無効であり、完全な組み込み管理者によって `so_scim_v2_...` トークンとして再発行する必要があります。

| メソッド | パス | アクセス | 説明 |
|--------|------|--------|-------------|
| `GET` | `/api/v1/scim/v2/ServiceProviderConfig` | Public | SCIM サーバーの機能 |
| `GET` | `/api/v1/scim/v2/Schemas` | Public | SCIM スキーマのディスカバリ |
| `GET` | `/api/v1/scim/v2/ResourceTypes` | Public | SCIM リソースタイプのディスカバリ |
| `GET` | `/api/v1/scim/v2/Users` | SCIM token | ユーザーを一覧表示（オプションの SCIM フィルタ付き） |
| `POST` | `/api/v1/scim/v2/Users` | SCIM token | ユーザーを作成 |
| `GET` | `/api/v1/scim/v2/Users/:id` | SCIM token | ユーザーを取得 |
| `PUT` | `/api/v1/scim/v2/Users/:id` | SCIM token | ユーザーを置換 |
| `DELETE` | `/api/v1/scim/v2/Users/:id` | SCIM token | ユーザーをソフト無効化 |
| `GET` | `/api/v1/scim/v2/Groups` | SCIM token | チームを SCIM グループとして一覧表示 |
| `POST` | `/api/v1/scim/v2/Groups` | SCIM token | チームを作成 |
| `GET` | `/api/v1/scim/v2/Groups/:id` | SCIM token | チームを取得 |
| `PUT` | `/api/v1/scim/v2/Groups/:id` | SCIM token | チームとグループメンバーシップを置換 |
| `DELETE` | `/api/v1/scim/v2/Groups/:id` | SCIM token | チームを削除 |

## ミームテンプレート

ミームジェネレーターツールをサポートする API。

| メソッド | パス | アクセス | 説明 |
|--------|------|--------|-------------|
| `GET` | `/api/v1/meme-templates` | Auth | テキストボックスの位置を含むすべての利用可能なミームテンプレートを一覧表示 |
| `GET` | `/api/v1/meme-templates/full/:filename` | Auth | フルサイズのテンプレート画像を配信 |
| `GET` | `/api/v1/meme-templates/thumbs/:filename` | Auth | テンプレートのサムネイルを配信 |
| `GET` | `/api/v1/meme-templates/fonts/:filename` | Auth | ミームテキストのレンダリングに使用されるフォントファイルを配信 |

## エラーレスポンス

すべてのエラーは JSON を返します:

```json
{
  "error": "Human-readable message",
  "code": "MACHINE_READABLE_CODE"
}
```

| ステータス | 意味 |
|--------|---------|
| 400 | 無効なリクエスト / 検証失敗 |
| 401 | 未認証 |
| 403 | パーミッション不足 |
| 404 | リソースが見つからない |
| 413 | ファイルが大きすぎる（`MAX_UPLOAD_SIZE_MB` を参照） |
| 422 | 検証後に処理が失敗 |
| 429 | レート制限（`RATE_LIMIT_PER_MIN` を参照） |
| 501 | 必要な AI 機能バンドルがインストールされていない（`FEATURE_NOT_INSTALLED`） |
| 500 | 内部サーバーエラー |
