SnapOtter/apps/docs/th/api/rest.md

description, i18n_output_hash, i18n_source_hash, i18n_provenance

description	i18n_output_hash	i18n_source_hash	i18n_provenance
เอกสารอ้างอิง REST API ฉบับสมบูรณ์ เอนด์พอยต์ของเครื่องมือ การประมวลผลแบบแบตช์ ไปป์ไลน์ คลังไฟล์ การยืนยันตัวตน ทีม และการดำเนินงานของผู้ดูแลระบบ	34c52fe6305e	b89b5df16af5	human

เอกสารอ้างอิง REST API

เอกสาร API แบบโต้ตอบพร้อมตัวอย่างคำขอและการตอบกลับมีให้ใช้งานที่ http://localhost:1349/api/docs

สเปกแบบเครื่องอ่านได้:

• /api/v1/openapi.yaml - สเปก OpenAPI 3.1
• /llms.txt - สรุปที่เป็นมิตรกับ LLM
• /llms-full.txt - เอกสารฉบับสมบูรณ์ที่เป็นมิตรกับ LLM

การยืนยันตัวตน

ทุกเอนด์พอยต์ต้องมีการยืนยันตัวตน เว้นแต่ AUTH_ENABLED=false

โทเคนเซสชัน

# Login
curl -X POST http://localhost:1349/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin"}'
# Returns: {"token":"<session-token>"}

# Use token
curl http://localhost:1349/api/v1/tools/image/resize \
  -H "Authorization: Bearer <session-token>"

เซสชันจะหมดอายุหลังจาก 7 วัน (กำหนดค่าได้ผ่าน SESSION_DURATION_HOURS)

API Keys

# Create a key (returns key once - store it)
curl -X POST http://localhost:1349/api/v1/api-keys \
  -H "Authorization: Bearer <session-token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-script"}'
# Returns: {"key":"si_<96 hex chars>","id":"...","name":"my-script"}

# Use the key
curl http://localhost:1349/api/v1/tools/image/resize \
  -H "Authorization: Bearer si_<your-key>"

คีย์จะมีคำนำหน้า si_ และจัดเก็บเป็นแฮชแบบ scrypt คีย์ดิบจะแสดงเพียงครั้งเดียวและไม่สามารถเรียกคืนได้อีก

เอนด์พอยต์การยืนยันตัวตน

Method	Path	สิทธิ์เข้าถึง	คำอธิบาย
POST	/api/auth/login	สาธารณะ	ลงชื่อเข้าใช้ รับโทเคนเซสชัน
POST	/api/auth/logout	ยืนยันตัวตน	ทำลายเซสชันปัจจุบัน
GET	/api/auth/session	ยืนยันตัวตน	ตรวจสอบเซสชันปัจจุบัน
POST	/api/auth/change-password	ยืนยันตัวตน	เปลี่ยนรหัสผ่านของตนเอง (ทำให้เซสชันอื่นทั้งหมด + API keys ใช้ไม่ได้)
GET	/api/auth/users	ผู้ดูแลระบบ	แสดงรายชื่อผู้ใช้ทั้งหมด
POST	/api/auth/register	ผู้ดูแลระบบ	สร้างผู้ใช้ใหม่
PUT	/api/auth/users/:id	ผู้ดูแลระบบ	อัปเดตบทบาทหรือทีมของผู้ใช้
POST	/api/auth/users/:id/reset-password	ผู้ดูแลระบบ	รีเซ็ตรหัสผ่านของผู้ใช้
DELETE	/api/auth/users/:id	ผู้ดูแลระบบ	ลบผู้ใช้
GET	/api/v1/config/auth	สาธารณะ	ตรวจสอบว่าเปิดใช้งานการยืนยันตัวตนอยู่หรือไม่ ({ authEnabled: bool })
POST	/api/auth/mfa/enroll	ยืนยันตัวตน	เริ่มการลงทะเบียน TOTP MFA ต้องใช้ฟีเจอร์ mfa ระดับ enterprise
POST	/api/auth/mfa/verify	ยืนยันตัวตน	ยืนยันการลงทะเบียน MFA ด้วยรหัส TOTP
POST	/api/auth/mfa/complete	สาธารณะ	ทำ MFA login challenge ที่ค้างอยู่ให้เสร็จสมบูรณ์
POST	/api/auth/mfa/disable	ยืนยันตัวตน	ปิดใช้งาน MFA สำหรับผู้ใช้ปัจจุบัน
POST	/api/auth/users/:id/mfa/reset	ผู้ดูแลระบบ (users:manage)	รีเซ็ต MFA สำหรับผู้ใช้
GET	/api/auth/oidc/login	สาธารณะ	เริ่มการลงชื่อเข้าใช้ OIDC เมื่อเปิดใช้งาน OIDC
GET	/api/auth/oidc/callback	สาธารณะ	callback การอนุญาตของ OIDC
GET	/api/auth/saml/metadata	สาธารณะ	XML เมทาดาทา SAML SP เมื่อเปิดใช้งาน SAML
GET	/api/auth/saml/login	สาธารณะ	เริ่มการลงชื่อเข้าใช้ SAML
POST	/api/auth/saml/callback	สาธารณะ	บริการ SAML assertion consumer

เมื่อเปิดใช้งาน MFA สำหรับผู้ใช้ POST /api/auth/login จะคืนค่า {"requiresMfa":true,"mfaToken":"...","mfaRequired":true|false} แทนโทเคนเซสชัน ส่ง mfaToken นั้นพร้อมรหัส TOTP หรือรหัสกู้คืนไปยัง /api/auth/mfa/complete

สิทธิ์

สิทธิ์	ผู้ดูแลระบบ	ผู้ใช้
ใช้เครื่องมือ	✓	✓
ไฟล์/ไปป์ไลน์/API keys ของตนเอง	✓	✓
ดูไฟล์/ไปป์ไลน์/คีย์ของผู้ใช้ทุกคน	✓	-
เขียนการตั้งค่า	✓	-
จัดการผู้ใช้และทีม	✓	-
จัดการแบรนด์	✓	-

การตรวจสอบสถานะ

Method	Path	สิทธิ์เข้าถึง	คำอธิบาย
GET	/api/v1/health	สาธารณะ	การตรวจสอบสถานะพื้นฐาน คืนค่า {"status":"healthy","version":"..."} พร้อม 200 หรือ {"status":"unhealthy"} พร้อม 503 หากไม่สามารถเข้าถึงฐานข้อมูลได้
GET	/api/v1/readyz	สาธารณะ	Readiness probe ตรวจสอบ PostgreSQL, Redis, พื้นที่ดิสก์ และ S3 เมื่อมีการกำหนดค่า คืนค่า 503 เมื่ออินสแตนซ์ไม่ควรรับทราฟฟิก
GET	/api/v1/admin/health	ผู้ดูแลระบบ (system:health)	การวินิจฉัยแบบละเอียด รวมถึง uptime, โหมดการจัดเก็บ, สถานะฐานข้อมูล, สถานะคิว และความพร้อมใช้งานของ GPU

การใช้เครื่องมือ

ทุกเครื่องมือใช้รูปแบบเดียวกัน:

# Single file
curl -X POST http://localhost:1349/api/v1/tools/<section>/<toolId> \
  -H "Authorization: Bearer <token>" \
  -F "file=@input.jpg" \
  -F 'settings={"width":800,"height":600}'

# Batch (returns ZIP)
curl -X POST http://localhost:1349/api/v1/tools/<section>/<toolId>/batch \
  -H "Authorization: Bearer <token>" \
  -F "files=@a.jpg" \
  -F "files=@b.jpg" \
  -F 'settings={...}'

<section> เป็นหนึ่งใน image, video, audio, pdf หรือ files

