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

description, i18n_output_hash, i18n_source_hash, i18n_provenance

description	i18n_output_hash	i18n_source_hash	i18n_provenance
모든 로컬 ML 도구를 다루는 AI 엔진 레퍼런스. 배경 제거, 업스케일링, OCR, 얼굴 감지, 사진 복원 등.	534278b9910c	aa9a56cdddc7	human

AI 엔진 레퍼런스

@snapotter/ai 패키지는 로컬 ML 작업을 위해 기본 도구와 Python 런타임을 조정합니다. 대부분의 ML 도구는 빠른 웜 스타트를 위해 영구 Python sidecar 를 사용합니다. OCR 는 의도적으로 분리되어 있습니다. fast는 기본 Tesseract 바이너리를 호출하는 반면, balanced 및 best는 /data/ai/v3 아래의 활성 불변 RapidOCR 세대에 고정된 전용 영구 JSONL dispatcher 를 사용합니다. 각 요청에는 generation lease 가 포함됩니다. 업그레이드 중에 SnapOtter 는 활성화하기 전에 후보에서 smoke test 를 실행하고 새로운 dispatcher 로 원자적으로 전환한 다음 garbage collection 이전의 이전 세대를 제거합니다.

NVIDIA CUDA 는 이를 지원하는 런타임에서 자동 감지되고 사용됩니다. OCR 는 NVIDIA GPU가 있는 시스템을 포함하여 모든 호스트에서 CPU 를 사용하여 이 도구에 대한 CUDA 및 드라이버 결합을 방지합니다.

VA-API, Quick Sync, OpenCL을 통한 Intel/AMD iGPU 가속은 현재 AI 추론에 지원되지 않는다. CUDA를 지원하는 NVIDIA GPU가 없는 한, 컨테이너에 /dev/dri를 매핑해도 이러한 Python 사이드카 도구는 가속되지 않는다.

네 가지 모달리티(이미지, 오디오, 비디오, 문서)에 걸쳐 19개의 Python 사이드카 AI 도구가 있으며, 여기에 선택적 AI 기능을 갖춘 2개의 도구가 추가된다. 모든 모델은 로컬에서 실행되며, 최초 모델 다운로드 이후에는 인터넷이 필요하지 않다.

::: info 한국어 OCR 호환성 빠른 OCR은 auto, en, de, es, fr, zh, ja를 지원하지만 한국어(ko)는 지원하지 않습니다. 한국어에는 정확한 OCR 팩과 balanced 또는 best가 필요합니다. 이 팩은 공식 Linux amd64 및 arm64 컨테이너에서 작동하며 NVIDIA 호스트에서도 OCR은 CPU에서 실행됩니다. 지원되지 않는 시스템은 명시적인 호환성 오류를 반환하며 조용히 fast로 대체하지 않습니다. 한국어에 fast 또는 이전 tesseract 별칭을 지정하면 큐에 넣기 전에 FEATURE_INCOMPATIBLE 및 fast-korean-unsupported로 거부됩니다. :::

아키텍처

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)

별도의 "docs" 디스패처 프로파일은 AI 허용 목록을 문서 처리 스크립트(doc_pagecount, doc_health, doc_flatten, doc_redact, doc_text, doc_to_word, doc_metadata, doc_html_pdf)로 대체하고 무거운 ML 임포트를 건너뛴다.

타임아웃: 기본 300초. OCR과 BiRefNet 배경 제거는 600초가 주어진다.

기능 번들

AI 모델은 도구별로 아카이브 하나씩이 아니라 공유 의존성 스택 단위로 패키징된다. 하나의 기능 번들은 여러 도구가 동일한 모델 계열, Python 휠, 또는 네이티브 라이브러리를 사용할 때 그 도구들을 함께 활성화할 수 있다. 이렇게 하면 릴리스 Docker 이미지가 더 작게 유지되고, 동일한 배경 매팅, 얼굴 감지, OCR, 복원, 음성 모델의 중복 사본을 저장하는 일을 피할 수 있다.

