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

description, i18n_output_hash, i18n_source_hash, i18n_provenance

description	i18n_output_hash	i18n_source_hash	i18n_provenance
完整的 REST API 参考。工具端点、批处理、流水线、文件库、身份验证、团队以及管理操作。	c43973438a42	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 密钥

# 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 哈希形式存储，原始密钥只显示一次，之后再也无法取回。

身份验证端点

方法	路径	访问权限	说明
POST	/api/auth/login	公开	登录，获取会话令牌
POST	/api/auth/logout	需身份验证	销毁当前会话
GET	/api/auth/session	需身份验证	校验当前会话
POST	/api/auth/change-password	需身份验证	修改自己的密码（会使所有其他会话和 API 密钥失效）
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 功能
POST	/api/auth/mfa/verify	需身份验证	用 TOTP 验证码确认 MFA 注册
POST	/api/auth/mfa/complete	公开	完成待处理的 MFA 登录挑战
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	公开	OIDC 授权回调
GET	/api/auth/saml/metadata	公开	启用 SAML 时提供 SAML SP 元数据 XML
GET	/api/auth/saml/login	公开	开始 SAML 登录
POST	/api/auth/saml/callback	公开	SAML 断言消费者服务

当用户启用了 MFA 时，POST /api/auth/login 会返回 {"requiresMfa":true,"mfaToken":"...","mfaRequired":true|false} 而不是会话令牌。将该 mfaToken 连同 TOTP 或恢复码一起发送到 /api/auth/mfa/complete。

权限

权限	管理员	用户
使用工具	✓	✓
自己的文件/流水线/API 密钥	✓	✓
查看所有用户的文件/流水线/密钥	✓	-
写入设置	✓	-
管理用户与团队	✓	-
管理品牌设置	✓	-

健康检查

方法	路径	访问权限	说明
GET	/api/v1/health	公开	基础健康检查。数据库可用时返回 {"status":"healthy","version":"..."} 与 200，数据库不可达时返回 {"status":"unhealthy"} 与 503。
GET	/api/v1/readyz	公开	就绪探针。检查 PostgreSQL、Redis、磁盘空间，以及在配置了 S3 时检查 S3。当实例不应接收流量时返回 503。
GET	/api/v1/admin/health	管理员（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。完整的路由表和可选设置见 转换预设。

基础工具

工具 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

优化

工具 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	网站图标生成器	padding、backgroundColor、borderRadius - 生成所有标准尺寸

调整

工具 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 核显进行 AI 推理加速。无需联网。

工具 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；生成使用带 countryCode、bgColor、printLayout（none/4x6/a4）、关键点、图片尺寸的 JSON
content-aware-resize	内容感知调整尺寸	接缝裁剪 (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

水印与叠加

工具 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）。

实用工具

工具 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	二维码生成器	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 请求体，无需上传文件。

布局与合成

工具 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 张图片）

格式与转换

工具 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）

视频工具

工具 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（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）

音频工具

工具 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）

文档工具

工具 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	-（线性化以便快速网页查看）
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

文件工具

工具 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	-（已做 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> 之外还暴露了额外端点：

方法	路径	说明
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 可移除该限制。

保存和管理流水线

方法	路径	说明
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}。

文件库

带版本历史的持久化文件存储。

方法	路径	说明
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 密钥管理

方法	路径	访问权限	说明
POST	/api/v1/api-keys	需身份验证	生成新密钥 - 只显示一次
GET	/api/v1/api-keys	需身份验证	列出密钥（name、id、lastUsedAt - 不含原始密钥）
DELETE	/api/v1/api-keys/:id	需身份验证	删除密钥

团队

方法	路径	访问权限	说明
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）	删除团队（无法删除默认团队或有成员的团队）

设置

运行时键值配置（任何已验证用户可读，仅管理员可写）。

方法	路径	说明
GET	/api/v1/settings	获取所有设置
PUT	/api/v1/settings	批量更新设置（带键值对的 JSON 请求体）
GET	/api/v1/settings/:key	按键获取指定设置

已知键：disabledTools（工具 ID 的 JSON 数组）、enableExperimentalTools（bool 字符串）、loginAttemptLimit（数字）。

偏好设置

每用户偏好设置与实例设置是分开的。任何已验证用户都可以读取和更新自己的偏好映射。

方法	路径	说明
GET	/api/v1/preferences	以 { "preferences": { ... } } 获取当前用户的偏好设置
PUT	/api/v1/preferences	为当前用户新增或更新一个或多个偏好键

角色

带细粒度权限的自定义角色管理。

方法	路径	访问权限	说明
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。

审计日志

仅管理员的端点，用于审查与安全相关的操作。

方法	路径	访问权限	说明
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 日期之前的条目

分析