• การอัปโหลดคือ multipart/form-data
• settings เป็นสตริง JSON ที่มีตัวเลือกเฉพาะของเครื่องมือ
• clientJobId เป็นฟิลด์ฟอร์มที่ไม่บังคับสำหรับการเชื่อมโยงความคืบหน้าที่ผู้เรียกจัดเตรียมให้
• fileId เป็นฟิลด์ฟอร์มที่ไม่บังคับซึ่งอ้างอิงถึงรายการในคลังไฟล์ที่มีอยู่ เมื่อมีค่านี้ ผลลัพธ์ที่ประมวลผลแล้วจะถูกบันทึกเป็นเวอร์ชันใหม่ และการตอบกลับจะรวม savedFileId
• เครื่องมือแบบเร็ว โดยทั่วไปจะคืนค่า 200 JSON: {"jobId":"...","downloadUrl":"/api/v1/download/<jobId>/<filename>","originalSize":1234,"processedSize":567} ดึงไฟล์ที่ประมวลผลแล้วจาก downloadUrl
• เครื่องมือที่เข้าคิวใดๆ สามารถคืนค่า 202 JSON ได้หากทำงานนานหรือเกินหน้าต่างการรอแบบซิงโครนัส: {"jobId":"...","async":true} เชื่อมต่อกับ SSE เพื่อรับความคืบหน้า แล้วดาวน์โหลดเมื่อเสร็จสมบูรณ์ (ดู การติดตามความคืบหน้า)
• แบตช์ เส้นทางจะคืนค่าไฟล์บีบอัด ZIP แบบสตรีมโดยตรง (พร้อมส่วนหัว X-Job-Id) สำหรับเครื่องมือที่ลงทะเบียนใน generic batch registry

เอกสารอ้างอิงเครื่องมือ

พรีเซ็ตการแปลง

แคตตาล็อกที่ใช้ร่วมกันมีเอนด์พอยต์พรีเซ็ตการแปลงเฉพาะ 83 รายการ เช่น jpg-to-png, mov-to-mp4, m4a-to-mp3, pdf-to-jpg และ excel-to-csv พรีเซ็ตเป็นเส้นทางเครื่องมือระดับหนึ่ง:

POST /api/v1/tools/<section>/<presetId>

แต่ละพรีเซ็ตล็อกรูปแบบเอาต์พุตและมอบหมายให้เครื่องมือฐาน เช่น convert, convert-video, extract-audio, convert-audio, image-to-pdf, pdf-to-image, svg-to-raster หรือ convert-spreadsheet ดู พรีเซ็ตการแปลง สำหรับตารางเส้นทางฉบับสมบูรณ์และการตั้งค่าที่ไม่บังคับ

พื้นฐาน

Tool ID	ชื่อ	การตั้งค่าหลัก
resize	ปรับขนาด	width, height, fit (cover/contain/fill/inside/outside), percentage, withoutEnlargement พร้อมพรีเซ็ตโซเชียลมีเดีย 23 รายการ
crop	ครอป	left, top, width, height, unit (px/percent)
rotate	หมุนและพลิก	angle, horizontal (bool), vertical (bool)
convert	แปลง	format (jpg/png/webp/avif/tiff/gif/heic/heif), quality
compress	บีบอัด	mode (quality/targetSize), quality (1–100), targetSizeKb

การปรับปรุงประสิทธิภาพ

Tool ID	ชื่อ	การตั้งค่าหลัก
optimize-for-web	ปรับให้เหมาะกับเว็บ	format (webp/jpeg/avif/png), quality, maxWidth, maxHeight, progressive, stripMetadata
strip-metadata	ลบเมทาดาทา	-
edit-metadata	แก้ไขเมทาดาทา	title, description, author, copyright, keywords, gps (lat/lon), dateTime
bulk-rename	เปลี่ยนชื่อแบบกลุ่ม	pattern (รองรับ {n}, {date}, {original}), startIndex, padding
image-to-pdf	รูปภาพเป็น PDF	pageSize (A4/Letter/...), orientation, margin, targetSize ({value, unit})
favicon	ตัวสร้าง Favicon	padding, backgroundColor, borderRadius - สร้างขนาดมาตรฐานทั้งหมด

การปรับแต่ง

Tool ID	ชื่อ	การตั้งค่าหลัก
adjust-colors	ปรับสี	brightness, contrast, exposure, saturation, temperature, tint, hue, sharpness, red, green, blue, effect (none/grayscale/sepia/invert)
sharpening	การทำให้คมชัด	method (adaptive/unsharp-mask/high-pass), sigma, m1, m2, x1, y2, y3, amount, radius, threshold, strength, kernelSize (3/5), denoise (off/light/medium/strong)
replace-color	แทนที่สี	sourceColor, targetColor (สีที่ใช้แทน), makeTransparent, tolerance
color-blindness	จำลองภาวะตาบอดสี	simulationType (protanopia/deuteranopia/tritanopia/protanomaly/deuteranomaly/tritanomaly/achromatopsia/blueConeMonochromacy, ค่าเริ่มต้น "deuteranomaly")
duotone	Duotone	shadow (hex), highlight (hex), intensity (0-100)
pixelate	Pixelate	blockSize (2-128), region ({left, top, width, height} สำหรับการทำ pixelation บางส่วน)
vignette	Vignette	strength (0.1-1), color (hex), radius, softness, roundness, centerX, centerY

เครื่องมือ AI

เครื่องมือ AI ทั้งหมดทำงานบนฮาร์ดแวร์ของคุณ: CPU โดยค่าเริ่มต้น หรือ NVIDIA CUDA เมื่อมี NVIDIA GPU ที่รองรับ การเร่งความเร็ว iGPU ของ Intel/AMD ผ่าน VA-API, Quick Sync หรือ OpenCL ยังไม่รองรับสำหรับการอนุมาน AI ในปัจจุบัน ไม่ต้องใช้อินเทอร์เน็ต

Tool ID	ชื่อ	โมเดล AI	การตั้งค่าหลัก
remove-background	ลบพื้นหลัง	rembg (BiRefNet / U2-Net)	model, backgroundType (transparent/color/gradient/blur/image), backgroundColor, gradientColor1, gradientColor2, gradientAngle, blurEnabled, blurIntensity, shadowEnabled, shadowOpacity
upscale	ขยายภาพ	RealESRGAN	scale (2/4), model, faceEnhance, denoise, format, quality
erase-object	ลบวัตถุ	LaMa (ONNX)	ส่ง Mask เป็นส่วนไฟล์ที่สอง (fieldname mask), format, quality
ocr	OCR / การแยกข้อความ	Tesseract (เร็ว); RapidOCR + PP-OCR ONNX (สมดุล/ดีที่สุด)	quality (เร็ว/สมดุล/ดีที่สุด), language, enhance
blur-faces	เบลอใบหน้า / PII	MediaPipe	blurRadius, sensitivity
smart-crop	ครอปอัจฉริยะ	MediaPipe + Sharp	mode (subject/face/trim), strategy (attention/entropy), width, height, padding, facePreset (closeup/head-shoulders/upper-body/half-body), sensitivity, threshold, padToSquare, padColor, targetSize, quality
image-enhancement	เพิ่มคุณภาพภาพ	อิงจากการวิเคราะห์	mode (auto/exposure/contrast/color/sharpness), strength
enhance-faces	เพิ่มคุณภาพใบหน้า	GFPGAN / CodeFormer	model (gfpgan/codeformer), strength, sensitivity, centerFace
colorize	ลงสีด้วย AI	DDColor	intensity, model
noise-removal	ลบสัญญาณรบกวน	การลดสัญญาณรบกวนแบบหลายระดับ	tier (quick/balanced/quality/maximum), strength, detailPreservation, colorNoise, format, quality
red-eye-removal	ลบตาแดง	Face landmark + การวิเคราะห์สี	sensitivity, strength
restore-photo	ฟื้นฟูภาพถ่าย	ไปป์ไลน์หลายขั้นตอน	mode (auto/light/heavy), scratchRemoval, faceEnhancement, fidelity, denoise, denoiseStrength, colorize
passport-photo	รูปถ่ายพาสปอร์ต	MediaPipe landmarks	โฟลว์แบบสองขั้นตอน การวิเคราะห์ใช้ multipart file; การสร้างใช้ JSON พร้อม countryCode, bgColor, printLayout (none/4x6/a4), landmarks, มิติภาพ
content-aware-resize	ปรับขนาดแบบรับรู้เนื้อหา	Seam carving (caire)	width, height, protectFaces, blurRadius, sobelThreshold, square
transparency-fixer	ตัวแก้ความโปร่งใส PNG	BiRefNet HR-matting	defringe (0-100), outputFormat (png/webp)
background-replace	แทนที่พื้นหลัง	rembg (BiRefNet)	backgroundType (color/gradient), color (hex), gradientColor1, gradientColor2, gradientAngle, feather (0-20), format (png/webp)
blur-background	เบลอพื้นหลัง	rembg (BiRefNet)	intensity (1-100), feather (0-20), format (png/webp)
ai-canvas-expand	ขยายผืนผ้าใบด้วย AI	LaMa (outpainting)	extendTop, extendRight, extendBottom, extendLeft (px), tier (fast/balanced/high), format, quality