Docker 이미지는 애플리케이션과 공통 런타임을 함께 제공한다. 대용량 모델 아카이브는 필요할 때 상시 유지되는 /data/ai 볼륨으로 다운로드된 뒤, 이를 필요로 하는 모든 도구가 재사용한다. 다른 도구가 이미 필요로 해서 어떤 번들이 이미 설치되어 있다면, 새로 의존하는 도구를 활성화해도 그 번들을 다시 다운로드하지 않는다.

대부분의 AI 도구를 실행하려면 하나 이상의 기능 번들이 필요합니다. 관리 UI는 전체 번들 목록을 확인하고 이미 설치된 번들을 건너뛰며 누락된 다운로드만 대기열에 추가하는 POST /api/v1/admin/tools/:toolId/features/install를 통해 도구로 해당 항목을 설치합니다. 예를 들어, 새로운 인스턴스 큐 background-removal 및 face-detection에서 여권 사진을 활성화합니다. 백그라운드 제거가 이미 설치된 후에 활성화하면 face-detection만 대기열에 추가됩니다. OCR 는 예외입니다. fast에는 팩이 필요하지 않기 때문입니다. UI 또는 POST /api/v1/admin/features/ocr/install를 통해 선택적 정확한 런타임을 설치합니다.

번들	크기	공유 의존성 그룹	사용하는 도구
background-removal	4-5 GB	rembg / BiRefNet 배경 매팅	remove-background, passport-photo, transparency-fixer, background-replace, blur-background
face-detection	200-300 MB	MediaPipe 얼굴 감지 및 랜드마크	blur-faces, red-eye-removal, smart-crop
object-eraser-colorize	1-2 GB	LaMa 인페인팅/아웃페인팅 및 DDColor	erase-object, colorize, ai-canvas-expand
upscale-enhance	5-6 GB	RealESRGAN, GFPGAN / CodeFormer, 노이즈 제거	upscale, enhance-faces, noise-removal
photo-restoration	4-5 GB	스크래치 복구 및 복원 파이프라인	restore-photo
ocr	~208-234 MiB 다운로드 / ~409-488 MiB 설치됨	옵션 RapidOCR 3.9.1, ONNX Runtime 1.20.1 및 고정형 PP-OCR 모델	ocr, ocr-pdf(balanced 및 best에만 해당)
transcription	~600 MB	faster-whisper 음성-텍스트 변환 모델	transcribe-audio, auto-subtitles

교차 번들 의존성을 갖는 도구:

도구	필요한 번들	이유
passport-photo	background-removal, face-detection	배경을 제거한 뒤, 얼굴 랜드마크를 사용해 여권 및 신분증 사진 규정에 맞게 크롭 구도를 잡는다.
enhance-faces	upscale-enhance, face-detection	선택된 얼굴 영역에 GFPGAN 또는 CodeFormer 보정을 적용하기 전에 얼굴을 감지한다.

도구는 OCR 를 제외하고 모든 필수 번들이 설치된 경우에만 사용할 수 있습니다. 내장된 fast 계층은 선택적 OCR 팩 없이도 계속 사용할 수 있습니다. 부분 설치는 유효하며 증분적으로 처리됩니다. 설치된 번들은 재사용되고, 누락된 번들은 다운로드로 표시되며, 대기 중인 설치는 한 번에 하나씩 실행되므로 공유 Python 환경이 동시에 수정되지 않습니다.

정확한 OCR 런타임 설치

