SnapOtter/apps/docs/zh-TW/api/rest.md

description, i18n_output_hash, i18n_source_hash, i18n_provenance

description	i18n_output_hash	i18n_source_hash	i18n_provenance
完整的 REST API 參考。工具端點、批次處理、管線、檔案庫、驗證、團隊與管理操作。	9fa4a9a91996	b89b5df16af5	human

REST API 參考

可在 http://localhost:1349/api/docs 取得含請求／回應範例的互動式 API 文件。

機器可讀規格：

• /api/v1/openapi.yaml - OpenAPI 3.1 規格
• /llms.txt - 便於 LLM 使用的摘要
• /llms-full.txt - 完整的 LLM 友善文件

驗證

除非 AUTH_ENABLED=false，所有端點都需要驗證。

Session Token

# 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>"

Session 會在 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>"

Key 以 si_ 為前綴並以 scrypt 雜湊儲存，原始 key 只會顯示一次，之後無法再取回。

驗證端點

Method	Path	存取權限	說明
POST	/api/auth/login	Public	登入，取得 session token
POST	/api/auth/logout	Auth	銷毀目前的 session
GET	/api/auth/session	Auth	驗證目前的 session
POST	/api/auth/change-password	Auth	變更自己的密碼（會使所有其他 session 與 API key 失效）
GET	/api/auth/users	Admin	列出所有使用者
POST	/api/auth/register	Admin	建立新使用者
PUT	/api/auth/users/:id	Admin	更新使用者角色或團隊
POST	/api/auth/users/:id/reset-password	Admin	重設使用者密碼
DELETE	/api/auth/users/:id	Admin	刪除使用者
GET	/api/v1/config/auth	Public	檢查是否已啟用驗證（{ authEnabled: bool }）
POST	/api/auth/mfa/enroll	Auth	啟動 TOTP MFA 註冊。需要企業版 mfa 功能
POST	/api/auth/mfa/verify	Auth	以 TOTP 代碼確認 MFA 註冊
POST	/api/auth/mfa/complete	Public	完成待處理的 MFA 登入挑戰
POST	/api/auth/mfa/disable	Auth	為目前使用者停用 MFA
POST	/api/auth/users/:id/mfa/reset	Admin（users:manage）	重設某使用者的 MFA
GET	/api/auth/oidc/login	Public	啟用 OIDC 時啟動 OIDC 登入
GET	/api/auth/oidc/callback	Public	OIDC 授權回呼
GET	/api/auth/saml/metadata	Public	啟用 SAML 時的 SAML SP metadata XML
GET	/api/auth/saml/login	Public	啟動 SAML 登入
POST	/api/auth/saml/callback	Public	SAML assertion consumer service

當使用者啟用 MFA 時，POST /api/auth/login 會回傳 {"requiresMfa":true,"mfaToken":"...","mfaRequired":true|false} 而非 session token。將該 mfaToken 加上 TOTP 或復原代碼送至 /api/auth/mfa/complete。

權限

權限	Admin	User
使用工具	✓	✓
擁有檔案／管線／API key	✓	✓
查看所有使用者的檔案／管線／key	✓	-
寫入設定	✓	-
管理使用者與團隊	✓	-
管理品牌	✓	-

健康檢查

Method	Path	存取權限	說明
GET	/api/v1/health	Public	基本健康檢查。健康時回傳 {"status":"healthy","version":"..."} 與 200；若資料庫無法連線則回傳 {"status":"unhealthy"} 與 503。
GET	/api/v1/readyz	Public	就緒探測。檢查 PostgreSQL、Redis、磁碟空間，以及設定後的 S3。當該執行個體不應接收流量時回傳 503。
GET	/api/v1/admin/health	Admin（system:health）	詳細診斷資訊，包含執行時間、儲存模式、資料庫狀態、佇列狀態與 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 標頭），適用於註冊在通用批次登錄表中的工具。

工具參考

轉換預設

共用目錄包含 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	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	雙色調	shadow（hex）、highlight（hex）、intensity（0-100）
pixelate	像素化	blockSize（2-128）、region（{left, top, width, height}，用於部分像素化）
vignette	暈影	strength（0.1-1）、color（hex）、radius、softness、roundness、centerX、centerY

AI 工具