ลายน้ำและการซ้อนทับ

Tool ID	ชื่อ	การตั้งค่าหลัก
watermark-text	ลายน้ำข้อความ	text, font, fontSize, color, opacity, position, rotation, tile
watermark-image	ลายน้ำรูปภาพ	opacity, position, scale - ไฟล์ที่สองคือลายน้ำ
text-overlay	ซ้อนทับข้อความ	text, font, fontSize, color, x, y, background, padding, borderRadius
compose	การประกอบภาพ	x, y, opacity, blend - ไฟล์ที่สองถูกวางเป็นเลเยอร์ด้านบน
meme-generator	ตัวสร้างมีม	templateId, textLayout (top-bottom/top-only/bottom-only/center/side-by-side), textBoxes ([{id, text}]), fontFamily (anton/arial-black/comic-sans/montserrat/bebas-neue/permanent-marker/roboto), fontSize, textColor, strokeColor, textAlign, allCaps รองรับโหมดเทมเพลต (JSON body พร้อม templateId) หรือโหมดรูปภาพกำหนดเอง (multipart พร้อมไฟล์)

ยูทิลิตี

Tool ID	ชื่อ	การตั้งค่าหลัก
info	ข้อมูลรูปภาพ	- (คืนค่า width, height, format, size, channels, hasAlpha, DPI, EXIF)
compare	เปรียบเทียบรูปภาพ	mode (side-by-side/overlay/diff), diffThreshold - ไฟล์ที่สองคือเป้าหมายการเปรียบเทียบ
find-duplicates	ค้นหารูปซ้ำ	threshold (ระยะห่างของ perceptual hash, ค่าเริ่มต้น 8) - หลายไฟล์
color-palette	จานสี	count (จำนวนสีเด่น), format (hex/rgb)
qr-generate	ตัวสร้าง QR Code	data, size, margin, colorDark, colorLight, errorCorrectionLevel, dotStyle, cornerStyle, logo (ไฟล์ที่ไม่บังคับ)
barcode-read	ตัวอ่านบาร์โค้ด	- (ตรวจจับ QR, EAN, Code128, DataMatrix ฯลฯ โดยอัตโนมัติ)
image-to-base64	รูปภาพเป็น Base64	format (data-uri/plain), mimeType
html-to-image	HTML เป็นรูปภาพ	url, format (png/jpg/webp), quality, fullPage, devicePreset (desktop/tablet/mobile/custom), viewportWidth, viewportHeight
histogram	ฮิสโทแกรม	scale (linear/log) - คืนค่าแผนภูมิฮิสโทแกรม RGB + สถิติต่อแชนเนล
lqip-placeholder	LQIP Placeholder	width (4-64), blur, strategy (blur/pixelate/solid), format (webp/png/jpeg), quality
barcode-generate	ตัวสร้างบาร์โค้ด	text, type (code128/ean13/upca/code39/itf14/datamatrix), scale (1-8), includeText (bool) JSON body ไม่มีการอัปโหลดไฟล์

เลย์เอาต์และการประกอบภาพ

Tool ID	ชื่อ	การตั้งค่าหลัก
collage	คอลลาจ / ตาราง	template (เลย์เอาต์ 25+ แบบ), gap, backgroundColor, borderRadius - หลายไฟล์
stitch	เย็บ / รวมภาพ	direction (horizontal/vertical/grid), gap, backgroundColor, alignment - หลายไฟล์
split	แยกรูปภาพ	mode (grid/rows/cols), rows, cols, tileWidth, tileHeight
border	ขอบและกรอบ	width, color, style (solid/gradient/pattern), borderRadius, padding, shadow
beautify	ตกแต่งภาพหน้าจอ	backgroundType (solid/linear-gradient/radial-gradient/image/transparent), gradientStops, padding, borderRadius, shadowPreset, frame (none/macos-light/macos-dark/windows-light/windows-dark/browser-light/browser-dark/iphone/macbook/ipad/...), socialPreset (none/twitter/linkedin/instagram-square/instagram-story/facebook/producthunt), watermarkText, outputFormat
circle-crop	ครอปวงกลม	zoom (1-5), offsetX, offsetY, borderWidth, borderColor, background (transparent/hex), outputSize
image-pad	เติมขอบรูปภาพ	target (16:9/9:16/1:1/4:3/3:4/custom), ratioW, ratioH, background (color/transparent/blur), color (hex), padding (0-50%)
sprite-sheet	Sprite Sheet	columns (1-16), padding, background (hex), format (png/webp/jpeg), quality - หลายไฟล์ (2-64 รูป)

รูปแบบและการแปลง

Tool ID	ชื่อ	การตั้งค่าหลัก
svg-to-raster	SVG เป็นแรสเตอร์	format (png/jpeg/webp/avif/tiff/gif/heif), width, height, scale, dpi, background
vectorize	รูปภาพเป็น SVG	colorMode (bw/color), threshold, colorPrecision, filterSpeckle, pathMode (none/polygon/spline)
gif-tools	เครื่องมือ GIF	action (resize/optimize/reverse/speed/extract-frames/rotate/add-text), พารามิเตอร์เฉพาะแอ็กชัน
gif-webp	ตัวแปลง GIF/WebP	quality (1-100), lossless (bool), resizePercent (10-100)

เครื่องมือวิดีโอ

Tool ID	ชื่อ	การตั้งค่าหลัก
convert-video	แปลงวิดีโอ	format (mp4/mov/webm/avi/mkv), quality (high/balanced/small)
compress-video	บีบอัดวิดีโอ	quality (light/balanced/strong), resolution (original/1080p/720p/480p)
trim-video	ตัดวิดีโอ	startS, endS, precise (bool, ตัดแบบแม่นยำระดับเฟรม)
mute-video	ปิดเสียงวิดีโอ	-
video-to-gif	วิดีโอเป็น GIF	fps (1-30), width, startS, durationS (สูงสุด 60 วินาที)
resize-video	ปรับขนาดวิดีโอ	width, height, preset (custom/2160p/1440p/1080p/720p/480p/360p)
crop-video	ครอปวิดีโอ	width, height, x, y
rotate-video	หมุนวิดีโอ	transform (cw90/ccw90/180/hflip/vflip)
change-fps	เปลี่ยน FPS	fps (1-120)
video-color	สีวิดีโอ	brightness, contrast, saturation, gamma
video-speed	ความเร็ววิดีโอ	factor (0.25-4), keepPitch (bool)
reverse-video	ย้อนวิดีโอ	- (สูงสุด 5 นาที)
video-loudnorm	ปรับระดับเสียงให้เท่ากัน	- (EBU R128)
aspect-pad	เติมขอบตามอัตราส่วน	target (16:9/9:16/1:1/4:3/3:4), color (hex)
blur-pad	เติมขอบด้วยความเบลอ	target (16:9/9:16/1:1/4:3/3:4), blur (2-50)
watermark-video	ลายน้ำวิดีโอ	text, position, fontSize, opacity, color
stabilize-video	ทำวิดีโอให้นิ่ง	smoothing (5-60, เป็นเฟรม)
gif-to-video	GIF เป็นวิดีโอ	format (mp4/webm/mov)
video-to-webp	วิดีโอเป็น WebP	fps, width, quality, loop (bool)
video-to-frames	วิดีโอเป็นเฟรม	mode (all/nth/timestamps), n, timestamps, format (png/jpg)
merge-videos	รวมวิดีโอ	- (หลายไฟล์ ปรับเป็นความละเอียดของวิดีโอแรก)
replace-audio	แทนที่เสียง	- (วิดีโอ + ไฟล์เสียง สองไฟล์)
burn-subtitles	ฝังคำบรรยาย (Burn)	fontSize (8-72) - วิดีโอ + ไฟล์คำบรรยาย
embed-subtitles	ฝังคำบรรยาย (Embed)	language (รหัส ISO 639-2/B) - วิดีโอ + ไฟล์คำบรรยาย
extract-subtitles	สกัดคำบรรยาย	- (ส่งออก SRT)
images-to-video	รูปภาพเป็นวิดีโอ	secondsPerImage (0.5-10), resolution (1080p/720p/square), fps - หลายไฟล์
video-metadata	ล้างเมทาดาทาวิดีโอ	-
auto-subtitles	คำบรรยายอัตโนมัติ (AI)	language (auto/en/de/fr/es/zh/ja/ko/id/th/vi), format (srt/vtt)
extract-audio	สกัดเสียง	format (mp3/wav/m4a/ogg)

