feat(docs-i18n): translate all documentation into 20 languages

All 181 docs markdown files translated into 20 languages (apps/docs/<locale>/**). Companion to the i18n code PR; admin-merged because the file count exceeds GitHub's per-PR CI trigger limit. Validated by pnpm i18n:check (all surfaces, 0 stale/missing) and a clean all-locale docs build.
2026-08-03 07:46:42 +02:00 · 2026-07-11 13:52:47 +08:00
parent 00b651c9f8
commit 4963ab3bbd
3620 changed files with 306134 additions and 0 deletions
@@ -0,0 +1,438 @@
+---
+description: "모든 로컬 ML 도구를 다루는 AI 엔진 레퍼런스. 배경 제거, 업스케일링, OCR, 얼굴 감지, 사진 복원 등."
+i18n_source_hash: 14728c1dcd05
+i18n_provenance: machine
+i18n_output_hash: 0345ba8791f7
+---
+
+# AI 엔진 레퍼런스 {#ai-engine-reference}
+
+`@snapotter/ai` 패키지는 모든 ML 작업을 위해 Node.js와 **상시 실행되는 Python 사이드카**를 연결한다. 디스패처 프로세스는 요청 사이에도 살아 있어 빠른 웜 스타트 성능을 낸다. NVIDIA CUDA는 시작 시 자동으로 감지되어 사용 가능하면 사용되고, 그렇지 않으면 AI 도구가 CPU에서 실행된다.
+
+VA-API, Quick Sync, OpenCL을 통한 Intel/AMD iGPU 가속은 현재 AI 추론에 지원되지 않는다. CUDA를 지원하는 NVIDIA GPU가 없는 한, 컨테이너에 `/dev/dri`를 매핑해도 이러한 Python 사이드카 도구는 가속되지 않는다.
+
+네 가지 모달리티(이미지, 오디오, 비디오, 문서)에 걸쳐 19개의 Python 사이드카 AI 도구가 있으며, 여기에 선택적 AI 기능을 갖춘 2개의 도구가 추가된다. 모든 모델은 로컬에서 실행되며, 최초 모델 다운로드 이후에는 인터넷이 필요하지 않다.
+
+## 아키텍처 {#architecture}
+
+```
+Node.js Tool Route
+      |
+      v
+ @snapotter/ai bridge.ts
+      | (stdin/stdout JSON + stderr progress events)
+      v
+ Python dispatcher (persistent process, "ai" profile)
+      |
+      |-- remove_bg.py        (rembg / BiRefNet)
+      |-- upscale.py          (RealESRGAN)
+      |-- inpaint.py          (LaMa ONNX)
+      |-- outpaint.py         (LaMa canvas expansion)
+      |-- ocr.py              (PaddleOCR / Tesseract)
+      |-- ocr_pdf.py          (page-by-page document OCR)
+      |-- ocr_preprocess.py   (image enhancement for OCR)
+      |-- detect_faces.py     (MediaPipe)
+      |-- face_landmarks.py   (MediaPipe landmarks)
+      |-- enhance_faces.py    (GFPGAN / CodeFormer)
+      |-- colorize.py         (DDColor)
+      |-- noise_removal.py    (SCUNet / tiered denoising)
+      |-- red_eye_removal.py  (landmark + color analysis)
+      |-- restore.py          (scratch repair + enhancement + denoising)
+      |-- transcribe.py       (faster-whisper speech-to-text)
+      +-- install_feature.py  (on-demand bundle installer)
+```
+
+별도의 "docs" 디스패처 프로파일은 AI 허용 목록을 문서 처리 스크립트(`doc_pagecount`, `doc_health`, `doc_flatten`, `doc_redact`, `doc_text`, `doc_to_word`, `doc_metadata`, `doc_html_pdf`)로 대체하고 무거운 ML 임포트를 건너뛴다.
+
+**타임아웃:** 기본 300초. OCR과 BiRefNet 배경 제거는 600초가 주어진다.
+
+## 기능 번들 {#feature-bundles}
+
+AI 모델은 도구별로 아카이브 하나씩이 아니라 공유 의존성 스택 단위로 패키징된다. 하나의 기능 번들은 여러 도구가 동일한 모델 계열, Python 휠, 또는 네이티브 라이브러리를 사용할 때 그 도구들을 함께 활성화할 수 있다. 이렇게 하면 릴리스 Docker 이미지가 더 작게 유지되고, 동일한 배경 매팅, 얼굴 감지, OCR, 복원, 음성 모델의 중복 사본을 저장하는 일을 피할 수 있다.
+
+Docker 이미지는 애플리케이션과 공통 런타임을 함께 제공한다. 대용량 모델 아카이브는 필요할 때 상시 유지되는 `/data/ai` 볼륨으로 다운로드된 뒤, 이를 필요로 하는 모든 도구가 재사용한다. 다른 도구가 이미 필요로 해서 어떤 번들이 이미 설치되어 있다면, 새로 의존하는 도구를 활성화해도 그 번들을 다시 다운로드하지 않는다.
+
+각 AI 도구는 실행되기 전에 하나 이상의 기능 번들이 필요하다. 관리자 UI는 `POST /api/v1/admin/tools/:toolId/features/install`을 통해 도구 단위로 설치하며, 이는 전체 번들 목록을 해석하고, 이미 설치된 번들은 건너뛰며, 누락된 다운로드만 대기열에 넣는다. 예를 들어, 새 인스턴스에서 여권 사진을 활성화하면 `background-removal`와 `face-detection`가 대기열에 들어가고, 배경 제거가 이미 설치된 상태에서 활성화하면 `face-detection`만 대기열에 들어간다.
+
+| 번들 | 크기 | 공유 의존성 그룹 | 사용하는 도구 |
+|--------|------|-------------------------|-------------------|
+| `background-removal` | 4-5 GB | rembg / BiRefNet 배경 매팅 | remove-background, passport-photo, transparency-fixer, background-replace, blur-background |
+| `face-detection` | 200-300 MB | MediaPipe 얼굴 감지 및 랜드마크 | blur-faces, red-eye-removal, smart-crop |
+| `object-eraser-colorize` | 1-2 GB | LaMa 인페인팅/아웃페인팅 및 DDColor | erase-object, colorize, ai-canvas-expand |
+| `upscale-enhance` | 5-6 GB | RealESRGAN, GFPGAN / CodeFormer, 노이즈 제거 | upscale, enhance-faces, noise-removal |
+| `photo-restoration` | 4-5 GB | 스크래치 복구 및 복원 파이프라인 | restore-photo |
+| `ocr` | 5-6 GB | PaddleOCR / Tesseract OCR 스택 | ocr, ocr-pdf |
+| `transcription` | ~600 MB | faster-whisper 음성-텍스트 변환 모델 | transcribe-audio, auto-subtitles |
+
+교차 번들 의존성을 갖는 도구:
+
+| 도구 | 필요한 번들 | 이유 |
+|------|------------------|-----|
+| `passport-photo` | `background-removal`, `face-detection` | 배경을 제거한 뒤, 얼굴 랜드마크를 사용해 여권 및 신분증 사진 규정에 맞게 크롭 구도를 잡는다. |
+| `enhance-faces` | `upscale-enhance`, `face-detection` | 선택된 얼굴 영역에 GFPGAN 또는 CodeFormer 보정을 적용하기 전에 얼굴을 감지한다. |
+
+도구는 필요한 모든 번들이 설치되어 있을 때만 사용할 수 있다. 부분 설치도 유효하며 점진적으로 처리된다. 설치된 번들은 재사용되고, 누락된 번들은 다운로드로 표시되며, 대기 중인 설치는 한 번에 하나씩 실행되어 공유 Python 환경이 동시에 수정되지 않도록 한다.
+
+---
+
+## 배경 제거 {#background-removal}
+
+**도구 경로:** `remove-background`  
+**모델:** rembg with BiRefNet (기본값) 또는 U2-Net 변형
+
+| 매개변수 | 타입 | 기본값 | 설명 |
+|-----------|------|---------|-------------|
+| `model` | string | - | 모델 변형 (선택적 재정의) |
+| `backgroundType` | string | `"transparent"` | 다음 중 하나: `transparent`, `color`, `gradient`, `blur`, `image` |
+| `backgroundColor` | string | - | 단색 배경용 Hex 색상 |
+| `gradientColor1` | string | - | 첫 번째 그라디언트 색상 |
+| `gradientColor2` | string | - | 두 번째 그라디언트 색상 |
+| `gradientAngle` | number | - | 그라디언트 각도(도 단위) |
+| `blurEnabled` | boolean | - | 배경 블러 효과 활성화 |
+| `blurIntensity` | number (0-100) | - | 블러 강도 |
+| `shadowEnabled` | boolean | - | 피사체에 드롭 섀도 활성화 |
+| `shadowOpacity` | number (0-100) | - | 그림자 불투명도 |
+| `outputFormat` | string | - | 출력 형식: `png`, `webp`, 또는 `avif` |
+| `edgeRefine` | integer (0-3) | - | 가장자리 정제 수준 |
+| `decontaminate` | boolean | - | 가장자리의 색상 번짐 제거 |
+
+## 배경 교체 {#background-replace}
+
+**도구 경로:** `background-replace`  
+**모델:** rembg / BiRefNet (remove-background와 공유)
+
+배경을 제거하고 단색 또는 그라디언트로 교체한다.
+
+| 매개변수 | 타입 | 기본값 | 설명 |
+|-----------|------|---------|-------------|
+| `backgroundType` | `"color"` \| `"gradient"` | `"color"` | 배경 모드 |
+| `color` | string | `"#ffffff"` | 배경 hex 색상 (`backgroundType`이 `color`일 때) |
+| `gradientColor1` | string | - | 첫 번째 그라디언트 hex 색상 |
+| `gradientColor2` | string | - | 두 번째 그라디언트 hex 색상 |
+| `gradientAngle` | integer (0-360) | `180` | 그라디언트 각도(도 단위) |
+| `feather` | integer (0-20) | `0` | 가장자리 페더링 반경 |
+| `format` | `"png"` \| `"webp"` | `"png"` | 출력 형식 |
+
+## 배경 블러 {#blur-background}
+
+**도구 경로:** `blur-background`  
+**모델:** rembg / BiRefNet (remove-background와 공유)
+
+피사체는 선명하게 유지하면서 배경을 흐리게 만든다.
+
+| 매개변수 | 타입 | 기본값 | 설명 |
+|-----------|------|---------|-------------|
+| `intensity` | integer (1-100) | `50` | 블러 강도 |
+| `feather` | integer (0-20) | `0` | 가장자리 페더링 반경 |
+| `format` | `"png"` \| `"webp"` | `"png"` | 출력 형식 |
+
+## 이미지 업스케일링 {#image-upscaling}
+
+**도구 경로:** `upscale`  
+**모델:** RealESRGAN (사용 불가 시 Lanczos 폴백)
+
+| 매개변수 | 타입 | 기본값 | 설명 |
+|-----------|------|---------|-------------|
+| `scale` | number | `2` | 업스케일 배율 |
+| `model` | string | `"auto"` | 모델 변형 |
+| `faceEnhance` | boolean | `false` | GFPGAN 얼굴 보정 패스 적용 |
+| `denoise` | number | `0` | 노이즈 제거 강도 |
+| `format` | string | `"auto"` | 출력 형식 재정의 |
+| `quality` | number | `95` | 출력 품질 (1-100) |
+
+## OCR / 텍스트 추출 {#ocr-text-extraction}
+
+**도구 경로:** `ocr`  
+**모델:** Tesseract (빠름), PaddleOCR PP-OCRv5 (균형), PaddleOCR-VL 1.5 (최상)
+
+| 매개변수 | 타입 | 기본값 | 설명 |
+|-----------|------|---------|-------------|
+| `quality` | `"fast"` \| `"balanced"` \| `"best"` | `"balanced"` | 처리 등급 |
+| `language` | string | `"auto"` | 언어: `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko` |
+| `enhance` | boolean | `true` | OCR 정확도 향상을 위해 이미지 사전 처리 |
+| `engine` | string | - | 사용 중단됨. `tesseract`을 `fast`로, `paddleocr`을 `balanced`로 매핑 |
+
+경계 상자, 신뢰도 점수, 추출된 텍스트 블록을 포함한 구조화된 결과를 반환한다.
+
+## PDF OCR {#pdf-ocr}
+
+**도구 경로:** `ocr-pdf`  
+**모델:** 이미지 OCR와 동일한 등급 체계
+
+AI 기반 OCR을 사용해 스캔된 PDF 문서에서 페이지별로 텍스트를 추출한다.
+
+| 매개변수 | 타입 | 기본값 | 설명 |
+|-----------|------|---------|-------------|
+| `quality` | `"fast"` \| `"balanced"` \| `"best"` | `"balanced"` | 처리 등급 |
+| `language` | string | `"auto"` | 언어: `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko` |
+| `pages` | string | `"all"` | 페이지 선택: `"all"`, `"1-3"`, `"1,3,5"` |
+
+## 얼굴 / PII 블러 {#face-pii-blur}
+
+**도구 경로:** `blur-faces`  
+**모델:** MediaPipe 얼굴 감지
+
+| 매개변수 | 타입 | 기본값 | 설명 |
+|-----------|------|---------|-------------|
+| `blurRadius` | number (1-100) | `30` | 가우시안 블러 반경 |
+| `sensitivity` | number (0-1) | `0.5` | 감지 신뢰도 임계값 |
+
+## 얼굴 보정 {#face-enhancement}
+
+**도구 경로:** `enhance-faces`  
+**모델:** GFPGAN, CodeFormer
+
+| 매개변수 | 타입 | 기본값 | 설명 |
+|-----------|------|---------|-------------|
+| `model` | `"auto"` \| `"gfpgan"` \| `"codeformer"` | `"auto"` | 보정 모델 |
+| `strength` | number (0-1) | `0.8` | 보정 강도 |
+| `sensitivity` | number (0-1) | `0.5` | 얼굴 감지 임계값 |
+| `onlyCenterFace` | boolean | `false` | 가장 중앙에 있는 얼굴만 보정 |
+
+## AI 컬러화 {#ai-colorization}
+
+**도구 경로:** `colorize`  
+**모델:** DDColor (OpenCV DNN 폴백)
+
+흑백 또는 그레이스케일 사진을 풀컬러로 변환한다.
+
+| 매개변수 | 타입 | 기본값 | 설명 |
+|-----------|------|---------|-------------|
+| `intensity` | number (0-1) | `1.0` | 색상 채도 강도 |
+| `model` | `"auto"` \| `"ddcolor"` \| `"opencv"` | `"auto"` | 모델 변형 |
+
+## 노이즈 제거 {#noise-removal}
+
+**도구 경로:** `noise-removal`  
+**모델:** SCUNet (등급형 노이즈 제거 파이프라인)
+
+| 매개변수 | 타입 | 기본값 | 설명 |
+|-----------|------|---------|-------------|
+| `tier` | `"quick"` \| `"balanced"` \| `"quality"` \| `"maximum"` | `"balanced"` | 처리 등급 |
+| `strength` | number (0-100) | `50` | 노이즈 제거 강도 |
+| `detailPreservation` | number (0-100) | `50` | 보존할 디테일 정도. 높을수록 텍스처가 더 많이 유지됨 |
+| `colorNoise` | number (0-100) | `30` | 컬러 노이즈 감소 강도 |
+| `format` | string | `"original"` | 출력 형식: `original`, `png`, `jpeg`, `webp`, `avif`, `jxl` |
+| `quality` | number (1-100) | `90` | 출력 인코딩 품질 |
+
+## 적목 현상 제거 {#red-eye-removal}
+
+**도구 경로:** `red-eye-removal`
+
+얼굴 랜드마크를 감지하고 눈 영역을 찾아 적색 채널 과포화를 보정한다.
+
+| 매개변수 | 타입 | 기본값 | 설명 |
+|-----------|------|---------|-------------|
+| `sensitivity` | number (0-100) | `50` | 적색 픽셀 감지 임계값 |
+| `strength` | number (0-100) | `70` | 보정 강도 |
+| `format` | string | - | 출력 형식 재정의 (선택 사항) |
+| `quality` | number (1-100) | `90` | 출력 품질 |
+
+## 사진 복원 {#photo-restoration}
+
+**도구 경로:** `restore-photo`
+
+오래되거나 손상된 사진을 위한 다단계 파이프라인: 스크래치/찢김 감지 및 복구, 얼굴 보정, 노이즈 제거, 그리고 선택적 컬러화.
+
+| 매개변수 | 타입 | 기본값 | 설명 |
+|-----------|------|---------|-------------|
+| `scratchRemoval` | boolean | `true` | 스크래치, 찢김 감지 및 복구 |
+| `faceEnhancement` | boolean | `true` | 얼굴 보정 패스 적용 |
+| `fidelity` | number (0-1) | `0.7` | 얼굴 보정 강도 (높을수록 더 보수적) |
+| `denoise` | boolean | `true` | 노이즈 제거 패스 적용 |
+| `denoiseStrength` | number (0-100) | `25` | 노이즈 제거 강도 |
+| `colorize` | boolean | `false` | 복원 후 컬러화 |
+| `colorizeStrength` | number (0-100) | `85` | 컬러화 강도 |
+
+## 여권 사진 {#passport-photo}
+
+**도구 경로:** `passport-photo`  
+**모델:** MediaPipe 얼굴 랜드마크 + BiRefNet 배경 제거
+
+두 단계 워크플로: 분석(얼굴 감지 + 배경 제거) 후 생성(크롭, 크기 조정, 타일 배치). 6개 지역에 걸쳐 37개 이상의 국가를 지원한다.
+
+### 1단계: 분석 {#phase-1-analyze}
+
+`POST /api/v1/tools/image/passport-photo/analyze`
+
+이미지 파일(multipart)을 받는다. 얼굴 랜드마크 데이터, base64 미리보기, 이미지 치수를 반환한다.
+
+### 2단계: 생성 {#phase-2-generate}
+
+`POST /api/v1/tools/image/passport-photo/generate`
+
+1단계 결과와 생성 설정이 담긴 JSON 본문을 받는다:
+
+| 매개변수 | 타입 | 기본값 | 설명 |
+|-----------|------|---------|-------------|
+| `jobId` | string | (필수) | 1단계의 작업 ID |
+| `filename` | string | (필수) | 1단계의 원본 파일 이름 |
+| `countryCode` | string | (필수) | ISO 국가 코드 (예: `US`, `GB`, `IN`) |
+| `documentType` | string | `"passport"` | 문서 유형 |
+| `bgColor` | string | `"#FFFFFF"` | 배경 색상 hex |
+| `printLayout` | string | `"none"` | 인쇄 레이아웃: `none`, `4x6`, `a4`, `letter` |
+| `maxFileSizeKb` | number | `0` | 최대 파일 크기(KB) (0 = 제한 없음) |
+| `dpi` | number (72-1200) | `300` | 출력 DPI |
+| `customWidthMm` | number | - | 사용자 지정 너비(mm) (국가 사양을 재정의) |
+| `customHeightMm` | number | - | 사용자 지정 높이(mm) (국가 사양을 재정의) |
+| `zoom` | number (0.5-3) | `1` | 줌 배율 |
+| `adjustX` | number | `0` | 수평 위치 조정 |
+| `adjustY` | number | `0` | 수직 위치 조정 |
+| `landmarks` | object | (필수) | 1단계의 랜드마크 |
+| `imageWidth` | number | (필수) | 1단계의 이미지 너비 |
+| `imageHeight` | number | (필수) | 1단계의 이미지 높이 |
+
+## 객체 지우기 (인페인팅) {#object-erasing-inpainting}
+
+**도구 경로:** `erase-object`  
+**모델:** ONNX Runtime을 통한 LaMa
+
+마스크는 base64가 아니라 **두 번째 파일 파트**(fieldname `mask`)로 전송된다. 마스크에서 흰색 픽셀은 지울 영역을 나타낸다. `format`와 `quality` 설정은 최상위 폼 필드로 전송된다.
+
+| 매개변수 | 타입 | 기본값 | 설명 |
+|-----------|------|---------|-------------|
+| `file` | file | (필수) | 원본 이미지 (multipart) |
+| `mask` | file | (필수) | 마스크 이미지 (multipart, fieldname `mask`, 흰색 = 지우기) |
+| `format` | string | `"auto"` | 출력 형식: `auto`, `png`, `jpg`, `jpeg`, `webp`, `tiff`, `gif`, `avif`, `heic`, `heif`, `jxl` |
+| `quality` | integer (1-100) | `95` | 출력 품질 |
+
+NVIDIA GPU가 있을 때 CUDA 가속된다.
+
+## AI 캔버스 확장 {#ai-canvas-expand}
+
+**도구 경로:** `ai-canvas-expand`  
+**모델:** LaMa 기반 아웃페인팅
+
+이미지의 캔버스를 어느 방향으로든 확장하고, 새 영역을 기존 이미지와 어울리는 AI 생성 콘텐츠로 채운다.
+
+| 매개변수 | 타입 | 기본값 | 설명 |
+|-----------|------|---------|-------------|
+| `extendTop` | integer | `0` | 위쪽으로 확장할 픽셀 |
+| `extendRight` | integer | `0` | 오른쪽으로 확장할 픽셀 |
+| `extendBottom` | integer | `0` | 아래쪽으로 확장할 픽셀 |
+| `extendLeft` | integer | `0` | 왼쪽으로 확장할 픽셀 |
+| `tier` | `"fast"` \| `"balanced"` \| `"high"` | `"balanced"` | 품질 등급 |
+| `format` | string | `"auto"` | 출력 형식: `auto`, `png`, `jpg`, `jpeg`, `webp`, `tiff`, `gif`, `avif`, `heic`, `heif`, `jxl` |
+| `quality` | integer (1-100) | `95` | 출력 품질 |
+
+확장 방향 중 하나 이상이 0보다 커야 한다.
+
+## 스마트 크롭 {#smart-crop}
+
+**도구 경로:** `smart-crop`  
+**모델:** MediaPipe 얼굴 감지 (얼굴 모드 전용)
+
+| 매개변수 | 타입 | 기본값 | 설명 |
+|-----------|------|---------|-------------|
+| `mode` | string | `"subject"` | 크롭 전략: `subject`, `face`, `trim` |
+| `strategy` | `"attention"` \| `"entropy"` | `"attention"` | 피사체 모드 전략 |
+| `width` | integer | - | 출력 너비 |
+| `height` | integer | - | 출력 높이 |
+| `padding` | integer (0-50) | `0` | 피사체 주변 여백 백분율 |
+| `facePreset` | string | `"head-shoulders"` | `mode=face`일 때의 프리셋 구도 |
+| `sensitivity` | number (0-1) | `0.5` | 얼굴 감지 임계값 |
+| `threshold` | integer (0-255) | `30` | 배경 감지 임계값 (트림 모드) |
+| `padToSquare` | boolean | `false` | 트림된 결과를 정사각형으로 패딩 |
+| `padColor` | string | `"#ffffff"` | 정사각형 패딩용 배경 색상 |
+| `targetSize` | integer | - | 패딩된 출력의 목표 크기(픽셀) |
+| `quality` | integer (1-100) | - | 출력 품질 |
+
+레거시 `mode` 값 `attention`와 `content`은 허용되며 각각 `subject`와 `trim`로 매핑된다.
+
+**얼굴 프리셋:**
+
+| 프리셋 | 적합한 용도 |
+|--------|---------|
+| `closeup` | 헤드샷 |
+| `head-shoulders` | 프로필 사진 |
+| `upper-body` | LinkedIn / 격식 있는 용도 |
+| `half-body` | 상반신 전체 |
+
+## 오디오 전사 {#transcribe-audio}
+
+**도구 경로:** `transcribe-audio`  
+**모델:** faster-whisper
+
+음성을 텍스트로 변환한다. 일반 텍스트, SRT, VTT 출력 형식을 지원한다.
+
+| 매개변수 | 타입 | 기본값 | 설명 |
+|-----------|------|---------|-------------|
+| `language` | string | `"auto"` | 언어: `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko`, `id`, `th`, `vi` |
+| `outputFormat` | `"txt"` \| `"srt"` \| `"vtt"` | `"txt"` | 출력 형식 |
+
+## 자동 자막 {#auto-subtitles}
+
+**도구 경로:** `auto-subtitles`  
+**모델:** faster-whisper (비디오에서 오디오를 추출한 뒤 전사)
+
+비디오의 오디오 트랙에서 자막 파일을 생성한다.
+
+| 매개변수 | 타입 | 기본값 | 설명 |
+|-----------|------|---------|-------------|
+| `language` | string | `"auto"` | 언어: `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko`, `id`, `th`, `vi` |
+| `format` | `"srt"` \| `"vtt"` | `"srt"` | 출력 자막 형식 |
+
+## PNG 투명도 수정 {#png-transparency-fixer}
+
+**도구 경로:** `transparency-fixer`  
+**모델:** BiRefNet HR-매팅 (2048x2048 해상도)
+
+배경은 제거되었지만 프린징, 헤일로, 반투명 아티팩트가 남은 "가짜 투명" PNG를 수정한다. BiRefNet의 고해상도 매팅 모델을 사용해 깨끗한 알파 채널을 만든 다음, 구성 가능한 디프린지 처리를 적용해 가장자리를 따라 남은 색상 오염을 제거한다.
+
+**OOM 폴백 체인:** BiRefNet HR-매팅이 가용 메모리를 초과하면, 도구는 자동으로 `birefnet-general`로, 그다음 `u2net`로 폴백한다.
+
+| 매개변수 | 타입 | 기본값 | 설명 |
+|-----------|------|---------|-------------|
+| `defringe` | number (0-100) | `30` | 색상 오염을 제거하는 가장자리 디프린지 강도 |
+| `outputFormat` | `"png"` \| `"webp"` | `"png"` | 출력 이미지 형식 |
+| `removeWatermark` | boolean | `false` | 워터마크 제거 사전 처리 적용 (미디안 필터) |
+
+```bash
+curl -X POST http://localhost:1349/api/v1/tools/image/transparency-fixer \
+  -H "Authorization: Bearer <token>" \
+  -F "file=@fake-transparent.png" \
+  -F 'settings={"defringe":30,"outputFormat":"png"}'
+```
+
+---
+
+## 선택적 AI 기능을 갖춘 도구 {#tools-with-optional-ai-capabilities}
+
+다음 도구는 Python 사이드카 도구는 아니지만 특정 옵션이 활성화되면 AI 기능을 사용한다.
+
+### 이미지 향상 {#image-enhancement}
+
+**도구 경로:** `image-enhancement`  
+**엔진:** 분석 기반 (Sharp 히스토그램 및 통계)
+
+이미지를 분석하여 노출, 대비, 화이트 밸런스, 채도, 선명도, 노이즈에 대한 자동 보정을 적용한다. 장면별 모드를 지원한다.
+
+| 매개변수 | 타입 | 기본값 | 설명 |
+|-----------|------|---------|-------------|
+| `mode` | `"auto"` \| `"portrait"` \| `"landscape"` \| `"low-light"` \| `"food"` \| `"document"` | `"auto"` | 보정 튜닝용 장면 모드 |
+| `intensity` | number (0-100) | `50` | 전체 보정 강도 |
+| `corrections.exposure` | boolean | `true` | 노출 보정 적용 |
+| `corrections.contrast` | boolean | `true` | 대비 보정 적용 |
+| `corrections.whiteBalance` | boolean | `true` | 화이트 밸런스 보정 적용 |
+| `corrections.saturation` | boolean | `true` | 채도 보정 적용 |
+| `corrections.sharpness` | boolean | `true` | 선명도 보정 적용 |
+| `corrections.denoise` | boolean | `true` | 노이즈 제거 적용 |
+| `deepEnhance` | boolean | `false` | SCUNet을 통한 AI 노이즈 제거 활성화 (`upscale-enhance` 번들 필요) |
+
+적용하지 않고 감지된 보정만 반환하는 추가 분석 엔드포인트를 `POST /api/v1/tools/image/image-enhancement/analyze`에서 사용할 수 있다.
+
+### 콘텐츠 인식 크기 조정 (심 카빙) {#content-aware-resize-seam-carving}
+
+**도구 경로:** `content-aware-resize`  
+**엔진:** Go `caire` 바이너리 (Python이 아니므로 GPU 이점 없음)
+
+저에너지 심을 제거하여 중요한 콘텐츠를 보존하면서 이미지 크기를 지능적으로 조정한다.
+
+| 매개변수 | 타입 | 기본값 | 설명 |
+|-----------|------|---------|-------------|
+| `width` | number | - | 목표 너비 |
+| `height` | number | - | 목표 높이 |
+| `protectFaces` | boolean | `false` | 감지된 얼굴 영역 보호 (`face-detection` 번들 필요) |
+| `blurRadius` | number (0-20) | `4` | 에너지 계산을 위한 사전 블러 |
+| `sobelThreshold` | number (1-20) | `2` | 가장자리 민감도 임계값 |
+| `square` | boolean | `false` | 정사각형 출력 강제 |
@@ -0,0 +1,211 @@
+---
+description: "이미지 엔진 작업 레퍼런스. 모든 Sharp 기반 이미지 처리 작업과 매개변수."
+i18n_source_hash: 42febdf85fa8
+i18n_provenance: human
+i18n_output_hash: 9a40c4b2dc21
+---
+
+# 이미지 엔진 {#image-engine}
+
+`@snapotter/image-engine` 패키지는 AI가 아닌 모든 이미지 작업을 처리합니다. 이 패키지는 [Sharp](https://sharp.pixelplumbing.com/)를 감싸며, 외부 의존성 없이 프로세스 내에서 완전히 실행됩니다.
+
+## 작업 {#operations}
+
+### resize {#resize}
+
+이미지를 특정 치수 또는 백분율로 확대/축소합니다.
+
+| 매개변수 | 타입 | 설명 |
+|---|---|---|
+| `width` | number | 목표 너비(픽셀) |
+| `height` | number | 목표 높이(픽셀) |
+| `fit` | string | `cover`, `contain`, `fill`, `inside`, 또는 `outside` |
+| `withoutEnlargement` | boolean | true이면 더 작은 이미지를 확대하지 않음 |
+| `percentage` | number | 절대 치수 대신 백분율로 확대/축소 |
+
+`width`, `height` 또는 둘 다 설정할 수 있습니다. 하나만 설정하면 나머지는 종횡비를 유지하도록 계산됩니다.
+
+### crop {#crop}
+
+이미지에서 직사각형 영역을 잘라냅니다.
+
+| 매개변수 | 타입 | 설명 |
+|---|---|---|
+| `left` | number | 왼쪽 가장자리로부터의 X 오프셋 |
+| `top` | number | 위쪽 가장자리로부터의 Y 오프셋 |
+| `width` | number | 자르기 영역의 너비 |
+| `height` | number | 자르기 영역의 높이 |
+| `unit` | string | `px`(기본값) 또는 `percent` |
+
+### rotate {#rotate}
+
+이미지를 지정한 각도만큼 회전합니다.
+
+| 매개변수 | 타입 | 설명 |
+|---|---|---|
+| `angle` | number | 회전 각도(도 단위, 0-360) |
+| `background` | string | 노출된 영역의 채우기 색상(기본값: `#000000`). 90도가 아닌 각도에만 적용됩니다. |
+
+### flip {#flip}
+
+이미지를 수평, 수직 또는 둘 다 반전합니다. 최소한 하나는 true여야 합니다.
+
+| 매개변수 | 타입 | 설명 |
+|---|---|---|
+| `horizontal` | boolean | 좌우 반전 |
+| `vertical` | boolean | 상하 반전 |
+
+### convert {#convert}
+
+이미지 형식을 변경합니다.
+
+| 매개변수 | 타입 | 설명 |
+|---|---|---|
+| `format` | string | 목표 형식: `jpg`, `png`, `webp`, `avif`, `tiff`, `gif`, `jxl`, `heic`, `heif`, `bmp`, `ico`, `jp2`, `qoi` |
+| `quality` | number | 압축 품질(1-100, 손실 형식에 적용) |
+
+처음 일곱 개 형식(`jpg`부터 `jxl`까지)은 Sharp에 의해 프로세스 내에서 인코딩됩니다. 나머지 형식은 API 계층에서 외부 인코더를 사용합니다: `heic`/`heif`는 heif-enc를 통해, `bmp`/`ico`는 ImageMagick을 통해, `jp2`는 opj_compress를 통해, `qoi`는 인라인 TypeScript 코덱을 통해 처리됩니다.
+
+### compress {#compress}
+
+형식은 그대로 유지하면서 파일 크기를 줄입니다.
+
+| 매개변수 | 타입 | 설명 |
+|---|---|---|
+| `quality` | number | 목표 품질(1-100) |
+| `targetSizeBytes` | number | 선택적 목표 파일 크기(바이트) |
+| `format` | string | 선택적 형식 재정의 |
+
+### strip-metadata {#strip-metadata}
+
+이미지에서 EXIF, IPTC, XMP, ICC 메타데이터를 제거합니다. 매개변수가 없으면(또는 `stripAll: true`) 모든 것을 제거합니다. 선택적 제거를 위해 개별 플래그를 전달하세요.
+
+| 매개변수 | 타입 | 설명 |
+|---|---|---|
+| `stripAll` | boolean | 모든 메타데이터 제거(플래그가 설정되지 않았을 때 기본값) |
+| `stripExif` | boolean | EXIF 데이터 제거(`stripGps`가 별도로 설정되지 않은 경우 GPS 포함) |
+| `stripGps` | boolean | GPS 위치 데이터 제거 |
+| `stripIcc` | boolean | ICC 색상 프로파일 제거 |
+| `stripXmp` | boolean | XMP 메타데이터 제거 |
+
+### 색상 조정 {#color-adjustments}
+
+이 작업들은 이미지의 색상 속성을 수정합니다. 각각 하나의 숫자 값을 받습니다.
+
+| 작업 | 매개변수 | 범위 | 설명 |
+|---|---|---|---|
+| `brightness` | `value` | -100 ~ 100 | 밝기 조정 |
+| `contrast` | `value` | -100 ~ 100 | 대비 조정 |
+| `saturation` | `value` | -100 ~ 100 | 색상 채도 조정 |
+
+### 색상 필터 {#color-filters}
+
+이 필터들은 고정된 색상 변환을 적용합니다. 매개변수를 받지 않습니다.
+
+| 작업 | 설명 |
+|---|---|
+| `grayscale` | 회색조로 변환 |
+| `sepia` | 세피아 톤 적용 |
+| `invert` | 모든 색상 반전 |
+
+### 색상 채널 {#color-channels}
+
+개별 RGB 색상 채널을 조정합니다. 값은 100 = 변화 없음인 배율입니다.
+
+| 매개변수 | 타입 | 설명 |
+|---|---|---|
+| `red` | number | 적색 채널 배율(0 ~ 200, 100 = 변화 없음) |
+| `green` | number | 녹색 채널 배율(0 ~ 200, 100 = 변화 없음) |
+| `blue` | number | 청색 채널 배율(0 ~ 200, 100 = 변화 없음) |
+
+### sharpen {#sharpen}
+
+단일 값으로 제어되는 간단한 선명화입니다.
+
+| 매개변수 | 타입 | 설명 |
+|---|---|---|
+| `value` | number | 선명화 강도(0 ~ 100). 0.5-10의 가우시안 시그마로 매핑됩니다. |
+
+### sharpen-advanced {#sharpen-advanced}
+
+선택 가능한 세 가지 방식과 선택적 노이즈 감소 사전 패스를 갖춘 고급 선명화입니다.
+
+| 매개변수 | 타입 | 설명 |
+|---|---|---|
+| `method` | string | `adaptive`, `unsharp-mask`, 또는 `high-pass` |
+| `sigma` | number | 가우시안 블러 반경, 0.5-10(적응형) |
+| `m1` | number | 평탄 영역 선명화, 0-10(적응형) |
+| `m2` | number | 텍스처 영역 선명화, 0-20(적응형) |
+| `x1` | number | 평탄/거친 영역 임계값, 0-10(적응형) |
+| `y2` | number | 최대 밝게 하기(헤일로 클램프), 0-50(적응형) |
+| `y3` | number | 최대 어둡게 하기(헤일로 클램프), 0-50(적응형) |
+| `amount` | number | 강도 백분율, 0-500(언샤프 마스크) |
+| `radius` | number | 블러 반경, 0.1-5.0(언샤프 마스크) |
+| `threshold` | number | 최소 가장자리 밝기, 0-255(언샤프 마스크) |
+| `strength` | number | 블렌드 강도, 0-100(하이패스) |
+| `kernelSize` | number | 3x3 / 5x5 커널에 대해 `3` 또는 `5`(하이패스) |
+| `denoise` | string | 노이즈 감소 사전 패스: `off`, `light`, `medium`, 또는 `strong` |
+
+매개변수는 방식별로 다릅니다. 선택한 방식에 관련된 것만 제공하세요.
+
+### color-blindness {#color-blindness}
+
+3x3 색상 재조합 행렬을 사용해 색각 이상을 시뮬레이션합니다.
+
+| 매개변수 | 타입 | 설명 |
+|---|---|---|
+| `type` | string | 다음 중 하나: `protanopia`, `deuteranopia`, `tritanopia`, `protanomaly`, `deuteranomaly`, `tritanomaly`, `achromatopsia`, `blueConeMonochromacy` |
+
+### edit-metadata {#edit-metadata}
+
+전체 블록을 제거하지 않고 개별 EXIF/IPTC 메타데이터 필드를 작성하거나 제거합니다.
+
+| 매개변수 | 타입 | 설명 |
+|---|---|---|
+| `artist` | string | EXIF Artist 태그 |
+| `copyright` | string | EXIF Copyright 태그 |
+| `imageDescription` | string | EXIF ImageDescription 태그 |
+| `software` | string | EXIF Software 태그 |
+| `dateTime` | string | EXIF DateTime 태그 |
+| `dateTimeOriginal` | string | EXIF DateTimeOriginal 태그 |
+| `clearGps` | boolean | 모든 GPS 태그 제거 |
+| `fieldsToRemove` | string[] | 삭제할 EXIF 필드명 목록 |
+
+모든 매개변수는 선택 사항입니다. `fieldsToRemove`에 나열된 필드는 기존 EXIF 블록에서 삭제됩니다. 명명된 매개변수를 통해 설정된 필드는 기록(또는 덮어쓰기)됩니다. MakerNote 같은 바이너리/안전하지 않은 키는 조용히 무시됩니다.
+
+## 형식 감지 {#format-detection}
+
+엔진은 파일 확장자뿐 아니라 파일 헤더로부터 입력 형식을 자동으로 감지합니다. 따라서 실제로는 PNG인 `.jpg` 파일도 올바르게 처리됩니다. 감지는 다층 방식을 사용합니다: 먼저 매직 바이트, 그다음 대체 수단으로 파일 확장자를 사용합니다.
+
+SnapOtter는 **55개 이상의 입력 형식**과 **13개의 출력 형식**을 지원하며, 여기에는 20개 이상 브랜드의 카메라 RAW 형식 23종, 전문 형식(PSD, EPS, OpenEXR, HDR), 최신 코덱(JPEG XL, AVIF, HEIC, QOI, JPEG 2000), 과학/게임 형식(FITS, DDS)이 포함됩니다. 디코딩은 가능한 경우 Sharp가 기본적으로 처리하며, ImageMagick, LibRaw, 특수 CLI 디코더로 자동 대체됩니다.
+
+전체 목록은 [지원 형식](/ko/guide/supported-formats) 페이지를 참고하세요.
+
+## 메타데이터 추출 {#metadata-extraction}
+
+`info` 도구는 이미지 메타데이터를 반환합니다. 전체 필드 레퍼런스는 [이미지 정보](/ko/tools/image/info)를 참고하세요.
+
+```json
+{
+  "filename": "photo.jpg",
+  "fileSize": 2450000,
+  "width": 4032,
+  "height": 3024,
+  "format": "jpeg",
+  "channels": 3,
+  "hasAlpha": false,
+  "colorSpace": "srgb",
+  "density": 72,
+  "isProgressive": false,
+  "hasExif": true,
+  "hasIcc": true,
+  "hasXmp": false,
+  "bitDepth": "8",
+  "pages": 1,
+  "histogram": [
+    { "channel": "red", "min": 0, "max": 255, "mean": 128.45, "stdev": 52.31 },
+    { "channel": "green", "min": 2, "max": 253, "mean": 115.22, "stdev": 48.76 },
+    { "channel": "blue", "min": 0, "max": 250, "mean": 102.89, "stdev": 55.14 }
+  ]
+}
+```
@@ -0,0 +1,702 @@
+---
+description: "전체 REST API 레퍼런스. 도구 엔드포인트, 배치 처리, 파이프라인, 파일 라이브러리, 인증, 팀, 관리 작업."
+i18n_source_hash: 8646977f7cc9
+i18n_provenance: machine
+i18n_output_hash: a4289adc1b56
+---
+
+# REST API 레퍼런스 {#rest-api-reference}
+
+요청/응답 예제가 포함된 대화형 API 문서는 [http://localhost:1349/api/docs](http://localhost:1349/api/docs)에서 확인할 수 있습니다.
+
+기계 판독 가능 스펙:
+- `/api/v1/openapi.yaml` - OpenAPI 3.1 스펙
+- `/llms.txt` - LLM 친화적 요약
+- `/llms-full.txt` - 전체 LLM 친화적 문서
+
+## 인증 {#authentication}
+
+`AUTH_ENABLED=false`가 아닌 한 모든 엔드포인트는 인증이 필요합니다.
+
+### 세션 토큰 {#session-token}
+
+```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
+curl http://localhost:1349/api/v1/tools/image/resize \
+  -H "Authorization: Bearer <session-token>"
+```
+
+세션은 7일 후 만료됩니다(`SESSION_DURATION_HOURS`로 구성 가능).
+
+### API 키 {#api-keys}
+
+```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 http://localhost:1349/api/v1/tools/image/resize \
+  -H "Authorization: Bearer si_<your-key>"
+```
+
+키는 `si_` 접두사가 붙으며 scrypt 해시로 저장됩니다. 원본 키는 한 번만 표시되며 이후 다시 조회할 수 없습니다.
+
+### 인증 엔드포인트 {#auth-endpoints}
+
+| 메서드 | 경로 | 접근 권한 | 설명 |
+|--------|------|--------|-------------|
+| `POST` | `/api/auth/login` | 공개 | 로그인, 세션 토큰 획득 |
+| `POST` | `/api/auth/logout` | 인증 | 현재 세션 종료 |
+| `GET` | `/api/auth/session` | 인증 | 현재 세션 검증 |
+| `POST` | `/api/auth/change-password` | 인증 | 본인 비밀번호 변경(다른 모든 세션 + API 키 무효화) |
+| `GET` | `/api/auth/users` | 관리자 | 전체 사용자 목록 조회 |
+| `POST` | `/api/auth/register` | 관리자 | 새 사용자 생성 |
+| `PUT` | `/api/auth/users/:id` | 관리자 | 사용자 역할 또는 팀 업데이트 |
+| `POST` | `/api/auth/users/:id/reset-password` | 관리자 | 사용자 비밀번호 재설정 |
+| `DELETE` | `/api/auth/users/:id` | 관리자 | 사용자 삭제 |
+| `GET` | `/api/v1/config/auth` | 공개 | 인증 활성화 여부 확인(`{ authEnabled: bool }`) |
+| `POST` | `/api/auth/mfa/enroll` | 인증 | TOTP MFA 등록 시작. 엔터프라이즈 `mfa` 기능 필요 |
+| `POST` | `/api/auth/mfa/verify` | 인증 | TOTP 코드로 MFA 등록 확인 |
+| `POST` | `/api/auth/mfa/complete` | 공개 | 대기 중인 MFA 로그인 챌린지 완료 |
+| `POST` | `/api/auth/mfa/disable` | 인증 | 현재 사용자의 MFA 비활성화 |
+| `POST` | `/api/auth/users/:id/mfa/reset` | 관리자(`users:manage`) | 사용자의 MFA 재설정 |
+| `GET` | `/api/auth/oidc/login` | 공개 | OIDC 활성화 시 OIDC 로그인 시작 |
+| `GET` | `/api/auth/oidc/callback` | 공개 | OIDC 인가 콜백 |
+| `GET` | `/api/auth/saml/metadata` | 공개 | SAML 활성화 시 SAML SP 메타데이터 XML |
+| `GET` | `/api/auth/saml/login` | 공개 | SAML 로그인 시작 |
+| `POST` | `/api/auth/saml/callback` | 공개 | SAML 어설션 컨슈머 서비스 |
+
+사용자에 대해 MFA가 활성화되면 `POST /api/auth/login`는 세션 토큰 대신 `{"requiresMfa":true,"mfaToken":"...","mfaRequired":true|false}`를 반환합니다. 해당 `mfaToken`와 함께 TOTP 또는 복구 코드를 `/api/auth/mfa/complete`로 전송하세요.
+
+### 권한 {#permissions}
+
+| 권한 | 관리자 | 사용자 |
+|-----------|:-----:|:----:|
+| 도구 사용 | ✓ | ✓ |
+| 본인 파일/파이프라인/API 키 | ✓ | ✓ |
+| 전체 사용자의 파일/파이프라인/키 조회 | ✓ | - |
+| 설정 쓰기 | ✓ | - |
+| 사용자 및 팀 관리 | ✓ | - |
+| 브랜딩 관리 | ✓ | - |
+
+## 상태 확인 {#health-check}
+
+| 메서드 | 경로 | 접근 권한 | 설명 |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/health` | 공개 | 기본 상태 확인. 200과 함께 `{"status":"healthy","version":"..."}`를 반환하거나, 데이터베이스에 연결할 수 없으면 503과 함께 `{"status":"unhealthy"}`을 반환합니다. |
+| `GET` | `/api/v1/readyz` | 공개 | 준비 상태 프로브. PostgreSQL, Redis, 디스크 공간, 그리고 구성된 경우 S3를 확인합니다. 인스턴스가 트래픽을 받으면 안 되는 경우 503을 반환합니다. |
+| `GET` | `/api/v1/admin/health` | 관리자(`system:health`) | 가동 시간, 스토리지 모드, 데이터베이스 상태, 큐 상태, GPU 가용성을 포함한 상세 진단. |
+
+## 도구 사용 {#using-tools}
+
+모든 도구는 동일한 패턴을 따릅니다:
+
+```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` 헤더 포함) 반환합니다.
+
+## 도구 레퍼런스 {#tools-reference}
+
+### 변환 프리셋 {#conversion-presets}
+
+공유 카탈로그에는 `jpg-to-png`, `mov-to-mp4`, `m4a-to-mp3`, `pdf-to-jpg`, `excel-to-csv`과 같은 83개의 전용 변환 프리셋 엔드포인트가 포함되어 있습니다. 프리셋은 일급 도구 경로입니다:
+
+`POST /api/v1/tools/<section>/<presetId>`
+
+각 프리셋은 출력 형식을 고정하고 `convert`, `convert-video`, `extract-audio`, `convert-audio`, `image-to-pdf`, `pdf-to-image`, `svg-to-raster`, `convert-spreadsheet`과 같은 기본 도구에 위임합니다. 전체 경로 표와 선택적 설정은 [변환 프리셋](/ko/tools/conversion-presets)을 참고하세요.
+
+### 필수 도구 {#essentials}
+
+| 도구 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` |
+
+### 최적화 {#optimization}
+
+| 도구 ID | 이름 | 주요 설정 |
+|---------|------|-------------|
+| `optimize-for-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` - 모든 표준 크기를 생성합니다 |
+
+### 조정 {#adjustments}
+
+| 도구 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-tools}
+
+모든 AI 도구는 사용자의 하드웨어에서 실행됩니다: 기본적으로 CPU, 지원되는 NVIDIA GPU가 있는 경우 NVIDIA CUDA. VA-API, Quick Sync 또는 OpenCL을 통한 Intel/AMD iGPU 가속은 현재 AI 추론에 지원되지 않습니다. 인터넷 연결이 필요 없습니다.
+
+| 도구 ID | 이름 | AI 모델 | 주요 설정 |
+|---------|------|---------|-------------|
+| `remove-background` | 배경 제거 | rembg(BiRefNet / U2-Net) | `model`, `backgroundType`(transparent/color/gradient/blur/image), `backgroundColor`, `gradientColor1`, `gradientColor2`, `gradientAngle`, `blurEnabled`, `blurIntensity`, `shadowEnabled`, `shadowOpacity` |
+| `upscale` | 이미지 업스케일 | RealESRGAN | `scale`(2/4), `model`, `faceEnhance`, `denoise`, `format`, `quality` |
+| `erase-object` | 오브젝트 지우개 | LaMa(ONNX) | 마스크는 두 번째 파일 파트로 전송(필드명 `mask`), `format`, `quality` |
+| `ocr` | OCR / 텍스트 추출 | PaddleOCR / Tesseract | `quality`(fast/balanced/best), `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-매팅 | `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` |
+
+### 워터마크 및 오버레이 {#watermark-overlay}
+
+| 도구 ID | 이름 | 주요 설정 |
+|---------|------|-------------|
+| `watermark-text` | 텍스트 워터마크 | `text`, `font`, `fontSize`, `color`, `opacity`, `position`, `rotation`, `tile` |
+| `watermark-image` | 이미지 워터마크 | `opacity`, `position`, `scale` - 두 번째 파일이 워터마크입니다 |
+| `text-overlay` | 텍스트 오버레이 | `text`, `font`, `fontSize`, `color`, `x`, `y`, `background`, `padding`, `borderRadius` |
+| `compose` | 이미지 합성 | `x`, `y`, `opacity`, `blend` - 두 번째 파일이 위에 레이어링됩니다 |
+| `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 본문) 또는 커스텀 이미지 모드(파일을 담은 멀티파트)를 지원합니다. |
+
+### 유틸리티 {#utilities}
+
+| 도구 ID | 이름 | 주요 설정 |
+|---------|------|-------------|
+| `info` | 이미지 정보 | - (너비, 높이, 형식, 크기, 채널, hasAlpha, DPI, EXIF 반환) |
+| `compare` | 이미지 비교 | `mode`(side-by-side/overlay/diff), `diffThreshold` - 두 번째 파일이 비교 대상입니다 |
+| `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 본문, 파일 업로드 없음. |
+
+### 레이아웃 및 합성 {#layout-composition}
+
+| 도구 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` |
+| `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개 이미지) |
+
+### 형식 및 변환 {#format-conversion}
+
+| 도구 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 도구 | `action`(resize/optimize/reverse/speed/extract-frames/rotate/add-text), 액션별 매개변수 |
+| `gif-webp` | GIF/WebP 변환기 | `quality`(1-100), `lossless`(bool), `resizePercent`(10-100) |
+
+### 비디오 도구 {#video-tools}
+
+| 도구 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` | 비디오 자르기 | `startS`, `endS`, `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-frames` | 비디오를 프레임으로 | `mode`(all/nth/timestamps), `n`, `timestamps`, `format`(png/jpg) |
+| `merge-videos` | 비디오 병합 | - (다중 파일, 첫 번째 비디오의 해상도로 정규화됨) |
+| `replace-audio` | 오디오 교체 | - (비디오 + 오디오 파일, 두 개 파일) |
+| `burn-subtitles` | 자막 굽기 | `fontSize`(8-72) - 비디오 + 자막 파일 |
+| `embed-subtitles` | 자막 임베드 | `language`(ISO 639-2/B 코드) - 비디오 + 자막 파일 |
+| `extract-subtitles` | 자막 추출 | - (SRT 출력) |
+| `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) |
+
+### 오디오 도구 {#audio-tools}
+
+| 도구 ID | 이름 | 주요 설정 |
+|---------|------|-------------|
+| `convert-audio` | 오디오 변환 | `format`(mp3/wav/ogg/flac/m4a), `bitrateKbps`(32-320) |
+| `trim-audio` | 오디오 자르기 | `startS`, `endS` |
+| `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) |
+
+### 문서 도구 {#document-tools}
+
+| 도구 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") |
+| `protect-pdf` | PDF 보호 | `userPassword`, `ownerPassword`(AES-256) |
+| `unlock-pdf` | PDF 잠금 해제 | `password` |
+| `repair-pdf` | PDF 복구 | - |
+| `linearize-pdf` | PDF 웹 최적화 | - (빠른 웹 뷰잉을 위한 선형화) |
+| `grayscale-pdf` | PDF 흑백화 | - |
+| `pdfa-convert` | PDF/A 변환 | - (보존용 PDF/A-2) |
+| `crop-pdf` | PDF 자르기 | `margin`(0-2000 포인트) |
+| `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-metadata` | PDF 메타데이터 | `title`, `author`, `subject`, `keywords` |
+| `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` |
+
+### 파일 도구 {#file-tools}
+
+| 도구 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 병합 | - (다중 파일, 일치하는 열) |
+| `yaml-json` | YAML / JSON | - (양방향) |
+| `xml-to-csv` | XML을 CSV로 | - (반복 요소 자동 탐지) |
+| `excel-to-csv` | Excel을 CSV로 | `convert-spreadsheet`로 지원되는 전용 변환 프리셋 |
+| `create-zip` | ZIP 생성 | - (다중 파일, 2-50개 파일) |
+| `extract-zip` | ZIP 추출 | - (봄 보호) |
+
+### HTML을 이미지로 {#html-to-image}
+
+웹페이지를 이미지로 캡처합니다. 다른 도구와 달리 이 엔드포인트는 멀티파트 폼 데이터 대신 `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 |
+
+**예시:**
+
+```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
+}
+```
+
+### 도구 하위 경로 {#tool-sub-routes}
+
+일부 도구는 표준 `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` | 실시간 매개변수 조정을 위한 경량 미리보기. 크기 헤더가 포함된 최적화된 이미지를 반환합니다. |
+
+## 배치 처리 {#batch-processing}
+
+제네릭 배치 지원 도구를 여러 파일에 한 번에 적용합니다. ZIP 아카이브를 반환합니다. PDF 서명, PDF 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으로 설정).
+
+## 파이프라인 {#pipelines}
+
+### 파이프라인 실행 {#execute-a-pipeline}
+
+```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`로 설정하면 제한이 제거됩니다.
+
+### 파이프라인 저장 및 관리 {#save-and-manage-pipelines}
+
+| 메서드 | 경로 | 설명 |
+|--------|------|-------------|
+| `POST` | `/api/v1/pipeline/save` | 이름이 지정된 파이프라인 저장(`name`, `description`, `steps[]`) |
+| `GET` | `/api/v1/pipeline/list` | 저장된 파이프라인 목록(관리자는 전체, 사용자는 본인 것 조회) |
+| `DELETE` | `/api/v1/pipeline/:id` | 삭제(소유자 또는 관리자) |
+| `GET` | `/api/v1/pipeline/tools` | 파이프라인 단계에 유효한 도구 ID 목록 |
+
+## 진행률 추적 {#progress-tracking}
+
+장시간 실행 작업, 큐에 들어간 도구, 배치 작업, 파이프라인은 Server-Sent Events를 통해 실시간 진행률을 발행합니다. 진행률 스트림은 공개이며 작업 ID로 키가 지정되므로 클라이언트가 이를 읽는 데 Authorization 헤더를 보낼 필요가 없습니다.
+
+```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
+```
+
+이벤트 형식:
+```
+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}`입니다.
+
+## 파일 라이브러리 {#file-library}
+
+버전 이력이 있는 영구 파일 저장소.
+
+| 메서드 | 경로 | 설명 |
+|--------|------|-------------|
+| `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/fetch-urls` | URL 기반 가져오기를 위해 원격 URL을 워크스페이스로 페치 |
+| `POST` | `/api/v1/preview` | 브라우저 호환 WebP 미리보기 생성(HEIC/HEIF/RAW 형식용) |
+| `GET` | `/api/v1/files/:id/preview` | 저장된 PDF, 오피스 문서, 비디오 또는 오디오 파일에 대해 캐시되었거나 생성된 브라우저 호환 미리보기 스트리밍 |
+| `POST` | `/api/v1/preview/generate` | 업로드된 미디어 파일을 먼저 저장하지 않고 온디맨드 MP4 또는 MP3 미리보기 생성 |
+| `GET` | `/api/v1/download/:jobId/:filename` | 워크스페이스에서 처리된 파일 다운로드 |
+
+도구 결과를 라이브러리에 자동 저장하려면 기존 라이브러리 파일을 참조하는 `fileId`을 멀티파트 폼 필드로 포함하세요. 처리된 결과가 새 버전으로 저장됩니다.
+
+## API 키 관리 {#api-key-management}
+
+| 메서드 | 경로 | 접근 권한 | 설명 |
+|--------|------|--------|-------------|
+| `POST` | `/api/v1/api-keys` | 인증 | 새 키 생성 - 한 번만 표시됨 |
+| `GET` | `/api/v1/api-keys` | 인증 | 키 목록(name, id, lastUsedAt - 원본 키 아님) |
+| `DELETE` | `/api/v1/api-keys/:id` | 인증 | 키 삭제 |
+
+## 팀 {#teams}
+
+| 메서드 | 경로 | 접근 권한 | 설명 |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/teams` | 관리자(`teams:manage`) | 팀 목록 |
+| `POST` | `/api/v1/teams` | 관리자(`teams:manage`) | 팀 생성 |
+| `PUT` | `/api/v1/teams/:id` | 관리자(`teams:manage`) | 팀 이름 변경 |
+| `DELETE` | `/api/v1/teams/:id` | 관리자(`teams:manage`) | 팀 삭제(기본 팀 또는 멤버가 있는 팀은 삭제 불가) |
+
+## 설정 {#settings}
+
+런타임 키-값 구성(인증된 모든 사용자가 읽기, 관리자만 쓰기).
+
+| 메서드 | 경로 | 설명 |
+|--------|------|-------------|
+| `GET` | `/api/v1/settings` | 모든 설정 획득 |
+| `PUT` | `/api/v1/settings` | 설정 일괄 업데이트(키-값 쌍을 담은 JSON 본문) |
+| `GET` | `/api/v1/settings/:key` | 키로 특정 설정 획득 |
+
+알려진 키: `disabledTools`(도구 ID의 JSON 배열), `enableExperimentalTools`(bool 문자열), `loginAttemptLimit`(number).
+
+## 환경설정 {#preferences}
+
+사용자별 환경설정은 인스턴스 설정과 별개입니다. 인증된 모든 사용자는 자신의 환경설정 맵을 읽고 업데이트할 수 있습니다.
+
+| 메서드 | 경로 | 설명 |
+|--------|------|-------------|
+| `GET` | `/api/v1/preferences` | 현재 사용자의 환경설정을 `{ "preferences": { ... } }`로 획득 |
+| `PUT` | `/api/v1/preferences` | 현재 사용자에 대해 하나 이상의 환경설정 키를 업서트 |
+
+## 역할 {#roles}
+
+세분화된 권한을 가진 커스텀 역할 관리.
+
+| 메서드 | 경로 | 접근 권한 | 설명 |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/roles` | 관리자(`audit:read`) | 사용자 수와 함께 모든 역할 목록 |
+| `POST` | `/api/v1/roles` | 관리자(`security:manage`) | 커스텀 역할 생성(`name`, `description`, `permissions`) |
+| `PUT` | `/api/v1/roles/:id` | 관리자(`security:manage`) | 커스텀 역할 업데이트(기본 제공 역할은 수정 불가) |
+| `DELETE` | `/api/v1/roles/:id` | 관리자(`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`.
+
+## 감사 로그 {#audit-log}
+
+보안 관련 작업을 검토하기 위한 관리자 전용 엔드포인트.
+
+| 메서드 | 경로 | 접근 권한 | 설명 |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/audit-log` | 관리자(`audit:read`) | 선택적 필터가 있는 페이지 처리된 감사 로그 |
+
+쿼리 매개변수:
+
+| 매개변수 | 설명 |
+|-----------|-------------|
+| `page` | 페이지 번호(기본값: 1) |
+| `limit` | 페이지당 항목 수(기본값: 50, 최대: 100) |
+| `action` | 액션 유형으로 필터링(예: `ROLE_CREATED`, `ROLE_DELETED`) |
+| `ip` | 소스 IP 주소로 필터링 |
+| `from` | 이 ISO 8601 날짜 이후의 항목 필터링 |
+| `to` | 이 ISO 8601 날짜 이전의 항목 필터링 |
+
+## 분석 {#analytics}
+
+| 메서드 | 경로 | 접근 권한 | 설명 |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/config/analytics` | 공개 | 유효한 분석 구성 획득(PostHog 키, Sentry DSN, 샘플 레이트). 컴파일 타임 베이크 또는 인스턴스 `analyticsEnabled` 설정으로 인해 분석이 꺼져 있으면 키, DSN, 인스턴스 ID는 비어 있습니다. |
+| `POST` | `/api/v1/feedback` | 인증 | 명시적 사용자 피드백을 구성된 PostHog 프로젝트에 `feedback_submitted`로 제출. 이 경로는 분석 게이트를 준수하고, 제출 속도를 제한하며, `contactOk`이 true가 아닌 한 연락처 필드를 제거하고, 파일 내용, 파일 이름, 업로드 경로 또는 원본 비공개 오류 텍스트를 절대 받지 않습니다. 분석이 비활성화되면 `{ "ok": true, "accepted": false }`를 반환합니다. |
+| `PUT` | `/api/v1/settings` | 관리자(`settings:write`) | 인스턴스 전체 옵트아웃 설정. 모두에 대해 분석을 끄려면 JSON 본문 `{ "analyticsEnabled": "false" }`을, 다시 켜려면 `"true"`를 보냅니다. |
+
+## 기능 / AI 번들 {#features-ai-bundles}
+
+AI 기능 번들 관리(Docker 환경에서 AI 모델 패키지 설치/제거). 커스텀 자동화에서 도구를 활성화할 때는 도구 수준 설치 엔드포인트를 선호하세요: 일부 AI 도구는 둘 이상의 공유 번들이 필요하며, 이 엔드포인트는 이미 설치된 번들을 건너뛰고 누락된 번들만 큐에 넣습니다.
+
+| 메서드 | 경로 | 접근 권한 | 설명 |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/features` | 인증 | 모든 기능 번들과 설치 상태 목록 |
+| `POST` | `/api/v1/admin/features/:bundleId/install` | 관리자(`features:manage`) | 기능 번들 설치(비동기, 진행률 추적을 위해 `jobId` 반환) |
+| `POST` | `/api/v1/admin/tools/:toolId/features/install` | 관리자(`features:manage`) | 도구에 필요한 모든 번들 설치; 번들별 큐잉/건너뜀 상태 반환 |
+| `POST` | `/api/v1/admin/features/:bundleId/uninstall` | 관리자(`features:manage`) | 기능 번들 제거 및 모델 파일 정리 |
+| `GET` | `/api/v1/admin/features/disk-usage` | 관리자(`features:manage`) | AI 모델의 총 디스크 사용량 획득 |
+| `POST` | `/api/v1/admin/features/import` | 관리자(`features:manage`) | 오프라인 AI 번들 아카이브 가져오기 |
+
+## 관리 작업 {#admin-operations}
+
+관찰 가능성, 지원, 사용량 보고, 백업 상태를 위한 운영 엔드포인트.
+
+| 메서드 | 경로 | 접근 권한 | 설명 |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/admin/log-level` | 관리자(`settings:write`) | 현재 런타임 로그 레벨 읽기 |
+| `POST` | `/api/v1/admin/log-level` | 관리자(`settings:write`) | 런타임 로그 레벨 변경(`fatal`, `error`, `warn`, `info`, `debug`, `trace` 또는 `silent`) |
+| `GET` | `/api/v1/metrics` | 관리자(`system:health`) | 텍스트 형식의 Prometheus 메트릭 |
+| `GET` | `/api/v1/admin/support-bundle` | 관리자(`system:health`) | 편집된 진단 지원 번들 ZIP 다운로드 |
+| `GET` | `/api/v1/admin/usage` | 관리자(`audit:read`) | 선택적 `days` 쿼리 매개변수가 있는 사용량 대시보드 데이터 |
+| `GET` | `/api/v1/admin/backup-status` | 관리자(`system:health`) | 마지막 백업 메타데이터와 최신성 상태 읽기 |
+| `POST` | `/api/v1/admin/backup-status` | 관리자(`system:health`) | 완료된 백업 기록(`type`, 선택적 `sizeBytes`, 선택적 `notes`) |
+
+## 엔터프라이즈 API {#enterprise-apis}
+
+이 경로들은 관련 엔터프라이즈 기능에 의해 라이선스 게이트가 적용됩니다. 여전히 나열된 SnapOtter 권한이 필요합니다.
+
+| 메서드 | 경로 | 접근 권한 | 설명 |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/enterprise/audit/export` | 관리자(`audit:read`) | 필터와 함께 감사 항목을 JSON 또는 CSV로 내보내기 |
+| `GET` | `/api/v1/enterprise/config/export` | 관리자(`system:health`) | 편집된 인스턴스 구성, 커스텀 역할, 팀 내보내기 |
+| `POST` | `/api/v1/enterprise/config/import` | 관리자(`system:health`) | 선택적 드라이런과 함께 구성 가져오기 |
+| `GET` | `/api/v1/enterprise/ip-allowlist` | 관리자(`security:manage`) | 구성된 CIDR 허용 목록 읽기 |
+| `PUT` | `/api/v1/enterprise/ip-allowlist` | 관리자(`security:manage`) | 자기 잠금 방지와 함께 CIDR 허용 목록 업데이트 |
+| `GET` | `/api/v1/enterprise/legal-hold` | 관리자(`compliance:manage`) | 사용자 및 팀 법적 보존 목록 |
+| `PUT` | `/api/v1/enterprise/legal-hold` | 관리자(`compliance:manage`) | 사용자 또는 팀에 법적 보존 적용 또는 해제 |
+| `POST` | `/api/v1/enterprise/scim/token` | 관리자(`users:manage`) | SCIM 베어러 토큰 생성, 한 번만 반환됨 |
+| `DELETE` | `/api/v1/enterprise/scim/token` | 관리자(`users:manage`) | 현재 SCIM 베어러 토큰 취소 |
+| `GET` | `/api/v1/enterprise/siem/config` | 관리자(`webhooks:manage`) | SIEM 포워딩 구성 읽기 |
+| `PUT` | `/api/v1/enterprise/siem/config` | 관리자(`webhooks:manage`) | SIEM 포워딩 구성 업데이트 |
+| `GET` | `/api/v1/enterprise/webhooks` | 관리자(`webhooks:manage`) | 웹훅 대상 목록 |
+| `POST` | `/api/v1/enterprise/webhooks` | 관리자(`webhooks:manage`) | 웹훅 대상 생성 |
+| `PUT` | `/api/v1/enterprise/webhooks/:index` | 관리자(`webhooks:manage`) | 웹훅 대상 업데이트 |
+| `DELETE` | `/api/v1/enterprise/webhooks/:index` | 관리자(`webhooks:manage`) | 웹훅 대상 삭제 |
+| `POST` | `/api/v1/enterprise/webhooks/:index/test` | 관리자(`webhooks:manage`) | 테스트 웹훅 페이로드 전송 |
+| `POST` | `/api/v1/enterprise/users/:id/export` | 관리자(`compliance:manage`) | GDPR 사용자 내보내기 작업 시작 |
+| `GET` | `/api/v1/enterprise/users/:id/export/:jobId` | 관리자(`compliance:manage`) | GDPR 내보내기 상태 및 다운로드 URL 읽기 |
+| `DELETE` | `/api/v1/enterprise/users/:id/purge` | 관리자(`compliance:manage`) | 확인 후 사용자 데이터 영구 삭제 |
+| `DELETE` | `/api/v1/enterprise/teams/:id/purge` | 관리자(`compliance:manage`) | 확인 후 팀 데이터 영구 삭제 |
+| `GET` | `/api/v1/admin/version` | 관리자(`system:health`) | 앱, 빌드, Node, 스키마 버전 메타데이터 읽기 |
+| `GET` | `/api/v1/admin/migrations/pending` | 관리자(`system:health`) | 패키징된 마이그레이션과 적용된 마이그레이션 비교 |
+| `GET` | `/api/v1/admin/upgrade-check` | 관리자(`system:health`) | 업그레이드 준비 상태 검사 실행 |
+
+### SCIM 2.0 {#scim-2-0}
+
+SCIM 디스커버리 엔드포인트는 공개입니다. 사용자 및 그룹 엔드포인트는 위에서 생성한 SCIM 베어러 토큰이 필요합니다.
+
+| 메서드 | 경로 | 접근 권한 | 설명 |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/scim/v2/ServiceProviderConfig` | 공개 | SCIM 서버 기능 |
+| `GET` | `/api/v1/scim/v2/Schemas` | 공개 | SCIM 스키마 디스커버리 |
+| `GET` | `/api/v1/scim/v2/ResourceTypes` | 공개 | SCIM 리소스 유형 디스커버리 |
+| `GET` | `/api/v1/scim/v2/Users` | SCIM 토큰 | 선택적 SCIM 필터가 있는 사용자 목록 |
+| `POST` | `/api/v1/scim/v2/Users` | SCIM 토큰 | 사용자 생성 |
+| `GET` | `/api/v1/scim/v2/Users/:id` | SCIM 토큰 | 사용자 획득 |
+| `PUT` | `/api/v1/scim/v2/Users/:id` | SCIM 토큰 | 사용자 교체 |
+| `DELETE` | `/api/v1/scim/v2/Users/:id` | SCIM 토큰 | 사용자 소프트 비활성화 |
+| `GET` | `/api/v1/scim/v2/Groups` | SCIM 토큰 | 팀을 SCIM 그룹으로 목록화 |
+| `POST` | `/api/v1/scim/v2/Groups` | SCIM 토큰 | 팀 생성 |
+| `GET` | `/api/v1/scim/v2/Groups/:id` | SCIM 토큰 | 팀 획득 |
+| `PUT` | `/api/v1/scim/v2/Groups/:id` | SCIM 토큰 | 팀 및 그룹 멤버십 교체 |
+| `DELETE` | `/api/v1/scim/v2/Groups/:id` | SCIM 토큰 | 팀 삭제 |
+
+## 밈 템플릿 {#meme-templates}
+
+밈 생성기 도구를 위한 지원 API.
+
+| 메서드 | 경로 | 접근 권한 | 설명 |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/meme-templates` | 인증 | 텍스트 상자 위치와 함께 사용 가능한 모든 밈 템플릿 목록 |
+| `GET` | `/api/v1/meme-templates/full/:filename` | 인증 | 전체 크기 템플릿 이미지 제공 |
+| `GET` | `/api/v1/meme-templates/thumbs/:filename` | 인증 | 템플릿 썸네일 제공 |
+| `GET` | `/api/v1/meme-templates/fonts/:filename` | 인증 | 밈 텍스트 렌더링에 사용되는 폰트 파일 제공 |
+
+## 오류 응답 {#error-responses}
+
+모든 오류는 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 | 내부 서버 오류 |