所有 AI 工具都在你的硬體上執行：預設使用 CPU，或在有支援的 NVIDIA GPU 時使用 NVIDIA CUDA。目前不支援透過 VA-API、Quick Sync 或 OpenCL 的 Intel/AMD iGPU 加速做 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）、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	移除紅眼	臉部特徵點 + 色彩分析	sensitivity、strength
restore-photo	照片修復	多步驟管線	mode（auto/light/heavy）、scratchRemoval、faceEnhancement、fidelity、denoise、denoiseStrength、colorize
passport-photo	證件照	MediaPipe 特徵點	兩階段流程。分析使用 multipart file；產生使用 JSON，含 countryCode、bgColor、printLayout（none/4x6/a4）、特徵點、影像尺寸
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。支援範本模式（帶有 templateId 的 JSON 主體）或自訂圖片模式（帶有檔案的 multipart）。

公用工具

Tool ID	名稱	主要設定
info	影像資訊	- （回傳寬度、高度、格式、大小、通道、hasAlpha、DPI、EXIF）
compare	影像比較	mode（side-by-side/overlay/diff）、diffThreshold - 第二個檔案為比較目標
find-duplicates	尋找重複	threshold（感知雜湊距離，預設 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 佔位圖	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 主體，不需上傳檔案。

版面與構圖

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	精靈圖表	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	燒錄字幕	fontSize（8-72） - 影片 + 字幕檔
embed-subtitles	嵌入字幕	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	音高位移	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	Web 最佳化 PDF	- （線性化以便快速網頁檢視）
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	平面化 PDF	- （將表單與註解烘焙進去）
redact-pdf	遮蔽 PDF	terms（string[]）、caseSensitive（bool）
sign-pdf	簽署 PDF	自訂 multipart 路由，含 PDF file、簽名檔案 sig0、sig1 與 placements JSON 陣列
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	- （防炸彈保護）

HTML 轉圖片

將網頁擷取為圖片。與其他工具不同，此端點接受 application/json 而非 multipart 表單資料（不需上傳檔案）。

端點： 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	自訂視窗寬度 320-3840
viewportHeight	number	720	自訂視窗高度 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	回傳熱門工具 ID；當使用資料稀少時退回到精選的預設清單
POST	/api/v1/tools/image/remove-background/effects	套用背景效果（color/gradient/blur/shadow）而不重新執行 AI。使用初次移除時快取的遮罩。
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 臉部偵測 + 移除背景。回傳臉部特徵點與快取資料。
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	取得專屬 JPG 預設的 PDF 中繼資料
POST	/api/v1/tools/pdf/pdf-to-jpg/preview	產生 JPG 預設的 PDF 頁面預覽
POST	/api/v1/tools/pdf/pdf-to-png/info	取得專屬 PNG 預設的 PDF 中繼資料
POST	/api/v1/tools/pdf/pdf-to-png/preview	產生 PNG 預設的 PDF 頁面預覽
POST	/api/v1/tools/pdf/pdf-to-tiff/info	取得專屬 TIFF 預設的 PDF 中繼資料
POST	/api/v1/tools/pdf/pdf-to-tiff/preview	產生 TIFF 預設的 PDF 頁面預覽
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	列出可用於管線步驟的工具 ID

進度追蹤

長時間執行的工作、排入佇列的工具、批次工作與管線都會透過 Server-Sent Events 發出即時進度。進度串流為公開且以工作 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	將檔案上傳至工作區（暫時處理）
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	取得 300px JPEG 縮圖
DELETE	/api/v1/files	批次刪除檔案及其版本鏈（主體：{ ids: [...] }）
POST	/api/v1/fetch-urls	將遠端 URL 抓取進工作區，用於以 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	從工作區下載已處理的檔案

若要將工具結果自動儲存至檔案庫，請將 fileId 作為 multipart 表單欄位傳入，參照現有的檔案庫檔案。處理結果會另存為新版本。

API Key 管理

Method	Path	存取權限	說明
POST	/api/v1/api-keys	Auth	產生新 key，僅顯示一次
GET	/api/v1/api-keys	Auth	列出 key（name、id、lastUsedAt，非原始 key）
DELETE	/api/v1/api-keys/:id	Auth	刪除 key

團隊

Method	Path	存取權限	說明
GET	/api/v1/teams	Admin（teams:manage）	列出團隊
POST	/api/v1/teams	Admin（teams:manage）	建立團隊
PUT	/api/v1/teams/:id	Admin（teams:manage）	重新命名團隊
DELETE	/api/v1/teams/:id	Admin（teams:manage）	刪除團隊（無法刪除預設團隊或含成員的團隊）

設定

執行時的鍵值設定（任何已驗證使用者可讀取，僅管理員可寫入）。