정확한 OCR 팩은 공식 Linux amd64 또는 Linux arm64 컨테이너를 위한 플랫폼별 런타임입니다. amd64 빌드는 Python 3.12를 사용하고 arm64 빌드는 Python 3.11을 사용합니다. 두 빌드 모두 ONNX Runtime의 CPUExecutionProvider를 통해 RapidOCR를 실행하므로 동일한 팩이 CPU 전용 및 NVIDIA Docker 호스트에서 작동합니다. 정확한 런타임에는 최소 4 GiB의 유효 메모리(구성된 컨테이너 cgroup 제한, 없으면 호스트 메모리)가 필요합니다. 서명된 호환성 최소값 미만의 시스템은 다운로드 전에 거부됩니다. 이 요구 사항은 내장 Fast OCR에는 적용되지 않습니다. Bare-metal 빌드는 libc 및 Python ABI를 안전하게 추론할 수 없으므로 거부됩니다. 호스트가 Tesseract와 Ghostscript를 제공하면 Fast OCR는 계속 사용할 수 있습니다.

선택적 아티팩트는 아키텍처에 따라 약 208-234 MiB 압축 및 409-488 MiB 추출입니다. 서명된 인덱스는 설치 프로그램에서 적용한 정확한 압축 및 추출 바이트 수를 바인딩합니다. 내장된 Tesseract 는 공식 이미지에 약 25개의 MiB 를 추가하며 /data/ai에는 파일이 필요하지 않습니다.

온라인 설치는 현재 플랫폼에 대한 서명된 릴리스 색인과 정확한 콘텐츠 주소 지정 아티팩트를 가져옵니다. SnapOtter 는 새로운 세대를 원자적으로 활성화하기 전에 Ed25519 인덱스 서명, 아티팩트 크기, SHA-256 다이제스트, 모델 다이제스트, 경로, 파일 모드 및 스테이지된 smoke test 를 확인합니다. 설치가 실패하면 이전 정상 세대가 활성 상태로 유지됩니다.

에어갭 설치의 경우 index 및 archive라는 다중 부분 필드를 사용하여 릴리스의 ocr-runtime-index.json 및 일치하는 OCR 런타임 아카이브를 모두 POST /api/v1/admin/features/import에 업로드합니다. 오프라인 가져오기는 온라인 설치와 동일한 서명, 해시, 추출, 호환성 및 스모크 테스트 검사를 적용합니다. 신뢰할 수 있는 서명된 인덱스가 없는 아카이브는 거부됩니다.

---

배경 제거

도구 경로: remove-background
모델: rembg with BiRefNet (기본값) 또는 U2-Net 변형

매개변수	타입	기본값	설명
model	string	-	모델 변형 (선택적 재정의)
backgroundType	string	"transparent"	다음 중 하나: transparent, color, gradient, blur, image
backgroundColor	string	-	단색 배경용 Hex 색상
gradientColor1	string	-	첫 번째 그라디언트 색상
gradientColor2	string	-	두 번째 그라디언트 색상
gradientAngle	number	-	그라디언트 각도(도 단위)
blurEnabled	boolean	-	배경 블러 효과 활성화
blurIntensity	number (0-100)	-	블러 강도
shadowEnabled	boolean	-	피사체에 드롭 섀도 활성화
shadowOpacity	number (0-100)	-	그림자 불투명도
outputFormat	string	-	출력 형식: png, webp, 또는 avif
edgeRefine	integer (0-3)	-	가장자리 정제 수준
decontaminate	boolean	-	가장자리의 색상 번짐 제거

배경 교체

도구 경로: background-replace
모델: rembg / BiRefNet (remove-background와 공유)

배경을 제거하고 단색 또는 그라디언트로 교체한다.

매개변수	타입	기본값	설명
backgroundType	"color" | "gradient"	"color"	배경 모드
color	string	"#ffffff"	배경 hex 색상 (backgroundType이 color일 때)
gradientColor1	string	-	첫 번째 그라디언트 hex 색상
gradientColor2	string	-	두 번째 그라디언트 hex 색상
gradientAngle	integer (0-360)	180	그라디언트 각도(도 단위)
feather	integer (0-20)	0	가장자리 페더링 반경
format	"png" | "webp"	"png"	출력 형식

배경 블러

도구 경로: blur-background
모델: rembg / BiRefNet (remove-background와 공유)

피사체는 선명하게 유지하면서 배경을 흐리게 만든다.

