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，否则所有端点都需要身份验证。

会话令牌

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

会话在 7 天后过期（可通过 SESSION_DURATION_HOURS 配置）。

API 密钥

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

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

使用工具

每个工具都遵循相同的模式：

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。完整的路由表和可选设置见转换预设。

基础工具

工具 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 / 文本提取	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`；生成使用带 `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

示例：

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> 之外还暴露了额外端点：

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

保存和管理流水线

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

文件库

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

方法	路径	说明
`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 工具需要多个共享捆绑包，而该端点会跳过已安装的捆绑包，仅将缺失的排队安装。

方法	路径	访问权限	说明
`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 捆绑包归档

管理操作

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

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

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	服务器内部错误

REST API 参考 ​

身份验证 ​

会话令牌 ​

API 密钥 ​

身份验证端点 ​

权限 ​

健康检查 ​

使用工具 ​

工具参考 ​

转换预设 ​

基础工具 ​

优化 ​

调整 ​

AI 工具 ​

水印与叠加 ​

实用工具 ​

布局与合成 ​

格式与转换 ​

视频工具 ​

音频工具 ​

文档工具 ​

文件工具 ​

HTML 转图片 ​

工具子路由 ​

批处理 ​

流水线 ​

执行流水线 ​

保存和管理流水线 ​

进度跟踪 ​

文件库 ​

API 密钥管理 ​

团队 ​

设置 ​

偏好设置 ​

角色 ​

审计日志 ​

分析 ​

功能 / AI 捆绑包 ​

管理操作 ​

企业版 API ​

SCIM 2.0 ​

表情包模板 ​

错误响应 ​

REST API 参考

身份验证

会话令牌

API 密钥

身份验证端点

权限

健康检查

使用工具

工具参考

转换预设

基础工具

优化

调整

AI 工具

水印与叠加

实用工具

布局与合成

格式与转换

视频工具

音频工具

文档工具

文件工具

HTML 转图片

工具子路由

批处理

流水线

执行流水线

保存和管理流水线

进度跟踪

文件库

API 密钥管理

团队

设置

偏好设置

角色

审计日志

分析

功能 / AI 捆绑包

管理操作

企业版 API

SCIM 2.0

表情包模板

错误响应