方法	路径	访问权限	说明
GET	/api/v1/config/analytics	公开	获取生效的分析配置（PostHog 密钥、Sentry DSN、采样率）。当分析关闭时（无论来自编译期烘焙还是实例 analyticsEnabled 设置），密钥、DSN 和实例 ID 均为空。
POST	/api/v1/feedback	需身份验证	将显式的用户反馈以 feedback_submitted 提交到已配置的 PostHog 项目。该路由遵守分析开关，对提交进行限流，除非 contactOk 为 true 否则会剥离联系字段，并且从不接受文件内容、文件名、上传路径或原始私有错误文本。分析被禁用时，返回 { "ok": true, "accepted": false }。
PUT	/api/v1/settings	管理员（settings:write）	设置实例范围的选择退出。发送 JSON 请求体 { "analyticsEnabled": "false" } 为所有人关闭分析，或 "true" 重新开启。

功能 / AI 捆绑包

管理 AI 功能捆绑包（在 Docker 环境中安装/卸载 AI 模型包）。从自定义自动化启用某个工具时，优先使用工具级安装端点：某些 AI 工具需要多个共享捆绑包，而该端点会跳过已安装的捆绑包，仅将缺失的排队安装。

OCR 是可选增强功能而不是硬依赖项。 其 fast Tesseract 层无需包装即可工作； POST /api/v1/admin/features/ocr/install 在 Linux amd64 或 arm64 上安装 balanced 和 best 的签名 RapidOCR 包。 准确的 OCR 运行时在仅 CPU 和 NVIDIA 主机上使用 CPU，并且需要至少 4 GiB 的有效内存（配置的容器 cgroup 限制，否则主机内存）。 SnapOtter 报告 requiredMemoryBytes、effectiveMemoryBytes 和 insufficient-memory 兼容性原因，并在下载前拒绝不兼容的安装。 此内存要求不适用于 fast。 该包大约需要下载 208-234 MiB 和安装 409-488 MiB，具体取决于目标； 签名索引绑定安装期间强制执行的确切大小。

方法	路径	访问权限	说明
GET	/api/v1/features	需身份验证	列出所有功能捆绑包及其安装状态
POST	/api/v1/admin/features/:bundleId/install	管理员（features:manage）	安装一个功能捆绑包（异步，返回 jobId 用于进度跟踪）
POST	/api/v1/admin/tools/:toolId/features/install	管理员（features:manage）	安装某工具所需的每个捆绑包；返回每个捆绑包的已排队/已跳过状态
POST	/api/v1/admin/features/:bundleId/uninstall	管理员（features:manage）	卸载一个功能捆绑包并清理模型文件
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"

在 arm64 上使用 linux-arm64-cpu-py311 存档。另一个目标的签名工件被拒绝而不是安装。

管理操作

用于可观测性、支持、用量报告和备份状态的运维端点。

方法	路径	访问权限	说明
GET	/api/v1/admin/log-level	管理员（settings:write）	读取当前运行时日志级别
POST	/api/v1/admin/log-level	管理员（settings:write）	更改运行时日志级别（fatal、error、warn、info、debug、trace 或 silent）
GET	/api/v1/metrics	管理员（system:health）	文本格式的 Prometheus 指标
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）

企业版 API

这些路由由其相关的企业版功能进行许可证限制。它们仍需要列出的 SnapOtter 权限。

方法	路径	访问权限	说明
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 承载令牌，仅返回一次
DELETE	/api/v1/enterprise/scim/token	管理员（users:manage）	吊销当前 SCIM 承载令牌
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）	发送一个测试 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）	读取应用、构建、Node 和 schema 版本元数据
GET	/api/v1/admin/migrations/pending	管理员（system:health）	比较打包的迁移与已应用的迁移
GET	/api/v1/admin/upgrade-check	管理员（system:health）	运行升级就绪检查

SCIM 2.0

SCIM 发现端点是公开的。用户和组端点需要上面生成的 SCIM 承载令牌。

方法	路径	访问权限	说明
GET	/api/v1/scim/v2/ServiceProviderConfig	公开	SCIM 服务器能力
GET	/api/v1/scim/v2/Schemas	公开	SCIM schema 发现
GET	/api/v1/scim/v2/ResourceTypes	公开	SCIM 资源类型发现
GET	/api/v1/scim/v2/Users	SCIM 令牌	列出用户，带可选的 SCIM 过滤器
POST	/api/v1/scim/v2/Users	SCIM 令牌	创建一个用户
GET	/api/v1/scim/v2/Users/:id	SCIM 令牌	获取一个用户
PUT	/api/v1/scim/v2/Users/:id	SCIM 令牌	替换一个用户
DELETE	/api/v1/scim/v2/Users/:id	SCIM 令牌	软停用一个用户
GET	/api/v1/scim/v2/Groups	SCIM 令牌	将团队列为 SCIM 组
POST	/api/v1/scim/v2/Groups	SCIM 令牌	创建一个团队
GET	/api/v1/scim/v2/Groups/:id	SCIM 令牌	获取一个团队
PUT	/api/v1/scim/v2/Groups/:id	SCIM 令牌	替换一个团队及组成员关系
DELETE	/api/v1/scim/v2/Groups/:id	SCIM 令牌	删除一个团队

表情包模板

为表情包生成器工具提供支持的 API。

方法	路径	访问权限	说明
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_NOT_INSTALLED）
500	服务器内部错误