เครื่องมือเสียง

Tool ID	ชื่อ	การตั้งค่าหลัก
convert-audio	แปลงเสียง	format (mp3/wav/ogg/flac/m4a), bitrateKbps (32-320)
trim-audio	ตัดเสียง	startS, endS
volume-adjust	ปรับระดับเสียง	gainDb (-30 ถึง 30)
normalize-audio	ปรับระดับเสียงให้เท่ากัน	- (EBU R128, -16 LUFS)
fade-audio	เฟดเสียง	fadeInS (0-30), fadeOutS (0-30)
reverse-audio	ย้อนเสียง	-
audio-speed	ความเร็วเสียง	factor (0.25-4)
pitch-shift	เปลี่ยนระดับเสียง (Pitch)	semitones (-12 ถึง 12)
audio-channels	ช่องสัญญาณเสียง	mode (stereo-to-mono/mono-to-stereo/swap)
silence-removal	ลบความเงียบ	thresholdDb (-80 ถึง -20), minSilenceS (0.1-5)
noise-reduction	ลดสัญญาณรบกวน	strength (light/medium/strong)
merge-audio	รวมเสียง	format (mp3/wav/flac/m4a) - หลายไฟล์
split-audio	แยกเสียง	mode (time/parts/silence), segmentS, parts, thresholdDb, minSilenceS
ringtone-maker	ตัวสร้างริงโทน	startS, durationS (1-30)
waveform-image	รูปภาพเวฟฟอร์ม	width, height, color (hex)
audio-metadata	เมทาดาทาเสียง	strip (bool), title, artist, album
transcribe-audio	ถอดเสียงเป็นข้อความ (AI)	language (auto/en/de/fr/es/zh/ja/ko/id/th/vi), outputFormat (txt/srt/vtt)

เครื่องมือเอกสาร

Tool ID	ชื่อ	การตั้งค่าหลัก
merge-pdf	รวม PDF	- (หลายไฟล์ สูงสุด 20 PDF)
split-pdf	แยก PDF	mode (range/every), range, everyN (1-500)
compress-pdf	บีบอัด PDF	mode (quality/targetSize), quality (1-100), targetSizeKb
rotate-pdf	หมุน PDF	angle (90/180/270), range (ช่วงหน้า)
extract-pages	สกัดหน้า	range (ไวยากรณ์ qpdf เช่น "1-5,8,10-z")
remove-pages	ลบหน้า	pages (ช่วง qpdf ที่จะลบ)
organize-pdf	จัดระเบียบ PDF	order (ลำดับหน้า qpdf เช่น "3,1,2,5-z")
protect-pdf	ป้องกัน PDF	userPassword, ownerPassword (AES-256)
unlock-pdf	ปลดล็อก PDF	password
repair-pdf	ซ่อมแซม PDF	-
linearize-pdf	ปรับ PDF ให้เหมาะกับเว็บ	- (linearize เพื่อการดูบนเว็บที่รวดเร็ว)
grayscale-pdf	PDF ระดับสีเทา	-
pdfa-convert	แปลงเป็น PDF/A	- (PDF/A-2 สำหรับการเก็บถาวร)
crop-pdf	ครอป PDF	margin (0-2000 จุด)
nup-pdf	N-up PDF	perSheet (2/3/4/8/9/12/16)
booklet-pdf	สมุดพับ PDF	perSheet (2/4/6/8)
watermark-pdf	ลายน้ำ PDF	text, position, fontSize, opacity, rotation
pdf-page-numbers	เลขหน้า PDF	position (bl/bc/br/tl/tc/tr), fontSize
flatten-pdf	Flatten PDF	- (ทำให้ฟอร์มและคำอธิบายประกอบกลายเป็นภาพ)
redact-pdf	ปกปิดข้อมูล PDF	terms (string[]), caseSensitive (bool)
sign-pdf	ลงนาม PDF	เส้นทาง multipart กำหนดเองพร้อม PDF file, ไฟล์ลายเซ็น sig0, sig1 และอาร์เรย์ JSON placements
pdf-to-text	PDF เป็นข้อความ	-
pdf-to-word	PDF เป็น Word	-
pdf-metadata	เมทาดาทา PDF	title, author, subject, keywords
convert-document	แปลงเอกสาร	format (docx/odt/rtf/txt)
convert-presentation	แปลงงานนำเสนอ	format (pptx/odp)
convert-spreadsheet	แปลงสเปรดชีต	format (xlsx/ods/csv)
excel-to-pdf	Excel เป็น PDF	-
word-to-pdf	Word เป็น PDF	-
powerpoint-to-pdf	PowerPoint เป็น PDF	-
html-to-pdf	HTML เป็น PDF	- (ปิดใช้งานทรัพยากรระยะไกล)
markdown-to-docx	Markdown เป็น Word	-
markdown-to-html	Markdown เป็น HTML	-
markdown-to-pdf	Markdown เป็น PDF	- (ปิดใช้งานทรัพยากรระยะไกล)
epub-convert	แปลง EPUB	format (pdf/docx/html/md)
to-epub	แปลงเป็น EPUB	- (รับ .docx, .md, .html, .txt)
ocr-pdf	PDF OCR (AI)	quality (fast/balanced/best), language (auto/en/de/fr/es/zh/ja/ko), pages
pdf-to-image	PDF เป็นรูปภาพ	pages (all/range), format, dpi, quality
pdf-to-jpg	PDF เป็น JPG	pages, dpi, quality, colorMode
pdf-to-png	PDF เป็น PNG	pages, dpi, quality, colorMode
pdf-to-tiff	PDF เป็น TIFF	pages, dpi, quality, colorMode

เครื่องมือไฟล์

Tool ID	ชื่อ	การตั้งค่าหลัก
chart-maker	ตัวสร้างแผนภูมิ	kind (bar/line/pie), title, width, height
csv-excel	CSV เป็น Excel	sheet (หมายเลขเวิร์กชีตสำหรับอินพุต XLSX) - แบบสองทิศทาง
csv-json	CSV เป็น JSON	pretty (bool) - แบบสองทิศทาง
json-xml	JSON เป็น XML	pretty (bool) - แบบสองทิศทาง
split-csv	แยก CSV	rowsPerFile (1-1000000), keepHeader (bool)
merge-csvs	รวม CSV	- (หลายไฟล์ คอลัมน์ตรงกัน)
yaml-json	YAML / JSON	- (แบบสองทิศทาง)
xml-to-csv	XML เป็น CSV	- (ค้นหาองค์ประกอบที่ซ้ำโดยอัตโนมัติ)
excel-to-csv	Excel เป็น CSV	พรีเซ็ตการแปลงเฉพาะที่รองรับโดย convert-spreadsheet
create-zip	สร้าง ZIP	- (หลายไฟล์ 2-50 ไฟล์)
extract-zip	แตก ZIP	- (ป้องกัน bomb)

HTML เป็นรูปภาพ

จับภาพหน้าเว็บเป็นรูปภาพ ต่างจากเครื่องมืออื่น เอนด์พอยต์นี้รับ application/json แทน multipart form data (ไม่ต้องอัปโหลดไฟล์)