Method	Path	說明
GET	/api/v1/settings	取得所有設定
PUT	/api/v1/settings	批次更新設定（帶有鍵值對的 JSON 主體）
GET	/api/v1/settings/:key	依 key 取得特定設定

已知的 key：disabledTools（工具 ID 的 JSON 陣列）、enableExperimentalTools（bool 字串）、loginAttemptLimit（number）。

偏好設定

各使用者的偏好設定與執行個體設定分開。任何已驗證使用者都可讀取並更新自己的偏好設定對應表。

Method	Path	說明
GET	/api/v1/preferences	以 { "preferences": { ... } } 取得目前使用者的偏好設定
PUT	/api/v1/preferences	為目前使用者新增或更新一個以上的偏好設定 key

角色

具細緻權限的自訂角色管理。

Method	Path	存取權限	說明
GET	/api/v1/roles	Admin（audit:read）	列出所有角色及其使用者數
POST	/api/v1/roles	Admin（security:manage）	建立自訂角色（name、description、permissions）
PUT	/api/v1/roles/:id	Admin（security:manage）	更新自訂角色（無法修改內建角色）
DELETE	/api/v1/roles/:id	Admin（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	Admin（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	Public	取得有效的分析設定（PostHog key、Sentry DSN、取樣率）。當分析關閉時（無論來自編譯時的烘焙或執行個體的 analyticsEnabled 設定），key、DSN 與執行個體 ID 皆為空白。
POST	/api/v1/feedback	Auth	將明確的使用者意見回饋提交至設定的 PostHog 專案，作為 feedback_submitted。此路由遵守分析開關、對提交做速率限制，除非 contactOk 為 true 否則移除聯絡欄位，且永不接受檔案內容、檔名、上傳路徑或原始的私密錯誤文字。當分析停用時，回傳 { "ok": true, "accepted": false }。
PUT	/api/v1/settings	Admin（settings:write）	設定整個執行個體的退出。送出 JSON 主體 { "analyticsEnabled": "false" } 為所有人關閉分析，或 "true" 重新開啟。

功能 / AI Bundle

管理 AI 功能 bundle（在 Docker 環境中安裝／解除安裝 AI 模型套件）。從自訂自動化流程啟用工具時，建議使用工具層級的安裝端點：某些 AI 工具需要一個以上的共用 bundle，而此端點會略過已安裝的 bundle，只將缺少的排入佇列。

OCR 是可選增強功能而不是硬依賴項。 其 fast Tesseract 層無需包裝即可運作； POST /api/v1/admin/features/ocr/install 安裝簽名的 RapidOCR 打包 balanced 和 best 在 Linux amd64 或者 arm64。 準確的 OCR 運行時在僅 CPU 和 NVIDIA 主機上使用 CPU，並且需要至少 4 GiB 的有效記憶體（配置的容器 cgroup 限制，否則主機記憶體）。 SnapOtter 報告 requiredMemoryBytes、effectiveMemoryBytes 和 insufficient-memory 相容性原因，並在下載前拒絕不相容的安裝。 此記憶體需求不適用於 fast。 該包大約需要下載 208-234 MiB 和安裝 409-488 MiB，具體取決於目標； 簽章索引綁定安裝期間強制執行的確切大小。

Method	Path	存取權限	說明
GET	/api/v1/features	Auth	列出所有功能 bundle 及其安裝狀態
POST	/api/v1/admin/features/:bundleId/install	Admin（features:manage）	安裝功能 bundle（非同步，回傳 jobId 以追蹤進度）
POST	/api/v1/admin/tools/:toolId/features/install	Admin（features:manage）	安裝某工具所需的每個 bundle；回傳各 bundle 的已排入佇列／已略過狀態
POST	/api/v1/admin/features/:bundleId/uninstall	Admin（features:manage）	解除安裝功能 bundle 並清除模型檔案
GET	/api/v1/admin/features/disk-usage	Admin（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"

在 arm64 上使用 linux-arm64-cpu-py311 檔案。另一個目標的簽名工件被拒絕而不是安裝。

管理操作

用於可觀測性、支援、使用量報告與備份狀態的維運端點。

