SnapOtter/apps/docs/vi/api/ai.md

description, i18n_output_hash, i18n_source_hash, i18n_provenance

description	i18n_output_hash	i18n_source_hash	i18n_provenance
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.	937f3b5907f4	aa9a56cdddc7	human

Tài liệu tham khảo Engine AI

Gói @snapotter/ai điều phối các công cụ gốc và thời gian chạy Python cho các hoạt động ML cục bộ. Hầu hết các công cụ ML đều sử dụng Python sidecar bền bỉ để khởi động ấm nhanh. OCR được cố ý tách biệt: fast gọi mã nhị phân Tesseract gốc, trong khi balanced và best sử dụng JSONL dispatcher liên tục chuyên dụng được ghim vào thế hệ RapidOCR bất biến đang hoạt động trong /data/ai/v3. Mỗi yêu cầu chứa một generation lease. Trong quá trình nâng cấp, SnapOtter chạy smoke test trên ứng viên trước khi kích hoạt, chuyển nguyên tử sang dispatcher mới, sau đó loại bỏ thế hệ cũ trước garbage collection.

NVIDIA CUDA được tự động phát hiện và sử dụng bởi các thời gian chạy hỗ trợ nó. OCR sử dụng CPU trên mọi máy chủ, bao gồm cả các hệ thống có GPU NVIDIA, tránh CUDA và khớp nối trình điều khiển cho công cụ này.

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.

::: info Khả năng tương thích OCR tiếng Hàn OCR Nhanh hỗ trợ auto, en, de, es, fr, zh và ja, nhưng không hỗ trợ tiếng Hàn (ko). Tiếng Hàn cần gói OCR Chính xác và balanced hoặc best. Gói chạy trên container Linux amd64 và arm64 chính thức, kể cả máy chủ NVIDIA nơi OCR vẫn chạy bằng CPU. Hệ thống không được hỗ trợ sẽ trả về lỗi tương thích rõ ràng và không âm thầm chuyển về fast. Tiếng Hàn với fast hoặc bí danh cũ tesseract bị từ chối trước khi xếp hàng với FEATURE_INCOMPATIBLE và fast-korean-unsupported. :::

Kiến trúc

Node.js Tool Route
      |
      v
 @snapotter/ai bridge.ts
      | (stdin/stdout JSON + stderr progress events)
      v
 +-- Native Tesseract + Ghostscript (fast image/PDF OCR)
 |
 +-- Isolated OCR runtime (persistent JSONL dispatcher)
 |     `-- RapidOCR + ONNX Runtime CPU + pinned PP-OCR models
 |
 `-- Python dispatcher (persistent process, "ai" profile)
      |
      |-- remove_bg.py        (rembg / BiRefNet)
      |-- upscale.py          (RealESRGAN)
      |-- inpaint.py          (LaMa ONNX)
      |-- outpaint.py         (LaMa canvas expansion)
      |-- 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

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 đó.

Hầu hết các công cụ AI đều yêu cầu một hoặc nhiều gói tính năng trước khi chúng có thể chạy. Giao diện người dùng quản trị viên cài đặt chúng theo công cụ thông qua POST /api/v1/admin/tools/:toolId/features/install, giải quyết danh sách gói đầy đủ, bỏ qua các gói đã được cài đặt và chỉ xếp hàng các bản tải xuống bị thiếu. Ví dụ: bật Ảnh hộ chiếu trên hàng đợi phiên bản mới background-removal và face-detection; kích hoạt nó sau khi loại bỏ nền đã được cài đặt chỉ xếp hàng face-detection. OCR là ngoại lệ vì fast không cần gói; cài đặt thời gian chạy chính xác tùy chọn thông qua UI hoặc POST /api/v1/admin/features/ocr/install.

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	~208-234 Tải xuống MiB / ~409-488 MiB đã cài đặt	Tùy chọn RapidOCR 3.9.1, ONNX Runtime 1.20.1 và các mẫu PP-OCR được ghim	ocr, ocr-pdf (chỉ balanced và best)
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ả các gói yêu cầu của nó được cài đặt, ngoại trừ OCR: tầng fast tích hợp của nó vẫn khả dụng mà không cần gói OCR tùy chọn. Các lượt 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 đặt được sử dụng lại, các gói bị thiếu được hiển thị dưới dạng tải xuống và các lượt cài đặt trong hàng đợi chạy lần lượt để môi trường Python dùng chung không bị sửa đổi đồng thời.

Cài đặt thời gian chạy OCR chính xác

Gói OCR chính xác là thời gian chạy dành riêng cho nền tảng cho vùng chứa Linux amd64 hoặc Linux arm64 chính thức. Bản dựng amd64 sử dụng Python 3.12; bản dựng arm64 sử dụng Python 3.11. Cả hai bản dựng đều chạy RapidOCR thông qua CPUExecutionProvider của ONNX Runtime, do đó, gói tương tự chỉ hoạt động trên các máy chủ chỉ dành cho CPU và NVIDIA Docker. Thời gian chạy chính xác yêu cầu ít nhất 4 GiB bộ nhớ hiệu dụng: giới hạn cgroup của vùng chứa được định cấu hình, nếu không thì bộ nhớ máy chủ. Hệ thống có mức độ tương thích tối thiểu đã được ký sẽ bị từ chối trước khi tải xuống. Yêu cầu này không áp dụng cho OCR nhanh được tích hợp sẵn. Các bản dựng Bare-metal bị từ chối vì libc và Python ABI của chúng không thể được suy ra một cách an toàn; OCR nhanh vẫn khả dụng khi máy chủ cung cấp Tesseract và Ghostscript.