매개변수	타입	기본값	설명
intensity	integer (1-100)	50	블러 강도
feather	integer (0-20)	0	가장자리 페더링 반경
format	"png" | "webp"	"png"	출력 형식

이미지 업스케일링

도구 경로: upscale
모델: RealESRGAN (사용 불가 시 Lanczos 폴백)

매개변수	타입	기본값	설명
scale	number	2	업스케일 배율
model	string	"auto"	모델 변형
faceEnhance	boolean	false	GFPGAN 얼굴 보정 패스 적용
denoise	number	0	노이즈 제거 강도
format	string	"auto"	출력 형식 재정의
quality	number	95	출력 품질 (1-100)

OCR / 텍스트 추출

도구 경로: ocr
모델: Tesseract(fast); RapidOCR(PP-OCRv6 소형 모델 포함)(balanced); 보정된 변형 점수가 포함된 PP-OCRv6 중형 모델(best)

매개변수	타입	기본값	설명
quality	"fast" | "balanced" | "best"	동적	quality와 engine을 생략하면 SnapOtter는 best, balanced, fast 순으로 사용 가능한 최상위 등급을 선택합니다. 한국어에서는 fast를 선택하지 않으며 best, 그다음 balanced를 사용하고, 둘 다 없으면 정확한 런타임의 설치 또는 호환성 오류를 반환합니다.
language	string	"auto"	언어: auto, en, de, fr, es, zh, ja, ko
enhance	부울	계층에 따라 다름	로컬 대비를 향상시킵니다. 빠르게 직접 적용합니다. 정확한 계층은 보정된 점수가 OCR 를 향상시키는 경우에만 변형을 유지합니다. 최고에 대한 기본값은 켜져 있습니다.
engine	끈	-	더 이상 사용되지 않는 호환성 별칭입니다. tesseract를 fast에 매핑하고 레거시 paddleocr 값을 balanced에 매핑합니다. PaddlePaddle 를 로드하지 않습니다.

추출된 텍스트와 출처 메타데이터(엔진, 요청 및 실제 품질, 장치, 공급자, 성능 저하 상태, 경고, 해당되는 경우 정확한 런타임/모델 버전)를 반환합니다. 명시적인 품질 요청은 다른 계층으로 돌아가지 않습니다. balanced 또는 best를 사용할 수 없는 경우 API 는 fast를 자동으로 실행하는 대신 FEATURE_NOT_INSTALLED 또는 FEATURE_INCOMPATIBLE를 반환합니다.

PDF OCR

도구 경로: ocr-pdf
모델: 이미지 OCR와 동일한 등급 체계

AI 기반 OCR을 사용해 스캔된 PDF 문서에서 페이지별로 텍스트를 추출한다.

매개변수	타입	기본값	설명
quality	"fast" | "balanced" | "best"	동적	quality와 engine을 생략하면 SnapOtter는 best, balanced, fast 순으로 사용 가능한 최상위 등급을 선택합니다. 한국어에서는 fast를 선택하지 않으며 best, 그다음 balanced를 사용하고, 둘 다 없으면 정확한 런타임의 설치 또는 호환성 오류를 반환합니다.
language	string	"auto"	언어: auto, en, de, fr, es, zh, ja, ko
pages	string	"all"	페이지 선택: "all", "1-3", "1,3,5"
enhance	부울	계층에 따라 다름	로컬 대비를 향상시킵니다. 빠르게 직접 적용합니다. 정확한 계층은 보정된 점수가 OCR 를 향상시키는 경우에만 변형을 유지합니다. 최고에 대한 기본값은 켜져 있습니다.
engine	끈	-	더 이상 사용되지 않는 호환성 별칭입니다. tesseract를 fast에 매핑하고 레거시 paddleocr 값을 balanced에 매핑합니다. PaddlePaddle 를 로드하지 않습니다.

PDF OCR 에도 동일한 다운그레이드 금지 규칙이 적용됩니다. PDF 페이지는 인식되기 전에 래스터화되며, 한 요청으로 최대 50페이지를 선택할 수 있습니다.

