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: "เอกสารอ้างอิงเอนจิน AI พร้อมเครื่องมือ ML ในเครื่องทั้งหมด การลบพื้นหลัง การขยายภาพ OCR การตรวจจับใบหน้า การกู้คืนภาพถ่าย และอื่น ๆ"
+i18n_source_hash: 14728c1dcd05
+i18n_provenance: machine
+i18n_output_hash: 76c10fa3ca33
+---
+
+# เอกสารอ้างอิงเอนจิน AI {#ai-engine-reference}
+
+แพ็กเกจ `@snapotter/ai` เชื่อมโยง Node.js เข้ากับ **Python sidecar แบบถาวร** สำหรับการดำเนินการ ML ทั้งหมด กระบวนการ dispatcher จะคงอยู่ระหว่างคำขอเพื่อประสิทธิภาพการเริ่มต้นแบบ warm-start ที่รวดเร็ว NVIDIA CUDA จะถูกตรวจจับโดยอัตโนมัติเมื่อเริ่มต้นและใช้งานเมื่อพร้อมใช้งาน มิฉะนั้นเครื่องมือ AI จะทำงานบน CPU
+
+การเร่งความเร็ว iGPU ของ Intel/AMD ผ่าน VA-API, Quick Sync หรือ OpenCL ยังไม่รองรับสำหรับการอนุมาน AI ในปัจจุบัน การแมป `/dev/dri` เข้าไปในคอนเทนเนอร์ไม่ได้เร่งความเร็วเครื่องมือ Python sidecar เหล่านี้ เว้นแต่จะมี NVIDIA GPU ที่รองรับ CUDA พร้อมใช้งาน
+
+เครื่องมือ AI แบบ Python sidecar จำนวน 19 รายการครอบคลุมสี่โมดาลิตี (ภาพ เสียง วิดีโอ เอกสาร) พร้อมด้วยเครื่องมืออีก 2 รายการที่มีความสามารถ AI เสริม โมเดลทั้งหมดทำงานในเครื่อง ไม่ต้องใช้อินเทอร์เน็ตหลังจากดาวน์โหลดโมเดลครั้งแรก
+
+## สถาปัตยกรรม {#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)
+```
+
+โปรไฟล์ dispatcher แบบ "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) {#feature-bundles}
+
+โมเดล AI ถูกจัดแพ็กเกจตามชุด dependency ที่ใช้ร่วมกัน ไม่ใช่หนึ่งไฟล์เก็บถาวรต่อหนึ่งเครื่องมือ ชุดฟีเจอร์หนึ่งชุดสามารถเปิดใช้งานเครื่องมือได้หลายรายการเมื่อเครื่องมือเหล่านั้นใช้ตระกูลโมเดล, Python wheel หรือไลบรารีเนทีฟเดียวกัน วิธีนี้ทำให้ Docker image สำหรับรีลีสมีขนาดเล็กลงและหลีกเลี่ยงการเก็บสำเนาซ้ำของโมเดล background matting, การตรวจจับใบหน้า, OCR, การกู้คืน และโมเดลเสียงพูดเดียวกัน
+
+Docker image มาพร้อมกับแอปพลิเคชันบวกกับรันไทม์ทั่วไป ไฟล์เก็บถาวรของโมเดลขนาดใหญ่จะถูกดาวน์โหลดตามความต้องการลงในโวลุ่ม `/data/ai` แบบถาวร แล้วนำกลับมาใช้ซ้ำโดยทุกเครื่องมือที่ต้องการ หากติดตั้งชุดฟีเจอร์แล้วเนื่องจากมีเครื่องมืออื่นต้องการใช้ การเปิดใช้งานเครื่องมือใหม่ที่ต้องพึ่งพาชุดนั้นจะไม่ดาวน์โหลดชุดฟีเจอร์นั้นซ้ำอีก
+
+เครื่องมือ AI แต่ละรายการต้องมีชุดฟีเจอร์ตั้งแต่หนึ่งชุดขึ้นไปก่อนจึงจะทำงานได้ UI ของผู้ดูแลระบบติดตั้งตามเครื่องมือผ่าน `POST /api/v1/admin/tools/:toolId/features/install` ซึ่งจะแยกรายการชุดฟีเจอร์ทั้งหมด ข้ามชุดที่ติดตั้งแล้ว และจัดคิวเฉพาะการดาวน์โหลดที่ขาดหายไปเท่านั้น ตัวอย่างเช่น การเปิดใช้งาน Passport Photo บนอินสแตนซ์ใหม่จะจัดคิว `background-removal` และ `face-detection` แต่การเปิดใช้งานหลังจากติดตั้ง Background Removal แล้วจะจัดคิวเฉพาะ `face-detection` เท่านั้น
+
+| ชุดฟีเจอร์ | ขนาด | กลุ่ม dependency ที่ใช้ร่วมกัน | เครื่องมือที่ใช้ |
+|--------|------|-------------------------|-------------------|
+| `background-removal` | 4-5 GB | rembg / BiRefNet background matting | 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 inpainting/outpainting และ DDColor | erase-object, colorize, ai-canvas-expand |
+| `upscale-enhance` | 5-6 GB | RealESRGAN, GFPGAN / CodeFormer, denoising | 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 |
+
+เครื่องมือที่มี dependency ข้ามชุดฟีเจอร์:
+
+| เครื่องมือ | ชุดฟีเจอร์ที่ต้องใช้ | เหตุผล |
+|------|------------------|-----|
+| `passport-photo` | `background-removal`, `face-detection` | ลบพื้นหลัง แล้วใช้จุดสังเกตใบหน้าจัดกรอบการครอปให้เป็นไปตามกฎของรูปหนังสือเดินทางและรูปบัตรประจำตัว |
+| `enhance-faces` | `upscale-enhance`, `face-detection` | ตรวจจับใบหน้าก่อนรันการปรับปรุงด้วย GFPGAN หรือ CodeFormer บนบริเวณใบหน้าที่เลือก |
+
+เครื่องมือจะพร้อมใช้งานเฉพาะเมื่อติดตั้งชุดฟีเจอร์ที่จำเป็นครบทุกชุดแล้ว การติดตั้งบางส่วนถือว่าใช้ได้และจัดการแบบเพิ่มทีละส่วน ชุดที่ติดตั้งแล้วจะถูกนำกลับมาใช้ซ้ำ ชุดที่ขาดหายไปจะแสดงเป็นการดาวน์โหลด และการติดตั้งที่จัดคิวไว้จะทำงานทีละรายการเพื่อไม่ให้มีการแก้ไขสภาพแวดล้อม Python ที่ใช้ร่วมกันพร้อมกัน
+
+---
+
+## การลบพื้นหลัง {#background-removal}
+
+**เส้นทางเครื่องมือ:** `remove-background`  
+**โมเดล:** rembg พร้อม BiRefNet (ค่าเริ่มต้น) หรือรุ่นย่อย U2-Net
+
+| พารามิเตอร์ | ประเภท | ค่าเริ่มต้น | คำอธิบาย |
+|-----------|------|---------|-------------|
+| `model` | string | - | รุ่นย่อยของโมเดล (การแทนที่แบบเสริม) |
+| `backgroundType` | string | `"transparent"` | หนึ่งใน: `transparent`, `color`, `gradient`, `blur`, `image` |
+| `backgroundColor` | string | - | สีเลขฐานสิบหกสำหรับพื้นหลังสีทึบ |
+| `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"` | สีเลขฐานสิบหกของพื้นหลัง (เมื่อ `backgroundType` เป็น `color`) |
+| `gradientColor1` | string | - | สีเลขฐานสิบหกไล่ระดับสีแรก |
+| `gradientColor2` | string | - | สีเลขฐานสิบหกไล่ระดับสีที่สอง |
+| `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 ภาพ
+
+แยกข้อความจากเอกสาร PDF ที่สแกนโดยใช้ OCR ที่ขับเคลื่อนด้วย AI ทีละหน้า
+
+| พารามิเตอร์ | ประเภท | ค่าเริ่มต้น | คำอธิบาย |
+|-----------|------|---------|-------------|
+| `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
+
+เวิร์กโฟลว์สองเฟส: วิเคราะห์ (ตรวจจับใบหน้า + ลบพื้นหลัง) จากนั้นสร้าง (ครอป ปรับขนาด เรียงเป็นแผ่น) รองรับกว่า 37 ประเทศใน 6 ภูมิภาค
+
+### เฟส 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`
+
+รับ JSON body ที่มีผลลัพธ์จากเฟส 1 พร้อมด้วยการตั้งค่าการสร้าง:
+
+| พารามิเตอร์ | ประเภท | ค่าเริ่มต้น | คำอธิบาย |
+|-----------|------|---------|-------------|
+| `jobId` | string | (จำเป็น) | Job ID จากเฟส 1 |
+| `filename` | string | (จำเป็น) | ชื่อไฟล์ต้นฉบับจากเฟส 1 |
+| `countryCode` | string | (จำเป็น) | รหัสประเทศ ISO (เช่น `US`, `GB`, `IN`) |
+| `documentType` | string | `"passport"` | ประเภทเอกสาร |
+| `bgColor` | string | `"#FFFFFF"` | สีเลขฐานสิบหกของพื้นหลัง |
+| `printLayout` | string | `"none"` | เลย์เอาต์การพิมพ์: `none`, `4x6`, `a4`, `letter` |
+| `maxFileSizeKb` | number | `0` | ขนาดไฟล์สูงสุดเป็น KB (0 = ไม่จำกัด) |
+| `dpi` | number (72-1200) | `300` | DPI เอาต์พุต |
+| `customWidthMm` | number | - | ความกว้างกำหนดเองเป็นมิลลิเมตร (แทนที่ข้อกำหนดของประเทศ) |
+| `customHeightMm` | number | - | ความสูงกำหนดเองเป็นมิลลิเมตร (แทนที่ข้อกำหนดของประเทศ) |
+| `zoom` | number (0.5-3) | `1` | ตัวคูณการซูม |
+| `adjustX` | number | `0` | การปรับตำแหน่งแนวนอน |
+| `adjustY` | number | `0` | การปรับตำแหน่งแนวตั้ง |
+| `landmarks` | object | (จำเป็น) | จุดสังเกตจากเฟส 1 |
+| `imageWidth` | number | (จำเป็น) | ความกว้างของภาพจากเฟส 1 |
+| `imageHeight` | number | (จำเป็น) | ความสูงของภาพจากเฟส 1 |
+
+## การลบวัตถุ (Inpainting) {#object-erasing-inpainting}
+
+**เส้นทางเครื่องมือ:** `erase-object`  
+**โมเดล:** LaMa ผ่าน ONNX Runtime
+
+มาสก์จะถูกส่งเป็น **ส่วนไฟล์ที่สอง** (fieldname `mask`) ไม่ใช่แบบ base64 พิกเซลสีขาวในมาสก์บ่งชี้บริเวณที่จะลบ การตั้งค่า `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` | คุณภาพเอาต์พุต |
+
+เร่งความเร็วด้วย CUDA เมื่อมี NVIDIA GPU พร้อมใช้งาน
+
+## AI Canvas Expand {#ai-canvas-expand}
+
+**เส้นทางเครื่องมือ:** `ai-canvas-expand`  
+**โมเดล:** outpainting ที่ใช้ 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}
+
+**เส้นทางเครื่องมือ:** `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` | เกณฑ์การตรวจจับพื้นหลัง (โหมด trim) |
+| `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-matting (ความละเอียด 2048x2048)
+
+แก้ไขไฟล์ PNG แบบ "โปร่งใสปลอม" ที่พื้นหลังถูกลบออกไปแล้วแต่ทิ้งขอบซ่อน, รัศมีเงา หรือสิ่งแปลกปลอมกึ่งโปร่งใสไว้ ใช้โมเดล matting ความละเอียดสูงของ BiRefNet เพื่อสร้างช่องอัลฟาที่สะอาด แล้วใช้การประมวลผล defringe ที่กำหนดค่าได้เพื่อลบการปนเปื้อนของสีตามขอบ
+
+**สายสำรองกรณี OOM:** หาก BiRefNet HR-matting ใช้หน่วยความจำเกินที่มี เครื่องมือจะถอยกลับไปใช้ `birefnet-general` โดยอัตโนมัติ จากนั้นไปที่ `u2net`
+
+| พารามิเตอร์ | ประเภท | ค่าเริ่มต้น | คำอธิบาย |
+|-----------|------|---------|-------------|
+| `defringe` | number (0-100) | `30` | ความแรงของ defringe ขอบเพื่อลบการปนเปื้อนของสี |
+| `outputFormat` | `"png"` \| `"webp"` | `"png"` | รูปแบบภาพเอาต์พุต |
+| `removeWatermark` | boolean | `false` | ใช้การประมวลผลล่วงหน้าเพื่อลบลายน้ำ (median filter) |
+
+```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 sidecar แต่ใช้ฟีเจอร์ 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` | เปิดใช้งานการลบสัญญาณรบกวนด้วย AI ผ่าน SCUNet (ต้องใช้ชุดฟีเจอร์ `upscale-enhance`) |
+
+มีปลายทางการวิเคราะห์เพิ่มเติมที่ `POST /api/v1/tools/image/image-enhancement/analyze` ซึ่งส่งคืนการแก้ไขที่ตรวจพบโดยไม่นำมาใช้จริง
+
+### การปรับขนาดตามเนื้อหา (Seam Carving) {#content-aware-resize-seam-carving}
+
+**เส้นทางเครื่องมือ:** `content-aware-resize`  
+**เอนจิน:** ไบนารี Go `caire` (ไม่ใช่ Python จึงไม่ได้ประโยชน์จาก GPU)
+
+ปรับขนาดภาพอย่างชาญฉลาดด้วยการลบ seam ที่มีพลังงานต่ำ โดยรักษาเนื้อหาสำคัญไว้
+
+| พารามิเตอร์ | ประเภท | ค่าเริ่มต้น | คำอธิบาย |
+|-----------|------|---------|-------------|
+| `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: e7056568e7b1
+---
+
+# เอนจินภาพ {#image-engine}
+
+แพ็กเกจ `@snapotter/image-engine` จัดการการทำงานกับภาพที่ไม่ใช่ AI ทั้งหมด มันห่อหุ้ม [Sharp](https://sharp.pixelplumbing.com/) และทำงานทั้งหมดในกระบวนการโดยไม่มี dependency ภายนอก
+
+## การทำงาน {#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` ผ่าน codec แบบ 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 (รวมถึง GPS หาก `stripGps` ไม่ได้ตั้งแยกต่างหาก) |
+| `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) แมปไปยังค่า Gaussian sigma ที่ 0.5-10 |
+
+### sharpen-advanced {#sharpen-advanced}
+
+การเพิ่มความคมชัดขั้นสูงพร้อมสามวิธีที่เลือกได้และการลดสัญญาณรบกวนล่วงหน้าแบบเสริม
+
+| พารามิเตอร์ | ชนิด | คำอธิบาย |
+|---|---|---|
+| `method` | string | `adaptive`, `unsharp-mask` หรือ `high-pass` |
+| `sigma` | number | รัศมี Gaussian blur, 0.5-10 (ปรับตัวได้) |
+| `m1` | number | การเพิ่มความคมชัดในพื้นที่เรียบ, 0-10 (ปรับตัวได้) |
+| `m2` | number | การเพิ่มความคมชัดในพื้นที่ที่มีพื้นผิว, 0-20 (ปรับตัวได้) |
+| `x1` | number | เกณฑ์พื้นที่เรียบ/หยัก, 0-10 (ปรับตัวได้) |
+| `y2` | number | การเพิ่มความสว่างสูงสุด (จำกัด halo), 0-50 (ปรับตัวได้) |
+| `y3` | number | การลดความสว่างสูงสุด (จำกัด halo), 0-50 (ปรับตัวได้) |
+| `amount` | number | เปอร์เซ็นต์ความเข้ม, 0-500 (unsharp-mask) |
+| `radius` | number | รัศมีการเบลอ, 0.1-5.0 (unsharp-mask) |
+| `threshold` | number | ความสว่างขอบต่ำสุด, 0-255 (unsharp-mask) |
+| `strength` | number | ความเข้มของการผสม, 0-100 (high-pass) |
+| `kernelSize` | number | `3` หรือ `5` สำหรับ kernel 3x3 / 5x5 (high-pass) |
+| `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}
+
+เอนจินตรวจจับรูปแบบอินพุตโดยอัตโนมัติจากส่วนหัวของไฟล์ ไม่ใช่แค่นามสกุลไฟล์ นี่หมายความว่าไฟล์ `.jpg` ที่จริง ๆ เป็น PNG จะถูกจัดการอย่างถูกต้อง การตรวจจับใช้แนวทางหลายชั้น: magic bytes ก่อน จากนั้นใช้นามสกุลไฟล์เป็น fallback
+
+SnapOtter รองรับ **รูปแบบอินพุตกว่า 55 รูปแบบ** และ **รูปแบบผลลัพธ์ 13 รูปแบบ** รวมถึงรูปแบบ RAW จากกล้อง 23 รูปแบบจากกว่า 20 แบรนด์ รูปแบบมืออาชีพ (PSD, EPS, OpenEXR, HDR) codec สมัยใหม่ (JPEG XL, AVIF, HEIC, QOI, JPEG 2000) และรูปแบบทางวิทยาศาสตร์/เกม (FITS, DDS) การถอดรหัสจัดการโดย Sharp โดยตรงเมื่อทำได้ พร้อม fallback อัตโนมัติไปยัง ImageMagick, LibRaw และตัวถอดรหัส CLI เฉพาะทาง
+
+ดูหน้า [Supported Formats](/th/guide/supported-formats) สำหรับรายการทั้งหมด
+
+## การสกัดเมทาดาทา {#metadata-extraction}
+
+เครื่องมือ `info` คืนเมทาดาทาของภาพ ดู [Image Info](/th/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: 34c52fe6305e
+---
+
+# เอกสารอ้างอิง 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 Keys {#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}
+
+| Method | Path | สิทธิ์เข้าถึง | คำอธิบาย |
+|--------|------|--------|-------------|
+| `POST` | `/api/auth/login` | สาธารณะ | ลงชื่อเข้าใช้ รับโทเคนเซสชัน |
+| `POST` | `/api/auth/logout` | ยืนยันตัวตน | ทำลายเซสชันปัจจุบัน |
+| `GET` | `/api/auth/session` | ยืนยันตัวตน | ตรวจสอบเซสชันปัจจุบัน |
+| `POST` | `/api/auth/change-password` | ยืนยันตัวตน | เปลี่ยนรหัสผ่านของตนเอง (ทำให้เซสชันอื่นทั้งหมด + API keys ใช้ไม่ได้) |
+| `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` ระดับ enterprise |
+| `POST` | `/api/auth/mfa/verify` | ยืนยันตัวตน | ยืนยันการลงทะเบียน MFA ด้วยรหัส TOTP |
+| `POST` | `/api/auth/mfa/complete` | สาธารณะ | ทำ MFA login challenge ที่ค้างอยู่ให้เสร็จสมบูรณ์ |
+| `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` | สาธารณะ | callback การอนุญาตของ OIDC |
+| `GET` | `/api/auth/saml/metadata` | สาธารณะ | XML เมทาดาทา SAML SP เมื่อเปิดใช้งาน SAML |
+| `GET` | `/api/auth/saml/login` | สาธารณะ | เริ่มการลงชื่อเข้าใช้ SAML |
+| `POST` | `/api/auth/saml/callback` | สาธารณะ | บริการ SAML assertion consumer |
+
+เมื่อเปิดใช้งาน MFA สำหรับผู้ใช้ `POST /api/auth/login` จะคืนค่า `{"requiresMfa":true,"mfaToken":"...","mfaRequired":true|false}` แทนโทเคนเซสชัน ส่ง `mfaToken` นั้นพร้อมรหัส TOTP หรือรหัสกู้คืนไปยัง `/api/auth/mfa/complete`
+
+### สิทธิ์ {#permissions}
+
+| สิทธิ์ | ผู้ดูแลระบบ | ผู้ใช้ |
+|-----------|:-----:|:----:|
+| ใช้เครื่องมือ | ✓ | ✓ |
+| ไฟล์/ไปป์ไลน์/API keys ของตนเอง | ✓ | ✓ |
+| ดูไฟล์/ไปป์ไลน์/คีย์ของผู้ใช้ทุกคน | ✓ | - |
+| เขียนการตั้งค่า | ✓ | - |
+| จัดการผู้ใช้และทีม | ✓ | - |
+| จัดการแบรนด์ | ✓ | - |
+
+## การตรวจสอบสถานะ {#health-check}
+
+| Method | Path | สิทธิ์เข้าถึง | คำอธิบาย |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/health` | สาธารณะ | การตรวจสอบสถานะพื้นฐาน คืนค่า `{"status":"healthy","version":"..."}` พร้อม 200 หรือ `{"status":"unhealthy"}` พร้อม 503 หากไม่สามารถเข้าถึงฐานข้อมูลได้ |
+| `GET` | `/api/v1/readyz` | สาธารณะ | Readiness probe ตรวจสอบ PostgreSQL, Redis, พื้นที่ดิสก์ และ S3 เมื่อมีการกำหนดค่า คืนค่า 503 เมื่ออินสแตนซ์ไม่ควรรับทราฟฟิก |
+| `GET` | `/api/v1/admin/health` | ผู้ดูแลระบบ (`system:health`) | การวินิจฉัยแบบละเอียด รวมถึง uptime, โหมดการจัดเก็บ, สถานะฐานข้อมูล, สถานะคิว และความพร้อมใช้งานของ 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`) สำหรับเครื่องมือที่ลงทะเบียนใน generic batch registry
+
+## เอกสารอ้างอิงเครื่องมือ {#tools-reference}
+
+### พรีเซ็ตการแปลง {#conversion-presets}
+
+แคตตาล็อกที่ใช้ร่วมกันมีเอนด์พอยต์พรีเซ็ตการแปลงเฉพาะ 83 รายการ เช่น `jpg-to-png`, `mov-to-mp4`, `m4a-to-mp3`, `pdf-to-jpg` และ `excel-to-csv` พรีเซ็ตเป็นเส้นทางเครื่องมือระดับหนึ่ง:
+
+`POST /api/v1/tools/<section>/<presetId>`
+
+แต่ละพรีเซ็ตล็อกรูปแบบเอาต์พุตและมอบหมายให้เครื่องมือฐาน เช่น `convert`, `convert-video`, `extract-audio`, `convert-audio`, `image-to-pdf`, `pdf-to-image`, `svg-to-raster` หรือ `convert-spreadsheet` ดู [พรีเซ็ตการแปลง](/th/tools/conversion-presets) สำหรับตารางเส้นทางฉบับสมบูรณ์และการตั้งค่าที่ไม่บังคับ
+
+### พื้นฐาน {#essentials}
+
+| Tool 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}
+
+| Tool 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` | ตัวสร้าง Favicon | `padding`, `backgroundColor`, `borderRadius` - สร้างขนาดมาตรฐานทั้งหมด |
+
+### การปรับแต่ง {#adjustments}
+
+| Tool 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` | Duotone | `shadow` (hex), `highlight` (hex), `intensity` (0-100) |
+| `pixelate` | Pixelate | `blockSize` (2-128), `region` ({left, top, width, height} สำหรับการทำ pixelation บางส่วน) |
+| `vignette` | Vignette | `strength` (0.1-1), `color` (hex), `radius`, `softness`, `roundness`, `centerX`, `centerY` |
+
+### เครื่องมือ AI {#ai-tools}
+
+เครื่องมือ AI ทั้งหมดทำงานบนฮาร์ดแวร์ของคุณ: CPU โดยค่าเริ่มต้น หรือ NVIDIA CUDA เมื่อมี NVIDIA GPU ที่รองรับ การเร่งความเร็ว iGPU ของ Intel/AMD ผ่าน VA-API, Quick Sync หรือ OpenCL ยังไม่รองรับสำหรับการอนุมาน AI ในปัจจุบัน ไม่ต้องใช้อินเทอร์เน็ต
+
+| Tool 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 เป็นส่วนไฟล์ที่สอง (fieldname `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` | ลบตาแดง | Face landmark + การวิเคราะห์สี | `sensitivity`, `strength` |
+| `restore-photo` | ฟื้นฟูภาพถ่าย | ไปป์ไลน์หลายขั้นตอน | `mode` (auto/light/heavy), `scratchRemoval`, `faceEnhancement`, `fidelity`, `denoise`, `denoiseStrength`, `colorize` |
+| `passport-photo` | รูปถ่ายพาสปอร์ต | MediaPipe landmarks | โฟลว์แบบสองขั้นตอน การวิเคราะห์ใช้ multipart `file`; การสร้างใช้ JSON พร้อม `countryCode`, `bgColor`, `printLayout` (none/4x6/a4), landmarks, มิติภาพ |
+| `content-aware-resize` | ปรับขนาดแบบรับรู้เนื้อหา | Seam carving (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 (outpainting) | `extendTop`, `extendRight`, `extendBottom`, `extendLeft` (px), `tier` (fast/balanced/high), `format`, `quality` |
+
+### ลายน้ำและการซ้อนทับ {#watermark-overlay}
+
+| Tool 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` รองรับโหมดเทมเพลต (JSON body พร้อม `templateId`) หรือโหมดรูปภาพกำหนดเอง (multipart พร้อมไฟล์) |
+
+### ยูทิลิตี {#utilities}
+
+| Tool ID | ชื่อ | การตั้งค่าหลัก |
+|---------|------|-------------|
+| `info` | ข้อมูลรูปภาพ | - (คืนค่า width, height, format, size, channels, hasAlpha, DPI, EXIF) |
+| `compare` | เปรียบเทียบรูปภาพ | `mode` (side-by-side/overlay/diff), `diffThreshold` - ไฟล์ที่สองคือเป้าหมายการเปรียบเทียบ |
+| `find-duplicates` | ค้นหารูปซ้ำ | `threshold` (ระยะห่างของ perceptual hash, ค่าเริ่มต้น 8) - หลายไฟล์ |
+| `color-palette` | จานสี | `count` (จำนวนสีเด่น), `format` (hex/rgb) |
+| `qr-generate` | ตัวสร้าง QR Code | `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 Placeholder | `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 body ไม่มีการอัปโหลดไฟล์ |
+
+### เลย์เอาต์และการประกอบภาพ {#layout-composition}
+
+| Tool 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` | Sprite Sheet | `columns` (1-16), `padding`, `background` (hex), `format` (png/webp/jpeg), `quality` - หลายไฟล์ (2-64 รูป) |
+
+### รูปแบบและการแปลง {#format-conversion}
+
+| Tool 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}
+
+| Tool 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` | ฝังคำบรรยาย (Burn) | `fontSize` (8-72) - วิดีโอ + ไฟล์คำบรรยาย |
+| `embed-subtitles` | ฝังคำบรรยาย (Embed) | `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}
+
+| Tool 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` | เปลี่ยนระดับเสียง (Pitch) | `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}
+
+| Tool 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 ให้เหมาะกับเว็บ | - (linearize เพื่อการดูบนเว็บที่รวดเร็ว) |
+| `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` | Flatten PDF | - (ทำให้ฟอร์มและคำอธิบายประกอบกลายเป็นภาพ) |
+| `redact-pdf` | ปกปิดข้อมูล PDF | `terms` (string[]), `caseSensitive` (bool) |
+| `sign-pdf` | ลงนาม PDF | เส้นทาง multipart กำหนดเองพร้อม PDF `file`, ไฟล์ลายเซ็น `sig0`, `sig1` และอาร์เรย์ JSON `placements` |
+| `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}
+
+| Tool 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 | - (ป้องกัน bomb) |
+
+### HTML เป็นรูปภาพ {#html-to-image}
+
+จับภาพหน้าเว็บเป็นรูปภาพ ต่างจากเครื่องมืออื่น เอนด์พอยต์นี้รับ `application/json` แทน multipart form data (ไม่ต้องอัปโหลดไฟล์)
+
+**เอนด์พอยต์:** `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` | ความกว้าง viewport กำหนดเอง 320-3840 |
+| `viewportHeight` | number | `720` | ความสูง viewport กำหนดเอง 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>` มาตรฐาน:
+
+| Method | Path | คำอธิบาย |
+|--------|------|-------------|
+| `GET` | `/api/v1/tools/popular` | คืนค่า tool ID ยอดนิยม โดยย้อนกลับไปใช้รายการเริ่มต้นที่คัดสรรไว้เมื่อข้อมูลการใช้งานมีน้อย |
+| `POST` | `/api/v1/tools/image/remove-background/effects` | ใช้เอฟเฟกต์พื้นหลัง (color/gradient/blur/shadow) โดยไม่ต้องรัน AI ใหม่ ใช้ mask ที่แคชไว้จากการลบครั้งแรก |
+| `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 + การลบพื้นหลัง คืนค่า face landmarks และข้อมูลที่แคชไว้ |
+| `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` | รับเมทาดาทา PDF สำหรับพรีเซ็ต JPG เฉพาะ |
+| `POST` | `/api/v1/tools/pdf/pdf-to-jpg/preview` | สร้างตัวอย่างหน้า PDF ของพรีเซ็ต JPG |
+| `POST` | `/api/v1/tools/pdf/pdf-to-png/info` | รับเมทาดาทา PDF สำหรับพรีเซ็ต PNG เฉพาะ |
+| `POST` | `/api/v1/tools/pdf/pdf-to-png/preview` | สร้างตัวอย่างหน้า PDF ของพรีเซ็ต PNG |
+| `POST` | `/api/v1/tools/pdf/pdf-to-tiff/info` | รับเมทาดาทา PDF สำหรับพรีเซ็ต TIFF เฉพาะ |
+| `POST` | `/api/v1/tools/pdf/pdf-to-tiff/preview` | สร้างตัวอย่างหน้า PDF ของพรีเซ็ต TIFF |
+| `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}
+
+| Method | Path | คำอธิบาย |
+|--------|------|-------------|
+| `POST` | `/api/v1/pipeline/save` | บันทึกไปป์ไลน์ที่ตั้งชื่อ (`name`, `description`, `steps[]`) |
+| `GET` | `/api/v1/pipeline/list` | แสดงรายการไปป์ไลน์ที่บันทึกไว้ (ผู้ดูแลระบบเห็นทั้งหมด; ผู้ใช้เห็นของตนเอง) |
+| `DELETE` | `/api/v1/pipeline/:id` | ลบ (เจ้าของหรือผู้ดูแลระบบ) |
+| `GET` | `/api/v1/pipeline/tools` | แสดงรายการ tool ID ที่ใช้ได้กับขั้นตอนไปป์ไลน์ |
+
+## การติดตามความคืบหน้า {#progress-tracking}
+
+งานที่ทำงานนาน เครื่องมือที่เข้าคิว งานแบตช์ และไปป์ไลน์จะส่งความคืบหน้าแบบเรียลไทม์ผ่าน Server-Sent Events สตรีมความคืบหน้าเป็นสาธารณะและระบุด้วย job 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}
+
+การจัดเก็บไฟล์แบบถาวรพร้อมประวัติเวอร์ชัน
+
+| Method | Path | คำอธิบาย |
+|--------|------|-------------|
+| `POST` | `/api/v1/upload` | อัปโหลดไฟล์ไปยัง workspace (การประมวลผลชั่วคราว) |
+| `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` | รับภาพขนาดย่อ JPEG 300px |
+| `DELETE` | `/api/v1/files` | ลบไฟล์และสายเวอร์ชันของไฟล์แบบกลุ่ม (body: `{ ids: [...] }`) |
+| `POST` | `/api/v1/fetch-urls` | ดึง URL ระยะไกลเข้าสู่ workspace สำหรับการนำเข้าแบบอิง 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` | ดาวน์โหลดไฟล์ที่ประมวลผลแล้วจาก workspace |
+
+หากต้องการบันทึกผลลัพธ์ของเครื่องมือไปยังคลังโดยอัตโนมัติ ให้รวม `fileId` เป็นฟิลด์ multipart form ที่อ้างอิงถึงไฟล์ในคลังที่มีอยู่ ผลลัพธ์ที่ประมวลผลแล้วจะถูกบันทึกเป็นเวอร์ชันใหม่
+
+## การจัดการ API Key {#api-key-management}
+
+| Method | Path | สิทธิ์เข้าถึง | คำอธิบาย |
+|--------|------|--------|-------------|
+| `POST` | `/api/v1/api-keys` | ยืนยันตัวตน | สร้างคีย์ใหม่ - แสดงเพียงครั้งเดียว |
+| `GET` | `/api/v1/api-keys` | ยืนยันตัวตน | แสดงรายการคีย์ (name, id, lastUsedAt - ไม่ใช่คีย์ดิบ) |
+| `DELETE` | `/api/v1/api-keys/:id` | ยืนยันตัวตน | ลบคีย์ |
+
+## ทีม {#teams}
+
+| Method | Path | สิทธิ์เข้าถึง | คำอธิบาย |
+|--------|------|--------|-------------|
+| `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}
+
+การกำหนดค่าคีย์-ค่าแบบรันไทม์ (อ่านได้โดยผู้ใช้ที่ยืนยันตัวตนแล้วทุกคน เขียนได้โดยผู้ดูแลระบบเท่านั้น)
+
+| Method | Path | คำอธิบาย |
+|--------|------|-------------|
+| `GET` | `/api/v1/settings` | รับการตั้งค่าทั้งหมด |
+| `PUT` | `/api/v1/settings` | อัปเดตการตั้งค่าแบบกลุ่ม (JSON body พร้อมคู่คีย์-ค่า) |
+| `GET` | `/api/v1/settings/:key` | รับการตั้งค่าที่ระบุตามคีย์ |
+
+คีย์ที่รู้จัก: `disabledTools` (อาร์เรย์ JSON ของ tool ID), `enableExperimentalTools` (สตริง bool), `loginAttemptLimit` (ตัวเลข)
+
+## ค่าปรับตั้ง {#preferences}
+
+ค่าปรับตั้งต่อผู้ใช้แยกจากการตั้งค่าของอินสแตนซ์ ผู้ใช้ที่ยืนยันตัวตนแล้วทุกคนสามารถอ่านและอัปเดตแผนที่ค่าปรับตั้งของตนเองได้
+
+| Method | Path | คำอธิบาย |
+|--------|------|-------------|
+| `GET` | `/api/v1/preferences` | รับค่าปรับตั้งของผู้ใช้ปัจจุบันในรูปแบบ `{ "preferences": { ... } }` |
+| `PUT` | `/api/v1/preferences` | เพิ่มหรืออัปเดตคีย์ค่าปรับตั้งหนึ่งรายการขึ้นไปสำหรับผู้ใช้ปัจจุบัน |
+
+## บทบาท {#roles}
+
+การจัดการบทบาทกำหนดเองพร้อมสิทธิ์แบบละเอียด
+
+| Method | Path | สิทธิ์เข้าถึง | คำอธิบาย |
+|--------|------|--------|-------------|
+| `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}
+
+เอนด์พอยต์เฉพาะผู้ดูแลระบบสำหรับตรวจสอบการกระทำที่เกี่ยวข้องกับความปลอดภัย
+
+| Method | Path | สิทธิ์เข้าถึง | คำอธิบาย |
+|--------|------|--------|-------------|
+| `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}
+
+| Method | Path | สิทธิ์เข้าถึง | คำอธิบาย |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/config/analytics` | สาธารณะ | รับการกำหนดค่าการวิเคราะห์ที่มีผล (PostHog key, Sentry DSN, sample rate) คีย์ DSN และ instance ID จะว่างเปล่าเมื่อปิดการวิเคราะห์ ไม่ว่าจะจากการ bake ตอนคอมไพล์หรือการตั้งค่า `analyticsEnabled` ของอินสแตนซ์ |
+| `POST` | `/api/v1/feedback` | ยืนยันตัวตน | ส่งความคิดเห็นของผู้ใช้อย่างชัดแจ้งไปยังโปรเจกต์ PostHog ที่กำหนดค่าไว้เป็น `feedback_submitted` เส้นทางนี้เคารพเกตการวิเคราะห์ จำกัดอัตราการส่ง ตัดฟิลด์ติดต่อออกเว้นแต่ `contactOk` เป็นจริง และไม่รับเนื้อหาไฟล์ ชื่อไฟล์ เส้นทางอัปโหลด หรือข้อความข้อผิดพลาดส่วนตัวแบบดิบ เมื่อปิดการวิเคราะห์ จะคืนค่า `{ "ok": true, "accepted": false }` |
+| `PUT` | `/api/v1/settings` | ผู้ดูแลระบบ (`settings:write`) | ตั้งค่าการเลือกไม่เข้าร่วมทั่วทั้งอินสแตนซ์ ส่ง JSON body `{ "analyticsEnabled": "false" }` เพื่อปิดการวิเคราะห์สำหรับทุกคน หรือ `"true"` เพื่อเปิดกลับมาอีกครั้ง |
+
+## ฟีเจอร์ / AI Bundles {#features-ai-bundles}
+
+จัดการ AI feature bundles (ติดตั้ง/ถอนการติดตั้งแพ็กเกจโมเดล AI ในสภาพแวดล้อม Docker) ควรใช้เอนด์พอยต์การติดตั้งระดับเครื่องมือเมื่อเปิดใช้งานเครื่องมือจากระบบอัตโนมัติกำหนดเอง: เครื่องมือ AI บางตัวต้องการ shared bundle มากกว่าหนึ่งรายการ และเอนด์พอยต์นี้จะข้าม bundle ที่ติดตั้งแล้วโดยเข้าคิวเฉพาะที่ขาดหายไป
+
+| Method | Path | สิทธิ์เข้าถึง | คำอธิบาย |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/features` | ยืนยันตัวตน | แสดงรายการ feature bundle ทั้งหมดและสถานะการติดตั้ง |
+| `POST` | `/api/v1/admin/features/:bundleId/install` | ผู้ดูแลระบบ (`features:manage`) | ติดตั้ง feature bundle (แบบอะซิงโครนัส คืนค่า `jobId` สำหรับการติดตามความคืบหน้า) |
+| `POST` | `/api/v1/admin/tools/:toolId/features/install` | ผู้ดูแลระบบ (`features:manage`) | ติดตั้งทุก bundle ที่เครื่องมือต้องการ; คืนค่าสถานะเข้าคิว/ข้ามต่อ bundle |
+| `POST` | `/api/v1/admin/features/:bundleId/uninstall` | ผู้ดูแลระบบ (`features:manage`) | ถอนการติดตั้ง feature bundle และล้างไฟล์โมเดล |
+| `GET` | `/api/v1/admin/features/disk-usage` | ผู้ดูแลระบบ (`features:manage`) | รับการใช้พื้นที่ดิสก์รวมของโมเดล AI |
+| `POST` | `/api/v1/admin/features/import` | ผู้ดูแลระบบ (`features:manage`) | นำเข้าไฟล์บีบอัด AI bundle แบบออฟไลน์ |
+
+## การดำเนินงานของผู้ดูแลระบบ {#admin-operations}
+
+เอนด์พอยต์ปฏิบัติการสำหรับการสังเกตการณ์ การสนับสนุน การรายงานการใช้งาน และสถานะการสำรองข้อมูล
+
+| Method | Path | สิทธิ์เข้าถึง | คำอธิบาย |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/admin/log-level` | ผู้ดูแลระบบ (`settings:write`) | อ่านระดับ log รันไทม์ปัจจุบัน |
+| `POST` | `/api/v1/admin/log-level` | ผู้ดูแลระบบ (`settings:write`) | เปลี่ยนระดับ log รันไทม์ (`fatal`, `error`, `warn`, `info`, `debug`, `trace` หรือ `silent`) |
+| `GET` | `/api/v1/metrics` | ผู้ดูแลระบบ (`system:health`) | Prometheus metrics ในรูปแบบข้อความ |
+| `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` ที่ไม่บังคับ) |
+
+## Enterprise API {#enterprise-apis}
+
+เส้นทางเหล่านี้ถูกเกตด้วยไลเซนส์ตามฟีเจอร์ enterprise ที่เกี่ยวข้อง ยังคงต้องมีสิทธิ์ SnapOtter ที่ระบุไว้
+
+| Method | Path | สิทธิ์เข้าถึง | คำอธิบาย |
+|--------|------|--------|-------------|
+| `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 bearer token คืนค่าเพียงครั้งเดียว |
+| `DELETE` | `/api/v1/enterprise/scim/token` | ผู้ดูแลระบบ (`users:manage`) | เพิกถอน SCIM bearer token ปัจจุบัน |
+| `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`) | แสดงรายการปลายทาง webhook |
+| `POST` | `/api/v1/enterprise/webhooks` | ผู้ดูแลระบบ (`webhooks:manage`) | สร้างปลายทาง webhook |
+| `PUT` | `/api/v1/enterprise/webhooks/:index` | ผู้ดูแลระบบ (`webhooks:manage`) | อัปเดตปลายทาง webhook |
+| `DELETE` | `/api/v1/enterprise/webhooks/:index` | ผู้ดูแลระบบ (`webhooks:manage`) | ลบปลายทาง webhook |
+| `POST` | `/api/v1/enterprise/webhooks/:index/test` | ผู้ดูแลระบบ (`webhooks:manage`) | ส่ง payload webhook ทดสอบ |
+| `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`) | อ่านเมทาดาทาเวอร์ชันของแอป build, Node และ schema |
+| `GET` | `/api/v1/admin/migrations/pending` | ผู้ดูแลระบบ (`system:health`) | เปรียบเทียบ migration ที่แพ็กเกจไว้กับ migration ที่ใช้แล้ว |
+| `GET` | `/api/v1/admin/upgrade-check` | ผู้ดูแลระบบ (`system:health`) | รันการตรวจสอบความพร้อมในการอัปเกรด |
+
+### SCIM 2.0 {#scim-2-0}
+
+เอนด์พอยต์การค้นพบ SCIM เป็นสาธารณะ เอนด์พอยต์ผู้ใช้และกลุ่มต้องใช้ SCIM bearer token ที่สร้างไว้ด้านบน
+
+| Method | Path | สิทธิ์เข้าถึง | คำอธิบาย |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/scim/v2/ServiceProviderConfig` | สาธารณะ | ความสามารถของเซิร์ฟเวอร์ SCIM |
+| `GET` | `/api/v1/scim/v2/Schemas` | สาธารณะ | การค้นพบ schema ของ SCIM |
+| `GET` | `/api/v1/scim/v2/ResourceTypes` | สาธารณะ | การค้นพบประเภททรัพยากรของ 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 | ปิดใช้งานผู้ใช้แบบ soft |
+| `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 | ลบทีม |
+
+## เทมเพลตมีม {#meme-templates}
+
+API สนับสนุนสำหรับเครื่องมือสร้างมีม
+
+| Method | Path | สิทธิ์เข้าถึง | คำอธิบาย |
+|--------|------|--------|-------------|
+| `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 bundle ที่จำเป็น (`FEATURE_NOT_INSTALLED`) |
+| 500 | ข้อผิดพลาดภายในเซิร์ฟเวอร์ |