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.

apps/docs/vi/api/ai.md

@@ -0,0 +1,438 @@
+---
+description: "Tài liệu tham khảo engine AI với tất cả công cụ ML chạy cục bộ. Xóa nền, upscale, OCR, phát hiện khuôn mặt, phục chế ảnh và nhiều tính năng khác."
+i18n_source_hash: 14728c1dcd05
+i18n_provenance: machine
+i18n_output_hash: 5f94f953cb34
+---
+
+# Tài liệu tham khảo Engine AI {#ai-engine-reference}
+
+Gói `@snapotter/ai` kết nối Node.js với một **sidecar Python thường trực** cho mọi thao tác ML. Tiến trình dispatcher luôn chạy giữa các yêu cầu để đạt hiệu năng khởi động ấm nhanh. NVIDIA CUDA được tự động phát hiện khi khởi động và dùng khi có sẵn; nếu không, các công cụ AI chạy trên CPU.
+
+Hiện chưa hỗ trợ tăng tốc iGPU Intel/AMD qua VA-API, Quick Sync hay OpenCL cho suy luận AI. Việc ánh xạ `/dev/dri` vào container không tăng tốc các công cụ sidecar Python này trừ khi có một GPU NVIDIA hỗ trợ CUDA.
+
+19 công cụ AI sidecar Python trên bốn phương thức (ảnh, âm thanh, video, tài liệu), cộng thêm 2 công cụ có khả năng AI tùy chọn. Mọi mô hình đều chạy cục bộ, không cần internet sau khi tải mô hình lần đầu.
+
+## Kiến trúc {#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)
+```
+
+Một hồ sơ dispatcher "docs" riêng thay thế danh sách cho phép AI bằng các script xử lý tài liệu (`doc_pagecount`, `doc_health`, `doc_flatten`, `doc_redact`, `doc_text`, `doc_to_word`, `doc_metadata`, `doc_html_pdf`) và bỏ qua việc import các thư viện ML nặng.
+
+**Thời gian chờ:** mặc định 300 giây; OCR và xóa nền BiRefNet được cấp 600 giây.
+
+## Gói tính năng {#feature-bundles}
+
+Các mô hình AI được đóng gói theo ngăn xếp phụ thuộc dùng chung, không phải một kho lưu trữ cho mỗi công cụ. Một gói tính năng có thể bật nhiều công cụ khi chúng dùng cùng họ mô hình, wheel Python hoặc thư viện native. Điều này giúp image Docker phát hành nhỏ hơn và tránh lưu trữ các bản sao trùng lặp của cùng một mô hình matting nền, phát hiện khuôn mặt, OCR, phục chế và giọng nói.
+
+Image Docker đi kèm ứng dụng cộng với runtime chung. Các kho lưu trữ mô hình lớn được tải theo yêu cầu vào volume `/data/ai` thường trực, rồi được tái sử dụng bởi mọi công cụ cần đến. Nếu một gói đã được cài vì công cụ khác cần, thì việc bật một công cụ phụ thuộc mới sẽ không tải lại gói đó.
+
+Mỗi công cụ AI yêu cầu một hoặc nhiều gói tính năng trước khi có thể chạy. Giao diện quản trị cài đặt theo công cụ thông qua `POST /api/v1/admin/tools/:toolId/features/install`, giao diện này giải quyết toàn bộ danh sách gói, bỏ qua những gói đã cài và chỉ xếp hàng những phần tải còn thiếu. Ví dụ, bật Passport Photo trên một phiên bản mới sẽ xếp hàng `background-removal` và `face-detection`; bật nó sau khi Background Removal đã được cài thì chỉ xếp hàng `face-detection`.
+
+| Gói | Kích thước | Nhóm phụ thuộc dùng chung | Công cụ sử dụng |
+|--------|------|-------------------------|-------------------|
+| `background-removal` | 4-5 GB | matting nền rembg / BiRefNet | remove-background, passport-photo, transparency-fixer, background-replace, blur-background |
+| `face-detection` | 200-300 MB | phát hiện khuôn mặt và mốc điểm MediaPipe | blur-faces, red-eye-removal, smart-crop |
+| `object-eraser-colorize` | 1-2 GB | inpainting/outpainting LaMa và DDColor | erase-object, colorize, ai-canvas-expand |
+| `upscale-enhance` | 5-6 GB | RealESRGAN, GFPGAN / CodeFormer, khử nhiễu | upscale, enhance-faces, noise-removal |
+| `photo-restoration` | 4-5 GB | quy trình sửa vết xước và phục chế | restore-photo |
+| `ocr` | 5-6 GB | ngăn xếp OCR PaddleOCR / Tesseract | ocr, ocr-pdf |
+| `transcription` | ~600 MB | mô hình chuyển giọng nói thành văn bản faster-whisper | transcribe-audio, auto-subtitles |
+
+Các công cụ có phụ thuộc chéo giữa nhiều gói:
+
+| Công cụ | Gói yêu cầu | Lý do |
+|------|------------------|-----|
+| `passport-photo` | `background-removal`, `face-detection` | Xóa nền, rồi dùng mốc điểm khuôn mặt để căn khung cắt theo quy tắc ảnh hộ chiếu và ảnh thẻ. |
+| `enhance-faces` | `upscale-enhance`, `face-detection` | Phát hiện khuôn mặt trước khi chạy tăng cường GFPGAN hoặc CodeFormer trên các vùng khuôn mặt đã chọn. |
+
+Một công cụ chỉ khả dụng khi tất cả gói yêu cầu của nó đã được cài. Cài đặt một phần là hợp lệ và được xử lý tăng dần: các gói đã cài được tái sử dụng, các gói còn thiếu hiển thị dưới dạng cần tải, và các lượt cài đã xếp hàng chạy lần lượt từng lượt để môi trường Python dùng chung không bị sửa đổi đồng thời.
+
+---
+
+## Xóa nền {#background-removal}
+
+**Đường dẫn công cụ:** `remove-background`  
+**Mô hình:** rembg với BiRefNet (mặc định) hoặc các biến thể U2-Net
+
+| Tham số | Kiểu | Mặc định | Mô tả |
+|-----------|------|---------|-------------|
+| `model` | string | - | Biến thể mô hình (ghi đè tùy chọn) |
+| `backgroundType` | string | `"transparent"` | Một trong: `transparent`, `color`, `gradient`, `blur`, `image` |
+| `backgroundColor` | string | - | Mã màu hex cho nền đơn sắc |
+| `gradientColor1` | string | - | Màu gradient thứ nhất |
+| `gradientColor2` | string | - | Màu gradient thứ hai |
+| `gradientAngle` | number | - | Góc gradient tính bằng độ |
+| `blurEnabled` | boolean | - | Bật hiệu ứng làm mờ nền |
+| `blurIntensity` | number (0-100) | - | Cường độ làm mờ |
+| `shadowEnabled` | boolean | - | Bật đổ bóng lên chủ thể |
+| `shadowOpacity` | number (0-100) | - | Độ mờ đục của bóng |
+| `outputFormat` | string | - | Định dạng đầu ra: `png`, `webp` hoặc `avif` |
+| `edgeRefine` | integer (0-3) | - | Mức độ tinh chỉnh cạnh |
+| `decontaminate` | boolean | - | Loại bỏ lem màu ở cạnh |
+
+## Thay nền {#background-replace}
+
+**Đường dẫn công cụ:** `background-replace`  
+**Mô hình:** rembg / BiRefNet (dùng chung với remove-background)
+
+Xóa nền và thay bằng màu đơn sắc hoặc gradient.
+
+| Tham số | Kiểu | Mặc định | Mô tả |
+|-----------|------|---------|-------------|
+| `backgroundType` | `"color"` \| `"gradient"` | `"color"` | Chế độ nền |
+| `color` | string | `"#ffffff"` | Màu nền hex (khi `backgroundType` là `color`) |
+| `gradientColor1` | string | - | Màu hex gradient thứ nhất |
+| `gradientColor2` | string | - | Màu hex gradient thứ hai |
+| `gradientAngle` | integer (0-360) | `180` | Góc gradient tính bằng độ |
+| `feather` | integer (0-20) | `0` | Bán kính làm mềm cạnh |
+| `format` | `"png"` \| `"webp"` | `"png"` | Định dạng đầu ra |
+
+## Làm mờ nền {#blur-background}
+
+**Đường dẫn công cụ:** `blur-background`  
+**Mô hình:** rembg / BiRefNet (dùng chung với remove-background)
+
+Làm mờ nền trong khi giữ chủ thể sắc nét.
+
+| Tham số | Kiểu | Mặc định | Mô tả |
+|-----------|------|---------|-------------|
+| `intensity` | integer (1-100) | `50` | Cường độ làm mờ |
+| `feather` | integer (0-20) | `0` | Bán kính làm mềm cạnh |
+| `format` | `"png"` \| `"webp"` | `"png"` | Định dạng đầu ra |
+
+## Upscale ảnh {#image-upscaling}
+
+**Đường dẫn công cụ:** `upscale`  
+**Mô hình:** RealESRGAN (dự phòng Lanczos khi không có sẵn)
+
+| Tham số | Kiểu | Mặc định | Mô tả |
+|-----------|------|---------|-------------|
+| `scale` | number | `2` | Hệ số upscale |
+| `model` | string | `"auto"` | Biến thể mô hình |
+| `faceEnhance` | boolean | `false` | Áp dụng lượt tăng cường khuôn mặt GFPGAN |
+| `denoise` | number | `0` | Cường độ khử nhiễu |
+| `format` | string | `"auto"` | Ghi đè định dạng đầu ra |
+| `quality` | number | `95` | Chất lượng đầu ra (1-100) |
+
+## OCR / Trích xuất văn bản {#ocr-text-extraction}
+
+**Đường dẫn công cụ:** `ocr`  
+**Mô hình:** Tesseract (nhanh), PaddleOCR PP-OCRv5 (cân bằng), PaddleOCR-VL 1.5 (tốt nhất)
+
+| Tham số | Kiểu | Mặc định | Mô tả |
+|-----------|------|---------|-------------|
+| `quality` | `"fast"` \| `"balanced"` \| `"best"` | `"balanced"` | Bậc xử lý |
+| `language` | string | `"auto"` | Ngôn ngữ: `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko` |
+| `enhance` | boolean | `true` | Tiền xử lý ảnh để cải thiện độ chính xác OCR |
+| `engine` | string | - | Không dùng nữa. Ánh xạ `tesseract` sang `fast`, `paddleocr` sang `balanced` |
+
+Trả về kết quả có cấu trúc với hộp giới hạn, điểm tin cậy và các khối văn bản đã trích xuất.
+
+## OCR PDF {#pdf-ocr}
+
+**Đường dẫn công cụ:** `ocr-pdf`  
+**Mô hình:** Cùng hệ thống bậc như OCR ảnh
+
+Trích xuất văn bản từ tài liệu PDF đã quét bằng OCR chạy trên AI, theo từng trang.
+
+| Tham số | Kiểu | Mặc định | Mô tả |
+|-----------|------|---------|-------------|
+| `quality` | `"fast"` \| `"balanced"` \| `"best"` | `"balanced"` | Bậc xử lý |
+| `language` | string | `"auto"` | Ngôn ngữ: `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko` |
+| `pages` | string | `"all"` | Chọn trang: `"all"`, `"1-3"`, `"1,3,5"` |
+
+## Làm mờ khuôn mặt / PII {#face-pii-blur}
+
+**Đường dẫn công cụ:** `blur-faces`  
+**Mô hình:** phát hiện khuôn mặt MediaPipe
+
+| Tham số | Kiểu | Mặc định | Mô tả |
+|-----------|------|---------|-------------|
+| `blurRadius` | number (1-100) | `30` | Bán kính làm mờ Gaussian |
+| `sensitivity` | number (0-1) | `0.5` | Ngưỡng tin cậy phát hiện |
+
+## Tăng cường khuôn mặt {#face-enhancement}
+
+**Đường dẫn công cụ:** `enhance-faces`  
+**Mô hình:** GFPGAN, CodeFormer
+
+| Tham số | Kiểu | Mặc định | Mô tả |
+|-----------|------|---------|-------------|
+| `model` | `"auto"` \| `"gfpgan"` \| `"codeformer"` | `"auto"` | Mô hình tăng cường |
+| `strength` | number (0-1) | `0.8` | Cường độ tăng cường |
+| `sensitivity` | number (0-1) | `0.5` | Ngưỡng phát hiện khuôn mặt |
+| `onlyCenterFace` | boolean | `false` | Chỉ tăng cường khuôn mặt ở trung tâm nhất |
+
+## Tô màu bằng AI {#ai-colorization}
+
+**Đường dẫn công cụ:** `colorize`  
+**Mô hình:** DDColor (dự phòng OpenCV DNN)
+
+Chuyển ảnh đen trắng hoặc thang xám thành ảnh màu đầy đủ.
+
+| Tham số | Kiểu | Mặc định | Mô tả |
+|-----------|------|---------|-------------|
+| `intensity` | number (0-1) | `1.0` | Cường độ bão hòa màu |
+| `model` | `"auto"` \| `"ddcolor"` \| `"opencv"` | `"auto"` | Biến thể mô hình |
+
+## Khử nhiễu {#noise-removal}
+
+**Đường dẫn công cụ:** `noise-removal`  
+**Mô hình:** SCUNet (quy trình khử nhiễu phân bậc)
+
+| Tham số | Kiểu | Mặc định | Mô tả |
+|-----------|------|---------|-------------|
+| `tier` | `"quick"` \| `"balanced"` \| `"quality"` \| `"maximum"` | `"balanced"` | Bậc xử lý |
+| `strength` | number (0-100) | `50` | Cường độ khử nhiễu |
+| `detailPreservation` | number (0-100) | `50` | Mức chi tiết cần giữ lại; cao hơn thì giữ nhiều kết cấu hơn |
+| `colorNoise` | number (0-100) | `30` | Cường độ giảm nhiễu màu |
+| `format` | string | `"original"` | Định dạng đầu ra: `original`, `png`, `jpeg`, `webp`, `avif`, `jxl` |
+| `quality` | number (1-100) | `90` | Chất lượng mã hóa đầu ra |
+
+## Xóa mắt đỏ {#red-eye-removal}
+
+**Đường dẫn công cụ:** `red-eye-removal`
+
+Phát hiện mốc điểm khuôn mặt, xác định vùng mắt và chỉnh việc kênh đỏ bị bão hòa quá mức.
+
+| Tham số | Kiểu | Mặc định | Mô tả |
+|-----------|------|---------|-------------|
+| `sensitivity` | number (0-100) | `50` | Ngưỡng phát hiện điểm ảnh đỏ |
+| `strength` | number (0-100) | `70` | Cường độ chỉnh sửa |
+| `format` | string | - | Ghi đè định dạng đầu ra (tùy chọn) |
+| `quality` | number (1-100) | `90` | Chất lượng đầu ra |
+
+## Phục chế ảnh {#photo-restoration}
+
+**Đường dẫn công cụ:** `restore-photo`
+
+Quy trình nhiều bước cho ảnh cũ hoặc hư hỏng: phát hiện và sửa vết xước/rách, tăng cường khuôn mặt, khử nhiễu và tô màu tùy chọn.
+
+| Tham số | Kiểu | Mặc định | Mô tả |
+|-----------|------|---------|-------------|
+| `scratchRemoval` | boolean | `true` | Phát hiện và sửa vết xước, vết rách |
+| `faceEnhancement` | boolean | `true` | Áp dụng lượt tăng cường khuôn mặt |
+| `fidelity` | number (0-1) | `0.7` | Cường độ tăng cường khuôn mặt (cao hơn = thận trọng hơn) |
+| `denoise` | boolean | `true` | Áp dụng lượt khử nhiễu |
+| `denoiseStrength` | number (0-100) | `25` | Cường độ khử nhiễu |
+| `colorize` | boolean | `false` | Tô màu sau khi phục chế |
+| `colorizeStrength` | number (0-100) | `85` | Cường độ tô màu |
+
+## Ảnh hộ chiếu {#passport-photo}
+
+**Đường dẫn công cụ:** `passport-photo`  
+**Mô hình:** mốc điểm khuôn mặt MediaPipe + xóa nền BiRefNet
+
+Quy trình hai giai đoạn: phân tích (phát hiện khuôn mặt + xóa nền) rồi tạo (cắt, đổi kích thước, xếp lưới). Hỗ trợ hơn 37 quốc gia trên 6 khu vực.
+
+### Giai đoạn 1: Phân tích {#phase-1-analyze}
+
+`POST /api/v1/tools/image/passport-photo/analyze`
+
+Nhận một tệp ảnh (multipart). Trả về dữ liệu mốc điểm khuôn mặt, bản xem trước base64 và kích thước ảnh.
+
+### Giai đoạn 2: Tạo {#phase-2-generate}
+
+`POST /api/v1/tools/image/passport-photo/generate`
+
+Nhận một body JSON gồm kết quả Giai đoạn 1 cộng với các thiết lập tạo:
+
+| Tham số | Kiểu | Mặc định | Mô tả |
+|-----------|------|---------|-------------|
+| `jobId` | string | (bắt buộc) | ID công việc từ Giai đoạn 1 |
+| `filename` | string | (bắt buộc) | Tên tệp gốc từ Giai đoạn 1 |
+| `countryCode` | string | (bắt buộc) | Mã quốc gia ISO (ví dụ `US`, `GB`, `IN`) |
+| `documentType` | string | `"passport"` | Loại giấy tờ |
+| `bgColor` | string | `"#FFFFFF"` | Mã hex màu nền |
+| `printLayout` | string | `"none"` | Bố cục in: `none`, `4x6`, `a4`, `letter` |
+| `maxFileSizeKb` | number | `0` | Kích thước tệp tối đa tính bằng KB (0 = không giới hạn) |
+| `dpi` | number (72-1200) | `300` | DPI đầu ra |
+| `customWidthMm` | number | - | Chiều rộng tùy chỉnh tính bằng mm (ghi đè thông số quốc gia) |
+| `customHeightMm` | number | - | Chiều cao tùy chỉnh tính bằng mm (ghi đè thông số quốc gia) |
+| `zoom` | number (0.5-3) | `1` | Hệ số thu phóng |
+| `adjustX` | number | `0` | Điều chỉnh vị trí ngang |
+| `adjustY` | number | `0` | Điều chỉnh vị trí dọc |
+| `landmarks` | object | (bắt buộc) | Mốc điểm từ Giai đoạn 1 |
+| `imageWidth` | number | (bắt buộc) | Chiều rộng ảnh từ Giai đoạn 1 |
+| `imageHeight` | number | (bắt buộc) | Chiều cao ảnh từ Giai đoạn 1 |
+
+## Xóa vật thể (Inpainting) {#object-erasing-inpainting}
+
+**Đường dẫn công cụ:** `erase-object`  
+**Mô hình:** LaMa qua ONNX Runtime
+
+Mask được gửi dưới dạng **phần tệp thứ hai** (tên trường `mask`), không phải base64. Điểm ảnh trắng trong mask cho biết vùng cần xóa. Các thiết lập `format` và `quality` được gửi dưới dạng trường form cấp trên cùng.
+
+| Tham số | Kiểu | Mặc định | Mô tả |
+|-----------|------|---------|-------------|
+| `file` | file | (bắt buộc) | Ảnh nguồn (multipart) |
+| `mask` | file | (bắt buộc) | Ảnh mask (multipart, tên trường `mask`, trắng = xóa) |
+| `format` | string | `"auto"` | Định dạng đầu ra: `auto`, `png`, `jpg`, `jpeg`, `webp`, `tiff`, `gif`, `avif`, `heic`, `heif`, `jxl` |
+| `quality` | integer (1-100) | `95` | Chất lượng đầu ra |
+
+Tăng tốc CUDA khi có GPU NVIDIA.
+
+## Mở rộng khung ảnh bằng AI {#ai-canvas-expand}
+
+**Đường dẫn công cụ:** `ai-canvas-expand`  
+**Mô hình:** outpainting dựa trên LaMa
+
+Mở rộng khung của một ảnh theo bất kỳ hướng nào và điền vào các vùng mới bằng nội dung do AI tạo ra khớp với ảnh hiện có.
+
+| Tham số | Kiểu | Mặc định | Mô tả |
+|-----------|------|---------|-------------|
+| `extendTop` | integer | `0` | Số điểm ảnh mở rộng ở phía trên |
+| `extendRight` | integer | `0` | Số điểm ảnh mở rộng ở phía phải |
+| `extendBottom` | integer | `0` | Số điểm ảnh mở rộng ở phía dưới |
+| `extendLeft` | integer | `0` | Số điểm ảnh mở rộng ở phía trái |
+| `tier` | `"fast"` \| `"balanced"` \| `"high"` | `"balanced"` | Bậc chất lượng |
+| `format` | string | `"auto"` | Định dạng đầu ra: `auto`, `png`, `jpg`, `jpeg`, `webp`, `tiff`, `gif`, `avif`, `heic`, `heif`, `jxl` |
+| `quality` | integer (1-100) | `95` | Chất lượng đầu ra |
+
+Ít nhất một hướng mở rộng phải lớn hơn 0.
+
+## Cắt thông minh {#smart-crop}
+
+**Đường dẫn công cụ:** `smart-crop`  
+**Mô hình:** phát hiện khuôn mặt MediaPipe (chỉ ở chế độ khuôn mặt)
+
+| Tham số | Kiểu | Mặc định | Mô tả |
+|-----------|------|---------|-------------|
+| `mode` | string | `"subject"` | Chiến lược cắt: `subject`, `face`, `trim` |
+| `strategy` | `"attention"` \| `"entropy"` | `"attention"` | Chiến lược cho chế độ chủ thể |
+| `width` | integer | - | Chiều rộng đầu ra |
+| `height` | integer | - | Chiều cao đầu ra |
+| `padding` | integer (0-50) | `0` | Phần trăm đệm quanh chủ thể |
+| `facePreset` | string | `"head-shoulders"` | Khung định sẵn khi `mode=face` |
+| `sensitivity` | number (0-1) | `0.5` | Ngưỡng phát hiện khuôn mặt |
+| `threshold` | integer (0-255) | `30` | Ngưỡng phát hiện nền (chế độ cắt viền) |
+| `padToSquare` | boolean | `false` | Đệm kết quả đã cắt viền thành hình vuông |
+| `padColor` | string | `"#ffffff"` | Màu nền cho phần đệm vuông |
+| `targetSize` | integer | - | Kích thước đích cho đầu ra đã đệm (điểm ảnh) |
+| `quality` | integer (1-100) | - | Chất lượng đầu ra |
+
+Các giá trị `mode` cũ `attention` và `content` vẫn được chấp nhận và ánh xạ lần lượt sang `subject` và `trim`.
+
+**Khung định sẵn cho khuôn mặt:**
+
+| Định sẵn | Phù hợp nhất cho |
+|--------|---------|
+| `closeup` | Ảnh chân dung cận |
+| `head-shoulders` | Ảnh hồ sơ |
+| `upper-body` | LinkedIn / trang trọng |
+| `half-body` | Toàn bộ nửa thân trên |
+
+## Chuyển âm thanh thành văn bản {#transcribe-audio}
+
+**Đường dẫn công cụ:** `transcribe-audio`  
+**Mô hình:** faster-whisper
+
+Chuyển giọng nói thành văn bản. Hỗ trợ định dạng đầu ra văn bản thuần, SRT và VTT.
+
+| Tham số | Kiểu | Mặc định | Mô tả |
+|-----------|------|---------|-------------|
+| `language` | string | `"auto"` | Ngôn ngữ: `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko`, `id`, `th`, `vi` |
+| `outputFormat` | `"txt"` \| `"srt"` \| `"vtt"` | `"txt"` | Định dạng đầu ra |
+
+## Phụ đề tự động {#auto-subtitles}
+
+**Đường dẫn công cụ:** `auto-subtitles`  
+**Mô hình:** faster-whisper (trích âm thanh từ video, rồi chuyển thành văn bản)
+
+Tạo tệp phụ đề từ track âm thanh của video.
+
+| Tham số | Kiểu | Mặc định | Mô tả |
+|-----------|------|---------|-------------|
+| `language` | string | `"auto"` | Ngôn ngữ: `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko`, `id`, `th`, `vi` |
+| `format` | `"srt"` \| `"vtt"` | `"srt"` | Định dạng phụ đề đầu ra |
+
+## Sửa độ trong suốt PNG {#png-transparency-fixer}
+
+**Đường dẫn công cụ:** `transparency-fixer`  
+**Mô hình:** BiRefNet HR-matting (độ phân giải 2048x2048)
+
+Sửa các PNG "trong suốt giả", nơi nền đã được xóa nhưng để lại viền tua, quầng sáng hoặc phần dư bán trong suốt. Dùng mô hình matting độ phân giải cao của BiRefNet để tạo kênh alpha sạch, rồi áp dụng xử lý khử viền có thể cấu hình để loại bỏ nhiễm màu dọc theo cạnh.
+
+**Chuỗi dự phòng khi hết bộ nhớ:** Nếu BiRefNet HR-matting vượt quá bộ nhớ khả dụng, công cụ tự động chuyển sang dự phòng `birefnet-general`, rồi đến `u2net`.
+
+| Tham số | Kiểu | Mặc định | Mô tả |
+|-----------|------|---------|-------------|
+| `defringe` | number (0-100) | `30` | Cường độ khử viền để loại bỏ nhiễm màu ở cạnh |
+| `outputFormat` | `"png"` \| `"webp"` | `"png"` | Định dạng ảnh đầu ra |
+| `removeWatermark` | boolean | `false` | Áp dụng tiền xử lý xóa hình mờ (bộ lọc trung vị) |
+
+```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"}'
+```
+
+---
+
+## Công cụ có khả năng AI tùy chọn {#tools-with-optional-ai-capabilities}
+
+Các công cụ sau không phải công cụ sidecar Python nhưng dùng tính năng AI khi bật một số tùy chọn.
+
+### Tăng cường ảnh {#image-enhancement}
+
+**Đường dẫn công cụ:** `image-enhancement`  
+**Engine:** Dựa trên phân tích (biểu đồ histogram và thống kê Sharp)
+
+Phân tích ảnh và áp dụng chỉnh sửa tự động cho phơi sáng, tương phản, cân bằng trắng, độ bão hòa, độ nét và nhiễu. Hỗ trợ các chế độ theo cảnh cụ thể.
+
+| Tham số | Kiểu | Mặc định | Mô tả |
+|-----------|------|---------|-------------|
+| `mode` | `"auto"` \| `"portrait"` \| `"landscape"` \| `"low-light"` \| `"food"` \| `"document"` | `"auto"` | Chế độ cảnh để tinh chỉnh việc chỉnh sửa |
+| `intensity` | number (0-100) | `50` | Cường độ chỉnh sửa tổng thể |
+| `corrections.exposure` | boolean | `true` | Áp dụng chỉnh phơi sáng |
+| `corrections.contrast` | boolean | `true` | Áp dụng chỉnh tương phản |
+| `corrections.whiteBalance` | boolean | `true` | Áp dụng chỉnh cân bằng trắng |
+| `corrections.saturation` | boolean | `true` | Áp dụng chỉnh độ bão hòa |
+| `corrections.sharpness` | boolean | `true` | Áp dụng chỉnh độ nét |
+| `corrections.denoise` | boolean | `true` | Áp dụng khử nhiễu |
+| `deepEnhance` | boolean | `false` | Bật khử nhiễu AI qua SCUNet (yêu cầu gói `upscale-enhance`) |
+
+Một endpoint phân tích bổ sung có tại `POST /api/v1/tools/image/image-enhancement/analyze`, trả về các chỉnh sửa được phát hiện mà không áp dụng chúng.
+
+### Đổi kích thước theo nội dung (Seam Carving) {#content-aware-resize-seam-carving}
+
+**Đường dẫn công cụ:** `content-aware-resize`  
+**Engine:** binary Go `caire` (không phải Python, không hưởng lợi từ GPU)
+
+Đổi kích thước ảnh một cách thông minh bằng cách loại bỏ các đường nối năng lượng thấp, giữ lại nội dung quan trọng.
+
+| Tham số | Kiểu | Mặc định | Mô tả |
+|-----------|------|---------|-------------|
+| `width` | number | - | Chiều rộng đích |
+| `height` | number | - | Chiều cao đích |
+| `protectFaces` | boolean | `false` | Bảo vệ vùng khuôn mặt đã phát hiện (yêu cầu gói `face-detection`) |
+| `blurRadius` | number (0-20) | `4` | Làm mờ trước để tính năng lượng |
+| `sobelThreshold` | number (1-20) | `2` | Ngưỡng độ nhạy cạnh |
+| `square` | boolean | `false` | Buộc đầu ra vuông |

apps/docs/vi/api/image-engine.md

@@ -0,0 +1,211 @@
+---
+description: "Tài liệu tham khảo các thao tác của engine hình ảnh. Tất cả thao tác xử lý ảnh dựa trên Sharp và tham số của chúng."
+i18n_source_hash: 42febdf85fa8
+i18n_provenance: human
+i18n_output_hash: 41a2d7276a22
+---
+
+# Engine hình ảnh {#image-engine}
+
+Gói `@snapotter/image-engine` xử lý mọi thao tác ảnh không dùng AI. Nó bao bọc [Sharp](https://sharp.pixelplumbing.com/) và chạy hoàn toàn trong tiến trình mà không có phụ thuộc bên ngoài.
+
+## Thao tác {#operations}
+
+### resize {#resize}
+
+Thay đổi tỷ lệ ảnh theo kích thước cụ thể hoặc theo phần trăm.
+
+| Tham số | Kiểu | Mô tả |
+|---|---|---|
+| `width` | number | Chiều rộng mục tiêu tính bằng điểm ảnh |
+| `height` | number | Chiều cao mục tiêu tính bằng điểm ảnh |
+| `fit` | string | `cover`, `contain`, `fill`, `inside`, hoặc `outside` |
+| `withoutEnlargement` | boolean | Nếu true, sẽ không phóng to các ảnh nhỏ hơn |
+| `percentage` | number | Thay đổi tỷ lệ theo phần trăm thay vì kích thước tuyệt đối |
+
+Bạn có thể đặt `width`, `height`, hoặc cả hai. Nếu chỉ đặt một, giá trị còn lại được tính để giữ tỷ lệ khung hình.
+
+### crop {#crop}
+
+Cắt một vùng hình chữ nhật ra khỏi ảnh.
+
+| Tham số | Kiểu | Mô tả |
+|---|---|---|
+| `left` | number | Độ lệch X từ cạnh trái |
+| `top` | number | Độ lệch Y từ cạnh trên |
+| `width` | number | Chiều rộng của vùng cắt |
+| `height` | number | Chiều cao của vùng cắt |
+| `unit` | string | `px` (mặc định) hoặc `percent` |
+
+### rotate {#rotate}
+
+Xoay ảnh theo một góc cho trước.
+
+| Tham số | Kiểu | Mô tả |
+|---|---|---|
+| `angle` | number | Góc xoay tính bằng độ (0-360) |
+| `background` | string | Màu tô cho vùng lộ ra (mặc định: `#000000`). Chỉ áp dụng cho các góc không phải 90 độ. |
+
+### flip {#flip}
+
+Lật ảnh theo chiều ngang, chiều dọc, hoặc cả hai. Ít nhất một phải là true.
+
+| Tham số | Kiểu | Mô tả |
+|---|---|---|
+| `horizontal` | boolean | Lật từ trái sang phải |
+| `vertical` | boolean | Lật từ trên xuống dưới |
+
+### convert {#convert}
+
+Thay đổi định dạng ảnh.
+
+| Tham số | Kiểu | Mô tả |
+|---|---|---|
+| `format` | string | Định dạng mục tiêu: `jpg`, `png`, `webp`, `avif`, `tiff`, `gif`, `jxl`, `heic`, `heif`, `bmp`, `ico`, `jp2`, `qoi` |
+| `quality` | number | Chất lượng nén (1-100, áp dụng cho các định dạng có tổn hao) |
+
+Bảy định dạng đầu tiên (từ `jpg` đến `jxl`) được Sharp mã hóa trong tiến trình. Các định dạng còn lại dùng bộ mã hóa bên ngoài ở lớp API: `heic`/`heif` qua heif-enc, `bmp`/`ico` qua ImageMagick, `jp2` qua opj_compress, và `qoi` qua một codec TypeScript nội tuyến.
+
+### compress {#compress}
+
+Giảm kích thước tệp trong khi giữ nguyên định dạng.
+
+| Tham số | Kiểu | Mô tả |
+|---|---|---|
+| `quality` | number | Chất lượng mục tiêu (1-100) |
+| `targetSizeBytes` | number | Kích thước tệp mục tiêu tùy chọn tính bằng byte |
+| `format` | string | Ghi đè định dạng tùy chọn |
+
+### strip-metadata {#strip-metadata}
+
+Xóa siêu dữ liệu EXIF, IPTC, XMP, và ICC khỏi ảnh. Khi không có tham số nào (hoặc `stripAll: true`), xóa tất cả. Truyền các cờ riêng lẻ để xóa có chọn lọc.
+
+| Tham số | Kiểu | Mô tả |
+|---|---|---|
+| `stripAll` | boolean | Xóa toàn bộ siêu dữ liệu (mặc định khi không đặt cờ nào) |
+| `stripExif` | boolean | Xóa dữ liệu EXIF (bao gồm GPS nếu `stripGps` không được đặt riêng) |
+| `stripGps` | boolean | Xóa dữ liệu vị trí GPS |
+| `stripIcc` | boolean | Xóa hồ sơ màu ICC |
+| `stripXmp` | boolean | Xóa siêu dữ liệu XMP |
+
+### Điều chỉnh màu {#color-adjustments}
+
+Các thao tác này chỉnh sửa thuộc tính màu của ảnh. Mỗi thao tác nhận một giá trị số duy nhất.
+
+| Thao tác | Tham số | Khoảng | Mô tả |
+|---|---|---|---|
+| `brightness` | `value` | -100 đến 100 | Điều chỉnh độ sáng |
+| `contrast` | `value` | -100 đến 100 | Điều chỉnh độ tương phản |
+| `saturation` | `value` | -100 đến 100 | Điều chỉnh độ bão hòa màu |
+
+### Bộ lọc màu {#color-filters}
+
+Các bộ lọc này áp dụng một biến đổi màu cố định. Chúng không nhận tham số.
+
+| Thao tác | Mô tả |
+|---|---|
+| `grayscale` | Chuyển sang thang xám |
+| `sepia` | Áp dụng tông màu sepia |
+| `invert` | Đảo ngược toàn bộ màu |
+
+### Kênh màu {#color-channels}
+
+Điều chỉnh từng kênh màu RGB riêng lẻ. Giá trị là hệ số nhân trong đó 100 = không thay đổi.
+
+| Tham số | Kiểu | Mô tả |
+|---|---|---|
+| `red` | number | Hệ số nhân kênh đỏ (0 đến 200, 100 = không đổi) |
+| `green` | number | Hệ số nhân kênh xanh lá (0 đến 200, 100 = không đổi) |
+| `blue` | number | Hệ số nhân kênh xanh dương (0 đến 200, 100 = không đổi) |
+
+### sharpen {#sharpen}
+
+Làm sắc nét đơn giản được điều khiển bởi một giá trị duy nhất.
+
+| Tham số | Kiểu | Mô tả |
+|---|---|---|
+| `value` | number | Cường độ làm sắc nét (0 đến 100). Được ánh xạ sang sigma Gaussian từ 0.5-10. |
+
+### sharpen-advanced {#sharpen-advanced}
+
+Làm sắc nét nâng cao với ba phương pháp có thể chọn và một bước tiền xử lý giảm nhiễu tùy chọn.
+
+| Tham số | Kiểu | Mô tả |
+|---|---|---|
+| `method` | string | `adaptive`, `unsharp-mask`, hoặc `high-pass` |
+| `sigma` | number | Bán kính làm mờ Gaussian, 0.5-10 (thích ứng) |
+| `m1` | number | Làm sắc nét vùng phẳng, 0-10 (thích ứng) |
+| `m2` | number | Làm sắc nét vùng có kết cấu, 0-20 (thích ứng) |
+| `x1` | number | Ngưỡng phẳng/gồ ghề, 0-10 (thích ứng) |
+| `y2` | number | Làm sáng tối đa (kẹp quầng sáng), 0-50 (thích ứng) |
+| `y3` | number | Làm tối tối đa (kẹp quầng sáng), 0-50 (thích ứng) |
+| `amount` | number | Phần trăm cường độ, 0-500 (unsharp-mask) |
+| `radius` | number | Bán kính làm mờ, 0.1-5.0 (unsharp-mask) |
+| `threshold` | number | Độ sáng cạnh tối thiểu, 0-255 (unsharp-mask) |
+| `strength` | number | Cường độ hòa trộn, 0-100 (high-pass) |
+| `kernelSize` | number | `3` hoặc `5` cho kernel 3x3 / 5x5 (high-pass) |
+| `denoise` | string | Bước tiền xử lý giảm nhiễu: `off`, `light`, `medium`, hoặc `strong` |
+
+Các tham số là riêng theo phương pháp. Chỉ cung cấp những tham số liên quan đến phương pháp đã chọn.
+
+### color-blindness {#color-blindness}
+
+Mô phỏng khiếm khuyết thị giác màu bằng ma trận tái kết hợp màu 3x3.
+
+| Tham số | Kiểu | Mô tả |
+|---|---|---|
+| `type` | string | Một trong: `protanopia`, `deuteranopia`, `tritanopia`, `protanomaly`, `deuteranomaly`, `tritanomaly`, `achromatopsia`, `blueConeMonochromacy` |
+
+### edit-metadata {#edit-metadata}
+
+Ghi hoặc xóa từng trường siêu dữ liệu EXIF/IPTC riêng lẻ mà không xóa toàn bộ khối.
+
+| Tham số | Kiểu | Mô tả |
+|---|---|---|
+| `artist` | string | Thẻ EXIF Artist |
+| `copyright` | string | Thẻ EXIF Copyright |
+| `imageDescription` | string | Thẻ EXIF ImageDescription |
+| `software` | string | Thẻ EXIF Software |
+| `dateTime` | string | Thẻ EXIF DateTime |
+| `dateTimeOriginal` | string | Thẻ EXIF DateTimeOriginal |
+| `clearGps` | boolean | Xóa tất cả thẻ GPS |
+| `fieldsToRemove` | string[] | Danh sách tên trường EXIF cần xóa |
+
+Tất cả tham số đều tùy chọn. Các trường được liệt kê trong `fieldsToRemove` bị xóa khỏi khối EXIF hiện có. Các trường được đặt qua tham số có tên sẽ được ghi (hoặc ghi đè). Các khóa nhị phân/không an toàn như MakerNote bị bỏ qua một cách âm thầm.
+
+## Phát hiện định dạng {#format-detection}
+
+Engine tự động phát hiện định dạng đầu vào từ phần đầu tệp, không chỉ từ phần mở rộng tệp. Điều này có nghĩa là một tệp `.jpg` thực chất là PNG sẽ được xử lý đúng cách. Việc phát hiện dùng cách tiếp cận nhiều lớp: các byte magic trước, rồi phần mở rộng tệp làm dự phòng.
+
+SnapOtter hỗ trợ **hơn 55 định dạng đầu vào** và **13 định dạng đầu ra**, bao gồm 23 định dạng camera RAW từ hơn 20 hãng, các định dạng chuyên nghiệp (PSD, EPS, OpenEXR, HDR), các codec hiện đại (JPEG XL, AVIF, HEIC, QOI, JPEG 2000), và các định dạng khoa học/trò chơi (FITS, DDS). Việc giải mã được Sharp xử lý nguyên bản khi có thể, với dự phòng tự động sang ImageMagick, LibRaw, và các bộ giải mã CLI chuyên dụng.
+
+Xem trang [Định dạng được hỗ trợ](/vi/guide/supported-formats) để có danh sách đầy đủ.
+
+## Trích xuất siêu dữ liệu {#metadata-extraction}
+
+Công cụ `info` trả về siêu dữ liệu ảnh. Xem [Thông tin ảnh](/vi/tools/image/info) để có tài liệu tham khảo đầy đủ về các trường.
+
+```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 }
+  ]
+}
+```