Tạo phẩm tùy chọn có khoảng 208-234 MiB được nén và 409-488 MiB được trích xuất, tùy thuộc vào kiến ​​trúc. Chỉ mục đã ký liên kết số byte được nén và trích xuất chính xác được thực thi bởi trình cài đặt. Tesseract tích hợp thêm khoảng 25 MiB vào hình ảnh chính thức và không cần tệp trong /data/ai.

Cài đặt trực tuyến tìm nạp chỉ mục phát hành đã ký và tạo phẩm có địa chỉ nội dung chính xác cho nền tảng hiện tại. SnapOtter xác minh chữ ký chỉ mục Ed25519, kích thước tạo phẩm, thông báo SHA-256, thông báo mô hình, đường dẫn, chế độ tệp và smoke test theo giai đoạn trước khi kích hoạt thế hệ mới một cách nguyên tử. Cài đặt không thành công sẽ khiến thế hệ khỏe mạnh trước đó hoạt động.

Để cài đặt air-gapped, hãy tải cả ocr-runtime-index.json của bản phát hành và kho lưu trữ thời gian chạy OCR phù hợp lên POST /api/v1/admin/features/import bằng cách sử dụng các trường nhiều phần có tên index và archive. Nhập ngoại tuyến áp dụng các kiểm tra chữ ký, hàm băm, trích xuất, tính tương thích và kiểm tra khói giống như cài đặt trực tuyến; một kho lưu trữ không có chỉ mục được ký đáng tin cậy sẽ bị từ chối.

---

Xóa nền

Đườ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

Đườ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

Đườ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

Đườ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

Đường dẫn công cụ: ocr
Mẫu mã: Tesseract (fast); RapidOCR với các mẫu nhỏ PP-OCRv6 (balanced); Các mô hình trung bình PP-OCRv6 có tính năng chấm điểm biến thể đã hiệu chỉnh (best)

Tham số	Kiểu	Mặc định	Mô tả
quality	"fast" | "balanced" | "best"	Năng động	Khi bỏ qua quality và engine, SnapOtter chọn cấp tốt nhất hiện có theo thứ tự best, balanced, fast. Với tiếng Hàn, hệ thống không bao giờ chọn fast; hệ thống dùng best, sau đó balanced, hoặc trả về lỗi cài đặt hay tương thích của runtime chính xác.
language	string	"auto"	Ngôn ngữ: auto, en, de, fr, es, zh, ja, ko
enhance	boolean	Phụ thuộc vào cấp bậc	Cải thiện độ tương phản cục bộ Nhanh chóng áp dụng nó trực tiếp; các cấp chính xác chỉ giữ lại biến thể khi tính điểm đã hiệu chỉnh cải thiện OCR. Bật mặc định cho Tốt nhất
engine	sợi dây	-	Bí danh tương thích không được dùng nữa. Ánh xạ tesseract tới fast và giá trị paddleocr kế thừa thành balanced; nó không tải PaddlePaddle

Trả về văn bản được trích xuất cùng với siêu dữ liệu xuất xứ: công cụ, chất lượng thực tế và được yêu cầu, thiết bị, nhà cung cấp, trạng thái xuống cấp, cảnh báo và phiên bản mô hình/thời gian chạy chính xác khi có thể. Yêu cầu chất lượng rõ ràng không bao giờ rơi vào cấp độ khác. Nếu balanced hoặc best không khả dụng thì API trả về FEATURE_NOT_INSTALLED hoặc FEATURE_INCOMPATIBLE thay vì chạy fast âm thầm.

OCR PDF

Đườ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"	Năng động	Khi bỏ qua quality và engine, SnapOtter chọn cấp tốt nhất hiện có theo thứ tự best, balanced, fast. Với tiếng Hàn, hệ thống không bao giờ chọn fast; hệ thống dùng best, sau đó balanced, hoặc trả về lỗi cài đặt hay tương thích của runtime chính xác.
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"
enhance	boolean	Phụ thuộc vào cấp bậc	Cải thiện độ tương phản cục bộ Nhanh chóng áp dụng nó trực tiếp; các cấp chính xác chỉ giữ lại biến thể khi tính điểm đã hiệu chỉnh cải thiện OCR. Bật mặc định cho Tốt nhất
engine	sợi dây	-	Bí danh tương thích không được dùng nữa. Ánh xạ tesseract tới fast và giá trị paddleocr kế thừa thành balanced; nó không tải PaddlePaddle

Quy tắc không hạ cấp tương tự áp dụng cho PDF OCR. Các trang PDF được rasterized trước khi nhận dạng và một yêu cầu có thể chọn tối đa 50 trang.

Làm mờ khuôn mặt / PII

Đườ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

Đườ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

Đườ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

Đườ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 đỏ

Đườ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

Đườ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

Đườ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

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

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)

Đườ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

Đườ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

Đườ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

Đườ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

Đườ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

Đườ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ị)

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

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

Đườ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)

Đườ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