mirror of https://github.com/snapotter-hq/SnapOtter.git synced 2026-08-03 07:46:42 +02:00

Files

T

SnapOtterandGitHub d10d0f544f fix: release QA hardening across processing, media, security, and CI gates (#649 )

A release-readiness QA pass over the whole product. The commits split into
defects a user would hit and gates that were reporting green while measuring
nothing.

## Fixes that change behaviour

Rate limiting was bypassable on every install: TRUST_PROXY defaulted to true, so
request.ip came from a client-set header and a forged X-Forwarded-For got past
the login limiter. The default is now a private-network trust list.

A transient Postgres outage stranded in-flight jobs, leaving finished output on
disk with no row pointing at it. A reconciler now resolves those rows and adopts
the bytes rather than dropping the work.

A Redis connection that moved to a new address wedged every read-blocked
consumer, so completions stopped signalling while health still answered 200.
Socket timeouts plus subscriber pings recover it.

Installing more than one AI bundle left the shared venv multi-versioned and
silently broke three tools. The installer now reconciles distributions to one
version each.

Converting an image to JXL at quality 1 through 4 returned a 500, because
libjxl 0.7 rejects the distance those values compute. The quality is floored at
what the encoder honours. A missing ffmpeg was also reported to the user as a
corrupt upload; it now says the engine is unavailable.

RAW uploads reached an unpatched LibRaw on arm64, so it is built from source at
0.22.2, and the release scan was split so it can fail on an unfixed critical
instead of hiding it behind ignore-unfixed.

## Gates that could not fail

Two mutation lanes ran zero mutants because Stryker crawled the gitignored docs
build; coverage discarded its whole report on any failing test; the lint gate
skipped root tests, scripts, and two workspaces; and several generated matrices
counted a host missing ffmpeg as a passing tool. Each now measures what it
claims.

Full evidence and the outstanding release items are tracked locally and are not
part of this branch.

2026-07-27 15:37:30 +08:00

46 KiB

Raw Blame History

description, i18n_output_hash, i18n_source_hash, i18n_provenance

description	i18n_output_hash	i18n_source_hash	i18n_provenance
完整的 REST API 参考。工具端点、批处理、流水线、文件库、身份验证、团队以及管理操作。	c43973438a42	7e0a0db4abe0	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 (tool routes are POST multipart)
curl -X POST http://localhost:1349/api/v1/tools/image/resize \
  -H "Authorization: Bearer <session-token>" \
  -F "file=@photo.jpg" \
  -F 'settings={"width":800}'

会话在 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 -X POST http://localhost:1349/api/v1/tools/image/resize \
  -H "Authorization: Bearer si_<your-key>" \
  -F "file=@photo.jpg" \
  -F 'settings={"width":800}'

密钥以 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`）	删除团队（无法删除默认团队或有成员的团队）

设置

运行时配置仅使用一组封闭的已识别键。读取需要 settings:read，写入需要 settings:write；安全和合规键还分别需要 security:manage 或 compliance:manage。机密设置需要完整管理员权限，而由专用端点管理的凭据和状态在此处为只读。批量更新会在写入任何值之前完成验证。

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

代表性键包括：disabledTools（工具 ID 的 JSON 数组）、enableExperimentalTools（布尔值）、loginAttemptLimit（安全策略）和 auditRetentionDays（合规策略）。未知键会被拒绝。

偏好设置

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

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

拥有完整权限的内置管理员是指经过身份验证的主体拥有 admin 角色以及完整的有效管理员权限集。若 API 密钥的权限范围缺少任何管理员权限，则不符合此要求。

方法	路径	访问权限	说明
`GET`	`/api/v1/enterprise/audit/export`	管理员（`audit:read`）	带过滤器将审计条目导出为 JSON 或 CSV
`GET`	`/api/v1/enterprise/config/export`	拥有完整权限的内置管理员	导出已脱敏的实例配置、自定义角色和团队
`POST`	`/api/v1/enterprise/config/import`	拥有完整权限的内置管理员	导入配置，可选试运行
`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	服务器内部错误

46 KiB Raw Blame History Unescape Escape