apps/docs/vi/api/rest.md

@@ -0,0 +1,702 @@
+---
+description: "Tài liệu tham khảo REST API đầy đủ. Endpoint công cụ, xử lý hàng loạt, pipeline, thư viện tệp, xác thực, nhóm và các thao tác quản trị."
+i18n_source_hash: 8646977f7cc9
+i18n_provenance: machine
+i18n_output_hash: a2d3795ef769
+---
+
+# Tài liệu tham khảo REST API {#rest-api-reference}
+
+Tài liệu API tương tác kèm ví dụ request/response có sẵn tại [http://localhost:1349/api/docs](http://localhost:1349/api/docs).
+
+Đặc tả có thể đọc bằng máy:
+- `/api/v1/openapi.yaml` - đặc tả OpenAPI 3.1
+- `/llms.txt` - bản tóm tắt thân thiện với LLM
+- `/llms-full.txt` - tài liệu đầy đủ thân thiện với LLM
+
+## Xác thực {#authentication}
+
+Mọi endpoint đều yêu cầu xác thực trừ khi `AUTH_ENABLED=false`.
+
+### Token phiên {#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>"
+```
+
+Phiên hết hạn sau 7 ngày (có thể cấu hình qua `SESSION_DURATION_HOURS`).
+
+### Khóa 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>"
+```
+
+Khóa có tiền tố `si_` và được lưu dưới dạng hash scrypt - khóa thô chỉ hiển thị một lần và không bao giờ lấy lại được nữa.
+
+### Endpoint xác thực {#auth-endpoints}
+
+| Phương thức | Đường dẫn | Quyền truy cập | Mô tả |
+|--------|------|--------|-------------|
+| `POST` | `/api/auth/login` | Công khai | Đăng nhập, lấy token phiên |
+| `POST` | `/api/auth/logout` | Xác thực | Hủy phiên hiện tại |
+| `GET` | `/api/auth/session` | Xác thực | Xác thực phiên hiện tại |
+| `POST` | `/api/auth/change-password` | Xác thực | Đổi mật khẩu của chính mình (vô hiệu hóa mọi phiên khác + khóa API) |
+| `GET` | `/api/auth/users` | Admin | Liệt kê tất cả người dùng |
+| `POST` | `/api/auth/register` | Admin | Tạo người dùng mới |
+| `PUT` | `/api/auth/users/:id` | Admin | Cập nhật vai trò hoặc nhóm của người dùng |
+| `POST` | `/api/auth/users/:id/reset-password` | Admin | Đặt lại mật khẩu của người dùng |
+| `DELETE` | `/api/auth/users/:id` | Admin | Xóa một người dùng |
+| `GET` | `/api/v1/config/auth` | Công khai | Kiểm tra xác thực có được bật hay không (`{ authEnabled: bool }`) |
+| `POST` | `/api/auth/mfa/enroll` | Xác thực | Bắt đầu đăng ký TOTP MFA. Yêu cầu tính năng enterprise `mfa` |
+| `POST` | `/api/auth/mfa/verify` | Xác thực | Xác nhận đăng ký MFA bằng mã TOTP |
+| `POST` | `/api/auth/mfa/complete` | Công khai | Hoàn tất thử thách đăng nhập MFA đang chờ |
+| `POST` | `/api/auth/mfa/disable` | Xác thực | Tắt MFA cho người dùng hiện tại |
+| `POST` | `/api/auth/users/:id/mfa/reset` | Admin (`users:manage`) | Đặt lại MFA cho một người dùng |
+| `GET` | `/api/auth/oidc/login` | Công khai | Bắt đầu đăng nhập OIDC khi OIDC được bật |
+| `GET` | `/api/auth/oidc/callback` | Công khai | Callback ủy quyền OIDC |
+| `GET` | `/api/auth/saml/metadata` | Công khai | XML metadata SAML SP khi SAML được bật |
+| `GET` | `/api/auth/saml/login` | Công khai | Bắt đầu đăng nhập SAML |
+| `POST` | `/api/auth/saml/callback` | Công khai | Dịch vụ tiêu thụ khẳng định SAML |
+
+Khi MFA được bật cho một người dùng, `POST /api/auth/login` trả về `{"requiresMfa":true,"mfaToken":"...","mfaRequired":true|false}` thay vì token phiên. Gửi `mfaToken` đó cùng mã TOTP hoặc mã khôi phục tới `/api/auth/mfa/complete`.
+
+### Quyền hạn {#permissions}
+
+| Quyền hạn | Admin | User |
+|-----------|:-----:|:----:|
+| Dùng công cụ | ✓ | ✓ |
+| Tệp/pipeline/khóa API của riêng mình | ✓ | ✓ |
+| Xem tệp/pipeline/khóa của mọi người dùng | ✓ | - |
+| Ghi cài đặt | ✓ | - |
+| Quản lý người dùng & nhóm | ✓ | - |
+| Quản lý thương hiệu | ✓ | - |
+
+## Kiểm tra tình trạng {#health-check}
+
+| Phương thức | Đường dẫn | Quyền truy cập | Mô tả |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/health` | Công khai | Kiểm tra tình trạng cơ bản. Trả về `{"status":"healthy","version":"..."}` với 200, hoặc `{"status":"unhealthy"}` với 503 nếu không kết nối được cơ sở dữ liệu. |
+| `GET` | `/api/v1/readyz` | Công khai | Kiểm tra sẵn sàng. Kiểm tra PostgreSQL, Redis, dung lượng đĩa và S3 khi được cấu hình. Trả về 503 khi instance không nên nhận lưu lượng. |
+| `GET` | `/api/v1/admin/health` | Admin (`system:health`) | Chẩn đoán chi tiết bao gồm thời gian hoạt động, chế độ lưu trữ, trạng thái cơ sở dữ liệu, trạng thái hàng đợi và khả năng dùng GPU. |
+
+## Sử dụng công cụ {#using-tools}
+
+Mọi công cụ đều theo cùng một mẫu:
+
+```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>` là một trong `image`, `video`, `audio`, `pdf`, hoặc `files`.
+
+- Tải lên là `multipart/form-data`.
+- `settings` là một chuỗi JSON chứa các tùy chọn riêng của công cụ.
+- `clientJobId` là một trường form tùy chọn để đối chiếu tiến trình do bên gọi cung cấp.
+- `fileId` là một trường form tùy chọn tham chiếu đến một mục có sẵn trong thư viện tệp. Khi có mặt, đầu ra đã xử lý được lưu thành phiên bản mới và response bao gồm `savedFileId`.
+- **Công cụ nhanh** thường trả về 200 JSON: `{"jobId":"...","downloadUrl":"/api/v1/download/<jobId>/<filename>","originalSize":1234,"processedSize":567}`. Tải tệp đã xử lý từ `downloadUrl`.
+- **Bất kỳ công cụ nào được xếp hàng** có thể trả về 202 JSON nếu chạy lâu hoặc vượt quá khung chờ đồng bộ: `{"jobId":"...","async":true}`. Kết nối SSE để theo dõi tiến trình, rồi tải xuống khi hoàn tất (xem [Theo dõi tiến trình](#progress-tracking)).
+- **Route hàng loạt** trả về một kho lưu trữ ZIP được stream trực tiếp (kèm header `X-Job-Id`) cho các công cụ được đăng ký trong registry hàng loạt tổng quát.
+
+## Tham khảo công cụ {#tools-reference}
+
+### Cấu hình chuyển đổi sẵn {#conversion-presets}
+
+Danh mục dùng chung bao gồm 83 endpoint cấu hình chuyển đổi chuyên biệt như `jpg-to-png`, `mov-to-mp4`, `m4a-to-mp3`, `pdf-to-jpg`, và `excel-to-csv`. Cấu hình sẵn là các route công cụ hạng nhất:
+
+`POST /api/v1/tools/<section>/<presetId>`
+
+Mỗi cấu hình sẵn khóa định dạng đầu ra và ủy thác cho một công cụ nền tảng như `convert`, `convert-video`, `extract-audio`, `convert-audio`, `image-to-pdf`, `pdf-to-image`, `svg-to-raster`, hoặc `convert-spreadsheet`. Xem [Cấu hình chuyển đổi sẵn](/vi/tools/conversion-presets) để biết bảng route đầy đủ và các cài đặt tùy chọn.
+
+### Cơ bản {#essentials}
+
+| ID công cụ | Tên | Cài đặt chính |
+|---------|------|-------------|
+| `resize` | Đổi kích thước | `width`, `height`, `fit` (cover/contain/fill/inside/outside), `percentage`, `withoutEnlargement`, cùng 23 cấu hình mạng xã hội sẵn |
+| `crop` | Cắt | `left`, `top`, `width`, `height`, `unit` (px/percent) |
+| `rotate` | Xoay & Lật | `angle`, `horizontal` (bool), `vertical` (bool) |
+| `convert` | Chuyển đổi | `format` (jpg/png/webp/avif/tiff/gif/heic/heif), `quality` |
+| `compress` | Nén | `mode` (quality/targetSize), `quality` (1–100), `targetSizeKb` |
+
+### Tối ưu hóa {#optimization}
+
+| ID công cụ | Tên | Cài đặt chính |
+|---------|------|-------------|
+| `optimize-for-web` | Tối ưu cho Web | `format` (webp/jpeg/avif/png), `quality`, `maxWidth`, `maxHeight`, `progressive`, `stripMetadata` |
+| `strip-metadata` | Xóa Metadata | - |
+| `edit-metadata` | Sửa Metadata | `title`, `description`, `author`, `copyright`, `keywords`, `gps` (lat/lon), `dateTime` |
+| `bulk-rename` | Đổi tên hàng loạt | `pattern` (hỗ trợ `{n}`, `{date}`, `{original}`), `startIndex`, `padding` |
+| `image-to-pdf` | Ảnh sang PDF | `pageSize` (A4/Letter/...), `orientation`, `margin`, `targetSize` ({value, unit}) |
+| `favicon` | Trình tạo Favicon | `padding`, `backgroundColor`, `borderRadius` - tạo mọi kích thước tiêu chuẩn |
+
+### Điều chỉnh {#adjustments}
+
+| ID công cụ | Tên | Cài đặt chính |
+|---------|------|-------------|
+| `adjust-colors` | Điều chỉnh màu | `brightness`, `contrast`, `exposure`, `saturation`, `temperature`, `tint`, `hue`, `sharpness`, `red`, `green`, `blue`, `effect` (none/grayscale/sepia/invert) |
+| `sharpening` | Làm sắc nét | `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` | Thay màu | `sourceColor`, `targetColor` (thay thế), `makeTransparent`, `tolerance` |
+| `color-blindness` | Mô phỏng mù màu | `simulationType` (protanopia/deuteranopia/tritanopia/protanomaly/deuteranomaly/tritanomaly/achromatopsia/blueConeMonochromacy, mặc định "deuteranomaly") |
+| `duotone` | Duotone | `shadow` (hex), `highlight` (hex), `intensity` (0-100) |
+| `pixelate` | Làm mờ pixel | `blockSize` (2-128), `region` ({left, top, width, height} để làm mờ pixel một phần) |
+| `vignette` | Vignette | `strength` (0.1-1), `color` (hex), `radius`, `softness`, `roundness`, `centerX`, `centerY` |
+
+### Công cụ AI {#ai-tools}
+
+Mọi công cụ AI đều chạy trên phần cứng của bạn: mặc định là CPU, hoặc NVIDIA CUDA khi có GPU NVIDIA được hỗ trợ. Tăng tốc iGPU của Intel/AMD qua VA-API, Quick Sync hoặc OpenCL hiện chưa được hỗ trợ cho suy luận AI. Không cần internet.
+
+| ID công cụ | Tên | Mô hình AI | Cài đặt chính |
+|---------|------|---------|-------------|
+| `remove-background` | Xóa nền | rembg (BiRefNet / U2-Net) | `model`, `backgroundType` (transparent/color/gradient/blur/image), `backgroundColor`, `gradientColor1`, `gradientColor2`, `gradientAngle`, `blurEnabled`, `blurIntensity`, `shadowEnabled`, `shadowOpacity` |
+| `upscale` | Phóng to ảnh | RealESRGAN | `scale` (2/4), `model`, `faceEnhance`, `denoise`, `format`, `quality` |
+| `erase-object` | Xóa vật thể | LaMa (ONNX) | Mặt nạ được gửi làm phần tệp thứ hai (tên trường `mask`), `format`, `quality` |
+| `ocr` | OCR / Trích xuất văn bản | PaddleOCR / Tesseract | `quality` (fast/balanced/best), `language`, `enhance` |
+| `blur-faces` | Làm mờ khuôn mặt / PII | MediaPipe | `blurRadius`, `sensitivity` |
+| `smart-crop` | Cắt thông minh | 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` | Nâng cao ảnh | Dựa trên phân tích | `mode` (auto/exposure/contrast/color/sharpness), `strength` |
+| `enhance-faces` | Nâng cao khuôn mặt | GFPGAN / CodeFormer | `model` (gfpgan/codeformer), `strength`, `sensitivity`, `centerFace` |
+| `colorize` | Tô màu bằng AI | DDColor | `intensity`, `model` |
+| `noise-removal` | Khử nhiễu | Khử nhiễu phân tầng | `tier` (quick/balanced/quality/maximum), `strength`, `detailPreservation`, `colorNoise`, `format`, `quality` |
+| `red-eye-removal` | Xóa mắt đỏ | Điểm mốc khuôn mặt + phân tích màu | `sensitivity`, `strength` |
+| `restore-photo` | Phục hồi ảnh | Pipeline nhiều bước | `mode` (auto/light/heavy), `scratchRemoval`, `faceEnhancement`, `fidelity`, `denoise`, `denoiseStrength`, `colorize` |
+| `passport-photo` | Ảnh hộ chiếu | Điểm mốc MediaPipe | Luồng hai giai đoạn. Phân tích dùng multipart `file`; tạo dùng JSON với `countryCode`, `bgColor`, `printLayout` (none/4x6/a4), điểm mốc, kích thước ảnh |
+| `content-aware-resize` | Đổi kích thước nhận biết nội dung | Seam carving (caire) | `width`, `height`, `protectFaces`, `blurRadius`, `sobelThreshold`, `square` |
+| `transparency-fixer` | Sửa độ trong suốt PNG | BiRefNet HR-matting | `defringe` (0-100), `outputFormat` (png/webp) |
+| `background-replace` | Thay nền | rembg (BiRefNet) | `backgroundType` (color/gradient), `color` (hex), `gradientColor1`, `gradientColor2`, `gradientAngle`, `feather` (0-20), `format` (png/webp) |
+| `blur-background` | Làm mờ nền | rembg (BiRefNet) | `intensity` (1-100), `feather` (0-20), `format` (png/webp) |
+| `ai-canvas-expand` | Mở rộng khung vẽ bằng AI | LaMa (outpainting) | `extendTop`, `extendRight`, `extendBottom`, `extendLeft` (px), `tier` (fast/balanced/high), `format`, `quality` |
+
+### Đóng dấu & Lớp phủ {#watermark-overlay}
+
+| ID công cụ | Tên | Cài đặt chính |
+|---------|------|-------------|
+| `watermark-text` | Dấu chìm văn bản | `text`, `font`, `fontSize`, `color`, `opacity`, `position`, `rotation`, `tile` |
+| `watermark-image` | Dấu chìm hình ảnh | `opacity`, `position`, `scale` - tệp thứ hai là dấu chìm |
+| `text-overlay` | Lớp phủ văn bản | `text`, `font`, `fontSize`, `color`, `x`, `y`, `background`, `padding`, `borderRadius` |
+| `compose` | Ghép ảnh | `x`, `y`, `opacity`, `blend` - tệp thứ hai được xếp lớp lên trên |
+| `meme-generator` | Trình tạo Meme | `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`. Hỗ trợ chế độ mẫu (thân JSON với `templateId`) hoặc chế độ ảnh tùy chỉnh (multipart kèm tệp). |
+
+### Tiện ích {#utilities}
+
+| ID công cụ | Tên | Cài đặt chính |
+|---------|------|-------------|
+| `info` | Thông tin ảnh | - (trả về width, height, format, size, channels, hasAlpha, DPI, EXIF) |
+| `compare` | So sánh ảnh | `mode` (side-by-side/overlay/diff), `diffThreshold` - tệp thứ hai là đối tượng so sánh |
+| `find-duplicates` | Tìm ảnh trùng | `threshold` (khoảng cách hash tri giác, mặc định 8) - đa tệp |
+| `color-palette` | Bảng màu | `count` (số lượng màu chủ đạo), `format` (hex/rgb) |
+| `qr-generate` | Trình tạo mã QR | `data`, `size`, `margin`, `colorDark`, `colorLight`, `errorCorrectionLevel`, `dotStyle`, `cornerStyle`, `logo` (tệp tùy chọn) |
+| `barcode-read` | Đọc mã vạch | - (tự động phát hiện QR, EAN, Code128, DataMatrix, v.v.) |
+| `image-to-base64` | Ảnh sang Base64 | `format` (data-uri/plain), `mimeType` |
+| `html-to-image` | HTML sang ảnh | `url`, `format` (png/jpg/webp), `quality`, `fullPage`, `devicePreset` (desktop/tablet/mobile/custom), `viewportWidth`, `viewportHeight` |
+| `histogram` | Biểu đồ tần suất | `scale` (linear/log) - trả về biểu đồ histogram RGB + thống kê từng kênh |
+| `lqip-placeholder` | LQIP Placeholder | `width` (4-64), `blur`, `strategy` (blur/pixelate/solid), `format` (webp/png/jpeg), `quality` |
+| `barcode-generate` | Trình tạo mã vạch | `text`, `type` (code128/ean13/upca/code39/itf14/datamatrix), `scale` (1-8), `includeText` (bool). Thân JSON, không tải tệp lên. |
+
+### Bố cục & Sắp xếp {#layout-composition}
+
+| ID công cụ | Tên | Cài đặt chính |
+|---------|------|-------------|
+| `collage` | Ghép ảnh / Lưới | `template` (25+ bố cục), `gap`, `backgroundColor`, `borderRadius` - đa tệp |
+| `stitch` | Ghép nối / Kết hợp | `direction` (horizontal/vertical/grid), `gap`, `backgroundColor`, `alignment` - đa tệp |
+| `split` | Chia ảnh | `mode` (grid/rows/cols), `rows`, `cols`, `tileWidth`, `tileHeight` |
+| `border` | Viền & Khung | `width`, `color`, `style` (solid/gradient/pattern), `borderRadius`, `padding`, `shadow` |
+| `beautify` | Làm đẹp ảnh chụp màn hình | `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` | Cắt tròn | `zoom` (1-5), `offsetX`, `offsetY`, `borderWidth`, `borderColor`, `background` (transparent/hex), `outputSize` |
+| `image-pad` | Đệm ảnh | `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` - đa tệp (2-64 ảnh) |
+
+### Định dạng & Chuyển đổi {#format-conversion}
+
+| ID công cụ | Tên | Cài đặt chính |
+|---------|------|-------------|
+| `svg-to-raster` | SVG sang Raster | `format` (png/jpeg/webp/avif/tiff/gif/heif), `width`, `height`, `scale`, `dpi`, `background` |
+| `vectorize` | Ảnh sang SVG | `colorMode` (bw/color), `threshold`, `colorPrecision`, `filterSpeckle`, `pathMode` (none/polygon/spline) |
+| `gif-tools` | Công cụ GIF | `action` (resize/optimize/reverse/speed/extract-frames/rotate/add-text), tham số theo từng hành động |
+| `gif-webp` | Trình chuyển đổi GIF/WebP | `quality` (1-100), `lossless` (bool), `resizePercent` (10-100) |
+
+### Công cụ Video {#video-tools}
+
+| ID công cụ | Tên | Cài đặt chính |
+|---------|------|-------------|
+| `convert-video` | Chuyển đổi Video | `format` (mp4/mov/webm/avi/mkv), `quality` (high/balanced/small) |
+| `compress-video` | Nén Video | `quality` (light/balanced/strong), `resolution` (original/1080p/720p/480p) |
+| `trim-video` | Cắt Video | `startS`, `endS`, `precise` (bool, cắt chính xác từng khung hình) |
+| `mute-video` | Tắt tiếng Video | - |
+| `video-to-gif` | Video sang GIF | `fps` (1-30), `width`, `startS`, `durationS` (tối đa 60 giây) |
+| `resize-video` | Đổi kích thước Video | `width`, `height`, `preset` (custom/2160p/1440p/1080p/720p/480p/360p) |
+| `crop-video` | Cắt xén Video | `width`, `height`, `x`, `y` |
+| `rotate-video` | Xoay Video | `transform` (cw90/ccw90/180/hflip/vflip) |
+| `change-fps` | Đổi FPS | `fps` (1-120) |
+| `video-color` | Màu Video | `brightness`, `contrast`, `saturation`, `gamma` |
+| `video-speed` | Tốc độ Video | `factor` (0.25-4), `keepPitch` (bool) |
+| `reverse-video` | Đảo ngược Video | - (tối đa 5 phút) |
+| `video-loudnorm` | Chuẩn hóa âm thanh | - (EBU R128) |
+| `aspect-pad` | Đệm tỷ lệ khung hình | `target` (16:9/9:16/1:1/4:3/3:4), `color` (hex) |
+| `blur-pad` | Đệm mờ | `target` (16:9/9:16/1:1/4:3/3:4), `blur` (2-50) |
+| `watermark-video` | Đóng dấu Video | `text`, `position`, `fontSize`, `opacity`, `color` |
+| `stabilize-video` | Ổn định Video | `smoothing` (5-60, theo khung hình) |
+| `gif-to-video` | GIF sang Video | `format` (mp4/webm/mov) |
+| `video-to-webp` | Video sang WebP | `fps`, `width`, `quality`, `loop` (bool) |
+| `video-to-frames` | Video sang khung hình | `mode` (all/nth/timestamps), `n`, `timestamps`, `format` (png/jpg) |
+| `merge-videos` | Ghép Video | - (đa tệp, chuẩn hóa theo độ phân giải của video đầu tiên) |
+| `replace-audio` | Thay âm thanh | - (tệp video + âm thanh, hai tệp) |
+| `burn-subtitles` | Gắn phụ đề cứng | `fontSize` (8-72) - tệp video + phụ đề |
+| `embed-subtitles` | Nhúng phụ đề | `language` (mã ISO 639-2/B) - tệp video + phụ đề |
+| `extract-subtitles` | Trích xuất phụ đề | - (xuất SRT) |
+| `images-to-video` | Ảnh sang Video | `secondsPerImage` (0.5-10), `resolution` (1080p/720p/square), `fps` - đa tệp |
+| `video-metadata` | Dọn Metadata Video | - |
+| `auto-subtitles` | Phụ đề tự động (AI) | `language` (auto/en/de/fr/es/zh/ja/ko/id/th/vi), `format` (srt/vtt) |
+| `extract-audio` | Trích xuất âm thanh | `format` (mp3/wav/m4a/ogg) |
+
+### Công cụ Âm thanh {#audio-tools}
+
+| ID công cụ | Tên | Cài đặt chính |
+|---------|------|-------------|
+| `convert-audio` | Chuyển đổi âm thanh | `format` (mp3/wav/ogg/flac/m4a), `bitrateKbps` (32-320) |
+| `trim-audio` | Cắt âm thanh | `startS`, `endS` |
+| `volume-adjust` | Điều chỉnh âm lượng | `gainDb` (-30 đến 30) |
+| `normalize-audio` | Chuẩn hóa âm thanh | - (EBU R128, -16 LUFS) |
+| `fade-audio` | Làm mờ dần âm thanh | `fadeInS` (0-30), `fadeOutS` (0-30) |
+| `reverse-audio` | Đảo ngược âm thanh | - |
+| `audio-speed` | Tốc độ âm thanh | `factor` (0.25-4) |
+| `pitch-shift` | Dịch cao độ | `semitones` (-12 đến 12) |
+| `audio-channels` | Kênh âm thanh | `mode` (stereo-to-mono/mono-to-stereo/swap) |
+| `silence-removal` | Loại bỏ khoảng lặng | `thresholdDb` (-80 đến -20), `minSilenceS` (0.1-5) |
+| `noise-reduction` | Giảm nhiễu | `strength` (light/medium/strong) |
+| `merge-audio` | Ghép âm thanh | `format` (mp3/wav/flac/m4a) - đa tệp |
+| `split-audio` | Chia âm thanh | `mode` (time/parts/silence), `segmentS`, `parts`, `thresholdDb`, `minSilenceS` |
+| `ringtone-maker` | Trình tạo nhạc chuông | `startS`, `durationS` (1-30) |
+| `waveform-image` | Ảnh dạng sóng | `width`, `height`, `color` (hex) |
+| `audio-metadata` | Metadata âm thanh | `strip` (bool), `title`, `artist`, `album` |
+| `transcribe-audio` | Chuyển giọng nói thành văn bản (AI) | `language` (auto/en/de/fr/es/zh/ja/ko/id/th/vi), `outputFormat` (txt/srt/vtt) |
+
+### Công cụ Tài liệu {#document-tools}
+
+| ID công cụ | Tên | Cài đặt chính |
+|---------|------|-------------|
+| `merge-pdf` | Ghép PDF | - (đa tệp, tối đa 20 PDF) |
+| `split-pdf` | Chia PDF | `mode` (range/every), `range`, `everyN` (1-500) |
+| `compress-pdf` | Nén PDF | `mode` (quality/targetSize), `quality` (1-100), `targetSizeKb` |
+| `rotate-pdf` | Xoay PDF | `angle` (90/180/270), `range` (khoảng trang) |
+| `extract-pages` | Trích xuất trang | `range` (cú pháp qpdf, ví dụ "1-5,8,10-z") |
+| `remove-pages` | Xóa trang | `pages` (khoảng qpdf cần xóa) |
+| `organize-pdf` | Sắp xếp PDF | `order` (thứ tự trang qpdf, ví dụ "3,1,2,5-z") |
+| `protect-pdf` | Bảo vệ PDF | `userPassword`, `ownerPassword` (AES-256) |
+| `unlock-pdf` | Mở khóa PDF | `password` |
+| `repair-pdf` | Sửa chữa PDF | - |
+| `linearize-pdf` | Tối ưu PDF cho Web | - (tuyến tính hóa để xem web nhanh) |
+| `grayscale-pdf` | PDF thang xám | - |
+| `pdfa-convert` | Chuyển đổi PDF/A | - (PDF/A-2 lưu trữ) |
+| `crop-pdf` | Cắt PDF | `margin` (0-2000 điểm) |
+| `nup-pdf` | N-up PDF | `perSheet` (2/3/4/8/9/12/16) |
+| `booklet-pdf` | Booklet PDF | `perSheet` (2/4/6/8) |
+| `watermark-pdf` | Đóng dấu PDF | `text`, `position`, `fontSize`, `opacity`, `rotation` |
+| `pdf-page-numbers` | Đánh số trang PDF | `position` (bl/bc/br/tl/tc/tr), `fontSize` |
+| `flatten-pdf` | Làm phẳng PDF | - (nướng biểu mẫu và chú thích) |
+| `redact-pdf` | Che thông tin PDF | `terms` (string[]), `caseSensitive` (bool) |
+| `sign-pdf` | Ký PDF | Route multipart tùy chỉnh với PDF `file`, tệp chữ ký `sig0`, `sig1`, và mảng JSON `placements` |
+| `pdf-to-text` | PDF sang Text | - |
+| `pdf-to-word` | PDF sang Word | - |
+| `pdf-metadata` | Metadata PDF | `title`, `author`, `subject`, `keywords` |
+| `convert-document` | Chuyển đổi tài liệu | `format` (docx/odt/rtf/txt) |
+| `convert-presentation` | Chuyển đổi bản trình bày | `format` (pptx/odp) |
+| `convert-spreadsheet` | Chuyển đổi bảng tính | `format` (xlsx/ods/csv) |
+| `excel-to-pdf` | Excel sang PDF | - |
+| `word-to-pdf` | Word sang PDF | - |
+| `powerpoint-to-pdf` | PowerPoint sang PDF | - |
+| `html-to-pdf` | HTML sang PDF | - (tài nguyên từ xa bị tắt) |
+| `markdown-to-docx` | Markdown sang Word | - |
+| `markdown-to-html` | Markdown sang HTML | - |
+| `markdown-to-pdf` | Markdown sang PDF | - (tài nguyên từ xa bị tắt) |
+| `epub-convert` | Chuyển đổi EPUB | `format` (pdf/docx/html/md) |
+| `to-epub` | Chuyển đổi sang EPUB | - (nhận .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 sang ảnh | `pages` (all/range), `format`, `dpi`, `quality` |
+| `pdf-to-jpg` | PDF sang JPG | `pages`, `dpi`, `quality`, `colorMode` |
+| `pdf-to-png` | PDF sang PNG | `pages`, `dpi`, `quality`, `colorMode` |
+| `pdf-to-tiff` | PDF sang TIFF | `pages`, `dpi`, `quality`, `colorMode` |
+
+### Công cụ Tệp {#file-tools}
+
+| ID công cụ | Tên | Cài đặt chính |
+|---------|------|-------------|
+| `chart-maker` | Trình tạo biểu đồ | `kind` (bar/line/pie), `title`, `width`, `height` |
+| `csv-excel` | CSV sang Excel | `sheet` (số trang tính cho đầu vào XLSX) - hai chiều |
+| `csv-json` | CSV sang JSON | `pretty` (bool) - hai chiều |
+| `json-xml` | JSON sang XML | `pretty` (bool) - hai chiều |
+| `split-csv` | Chia CSV | `rowsPerFile` (1-1000000), `keepHeader` (bool) |
+| `merge-csvs` | Ghép CSV | - (đa tệp, cột khớp nhau) |
+| `yaml-json` | YAML / JSON | - (hai chiều) |
+| `xml-to-csv` | XML sang CSV | - (tự động tìm các phần tử lặp) |
+| `excel-to-csv` | Excel sang CSV | cấu hình chuyển đổi chuyên biệt được hỗ trợ bởi `convert-spreadsheet` |
+| `create-zip` | Tạo ZIP | - (đa tệp, 2-50 tệp) |
+| `extract-zip` | Giải nén ZIP | - (chống bom nén) |
+
+### HTML sang ảnh {#html-to-image}
+
+Chụp một trang web thành ảnh. Khác với các công cụ khác, endpoint này nhận `application/json` thay vì dữ liệu form multipart (không cần tải tệp lên).
+
+**Endpoint:** `POST /api/v1/tools/image/html-to-image`
+
+**Content-Type:** `application/json`
+
+| Tham số | Kiểu | Mặc định | Mô tả |
+|-----------|------|---------|-------------|
+| `url` | string | (bắt buộc) | URL cần chụp (chỉ http/https) |
+| `format` | string | `"png"` | Định dạng đầu ra: `jpg`, `png`, `webp` |
+| `quality` | number | `90` | Chất lượng 1-100 (chỉ JPG/WebP) |
+| `fullPage` | boolean | `false` | Chụp toàn bộ trang cuộn được |
+| `devicePreset` | string | `"desktop"` | `desktop`, `tablet`, `mobile`, `custom` |
+| `viewportWidth` | number | `1280` | Chiều rộng viewport tùy chỉnh 320-3840 |
+| `viewportHeight` | number | `720` | Chiều cao viewport tùy chỉnh 320-2160 |
+
+**Ví dụ:**
+
+```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"}'
+```
+
+**Response:**
+
+```json
+{
+  "jobId": "uuid",
+  "downloadUrl": "/api/v1/download/{jobId}/screenshot.png",
+  "originalSize": 0,
+  "processedSize": 54321
+}
+```
+
+### Route con của công cụ {#tool-sub-routes}
+
+Một số công cụ cung cấp thêm endpoint ngoài `POST /api/v1/tools/<section>/<toolId>` tiêu chuẩn:
+
+| Phương thức | Đường dẫn | Mô tả |
+|--------|------|-------------|
+| `GET` | `/api/v1/tools/popular` | Trả về ID công cụ phổ biến, quay lại danh sách mặc định được tuyển chọn khi dữ liệu sử dụng còn ít |
+| `POST` | `/api/v1/tools/image/remove-background/effects` | Áp dụng hiệu ứng nền (color/gradient/blur/shadow) mà không chạy lại AI. Dùng mặt nạ được cache từ lần xóa ban đầu. |
+| `POST` | `/api/v1/tools/image/edit-metadata/inspect` | Đọc metadata EXIF/IPTC/XMP có sẵn từ một ảnh |
+| `POST` | `/api/v1/tools/image/strip-metadata/inspect` | Kiểm tra các trường metadata trước khi xóa |
+| `POST` | `/api/v1/tools/image/passport-photo/analyze` | Giai đoạn 1: Phát hiện khuôn mặt bằng AI + xóa nền. Trả về điểm mốc khuôn mặt và dữ liệu được cache. |
+| `POST` | `/api/v1/tools/image/passport-photo/generate` | Giai đoạn 2: Cắt, đổi kích thước và xếp ô bằng phân tích được cache. Không chạy lại AI. |
+| `POST` | `/api/v1/tools/image/gif-tools/info` | Lấy metadata GIF (số khung hình, kích thước, thời lượng) |
+| `POST` | `/api/v1/tools/pdf/pdf-to-image/info` | Lấy metadata PDF (số trang, kích thước) |
+| `POST` | `/api/v1/tools/pdf/pdf-to-image/preview` | Tạo bản xem trước của một trang PDF cụ thể |
+| `POST` | `/api/v1/tools/pdf/pdf-to-jpg/info` | Lấy metadata PDF cho cấu hình JPG chuyên biệt |
+| `POST` | `/api/v1/tools/pdf/pdf-to-jpg/preview` | Tạo bản xem trước trang PDF cấu hình JPG |
+| `POST` | `/api/v1/tools/pdf/pdf-to-png/info` | Lấy metadata PDF cho cấu hình PNG chuyên biệt |
+| `POST` | `/api/v1/tools/pdf/pdf-to-png/preview` | Tạo bản xem trước trang PDF cấu hình PNG |
+| `POST` | `/api/v1/tools/pdf/pdf-to-tiff/info` | Lấy metadata PDF cho cấu hình TIFF chuyên biệt |
+| `POST` | `/api/v1/tools/pdf/pdf-to-tiff/preview` | Tạo bản xem trước trang PDF cấu hình TIFF |
+| `POST` | `/api/v1/tools/image/svg-to-raster/batch` | Chuyển đổi hàng loạt nhiều SVG sang raster |
+| `POST` | `/api/v1/tools/image/image-enhancement/analyze` | Phân tích chất lượng ảnh và trả về đề xuất nâng cao |
+| `POST` | `/api/v1/tools/image/optimize-for-web/preview` | Bản xem trước nhẹ để tinh chỉnh tham số trực tiếp. Trả về ảnh được tối ưu kèm header kích thước. |
+
+## Xử lý hàng loạt {#batch-processing}
+
+Áp dụng một công cụ hỗ trợ hàng loạt tổng quát cho nhiều tệp cùng lúc. Trả về một kho lưu trữ ZIP. Các route đa tệp hoặc nhiều bước tùy chỉnh, chẳng hạn ký PDF, OCR PDF và các route cấu hình PDF-sang-ảnh, dùng hợp đồng endpoint riêng thay vì route `/batch` tổng quát.
+
+```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}'
+```
+
+Độ đồng thời được kiểm soát bởi `CONCURRENT_JOBS` (mặc định: tự động phát hiện từ số lõi CPU). `MAX_BATCH_SIZE` giới hạn số tệp mỗi lô (mặc định: 100; đặt 0 để không giới hạn).
+
+## Pipeline {#pipelines}
+
+### Thực thi một pipeline {#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}}]}'
+```
+
+Đầu ra của mỗi bước là đầu vào của bước tiếp theo. Pipeline mặc định cho phép 20 bước, có thể cấu hình qua `MAX_PIPELINE_STEPS`. Đặt `MAX_PIPELINE_STEPS=0` để bỏ giới hạn.
+
+### Lưu và quản lý pipeline {#save-and-manage-pipelines}
+
+| Phương thức | Đường dẫn | Mô tả |
+|--------|------|-------------|
+| `POST` | `/api/v1/pipeline/save` | Lưu một pipeline có tên (`name`, `description`, `steps[]`) |
+| `GET` | `/api/v1/pipeline/list` | Liệt kê pipeline đã lưu (admin thấy tất cả; người dùng thấy của riêng mình) |
+| `DELETE` | `/api/v1/pipeline/:id` | Xóa (chủ sở hữu hoặc admin) |
+| `GET` | `/api/v1/pipeline/tools` | Liệt kê các ID công cụ hợp lệ cho các bước pipeline |
+
+## Theo dõi tiến trình {#progress-tracking}
+
+Các tác vụ chạy lâu, công cụ được xếp hàng, tác vụ hàng loạt và pipeline phát tiến trình theo thời gian thực qua Server-Sent Events. Luồng tiến trình là công khai và được khóa theo ID tác vụ, nên client không cần gửi header Authorization để đọc.
+
+```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
+```
+
+Định dạng sự kiện:
+```
+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":[]}
+```
+
+Bạn có thể yêu cầu hủy một tác vụ đang xếp hàng hoặc đang chạy bằng `POST /api/v1/jobs/:jobId/cancel`. Response là `{"canceled":true|false}`.
+
+## Thư viện tệp {#file-library}
+
+Lưu trữ tệp bền vững kèm lịch sử phiên bản.
+
+| Phương thức | Đường dẫn | Mô tả |
+|--------|------|-------------|
+| `POST` | `/api/v1/upload` | Tải tệp lên không gian làm việc (xử lý tạm thời) |
+| `POST` | `/api/v1/files/upload` | Tải tệp lên thư viện tệp bền vững |
+| `POST` | `/api/v1/files/save-result` | Lưu kết quả xử lý của công cụ thành phiên bản tệp mới |
+| `GET` | `/api/v1/files` | Liệt kê tệp đã lưu (phân trang, có tìm kiếm) |
+| `GET` | `/api/v1/files/:id` | Lấy metadata tệp + chuỗi phiên bản |
+| `GET` | `/api/v1/files/:id/download` | Tải tệp xuống |
+| `GET` | `/api/v1/files/:id/thumbnail` | Lấy hình thu nhỏ JPEG 300px |
+| `DELETE` | `/api/v1/files` | Xóa hàng loạt tệp và chuỗi phiên bản của chúng (thân: `{ ids: [...] }`) |
+| `POST` | `/api/v1/fetch-urls` | Tải URL từ xa vào không gian làm việc cho các lần nhập dựa trên URL |
+| `POST` | `/api/v1/preview` | Tạo bản xem trước WebP tương thích trình duyệt (cho định dạng HEIC/HEIF/RAW) |
+| `GET` | `/api/v1/files/:id/preview` | Stream bản xem trước tương thích trình duyệt được cache hoặc tạo mới cho một tệp PDF, tài liệu văn phòng, video hoặc âm thanh đã lưu |
+| `POST` | `/api/v1/preview/generate` | Tạo bản xem trước MP4 hoặc MP3 theo yêu cầu cho một tệp phương tiện đã tải lên mà không cần lưu trước |
+| `GET` | `/api/v1/download/:jobId/:filename` | Tải một tệp đã xử lý từ không gian làm việc |
+
+Để tự động lưu kết quả công cụ vào thư viện, hãy đưa vào `fileId` làm một trường form multipart tham chiếu đến một tệp có sẵn trong thư viện. Kết quả đã xử lý sẽ được lưu thành phiên bản mới.
+
+## Quản lý khóa API {#api-key-management}
+
+| Phương thức | Đường dẫn | Quyền truy cập | Mô tả |
+|--------|------|--------|-------------|
+| `POST` | `/api/v1/api-keys` | Xác thực | Tạo khóa mới - chỉ hiển thị một lần |
+| `GET` | `/api/v1/api-keys` | Xác thực | Liệt kê khóa (name, id, lastUsedAt - không phải khóa thô) |
+| `DELETE` | `/api/v1/api-keys/:id` | Xác thực | Xóa khóa |
+
+## Nhóm {#teams}
+
+| Phương thức | Đường dẫn | Quyền truy cập | Mô tả |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/teams` | Admin (`teams:manage`) | Liệt kê nhóm |
+| `POST` | `/api/v1/teams` | Admin (`teams:manage`) | Tạo nhóm |
+| `PUT` | `/api/v1/teams/:id` | Admin (`teams:manage`) | Đổi tên nhóm |
+| `DELETE` | `/api/v1/teams/:id` | Admin (`teams:manage`) | Xóa nhóm (không thể xóa nhóm mặc định hoặc nhóm có thành viên) |
+
+## Cài đặt {#settings}
+
+Cấu hình khóa-giá trị lúc chạy (bất kỳ người dùng đã xác thực nào cũng đọc được, chỉ admin ghi được).
+
+| Phương thức | Đường dẫn | Mô tả |
+|--------|------|-------------|
+| `GET` | `/api/v1/settings` | Lấy tất cả cài đặt |
+| `PUT` | `/api/v1/settings` | Cập nhật hàng loạt cài đặt (thân JSON với các cặp khóa-giá trị) |
+| `GET` | `/api/v1/settings/:key` | Lấy một cài đặt cụ thể theo khóa |
+
+Các khóa đã biết: `disabledTools` (mảng JSON gồm các ID công cụ), `enableExperimentalTools` (chuỗi bool), `loginAttemptLimit` (số).
+
+## Tùy chọn {#preferences}
+
+Tùy chọn theo từng người dùng tách biệt với cài đặt instance. Bất kỳ người dùng đã xác thực nào cũng có thể đọc và cập nhật bản đồ tùy chọn của riêng mình.
+
+| Phương thức | Đường dẫn | Mô tả |
+|--------|------|-------------|
+| `GET` | `/api/v1/preferences` | Lấy tùy chọn của người dùng hiện tại dưới dạng `{ "preferences": { ... } }` |
+| `PUT` | `/api/v1/preferences` | Chèn/cập nhật một hoặc nhiều khóa tùy chọn cho người dùng hiện tại |
+
+## Vai trò {#roles}
+
+Quản lý vai trò tùy chỉnh với quyền hạn chi tiết.
+
+| Phương thức | Đường dẫn | Quyền truy cập | Mô tả |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/roles` | Admin (`audit:read`) | Liệt kê tất cả vai trò kèm số người dùng |
+| `POST` | `/api/v1/roles` | Admin (`security:manage`) | Tạo một vai trò tùy chỉnh (`name`, `description`, `permissions`) |
+| `PUT` | `/api/v1/roles/:id` | Admin (`security:manage`) | Cập nhật một vai trò tùy chỉnh (không thể sửa vai trò tích hợp sẵn) |
+| `DELETE` | `/api/v1/roles/:id` | Admin (`security:manage`) | Xóa một vai trò tùy chỉnh (không thể xóa vai trò tích hợp sẵn; người dùng bị ảnh hưởng trở về vai trò `user`) |
+
+Các quyền hạn có sẵn (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`.
+
+## Nhật ký kiểm toán {#audit-log}
+
+Endpoint chỉ dành cho admin để xem lại các hành động liên quan đến bảo mật.
+
+| Phương thức | Đường dẫn | Quyền truy cập | Mô tả |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/audit-log` | Admin (`audit:read`) | Nhật ký kiểm toán phân trang với bộ lọc tùy chọn |
+
+Các tham số truy vấn:
+
+| Tham số | Mô tả |
+|-----------|-------------|
+| `page` | Số trang (mặc định: 1) |
+| `limit` | Số mục mỗi trang (mặc định: 50, tối đa: 100) |
+| `action` | Lọc theo loại hành động (ví dụ `ROLE_CREATED`, `ROLE_DELETED`) |
+| `ip` | Lọc theo địa chỉ IP nguồn |
+| `from` | Lọc các mục sau ngày ISO 8601 này |
+| `to` | Lọc các mục trước ngày ISO 8601 này |
+
+## Phân tích {#analytics}
+
+| Phương thức | Đường dẫn | Quyền truy cập | Mô tả |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/config/analytics` | Công khai | Lấy cấu hình phân tích có hiệu lực (khóa PostHog, Sentry DSN, tỷ lệ lấy mẫu). Khóa, DSN và ID instance để trống khi phân tích bị tắt, dù từ việc nướng lúc biên dịch hay từ cài đặt `analyticsEnabled` của instance. |
+| `POST` | `/api/v1/feedback` | Xác thực | Gửi phản hồi rõ ràng của người dùng đến dự án PostHog đã cấu hình dưới dạng `feedback_submitted`. Route tuân thủ cổng phân tích, giới hạn tốc độ gửi, loại bỏ các trường liên hệ trừ khi `contactOk` là true, và không bao giờ nhận nội dung tệp, tên tệp, đường dẫn tải lên hoặc văn bản lỗi riêng tư thô. Khi phân tích bị tắt, nó trả về `{ "ok": true, "accepted": false }`. |
+| `PUT` | `/api/v1/settings` | Admin (`settings:write`) | Đặt tùy chọn từ chối trên toàn instance. Gửi một thân JSON `{ "analyticsEnabled": "false" }` để tắt phân tích cho tất cả mọi người, hoặc `"true"` để bật lại. |
+
+## Tính năng / Bundle AI {#features-ai-bundles}
+
+Quản lý các bundle tính năng AI (cài đặt/gỡ cài đặt các gói mô hình AI trong môi trường Docker). Ưu tiên endpoint cài đặt ở cấp công cụ khi bật một công cụ từ tự động hóa tùy chỉnh: một số công cụ AI cần nhiều hơn một bundle dùng chung, và endpoint này bỏ qua các bundle đã cài đặt trong khi chỉ xếp hàng những bundle còn thiếu.
+
+| Phương thức | Đường dẫn | Quyền truy cập | Mô tả |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/features` | Xác thực | Liệt kê tất cả bundle tính năng và trạng thái cài đặt của chúng |
+| `POST` | `/api/v1/admin/features/:bundleId/install` | Admin (`features:manage`) | Cài đặt một bundle tính năng (bất đồng bộ, trả về `jobId` để theo dõi tiến trình) |
+| `POST` | `/api/v1/admin/tools/:toolId/features/install` | Admin (`features:manage`) | Cài đặt mọi bundle mà một công cụ cần; trả về trạng thái đã xếp hàng/đã bỏ qua theo từng bundle |
+| `POST` | `/api/v1/admin/features/:bundleId/uninstall` | Admin (`features:manage`) | Gỡ cài đặt một bundle tính năng và dọn dẹp các tệp mô hình |
+| `GET` | `/api/v1/admin/features/disk-usage` | Admin (`features:manage`) | Lấy tổng dung lượng đĩa của các mô hình AI |
+| `POST` | `/api/v1/admin/features/import` | Admin (`features:manage`) | Nhập một kho lưu trữ bundle AI ngoại tuyến |
+
+## Thao tác quản trị {#admin-operations}
+
+Các endpoint vận hành cho quan sát, hỗ trợ, báo cáo sử dụng và trạng thái sao lưu.
+
+| Phương thức | Đường dẫn | Quyền truy cập | Mô tả |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/admin/log-level` | Admin (`settings:write`) | Đọc mức log lúc chạy hiện tại |
+| `POST` | `/api/v1/admin/log-level` | Admin (`settings:write`) | Thay đổi mức log lúc chạy (`fatal`, `error`, `warn`, `info`, `debug`, `trace`, hoặc `silent`) |
+| `GET` | `/api/v1/metrics` | Admin (`system:health`) | Số liệu Prometheus ở định dạng văn bản |
+| `GET` | `/api/v1/admin/support-bundle` | Admin (`system:health`) | Tải một bundle hỗ trợ chẩn đoán đã ẩn thông tin dưới dạng ZIP |
+| `GET` | `/api/v1/admin/usage` | Admin (`audit:read`) | Dữ liệu bảng điều khiển sử dụng, với tham số truy vấn `days` tùy chọn |
+| `GET` | `/api/v1/admin/backup-status` | Admin (`system:health`) | Đọc metadata sao lưu gần nhất và trạng thái mới cũ |
+| `POST` | `/api/v1/admin/backup-status` | Admin (`system:health`) | Ghi nhận một lần sao lưu đã hoàn tất (`type`, `sizeBytes` tùy chọn, `notes` tùy chọn) |
+
+## API Enterprise {#enterprise-apis}
+
+Các route này bị khóa theo giấy phép của tính năng enterprise liên quan. Chúng vẫn yêu cầu quyền hạn SnapOtter được liệt kê.
+
+| Phương thức | Đường dẫn | Quyền truy cập | Mô tả |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/enterprise/audit/export` | Admin (`audit:read`) | Xuất các mục kiểm toán dưới dạng JSON hoặc CSV với bộ lọc |
+| `GET` | `/api/v1/enterprise/config/export` | Admin (`system:health`) | Xuất cấu hình instance, vai trò tùy chỉnh và nhóm đã ẩn thông tin |
+| `POST` | `/api/v1/enterprise/config/import` | Admin (`system:health`) | Nhập cấu hình, với chạy thử tùy chọn |
+| `GET` | `/api/v1/enterprise/ip-allowlist` | Admin (`security:manage`) | Đọc danh sách cho phép CIDR đã cấu hình |
+| `PUT` | `/api/v1/enterprise/ip-allowlist` | Admin (`security:manage`) | Cập nhật danh sách cho phép CIDR với cơ chế ngăn tự khóa mình ra ngoài |
+| `GET` | `/api/v1/enterprise/legal-hold` | Admin (`compliance:manage`) | Liệt kê các lệnh giữ pháp lý của người dùng và nhóm |
+| `PUT` | `/api/v1/enterprise/legal-hold` | Admin (`compliance:manage`) | Áp dụng hoặc gỡ bỏ lệnh giữ pháp lý cho một người dùng hoặc nhóm |
+| `POST` | `/api/v1/enterprise/scim/token` | Admin (`users:manage`) | Tạo một token bearer SCIM, chỉ trả về một lần |
+| `DELETE` | `/api/v1/enterprise/scim/token` | Admin (`users:manage`) | Thu hồi token bearer SCIM hiện tại |
+| `GET` | `/api/v1/enterprise/siem/config` | Admin (`webhooks:manage`) | Đọc cấu hình chuyển tiếp SIEM |
+| `PUT` | `/api/v1/enterprise/siem/config` | Admin (`webhooks:manage`) | Cập nhật cấu hình chuyển tiếp SIEM |
+| `GET` | `/api/v1/enterprise/webhooks` | Admin (`webhooks:manage`) | Liệt kê các đích webhook |
+| `POST` | `/api/v1/enterprise/webhooks` | Admin (`webhooks:manage`) | Tạo một đích webhook |
+| `PUT` | `/api/v1/enterprise/webhooks/:index` | Admin (`webhooks:manage`) | Cập nhật một đích webhook |
+| `DELETE` | `/api/v1/enterprise/webhooks/:index` | Admin (`webhooks:manage`) | Xóa một đích webhook |
+| `POST` | `/api/v1/enterprise/webhooks/:index/test` | Admin (`webhooks:manage`) | Gửi một payload webhook thử nghiệm |
+| `POST` | `/api/v1/enterprise/users/:id/export` | Admin (`compliance:manage`) | Bắt đầu một tác vụ xuất dữ liệu người dùng GDPR |
+| `GET` | `/api/v1/enterprise/users/:id/export/:jobId` | Admin (`compliance:manage`) | Đọc trạng thái xuất GDPR và URL tải xuống |
+| `DELETE` | `/api/v1/enterprise/users/:id/purge` | Admin (`compliance:manage`) | Xóa vĩnh viễn dữ liệu của một người dùng sau khi xác nhận |
+| `DELETE` | `/api/v1/enterprise/teams/:id/purge` | Admin (`compliance:manage`) | Xóa vĩnh viễn dữ liệu của một nhóm sau khi xác nhận |
+| `GET` | `/api/v1/admin/version` | Admin (`system:health`) | Đọc metadata phiên bản của app, build, Node và schema |
+| `GET` | `/api/v1/admin/migrations/pending` | Admin (`system:health`) | So sánh các migration được đóng gói với các migration đã áp dụng |
+| `GET` | `/api/v1/admin/upgrade-check` | Admin (`system:health`) | Chạy các kiểm tra sẵn sàng nâng cấp |
+
+### SCIM 2.0 {#scim-2-0}
+
+Các endpoint khám phá SCIM là công khai. Các endpoint người dùng và nhóm yêu cầu token bearer SCIM được tạo ở trên.
+
+| Phương thức | Đường dẫn | Quyền truy cập | Mô tả |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/scim/v2/ServiceProviderConfig` | Công khai | Khả năng của máy chủ SCIM |
+| `GET` | `/api/v1/scim/v2/Schemas` | Công khai | Khám phá schema SCIM |
+| `GET` | `/api/v1/scim/v2/ResourceTypes` | Công khai | Khám phá loại tài nguyên SCIM |
+| `GET` | `/api/v1/scim/v2/Users` | Token SCIM | Liệt kê người dùng, với bộ lọc SCIM tùy chọn |
+| `POST` | `/api/v1/scim/v2/Users` | Token SCIM | Tạo một người dùng |
+| `GET` | `/api/v1/scim/v2/Users/:id` | Token SCIM | Lấy một người dùng |
+| `PUT` | `/api/v1/scim/v2/Users/:id` | Token SCIM | Thay thế một người dùng |
+| `DELETE` | `/api/v1/scim/v2/Users/:id` | Token SCIM | Vô hiệu hóa mềm một người dùng |
+| `GET` | `/api/v1/scim/v2/Groups` | Token SCIM | Liệt kê nhóm dưới dạng nhóm SCIM |
+| `POST` | `/api/v1/scim/v2/Groups` | Token SCIM | Tạo một nhóm |
+| `GET` | `/api/v1/scim/v2/Groups/:id` | Token SCIM | Lấy một nhóm |
+| `PUT` | `/api/v1/scim/v2/Groups/:id` | Token SCIM | Thay thế một nhóm và thành viên nhóm |
+| `DELETE` | `/api/v1/scim/v2/Groups/:id` | Token SCIM | Xóa một nhóm |
+
+## Mẫu Meme {#meme-templates}
+
+API hỗ trợ cho công cụ trình tạo meme.
+
+| Phương thức | Đường dẫn | Quyền truy cập | Mô tả |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/meme-templates` | Xác thực | Liệt kê tất cả mẫu meme có sẵn kèm vị trí các ô văn bản |
+| `GET` | `/api/v1/meme-templates/full/:filename` | Xác thực | Phục vụ ảnh mẫu kích thước đầy đủ |
+| `GET` | `/api/v1/meme-templates/thumbs/:filename` | Xác thực | Phục vụ hình thu nhỏ của mẫu |
+| `GET` | `/api/v1/meme-templates/fonts/:filename` | Xác thực | Phục vụ tệp phông chữ dùng để hiển thị văn bản meme |
+
+## Phản hồi lỗi {#error-responses}
+
+Mọi lỗi đều trả về JSON:
+
+```json
+{
+  "error": "Human-readable message",
+  "code": "MACHINE_READABLE_CODE"
+}
+```
+
+| Trạng thái | Ý nghĩa |
+|--------|---------|
+| 400 | Request không hợp lệ / xác thực thất bại |
+| 401 | Chưa xác thực |
+| 403 | Không đủ quyền hạn |
+| 404 | Không tìm thấy tài nguyên |
+| 413 | Tệp quá lớn (xem `MAX_UPLOAD_SIZE_MB`) |
+| 422 | Xử lý thất bại sau khi xác thực |
+| 429 | Bị giới hạn tốc độ (xem `RATE_LIMIT_PER_MIN`) |
+| 501 | Bundle tính năng AI cần thiết chưa được cài đặt (`FEATURE_NOT_INSTALLED`) |
+| 500 | Lỗi máy chủ nội bộ |