얼굴 / PII 블러

도구 경로: blur-faces
모델: MediaPipe 얼굴 감지

매개변수	타입	기본값	설명
blurRadius	number (1-100)	30	가우시안 블러 반경
sensitivity	number (0-1)	0.5	감지 신뢰도 임계값

얼굴 보정

도구 경로: enhance-faces
모델: GFPGAN, CodeFormer

매개변수	타입	기본값	설명
model	"auto" | "gfpgan" | "codeformer"	"auto"	보정 모델
strength	number (0-1)	0.8	보정 강도
sensitivity	number (0-1)	0.5	얼굴 감지 임계값
onlyCenterFace	boolean	false	가장 중앙에 있는 얼굴만 보정

AI 컬러화

도구 경로: colorize
모델: DDColor (OpenCV DNN 폴백)

흑백 또는 그레이스케일 사진을 풀컬러로 변환한다.

매개변수	타입	기본값	설명
intensity	number (0-1)	1.0	색상 채도 강도
model	"auto" | "ddcolor" | "opencv"	"auto"	모델 변형

노이즈 제거

도구 경로: noise-removal
모델: SCUNet (등급형 노이즈 제거 파이프라인)

매개변수	타입	기본값	설명
tier	"quick" | "balanced" | "quality" | "maximum"	"balanced"	처리 등급
strength	number (0-100)	50	노이즈 제거 강도
detailPreservation	number (0-100)	50	보존할 디테일 정도. 높을수록 텍스처가 더 많이 유지됨
colorNoise	number (0-100)	30	컬러 노이즈 감소 강도
format	string	"original"	출력 형식: original, png, jpeg, webp, avif, jxl
quality	number (1-100)	90	출력 인코딩 품질

적목 현상 제거

도구 경로: red-eye-removal

얼굴 랜드마크를 감지하고 눈 영역을 찾아 적색 채널 과포화를 보정한다.

매개변수	타입	기본값	설명
sensitivity	number (0-100)	50	적색 픽셀 감지 임계값
strength	number (0-100)	70	보정 강도
format	string	-	출력 형식 재정의 (선택 사항)
quality	number (1-100)	90	출력 품질

사진 복원

도구 경로: restore-photo

오래되거나 손상된 사진을 위한 다단계 파이프라인: 스크래치/찢김 감지 및 복구, 얼굴 보정, 노이즈 제거, 그리고 선택적 컬러화.

매개변수	타입	기본값	설명
scratchRemoval	boolean	true	스크래치, 찢김 감지 및 복구
faceEnhancement	boolean	true	얼굴 보정 패스 적용
fidelity	number (0-1)	0.7	얼굴 보정 강도 (높을수록 더 보수적)
denoise	boolean	true	노이즈 제거 패스 적용
denoiseStrength	number (0-100)	25	노이즈 제거 강도
colorize	boolean	false	복원 후 컬러화
colorizeStrength	number (0-100)	85	컬러화 강도

여권 사진

도구 경로: passport-photo
모델: MediaPipe 얼굴 랜드마크 + BiRefNet 배경 제거

두 단계 워크플로: 분석(얼굴 감지 + 배경 제거) 후 생성(크롭, 크기 조정, 타일 배치). 6개 지역에 걸쳐 37개 이상의 국가를 지원한다.

1단계: 분석

POST /api/v1/tools/image/passport-photo/analyze

이미지 파일(multipart)을 받는다. 얼굴 랜드마크 데이터, base64 미리보기, 이미지 치수를 반환한다.

2단계: 생성

POST /api/v1/tools/image/passport-photo/generate

1단계 결과와 생성 설정이 담긴 JSON 본문을 받는다:

매개변수	타입	기본값	설명
jobId	string	(필수)	1단계의 작업 ID
filename	string	(필수)	1단계의 원본 파일 이름
countryCode	string	(필수)	ISO 국가 코드 (예: US, GB, IN)
documentType	string	"passport"	문서 유형
bgColor	string	"#FFFFFF"	배경 색상 hex
printLayout	string	"none"	인쇄 레이아웃: none, 4x6, a4, letter
maxFileSizeKb	number	0	최대 파일 크기(KB) (0 = 제한 없음)
dpi	number (72-1200)	300	출력 DPI
customWidthMm	number	-	사용자 지정 너비(mm) (국가 사양을 재정의)
customHeightMm	number	-	사용자 지정 높이(mm) (국가 사양을 재정의)
zoom	number (0.5-3)	1	줌 배율
adjustX	number	0	수평 위치 조정
adjustY	number	0	수직 위치 조정
landmarks	object	(필수)	1단계의 랜드마크
imageWidth	number	(필수)	1단계의 이미지 너비
imageHeight	number	(필수)	1단계의 이미지 높이

객체 지우기 (인페인팅)

도구 경로: erase-object
모델: ONNX Runtime을 통한 LaMa

마스크는 base64가 아니라 두 번째 파일 파트(fieldname mask)로 전송된다. 마스크에서 흰색 픽셀은 지울 영역을 나타낸다. format와 quality 설정은 최상위 폼 필드로 전송된다.

매개변수	타입	기본값	설명
file	file	(필수)	원본 이미지 (multipart)
mask	file	(필수)	마스크 이미지 (multipart, fieldname mask, 흰색 = 지우기)
format	string	"auto"	출력 형식: auto, png, jpg, jpeg, webp, tiff, gif, avif, heic, heif, jxl
quality	integer (1-100)	95	출력 품질

NVIDIA GPU가 있을 때 CUDA 가속된다.

AI 캔버스 확장

도구 경로: ai-canvas-expand
모델: LaMa 기반 아웃페인팅

이미지의 캔버스를 어느 방향으로든 확장하고, 새 영역을 기존 이미지와 어울리는 AI 생성 콘텐츠로 채운다.

매개변수	타입	기본값	설명
extendTop	integer	0	위쪽으로 확장할 픽셀
extendRight	integer	0	오른쪽으로 확장할 픽셀
extendBottom	integer	0	아래쪽으로 확장할 픽셀
extendLeft	integer	0	왼쪽으로 확장할 픽셀
tier	"fast" | "balanced" | "high"	"balanced"	품질 등급
format	string	"auto"	출력 형식: auto, png, jpg, jpeg, webp, tiff, gif, avif, heic, heif, jxl
quality	integer (1-100)	95	출력 품질

확장 방향 중 하나 이상이 0보다 커야 한다.

스마트 크롭

도구 경로: smart-crop
모델: MediaPipe 얼굴 감지 (얼굴 모드 전용)

매개변수	타입	기본값	설명
mode	string	"subject"	크롭 전략: subject, face, trim
strategy	"attention" | "entropy"	"attention"	피사체 모드 전략
width	integer	-	출력 너비
height	integer	-	출력 높이
padding	integer (0-50)	0	피사체 주변 여백 백분율
facePreset	string	"head-shoulders"	mode=face일 때의 프리셋 구도
sensitivity	number (0-1)	0.5	얼굴 감지 임계값
threshold	integer (0-255)	30	배경 감지 임계값 (트림 모드)
padToSquare	boolean	false	트림된 결과를 정사각형으로 패딩
padColor	string	"#ffffff"	정사각형 패딩용 배경 색상
targetSize	integer	-	패딩된 출력의 목표 크기(픽셀)
quality	integer (1-100)	-	출력 품질

레거시 mode 값 attention와 content은 허용되며 각각 subject와 trim로 매핑된다.

얼굴 프리셋:

프리셋	적합한 용도
closeup	헤드샷
head-shoulders	프로필 사진
upper-body	LinkedIn / 격식 있는 용도
half-body	상반신 전체

오디오 전사

도구 경로: transcribe-audio
모델: faster-whisper

음성을 텍스트로 변환한다. 일반 텍스트, SRT, VTT 출력 형식을 지원한다.

