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

bash

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

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

Session 會在 7 天後過期（可透過 SESSION_DURATION_HOURS 設定）。

API Keys

bash

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

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

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 可用性。

使用工具

每個工具都遵循相同模式：

bash

# Single file
curl -X POST http://localhost:1349/api/v1/tools/<section>/<toolId> \
  -H "Authorization: Bearer <token>" \
  -F "[email protected]" \
  -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 "[email protected]" \
  -F "[email protected]" \
  -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／文字擷取	PaddleOCR / Tesseract	`quality`（fast/balanced/best）、`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

範例：

bash

curl -X POST http://localhost:1349/api/v1/tools/image/html-to-image \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://snapotter.com", "format": "png", "devicePreset": "desktop"}'

回應：

json

{
  "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 OCR，以及 PDF 轉圖片預設路由）會使用各自的端點合約，而非通用的 /batch 路由。

bash

curl -X POST http://localhost:1349/api/v1/tools/image/compress/batch \
  -H "Authorization: Bearer <token>" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F 'settings={"quality":80}'

並行數由 CONCURRENT_JOBS 控制（預設：從 CPU 核心自動偵測）。MAX_BATCH_SIZE 限制每批的檔案數（預設：100；設為 0 代表不限）。

管線

執行管線

bash

# Single file
curl -X POST http://localhost:1349/api/v1/pipeline/execute \
  -H "Authorization: Bearer <token>" \
  -F "[email protected]" \
  -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 "[email protected]" \
  -F "[email protected]" \
  -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 標頭。

bash

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

事件格式：

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，只將缺少的排入佇列。

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`	Admin（`features:manage`）	匯入離線 AI bundle 封存

管理操作

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

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：

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	內部伺服器錯誤

REST API 參考 ​

驗證 ​

Session Token ​

API Keys ​

驗證端點 ​

權限 ​

健康檢查 ​

使用工具 ​

工具參考 ​

轉換預設 ​

基本功能 ​

最佳化 ​

調整 ​

AI 工具 ​

浮水印與疊加 ​

公用工具 ​

版面與構圖 ​

格式與轉換 ​

影片工具 ​

音訊工具 ​

文件工具 ​

檔案工具 ​

HTML 轉圖片 ​

工具子路由 ​

批次處理 ​

管線 ​

執行管線 ​

儲存與管理管線 ​

進度追蹤 ​

檔案庫 ​

API Key 管理 ​

團隊 ​

設定 ​

偏好設定 ​

角色 ​

稽核日誌 ​

分析 ​

功能 / AI Bundle ​

管理操作 ​

企業 API ​

SCIM 2.0 ​

迷因範本 ​

錯誤回應 ​

REST API 參考

驗證

Session Token

API Keys

驗證端點

權限

健康檢查

使用工具

工具參考

轉換預設

基本功能

最佳化

調整

AI 工具

浮水印與疊加

公用工具

版面與構圖

格式與轉換

影片工具

音訊工具

文件工具

檔案工具

HTML 轉圖片

工具子路由

批次處理

管線

執行管線

儲存與管理管線

進度追蹤

檔案庫

API Key 管理

團隊

設定

偏好設定

角色

稽核日誌

分析

功能 / AI Bundle

管理操作

企業 API

SCIM 2.0

迷因範本

錯誤回應