เอนด์พอยต์: POST /api/v1/tools/image/html-to-image

Content-Type: application/json

พารามิเตอร์	ประเภท	ค่าเริ่มต้น	คำอธิบาย
url	string	(จำเป็น)	URL ที่จะจับภาพ (http/https เท่านั้น)
format	string	"png"	รูปแบบเอาต์พุต: jpg, png, webp
quality	number	90	คุณภาพ 1-100 (JPG/WebP เท่านั้น)
fullPage	boolean	false	จับภาพทั้งหน้าที่เลื่อนได้
devicePreset	string	"desktop"	desktop, tablet, mobile, custom
viewportWidth	number	1280	ความกว้าง viewport กำหนดเอง 320-3840
viewportHeight	number	720	ความสูง viewport กำหนดเอง 320-2160

ตัวอย่าง:

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"}'

การตอบกลับ:

{
  "jobId": "uuid",
  "downloadUrl": "/api/v1/download/{jobId}/screenshot.png",
  "originalSize": 0,
  "processedSize": 54321
}

เส้นทางย่อยของเครื่องมือ

เครื่องมือบางตัวมีเอนด์พอยต์เพิ่มเติมนอกเหนือจาก POST /api/v1/tools/<section>/<toolId> มาตรฐาน:

Method	Path	คำอธิบาย
GET	/api/v1/tools/popular	คืนค่า tool ID ยอดนิยม โดยย้อนกลับไปใช้รายการเริ่มต้นที่คัดสรรไว้เมื่อข้อมูลการใช้งานมีน้อย
POST	/api/v1/tools/image/remove-background/effects	ใช้เอฟเฟกต์พื้นหลัง (color/gradient/blur/shadow) โดยไม่ต้องรัน AI ใหม่ ใช้ mask ที่แคชไว้จากการลบครั้งแรก
POST	/api/v1/tools/image/edit-metadata/inspect	อ่านเมทาดาทา EXIF/IPTC/XMP ที่มีอยู่จากรูปภาพ
POST	/api/v1/tools/image/strip-metadata/inspect	ตรวจสอบฟิลด์เมทาดาทาก่อนลบ
POST	/api/v1/tools/image/passport-photo/analyze	เฟส 1: การตรวจจับใบหน้าด้วย AI + การลบพื้นหลัง คืนค่า face landmarks และข้อมูลที่แคชไว้
POST	/api/v1/tools/image/passport-photo/generate	เฟส 2: ครอป ปรับขนาด และปูภาพโดยใช้การวิเคราะห์ที่แคชไว้ ไม่มีการรัน AI ใหม่
POST	/api/v1/tools/image/gif-tools/info	รับเมทาดาทา GIF (จำนวนเฟรม มิติ ระยะเวลา)
POST	/api/v1/tools/pdf/pdf-to-image/info	รับเมทาดาทา PDF (จำนวนหน้า มิติ)
POST	/api/v1/tools/pdf/pdf-to-image/preview	สร้างตัวอย่างของหน้า PDF ที่ระบุ
POST	/api/v1/tools/pdf/pdf-to-jpg/info	รับเมทาดาทา PDF สำหรับพรีเซ็ต JPG เฉพาะ
POST	/api/v1/tools/pdf/pdf-to-jpg/preview	สร้างตัวอย่างหน้า PDF ของพรีเซ็ต JPG
POST	/api/v1/tools/pdf/pdf-to-png/info	รับเมทาดาทา PDF สำหรับพรีเซ็ต PNG เฉพาะ
POST	/api/v1/tools/pdf/pdf-to-png/preview	สร้างตัวอย่างหน้า PDF ของพรีเซ็ต PNG
POST	/api/v1/tools/pdf/pdf-to-tiff/info	รับเมทาดาทา PDF สำหรับพรีเซ็ต TIFF เฉพาะ
POST	/api/v1/tools/pdf/pdf-to-tiff/preview	สร้างตัวอย่างหน้า PDF ของพรีเซ็ต TIFF
POST	/api/v1/tools/image/svg-to-raster/batch	แปลง SVG หลายไฟล์เป็นแรสเตอร์แบบแบตช์
POST	/api/v1/tools/image/image-enhancement/analyze	วิเคราะห์คุณภาพภาพและคืนค่าคำแนะนำการเพิ่มคุณภาพ
POST	/api/v1/tools/image/optimize-for-web/preview	ตัวอย่างแบบเบาสำหรับการปรับพารามิเตอร์แบบสด คืนค่ารูปภาพที่ปรับให้เหมาะสมพร้อมส่วนหัวขนาด

การประมวลผลแบบแบตช์

ใช้เครื่องมือที่รองรับแบตช์ทั่วไปกับหลายไฟล์พร้อมกัน คืนค่าไฟล์บีบอัด ZIP เส้นทางที่มีหลายไฟล์หรือหลายขั้นตอนกำหนดเอง เช่น การลงนาม PDF และเส้นทางพรีเซ็ต PDF-เป็น-รูปภาพ ใช้สัญญาเอนด์พอยต์ของตนเองแทนเส้นทาง /batch ทั่วไป

เครื่องมือ ocr-pdf รองรับเส้นทาง /batch ทั่วไปนี้

curl -X POST http://localhost:1349/api/v1/tools/image/compress/batch \
  -H "Authorization: Bearer <token>" \
  -F "files=@a.jpg" \
  -F "files=@b.jpg" \
  -F "files=@c.jpg" \
  -F 'settings={"quality":80}'

การทำงานพร้อมกันควบคุมโดย CONCURRENT_JOBS (ค่าเริ่มต้น: ตรวจจับอัตโนมัติจากคอร์ CPU) MAX_BATCH_SIZE จำกัดจำนวนไฟล์ต่อแบตช์ (ค่าเริ่มต้น: 100; ตั้งเป็น 0 สำหรับไม่จำกัด)

ไปป์ไลน์

รันไปป์ไลน์

# Single file
curl -X POST http://localhost:1349/api/v1/pipeline/execute \
  -H "Authorization: Bearer <token>" \
  -F "file=@input.jpg" \
  -F 'pipeline={"steps":[
    {"toolId":"resize","settings":{"width":1200}},
    {"toolId":"compress","settings":{"quality":80}},
    {"toolId":"watermark-text","settings":{"text":"© 2025"}}
  ]}'

# Batch (multiple files → ZIP)
curl -X POST http://localhost:1349/api/v1/pipeline/batch \
  -H "Authorization: Bearer <token>" \
  -F "files=@a.jpg" \
  -F "files=@b.jpg" \
  -F 'pipeline={"steps":[{"toolId":"resize","settings":{"width":800}}]}'

เอาต์พุตของแต่ละขั้นตอนคืออินพุตของขั้นตอนถัดไป ไปป์ไลน์อนุญาต 20 ขั้นตอนโดยค่าเริ่มต้น กำหนดค่าได้ผ่าน MAX_PIPELINE_STEPS ตั้งค่า MAX_PIPELINE_STEPS=0 เพื่อลบขีดจำกัด

บันทึกและจัดการไปป์ไลน์

Method	Path	คำอธิบาย
POST	/api/v1/pipeline/save	บันทึกไปป์ไลน์ที่ตั้งชื่อ (name, description, steps[])
GET	/api/v1/pipeline/list	แสดงรายการไปป์ไลน์ที่บันทึกไว้ (ผู้ดูแลระบบเห็นทั้งหมด; ผู้ใช้เห็นของตนเอง)
DELETE	/api/v1/pipeline/:id	ลบ (เจ้าของหรือผู้ดูแลระบบ)
GET	/api/v1/pipeline/tools	แสดงรายการ tool ID ที่ใช้ได้กับขั้นตอนไปป์ไลน์

การติดตามความคืบหน้า

งานที่ทำงานนาน เครื่องมือที่เข้าคิว งานแบตช์ และไปป์ไลน์จะส่งความคืบหน้าแบบเรียลไทม์ผ่าน Server-Sent Events สตรีมความคืบหน้าเป็นสาธารณะและระบุด้วย job ID ดังนั้นไคลเอนต์ไม่จำเป็นต้องส่งส่วนหัว Authorization เพื่ออ่าน