Method	Path	存取權限	說明
GET	/api/v1/admin/log-level	Admin（settings:write）	讀取目前執行時的日誌層級
POST	/api/v1/admin/log-level	Admin（settings:write）	變更執行時的日誌層級（fatal、error、warn、info、debug、trace 或 silent）
GET	/api/v1/metrics	Admin（system:health）	文字格式的 Prometheus metrics
GET	/api/v1/admin/support-bundle	Admin（system:health）	下載已遮蔽的診斷支援 bundle ZIP
GET	/api/v1/admin/usage	Admin（audit:read）	使用量儀表板資料，含選用的 days 查詢參數
GET	/api/v1/admin/backup-status	Admin（system:health）	讀取最近一次備份的中繼資料與新鮮度狀態
POST	/api/v1/admin/backup-status	Admin（system:health）	記錄一次已完成的備份（type、選用 sizeBytes、選用 notes）

企業 API

這些路由受其相關企業功能的授權控管。它們仍需要所列的 SnapOtter 權限。

Method	Path	存取權限	說明
GET	/api/v1/enterprise/audit/export	Admin（audit:read）	以 JSON 或 CSV 匯出稽核項目，可加篩選
GET	/api/v1/enterprise/config/export	Admin（system:health）	匯出已遮蔽的執行個體設定、自訂角色與團隊
POST	/api/v1/enterprise/config/import	Admin（system:health）	匯入設定，可選乾跑
GET	/api/v1/enterprise/ip-allowlist	Admin（security:manage）	讀取已設定的 CIDR 允許清單
PUT	/api/v1/enterprise/ip-allowlist	Admin（security:manage）	更新 CIDR 允許清單，並防止自我鎖定
GET	/api/v1/enterprise/legal-hold	Admin（compliance:manage）	列出使用者與團隊的法律保留
PUT	/api/v1/enterprise/legal-hold	Admin（compliance:manage）	對使用者或團隊套用或解除法律保留
POST	/api/v1/enterprise/scim/token	Admin（users:manage）	產生 SCIM bearer token，僅回傳一次
DELETE	/api/v1/enterprise/scim/token	Admin（users:manage）	撤銷目前的 SCIM bearer token
GET	/api/v1/enterprise/siem/config	Admin（webhooks:manage）	讀取 SIEM 轉發設定
PUT	/api/v1/enterprise/siem/config	Admin（webhooks:manage）	更新 SIEM 轉發設定
GET	/api/v1/enterprise/webhooks	Admin（webhooks:manage）	列出 webhook 目的地
POST	/api/v1/enterprise/webhooks	Admin（webhooks:manage）	建立 webhook 目的地
PUT	/api/v1/enterprise/webhooks/:index	Admin（webhooks:manage）	更新 webhook 目的地
DELETE	/api/v1/enterprise/webhooks/:index	Admin（webhooks:manage）	刪除 webhook 目的地
POST	/api/v1/enterprise/webhooks/:index/test	Admin（webhooks:manage）	送出測試 webhook 酬載
POST	/api/v1/enterprise/users/:id/export	Admin（compliance:manage）	啟動 GDPR 使用者匯出工作
GET	/api/v1/enterprise/users/:id/export/:jobId	Admin（compliance:manage）	讀取 GDPR 匯出狀態與下載 URL
DELETE	/api/v1/enterprise/users/:id/purge	Admin（compliance:manage）	確認後永久清除某使用者的資料
DELETE	/api/v1/enterprise/teams/:id/purge	Admin（compliance:manage）	確認後永久清除某團隊的資料
GET	/api/v1/admin/version	Admin（system:health）	讀取 app、build、Node 與 schema 版本中繼資料
GET	/api/v1/admin/migrations/pending	Admin（system:health）	比較封裝的遷移與已套用的遷移
GET	/api/v1/admin/upgrade-check	Admin（system:health）	執行升級就緒性檢查

SCIM 2.0

SCIM 探索端點為公開。使用者與群組端點需要上方產生的 SCIM bearer token。

Method	Path	存取權限	說明
GET	/api/v1/scim/v2/ServiceProviderConfig	Public	SCIM 伺服器能力
GET	/api/v1/scim/v2/Schemas	Public	SCIM schema 探索
GET	/api/v1/scim/v2/ResourceTypes	Public	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	軟性停用使用者
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	Auth	列出所有可用的迷因範本及文字方塊位置
GET	/api/v1/meme-templates/full/:filename	Auth	提供全尺寸範本圖片
GET	/api/v1/meme-templates/thumbs/:filename	Auth	提供範本縮圖
GET	/api/v1/meme-templates/fonts/:filename	Auth	提供迷因文字繪製所用的字型檔

錯誤回應

所有錯誤都回傳 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 功能 bundle（FEATURE_NOT_INSTALLED）
500	內部伺服器錯誤