매개변수	타입	기본값	설명
language	string	"auto"	언어: auto, en, de, fr, es, zh, ja, ko, id, th, vi
outputFormat	"txt" | "srt" | "vtt"	"txt"	출력 형식

자동 자막

도구 경로: auto-subtitles
모델: faster-whisper (비디오에서 오디오를 추출한 뒤 전사)

비디오의 오디오 트랙에서 자막 파일을 생성한다.

매개변수	타입	기본값	설명
language	string	"auto"	언어: auto, en, de, fr, es, zh, ja, ko, id, th, vi
format	"srt" | "vtt"	"srt"	출력 자막 형식

PNG 투명도 수정

도구 경로: transparency-fixer
모델: BiRefNet HR-매팅 (2048x2048 해상도)

배경은 제거되었지만 프린징, 헤일로, 반투명 아티팩트가 남은 "가짜 투명" PNG를 수정한다. BiRefNet의 고해상도 매팅 모델을 사용해 깨끗한 알파 채널을 만든 다음, 구성 가능한 디프린지 처리를 적용해 가장자리를 따라 남은 색상 오염을 제거한다.

OOM 폴백 체인: BiRefNet HR-매팅이 가용 메모리를 초과하면, 도구는 자동으로 birefnet-general로, 그다음 u2net로 폴백한다.

매개변수	타입	기본값	설명
defringe	number (0-100)	30	색상 오염을 제거하는 가장자리 디프린지 강도
outputFormat	"png" | "webp"	"png"	출력 이미지 형식
removeWatermark	boolean	false	워터마크 제거 사전 처리 적용 (미디안 필터)

curl -X POST http://localhost:1349/api/v1/tools/image/transparency-fixer \
  -H "Authorization: Bearer <token>" \
  -F "file=@fake-transparent.png" \
  -F 'settings={"defringe":30,"outputFormat":"png"}'

---

선택적 AI 기능을 갖춘 도구

다음 도구는 Python 사이드카 도구는 아니지만 특정 옵션이 활성화되면 AI 기능을 사용한다.

이미지 향상

도구 경로: image-enhancement
엔진: 분석 기반 (Sharp 히스토그램 및 통계)

이미지를 분석하여 노출, 대비, 화이트 밸런스, 채도, 선명도, 노이즈에 대한 자동 보정을 적용한다. 장면별 모드를 지원한다.

매개변수	타입	기본값	설명
mode	"auto" | "portrait" | "landscape" | "low-light" | "food" | "document"	"auto"	보정 튜닝용 장면 모드
intensity	number (0-100)	50	전체 보정 강도
corrections.exposure	boolean	true	노출 보정 적용
corrections.contrast	boolean	true	대비 보정 적용
corrections.whiteBalance	boolean	true	화이트 밸런스 보정 적용
corrections.saturation	boolean	true	채도 보정 적용
corrections.sharpness	boolean	true	선명도 보정 적용
corrections.denoise	boolean	true	노이즈 제거 적용
deepEnhance	boolean	false	SCUNet을 통한 AI 노이즈 제거 활성화 (upscale-enhance 번들 필요)

적용하지 않고 감지된 보정만 반환하는 추가 분석 엔드포인트를 POST /api/v1/tools/image/image-enhancement/analyze에서 사용할 수 있다.

콘텐츠 인식 크기 조정 (심 카빙)

도구 경로: content-aware-resize
엔진: Go caire 바이너리 (Python이 아니므로 GPU 이점 없음)

저에너지 심을 제거하여 중요한 콘텐츠를 보존하면서 이미지 크기를 지능적으로 조정한다.

매개변수	타입	기본값	설명
width	number	-	목표 너비
height	number	-	목표 높이
protectFaces	boolean	false	감지된 얼굴 영역 보호 (face-detection 번들 필요)
blurRadius	number (0-20)	4	에너지 계산을 위한 사전 블러
sobelThreshold	number (1-20)	2	가장자리 민감도 임계값
square	boolean	false	정사각형 출력 강제