# Connect to the SSE stream (jobId is in the JSON response body from the tool endpoint)
curl -N http://localhost:1349/api/v1/jobs/<jobId>/progress

รูปแบบอีเวนต์:

data: {"jobId":"...","type":"single","phase":"processing","stage":"Upscaling","percent":42}
data: {"jobId":"...","type":"single","phase":"complete","percent":100,"result":{"downloadUrl":"/api/v1/download/..."}}
data: {"jobId":"...","type":"batch","status":"processing","completedFiles":2,"totalFiles":5,"failedFiles":0,"errors":[]}

คุณสามารถขอยกเลิกงานที่เข้าคิวหรือกำลังทำงานได้ด้วย POST /api/v1/jobs/:jobId/cancel การตอบกลับคือ {"canceled":true|false}

คลังไฟล์

การจัดเก็บไฟล์แบบถาวรพร้อมประวัติเวอร์ชัน

Method	Path	คำอธิบาย
POST	/api/v1/upload	อัปโหลดไฟล์ไปยัง workspace (การประมวลผลชั่วคราว)
POST	/api/v1/files/upload	อัปโหลดไฟล์ไปยังคลังไฟล์ถาวร
POST	/api/v1/files/save-result	บันทึกผลการประมวลผลของเครื่องมือเป็นเวอร์ชันไฟล์ใหม่
GET	/api/v1/files	แสดงรายการไฟล์ที่บันทึกไว้ (แบ่งหน้า พร้อมการค้นหา)
GET	/api/v1/files/:id	รับเมทาดาทาไฟล์ + สายเวอร์ชัน
GET	/api/v1/files/:id/download	ดาวน์โหลดไฟล์
GET	/api/v1/files/:id/thumbnail	รับภาพขนาดย่อ JPEG 300px
DELETE	/api/v1/files	ลบไฟล์และสายเวอร์ชันของไฟล์แบบกลุ่ม (body: { ids: [...] })
POST	/api/v1/fetch-urls	ดึง URL ระยะไกลเข้าสู่ workspace สำหรับการนำเข้าแบบอิง URL
POST	/api/v1/preview	สร้างตัวอย่าง WebP ที่เข้ากันได้กับเบราว์เซอร์ (สำหรับรูปแบบ HEIC/HEIF/RAW)
GET	/api/v1/files/:id/preview	สตรีมตัวอย่างที่แคชไว้หรือสร้างขึ้นที่เข้ากันได้กับเบราว์เซอร์สำหรับ PDF, เอกสาร office, วิดีโอ หรือไฟล์เสียงที่บันทึกไว้
POST	/api/v1/preview/generate	สร้างตัวอย่าง MP4 หรือ MP3 แบบทันทีสำหรับไฟล์สื่อที่อัปโหลดโดยไม่ต้องบันทึกก่อน
GET	/api/v1/download/:jobId/:filename	ดาวน์โหลดไฟล์ที่ประมวลผลแล้วจาก workspace

หากต้องการบันทึกผลลัพธ์ของเครื่องมือไปยังคลังโดยอัตโนมัติ ให้รวม fileId เป็นฟิลด์ multipart form ที่อ้างอิงถึงไฟล์ในคลังที่มีอยู่ ผลลัพธ์ที่ประมวลผลแล้วจะถูกบันทึกเป็นเวอร์ชันใหม่

การจัดการ API Key

Method	Path	สิทธิ์เข้าถึง	คำอธิบาย
POST	/api/v1/api-keys	ยืนยันตัวตน	สร้างคีย์ใหม่ - แสดงเพียงครั้งเดียว
GET	/api/v1/api-keys	ยืนยันตัวตน	แสดงรายการคีย์ (name, id, lastUsedAt - ไม่ใช่คีย์ดิบ)
DELETE	/api/v1/api-keys/:id	ยืนยันตัวตน	ลบคีย์

ทีม

Method	Path	สิทธิ์เข้าถึง	คำอธิบาย
GET	/api/v1/teams	ผู้ดูแลระบบ (teams:manage)	แสดงรายการทีม
POST	/api/v1/teams	ผู้ดูแลระบบ (teams:manage)	สร้างทีม
PUT	/api/v1/teams/:id	ผู้ดูแลระบบ (teams:manage)	เปลี่ยนชื่อทีม
DELETE	/api/v1/teams/:id	ผู้ดูแลระบบ (teams:manage)	ลบทีม (ไม่สามารถลบทีมเริ่มต้นหรือทีมที่มีสมาชิก)

การตั้งค่า

การกำหนดค่าคีย์-ค่าแบบรันไทม์ (อ่านได้โดยผู้ใช้ที่ยืนยันตัวตนแล้วทุกคน เขียนได้โดยผู้ดูแลระบบเท่านั้น)

Method	Path	คำอธิบาย
GET	/api/v1/settings	รับการตั้งค่าทั้งหมด
PUT	/api/v1/settings	อัปเดตการตั้งค่าแบบกลุ่ม (JSON body พร้อมคู่คีย์-ค่า)
GET	/api/v1/settings/:key	รับการตั้งค่าที่ระบุตามคีย์

คีย์ที่รู้จัก: disabledTools (อาร์เรย์ JSON ของ tool ID), enableExperimentalTools (สตริง bool), loginAttemptLimit (ตัวเลข)

ค่าปรับตั้ง

ค่าปรับตั้งต่อผู้ใช้แยกจากการตั้งค่าของอินสแตนซ์ ผู้ใช้ที่ยืนยันตัวตนแล้วทุกคนสามารถอ่านและอัปเดตแผนที่ค่าปรับตั้งของตนเองได้

Method	Path	คำอธิบาย
GET	/api/v1/preferences	รับค่าปรับตั้งของผู้ใช้ปัจจุบันในรูปแบบ { "preferences": { ... } }
PUT	/api/v1/preferences	เพิ่มหรืออัปเดตคีย์ค่าปรับตั้งหนึ่งรายการขึ้นไปสำหรับผู้ใช้ปัจจุบัน

บทบาท

การจัดการบทบาทกำหนดเองพร้อมสิทธิ์แบบละเอียด

Method	Path	สิทธิ์เข้าถึง	คำอธิบาย
GET	/api/v1/roles	ผู้ดูแลระบบ (audit:read)	แสดงรายการบทบาททั้งหมดพร้อมจำนวนผู้ใช้
POST	/api/v1/roles	ผู้ดูแลระบบ (security:manage)	สร้างบทบาทกำหนดเอง (name, description, permissions)
PUT	/api/v1/roles/:id	ผู้ดูแลระบบ (security:manage)	อัปเดตบทบาทกำหนดเอง (ไม่สามารถแก้ไขบทบาทในตัว)
DELETE	/api/v1/roles/:id	ผู้ดูแลระบบ (security:manage)	ลบบทบาทกำหนดเอง (ไม่สามารถลบบทบาทในตัว; ผู้ใช้ที่ได้รับผลกระทบจะกลับไปใช้บทบาท user)

สิทธิ์ที่มีให้ (17): tools:use, files:own, files:all, apikeys:own, apikeys:all, pipelines:own, pipelines:all, settings:read, settings:write, users:manage, teams:manage, features:manage, system:health, audit:read, compliance:manage, webhooks:manage, security:manage

บันทึกการตรวจสอบ

เอนด์พอยต์เฉพาะผู้ดูแลระบบสำหรับตรวจสอบการกระทำที่เกี่ยวข้องกับความปลอดภัย

Method	Path	สิทธิ์เข้าถึง	คำอธิบาย
GET	/api/v1/audit-log	ผู้ดูแลระบบ (audit:read)	บันทึกการตรวจสอบแบบแบ่งหน้าพร้อมตัวกรองที่ไม่บังคับ

พารามิเตอร์คิวรี:

พารามิเตอร์	คำอธิบาย
page	หมายเลขหน้า (ค่าเริ่มต้น: 1)
limit	รายการต่อหน้า (ค่าเริ่มต้น: 50, สูงสุด: 100)
action	กรองตามประเภทการกระทำ (เช่น ROLE_CREATED, ROLE_DELETED)
ip	กรองตามที่อยู่ IP ต้นทาง
from	กรองรายการหลังวันที่ ISO 8601 นี้
to	กรองรายการก่อนวันที่ ISO 8601 นี้

การวิเคราะห์

Method	Path	สิทธิ์เข้าถึง	คำอธิบาย
GET	/api/v1/config/analytics	สาธารณะ	รับการกำหนดค่าการวิเคราะห์ที่มีผล (PostHog key, Sentry DSN, sample rate) คีย์ DSN และ instance ID จะว่างเปล่าเมื่อปิดการวิเคราะห์ ไม่ว่าจะจากการ bake ตอนคอมไพล์หรือการตั้งค่า analyticsEnabled ของอินสแตนซ์
POST	/api/v1/feedback	ยืนยันตัวตน	ส่งความคิดเห็นของผู้ใช้อย่างชัดแจ้งไปยังโปรเจกต์ PostHog ที่กำหนดค่าไว้เป็น feedback_submitted เส้นทางนี้เคารพเกตการวิเคราะห์ จำกัดอัตราการส่ง ตัดฟิลด์ติดต่อออกเว้นแต่ contactOk เป็นจริง และไม่รับเนื้อหาไฟล์ ชื่อไฟล์ เส้นทางอัปโหลด หรือข้อความข้อผิดพลาดส่วนตัวแบบดิบ เมื่อปิดการวิเคราะห์ จะคืนค่า { "ok": true, "accepted": false }
PUT	/api/v1/settings	ผู้ดูแลระบบ (settings:write)	ตั้งค่าการเลือกไม่เข้าร่วมทั่วทั้งอินสแตนซ์ ส่ง JSON body { "analyticsEnabled": "false" } เพื่อปิดการวิเคราะห์สำหรับทุกคน หรือ "true" เพื่อเปิดกลับมาอีกครั้ง

ฟีเจอร์ / AI Bundles

จัดการ AI feature bundles (ติดตั้ง/ถอนการติดตั้งแพ็กเกจโมเดล AI ในสภาพแวดล้อม Docker) ควรใช้เอนด์พอยต์การติดตั้งระดับเครื่องมือเมื่อเปิดใช้งานเครื่องมือจากระบบอัตโนมัติกำหนดเอง: เครื่องมือ AI บางตัวต้องการ shared bundle มากกว่าหนึ่งรายการ และเอนด์พอยต์นี้จะข้าม bundle ที่ติดตั้งแล้วโดยเข้าคิวเฉพาะที่ขาดหายไป

OCR เป็นการปรับปรุงทางเลือกมากกว่าการพึ่งพาอย่างหนัก ระดับ fast Tesseract ทำงานได้โดยไม่ต้องแพ็ค POST /api/v1/admin/features/ocr/install ติดตั้งชุด RapidOCR ที่ลงนามแล้วสำหรับ balanced และ best บน Linux amd64 หรือ arm64 รันไทม์ OCR ที่แม่นยำใช้ CPU บนโฮสต์ CPU เท่านั้นและ NVIDIA และต้องการหน่วยความจำที่มีประสิทธิภาพอย่างน้อย 4 GiB (ขีดจำกัดคอนเทนเนอร์ cgroup ที่กำหนดค่าไว้ มิฉะนั้น หน่วยความจำโฮสต์) SnapOtter รายงาน requiredMemoryBytes, effectiveMemoryBytes และเหตุผลด้านความเข้ากันได้ของ insufficient-memory และปฏิเสธการติดตั้งที่เข้ากันไม่ได้ก่อนที่จะดาวน์โหลด ข้อกำหนดหน่วยความจำนี้ใช้ไม่ได้กับ fast ชุดนี้มีขนาดประมาณ 208-234 MiB สำหรับดาวน์โหลดและติดตั้ง 409-488 MiB ขึ้นอยู่กับเป้าหมาย ดัชนีที่ลงนามจะผูกขนาดที่แน่นอนที่บังคับใช้ระหว่างการติดตั้ง

Method	Path	สิทธิ์เข้าถึง	คำอธิบาย
GET	/api/v1/features	ยืนยันตัวตน	แสดงรายการ feature bundle ทั้งหมดและสถานะการติดตั้ง
POST	/api/v1/admin/features/:bundleId/install	ผู้ดูแลระบบ (features:manage)	ติดตั้ง feature bundle (แบบอะซิงโครนัส คืนค่า jobId สำหรับการติดตามความคืบหน้า)
POST	/api/v1/admin/tools/:toolId/features/install	ผู้ดูแลระบบ (features:manage)	ติดตั้งทุก bundle ที่เครื่องมือต้องการ; คืนค่าสถานะเข้าคิว/ข้ามต่อ bundle
POST	/api/v1/admin/features/:bundleId/uninstall	ผู้ดูแลระบบ (features:manage)	ถอนการติดตั้ง feature bundle และล้างไฟล์โมเดล
GET	/api/v1/admin/features/disk-usage	ผู้ดูแลระบบ (features:manage)	รับการใช้พื้นที่ดิสก์รวมของโมเดล AI
POST	/api/v1/admin/features/import	ผู้ดูแลระบบ (features:manage)	นำเข้าชุด AI เดิม (file) หรือรุ่น OCR ออฟไลน์ที่ลงนามแล้ว (index บวก archive)

การนำเข้า OCR แบบมีช่องว่างอากาศจะต้องรวม ocr-runtime-index.json ที่ลงนามแล้วของรุ่นและไฟล์เก็บถาวรของแพลตฟอร์มที่ตรงกัน SnapOtter ใช้ลายเซ็น Ed25519 แฮชอาร์ติแฟกต์ ความเข้ากันได้ การแยก และการทดสอบควันที่ใช้โดยการติดตั้งออนไลน์:

curl -X POST http://localhost:1349/api/v1/admin/features/import \
  -H "Authorization: Bearer <admin-token>" \
  -F "index=@ocr-runtime-index.json" \
  -F "archive=@ocr-linux-amd64-cpu-py312.tar.gz"

ใช้ไฟล์เก็บถาวร linux-arm64-cpu-py311 บน arm64 อาร์ติแฟกต์ที่ลงนามสำหรับเป้าหมายอื่นถูกปฏิเสธแทนที่จะติดตั้ง

การดำเนินงานของผู้ดูแลระบบ

เอนด์พอยต์ปฏิบัติการสำหรับการสังเกตการณ์ การสนับสนุน การรายงานการใช้งาน และสถานะการสำรองข้อมูล

Method	Path	สิทธิ์เข้าถึง	คำอธิบาย
GET	/api/v1/admin/log-level	ผู้ดูแลระบบ (settings:write)	อ่านระดับ log รันไทม์ปัจจุบัน
POST	/api/v1/admin/log-level	ผู้ดูแลระบบ (settings:write)	เปลี่ยนระดับ log รันไทม์ (fatal, error, warn, info, debug, trace หรือ silent)
GET	/api/v1/metrics	ผู้ดูแลระบบ (system:health)	Prometheus metrics ในรูปแบบข้อความ
GET	/api/v1/admin/support-bundle	ผู้ดูแลระบบ (system:health)	ดาวน์โหลด ZIP ชุดสนับสนุนการวินิจฉัยที่ปกปิดข้อมูลแล้ว
GET	/api/v1/admin/usage	ผู้ดูแลระบบ (audit:read)	ข้อมูลแดชบอร์ดการใช้งาน พร้อมพารามิเตอร์คิวรี days ที่ไม่บังคับ
GET	/api/v1/admin/backup-status	ผู้ดูแลระบบ (system:health)	อ่านเมทาดาทาการสำรองข้อมูลล่าสุดและสถานะความใหม่
POST	/api/v1/admin/backup-status	ผู้ดูแลระบบ (system:health)	บันทึกการสำรองข้อมูลที่เสร็จสมบูรณ์ (type, sizeBytes ที่ไม่บังคับ, notes ที่ไม่บังคับ)

Enterprise API

เส้นทางเหล่านี้ถูกเกตด้วยไลเซนส์ตามฟีเจอร์ enterprise ที่เกี่ยวข้อง ยังคงต้องมีสิทธิ์ SnapOtter ที่ระบุไว้

Method	Path	สิทธิ์เข้าถึง	คำอธิบาย
GET	/api/v1/enterprise/audit/export	ผู้ดูแลระบบ (audit:read)	ส่งออกรายการการตรวจสอบเป็น JSON หรือ CSV พร้อมตัวกรอง
GET	/api/v1/enterprise/config/export	ผู้ดูแลระบบ (system:health)	ส่งออกการกำหนดค่าอินสแตนซ์ บทบาทกำหนดเอง และทีมที่ปกปิดข้อมูลแล้ว
POST	/api/v1/enterprise/config/import	ผู้ดูแลระบบ (system:health)	นำเข้าการกำหนดค่า พร้อมการทดลองรันที่ไม่บังคับ
GET	/api/v1/enterprise/ip-allowlist	ผู้ดูแลระบบ (security:manage)	อ่านรายการอนุญาต CIDR ที่กำหนดค่าไว้
PUT	/api/v1/enterprise/ip-allowlist	ผู้ดูแลระบบ (security:manage)	อัปเดตรายการอนุญาต CIDR พร้อมการป้องกันการล็อกตัวเองออก
GET	/api/v1/enterprise/legal-hold	ผู้ดูแลระบบ (compliance:manage)	แสดงรายการการระงับทางกฎหมายของผู้ใช้และทีม
PUT	/api/v1/enterprise/legal-hold	ผู้ดูแลระบบ (compliance:manage)	ใช้หรือปลดการระงับทางกฎหมายกับผู้ใช้หรือทีม
POST	/api/v1/enterprise/scim/token	ผู้ดูแลระบบ (users:manage)	สร้าง SCIM bearer token คืนค่าเพียงครั้งเดียว
DELETE	/api/v1/enterprise/scim/token	ผู้ดูแลระบบ (users:manage)	เพิกถอน SCIM bearer token ปัจจุบัน
GET	/api/v1/enterprise/siem/config	ผู้ดูแลระบบ (webhooks:manage)	อ่านการกำหนดค่าการส่งต่อ SIEM
PUT	/api/v1/enterprise/siem/config	ผู้ดูแลระบบ (webhooks:manage)	อัปเดตการกำหนดค่าการส่งต่อ SIEM
GET	/api/v1/enterprise/webhooks	ผู้ดูแลระบบ (webhooks:manage)	แสดงรายการปลายทาง webhook
POST	/api/v1/enterprise/webhooks	ผู้ดูแลระบบ (webhooks:manage)	สร้างปลายทาง webhook
PUT	/api/v1/enterprise/webhooks/:index	ผู้ดูแลระบบ (webhooks:manage)	อัปเดตปลายทาง webhook
DELETE	/api/v1/enterprise/webhooks/:index	ผู้ดูแลระบบ (webhooks:manage)	ลบปลายทาง webhook
POST	/api/v1/enterprise/webhooks/:index/test	ผู้ดูแลระบบ (webhooks:manage)	ส่ง payload webhook ทดสอบ
POST	/api/v1/enterprise/users/:id/export	ผู้ดูแลระบบ (compliance:manage)	เริ่มงานส่งออกข้อมูลผู้ใช้ตาม GDPR
GET	/api/v1/enterprise/users/:id/export/:jobId	ผู้ดูแลระบบ (compliance:manage)	อ่านสถานะการส่งออก GDPR และ URL ดาวน์โหลด
DELETE	/api/v1/enterprise/users/:id/purge	ผู้ดูแลระบบ (compliance:manage)	ล้างข้อมูลของผู้ใช้อย่างถาวรหลังการยืนยัน
DELETE	/api/v1/enterprise/teams/:id/purge	ผู้ดูแลระบบ (compliance:manage)	ล้างข้อมูลของทีมอย่างถาวรหลังการยืนยัน
GET	/api/v1/admin/version	ผู้ดูแลระบบ (system:health)	อ่านเมทาดาทาเวอร์ชันของแอป build, Node และ schema
GET	/api/v1/admin/migrations/pending	ผู้ดูแลระบบ (system:health)	เปรียบเทียบ migration ที่แพ็กเกจไว้กับ migration ที่ใช้แล้ว
GET	/api/v1/admin/upgrade-check	ผู้ดูแลระบบ (system:health)	รันการตรวจสอบความพร้อมในการอัปเกรด

SCIM 2.0

เอนด์พอยต์การค้นพบ SCIM เป็นสาธารณะ เอนด์พอยต์ผู้ใช้และกลุ่มต้องใช้ SCIM bearer token ที่สร้างไว้ด้านบน

Method	Path	สิทธิ์เข้าถึง	คำอธิบาย
GET	/api/v1/scim/v2/ServiceProviderConfig	สาธารณะ	ความสามารถของเซิร์ฟเวอร์ SCIM
GET	/api/v1/scim/v2/Schemas	สาธารณะ	การค้นพบ schema ของ SCIM
GET	/api/v1/scim/v2/ResourceTypes	สาธารณะ	การค้นพบประเภททรัพยากรของ SCIM
GET	/api/v1/scim/v2/Users	SCIM token	แสดงรายการผู้ใช้ พร้อมตัวกรอง SCIM ที่ไม่บังคับ
POST	/api/v1/scim/v2/Users	SCIM token	สร้างผู้ใช้
GET	/api/v1/scim/v2/Users/:id	SCIM token	รับผู้ใช้
PUT	/api/v1/scim/v2/Users/:id	SCIM token	แทนที่ผู้ใช้
DELETE	/api/v1/scim/v2/Users/:id	SCIM token	ปิดใช้งานผู้ใช้แบบ soft
GET	/api/v1/scim/v2/Groups	SCIM token	แสดงรายการทีมเป็นกลุ่ม SCIM
POST	/api/v1/scim/v2/Groups	SCIM token	สร้างทีม
GET	/api/v1/scim/v2/Groups/:id	SCIM token	รับทีม
PUT	/api/v1/scim/v2/Groups/:id	SCIM token	แทนที่ทีมและสมาชิกกลุ่ม
DELETE	/api/v1/scim/v2/Groups/:id	SCIM token	ลบทีม

เทมเพลตมีม

API สนับสนุนสำหรับเครื่องมือสร้างมีม

Method	Path	สิทธิ์เข้าถึง	คำอธิบาย
GET	/api/v1/meme-templates	ยืนยันตัวตน	แสดงรายการเทมเพลตมีมที่มีทั้งหมดพร้อมตำแหน่งกล่องข้อความ
GET	/api/v1/meme-templates/full/:filename	ยืนยันตัวตน	ให้บริการรูปภาพเทมเพลตขนาดเต็ม
GET	/api/v1/meme-templates/thumbs/:filename	ยืนยันตัวตน	ให้บริการภาพขนาดย่อของเทมเพลต
GET	/api/v1/meme-templates/fonts/:filename	ยืนยันตัวตน	ให้บริการไฟล์ฟอนต์ที่ใช้สำหรับการเรนเดอร์ข้อความมีม

การตอบกลับข้อผิดพลาด

ข้อผิดพลาดทั้งหมดคืนค่าเป็น JSON:

{
  "error": "Human-readable message",
  "code": "MACHINE_READABLE_CODE"
}

สถานะ	ความหมาย
400	คำขอไม่ถูกต้อง / การตรวจสอบล้มเหลว
401	ยังไม่ได้ยืนยันตัวตน
403	สิทธิ์ไม่เพียงพอ
404	ไม่พบทรัพยากร
413	ไฟล์ใหญ่เกินไป (ดู MAX_UPLOAD_SIZE_MB)
422	การประมวลผลล้มเหลวหลังการตรวจสอบ
429	ถูกจำกัดอัตรา (ดู RATE_LIMIT_PER_MIN)
501	ไม่ได้ติดตั้ง AI feature bundle ที่จำเป็น (FEATURE_NOT_INSTALLED)
500	ข้อผิดพลาดภายในเซิร์ฟเวอร์