用途说明:本文档专为用户侧的多模态与编码 AI Agent 编写。用户可将本文档直接作为上下文或 Skill 提供给自己的 Agent,使 Agent 能够通过 HTTP REST API 安全、自主地完成画师作品检索、压缩包解压、BLAKE3 去重、多模态看图角色识别与聚类打标、目录归档以及网盘任务派发。
Agent 在调用 Gallery API 时必须严格遵守以下规则:
- API 优先与主键不变量:
- 所有状态查询、解压、打标、删除与归档优先通过 HTTP API(默认
http://<NAS_IP>:8899,或读取环境变量GALLERY_API_URL)完成。 items.id是作品的永久稳定主键;文件重命名或目录移动仅改变items.file_path,已绑定的角色标签与收藏状态始终跟随items.id。- 获取作品预览图时,始终优先使用
GET /api/file/preview?item_id={item_id}&max_edge=800,避免手动拼接物理文件路径。
- 所有状态查询、解压、打标、删除与归档优先通过 HTTP API(默认
- 并发写锁与
HTTP 409 Conflict自动等待:- 扫描(
/api/scan*)、解压(/api/archives/extract)、删除(/api/file/delete)与目录归档执行(/api/folder-renames/execute*)共享服务端互斥写锁。 - 当任何请求返回
HTTP 409 Conflict时,禁止直接报错退出;必须轮询GET /api/scan/state(间隔2s),直到返回的state(或status)变为"idle"后再重试原请求。 - 若服务刚启动返回
HTTP 503 Service Unavailable,轮询GET /api/health直至initializing == false。
- 扫描(
- 危险与批量写操作审批门(
[STOP & ASK]):- 在执行以下会修改用户媒体库或元数据的批量操作前,Agent 必须先输出预览摘要表并等待用户在当前回合明确批准:
DELETE /api/file/delete或POST /api/folders/delete(移入回收站)PUT /api/items/tags、PUT /api/items/tags-by-name、PUT /api/folders/tags*(批量修改角色标签)DELETE /api/tags/{tag_id}(删除标签)DELETE /api/characters/{character_id}(删除角色)POST /api/characters/clusters/commit(提交角色聚类裁决)POST /api/folder-renames/execute//execute-all(执行物理目录重命名归档)
- 在执行以下会修改用户媒体库或元数据的批量操作前,Agent 必须先输出预览摘要表并等待用户在当前回合明确批准:
- 安全删除原则(严禁绕过回收站):
- 删除画廊内的重复或冗余文件时,必须调用
DELETE /api/file/delete?path={file_path}移入回收站(自动保留标签与收藏快照,可随时通过/api/recycle/{entry_id}/restore原路还原)。 - Agent 下载到本地临时目录(如
.tmp/)的 JPEG 预览缩略图,在看图核验完毕后可直接清理。
- 删除画廊内的重复或冗余文件时,必须调用
- 压缩包冷存储保护策略:
- 批量解压画师目录下的压缩包时,仅解压
.zip、.rar以及有密码保护(encrypted: true)的.7z。 - 无密码的
.7z压缩包通常用于 PSD/CLIP 工程源文件或游戏的冷存储归档,除非用户明确指定解压某一个.7z,否则批量整理时应跳过无密码.7z。
- 批量解压画师目录下的压缩包时,仅解压
- 查询参数布尔值格式:
- 所有 URL 查询参数中的布尔值(
duplicates_only、untagged、inbox、undated、favorite_only、search_tags_only)均支持true/false、1/0、yes/no。
- 所有 URL 查询参数中的布尔值(
当 Agent 具备多模态看图能力并执行角色打标或聚类复核时,必须遵循以下准则:
-
像素级视觉真值(禁止仅凭标题盲打标):
- 文件夹名、帖子标题或文件名仅作为文本线索(
text_hints),绝不能不看图直接根据文件名打标。 - 以下情况必须下载预览图(
GET /api/file/preview?item_id={id}&max_edge=800)进行人工/多模态视觉核验:- 确认或修改任何角色标签前;
- 单图 CCIP 最高候选置信度
< 0.7174,或前两名候选分差接近(< 0.05); - 文件名/目录名不含明确角色名;
- 作品为漫画、多图差分集或多人同框场景。
- 文件夹名、帖子标题或文件名仅作为文本线索(
-
单图物理出场判定标准(Per-Image Physical Presence):
- 仅当某个角色的物理身体(含正侧面、可辨识背影、剪影,或经同系列上下文确认的标志性肢体/尾巴/耳朵)实际出现在该张画面中时,才为该图打上该角色标签。
- 若单张画面中同时出现
$N$ 名可识别角色,则同时打上这$N$ 名角色的标签。 - 仅在台词气泡中提及名字、或画面中仅有脱离身体的孤立道具/玩偶而角色本人未出场时,不打该角色标签。
-
角色标准参考图(Reference Art)入库标准:
- 调用
POST /api/characters/{character_id}/references/upload上传角色参考图时,图片必须为清晰的单人竖版立绘或全身/半身设定图(建议分辨率width >= 350、height >= 500且width <= height * 1.05),严禁将多人同框图、纯头像截屏或 Q 版表情包上传为标准参考图。
- 调用
- 查找目标画师:
- 调用
GET /api/artists获取画师列表,匹配目标画师的id、name与根目录path。 - 调用
GET /api/artists/{artist_id}/stats与GET /api/folders?artist_id={artist_id}查看该画师的作品总数、目录树结构与归档状态。
- 调用
- 检索压缩包与同伴文本:
- 调用
GET /api/items?artist_id={artist_id}&media_type=archive&limit=500列出该画师下所有压缩包。 - 若需查找解压密码,可调用:
GET /api/artists/{artist_id}/links(查看服务端已从.txt/.html自动提取出的链接与提取码/密码);- 或检索文本项
GET /api/items?artist_id={artist_id}&media_type=text&limit=200,再调用GET /api/file/text?path={file_path}读取文本内容。
- 调用
- 预检压缩包(自动试密):
POST /api/archives/inspect Content-Type: application/json { "item_id": 2048, "password": "可选密码" }
- 服务端会自动尝试传入的
password、同目录.txt文本中的候选密码、网盘提取码以及该画师的历史成功密码。 - 检查返回的
encrypted、needs_password与entries。若为无密码.7z(file_path以.7z结尾且encrypted == false),按冷存储策略默认跳过。
- 服务端会自动尝试传入的
- 原子解压并回收源压缩包:
POST /api/archives/extract Content-Type: application/json { "item_id": 2048, "password": "已验证密码", "target_mode": "current_folder", "recycle_source": true }
target_mode:"current_folder"(解压至当前目录)或"new_folder"(解压至同名新建子目录)。recycle_source: true:解压成功后自动将源压缩包移入回收站。
- 触发增量扫描与哈希计算:
- 解压完成后调用
POST /api/scan/folder(传入{"path": "<画师根目录或子目录>"}),待GET /api/scan/state回到"idle"后调用POST /api/hash/run计算新文件 BLAKE3 哈希。
- 解压完成后调用
- 确保哈希计算完毕:
- 调用
GET /api/hash/status,确认items.remaining == 0且scan_candidates.remaining == 0(若大于0,调用POST /api/hash/run并等待完成)。
- 调用
- 分页拉取重复作品:
- 循环调用
GET /api/items?artist_id={artist_id}&duplicates_only=true&limit=500&offset={offset}直至拉取完该画师全部重复项。
- 循环调用
- 按
content_hash分组并挑选保留项(Canonical Selection):- 将返回的
items按content_hash分组(仅处理组内数量>= 2的组)。 - 在每个哈希组中挑选 1 个保留项(Keep),其余作为 待回收项(Delete),优先保留规则如下:
- 优先保留路径/目录名不含
(1)、(2)、(3)、副本、copy等重复后缀的文件; - 优先保留已整理归档目录或
display_date/file_mtime最早的原始文件; - 默认跳过同一文件夹内部的重复文件(除非用户明确要求清理同目录内重复)。
- 优先保留路径/目录名不含
- 将返回的
- 汇报审批并移入回收站(
[STOP & ASK]):- 向用户展示去重预览表(保留路径 vs 待删路径、哈希值、释放空间)。
- 获得用户批准后,对每个待删项调用:
DELETE /api/file/delete?path=<url_encoded_file_path>
针对存在大量未打标作品的画师,优先使用服务端完全连接聚类接口,每次只需看 1~2 张簇代表图即可完成整簇打标与参考图入库:
POST /api/characters/clusters/discover
Content-Type: application/json
{
"artist_id": 104,
"min_similarity": 0.7174,
"max_clusters": 30
}响应结构要点:
clusters[]:每个簇包含:cluster_id(整数标识)item_ids(该簇包含的所有作品 ID 列表)representative_samples[](1~2 张代表图:item_id、role为"medoid"或"diverse"、preview_url如"/api/file/preview?item_id=1024&max_edge=768")text_hints[](服务端从该簇作品文件名与目录名中提取的文本词条)
Agent 下载每个簇的 representative_samples[].preview_url 并结合 text_hints 出具结构化裁决:
- 裁决枚举(
verdict):"CONFIRMED_CANON":确认为已知官方版权角色;"ORIGINAL_CHARACTER":画师原创自设(OC)/ 看板娘 / 无法对应任何官方作品的原创人物;"UNKNOWN_CLUSTER":画面模糊、线索不足或无法确认身份(服务端将跳过写入,留待后续处理)。
- 防幻觉与服务端防投毒门(Server Anti-Poisoning Gates):
- 严禁盲猜套用:不认识的冷门角色必须归为
"UNKNOWN_CLUSTER",绝不可根据发色/瞳色强行套用热门角色名。 - 文本线索门(
matched_text_hint):若判定为"CONFIRMED_CANON",必须检查text_hints数组中是否有对应原词。若有,将matched_text_hint设为该完全一致的原词(此时特征向量以verified=1正式入库);若text_hints中无匹配词,matched_text_hint必须填null(服务端仍会完成作品打标,但会将特征向量降级为verified=0候选状态,防止无文本印证的视觉误判污染检索底库)。 - 多人画面门(
is_multi_character_shot):若代表图中包含>= 2名独立角色,必须将is_multi_character_shot设为true,并在characters数组中列出所有出场角色(服务端将只对作品打标,不将多人图写入单人参考向量库)。 - OC 门:
verdict为"ORIGINAL_CHARACTER"时,服务端仅创建角色标签并打标,不将向量写入通用版权角色底库。
- 严禁盲猜套用:不认识的冷门角色必须归为
经用户确认后,调用 POST /api/characters/clusters/commit 一次性原子提交:
POST /api/characters/clusters/commit
Content-Type: application/json
{
"artist_id": 104,
"decisions": [
{
"cluster_id": 1,
"item_ids": [1024, 1025, 1026, 1039],
"verdict": "CONFIRMED_CANON",
"matched_text_hint": "雷电将军",
"is_multi_character_shot": false,
"characters": [
{ "name": "雷电将军", "series": "原神" }
],
"enroll_prototypes": []
}
]
}说明:
enroll_prototypes传空数组[]时,服务端默认将簇内的medoid与diverse代表项注册为角色原型特征;请勿传入非代表项的item_id(否则会因invalid_enroll_prototype被拒绝)。
当处理零散作品或聚类未覆盖的单图时:
- 对单件作品运行 CCIP 角色识别:
POST /api/items/1024/character-recognition?top_k=5 Content-Type: application/json { "top_k": 5 }
- 默认高置信度命中阈值为
0.7174,待复核区间为0.5739 ~ 0.7174。
- 默认高置信度命中阈值为
- 角色建档与上传标准立绘(当角色尚未入库时):
- 搜索角色是否已存在:
GET /api/characters?search=角色名 - 若不存在则新建角色:
POST /api/characters Content-Type: application/json { "name": "雷电将军" }
- 上传合格的单人竖版参考立绘(二进制原始图片字节):
POST /api/characters/{character_id}/references/upload Content-Type: application/octet-stream <raw image binary bytes>
- 搜索角色是否已存在:
- 按角色名称批量打标(
[STOP & ASK]): 推荐使用PUT /api/items/tags-by-name(无需预先查询tag_id,不存在的标签会自动创建,且自动同步至同画师同 BLAKE3 哈希的所有副本):PUT /api/items/tags-by-name Content-Type: application/json { "item_ids": [1024, 1025], "tag_names": ["雷电将军", "八重神子"], "mode": "add" }
mode说明:"add":在同画师同哈希组上追加标签并集;"set":用tag_names覆盖同画师同哈希组的全部原有标签;"remove":从同画师同哈希组移除指定标签。
- 清理冗余或错别字标签(
[STOP & ASK]):- 先通过
PUT /api/items/tags-by-name将旧标签作品迁移至标准角色名,再调用DELETE /api/tags/{tag_id}?artist_id={artist_id}删除冗余标签。
- 先通过
- 批量修改作品日期:
(支持
PUT /api/items/date Content-Type: application/json { "artist_id": 104, "item_ids": [1024, 1025], "manual_date": "2026-05-15" }
YYYY-MM-DD或YYYY-MM,传null清空手动日期。) - 对整个子文件夹就地标注角色与日期:
POST /api/folders/annotate Content-Type: application/json { "artist_id": 104, "folder": "2026-05-15 untitled", "tag_names": ["雷电将军"], "mode": "add", "manual_date": "2026-05-15" }
- 生成并执行目录重命名归档计划(默认模板
{year}/{date} {tags}):- 第一步(生成计划):
POST /api/folder-renames/refresh,请求体{"artist_id": 104}。 - 第二步(预览计划):
GET /api/folder-renames?artist_id=104,向用户展示源目录与目标目录对照表([STOP & ASK])。 - 第三步(确认并执行):
POST /api/folder-renames/confirm-all Content-Type: application/json { "artist_id": 104 }
(执行前服务端会自动创建 SQLite 在线备份并重校验路径安全性。)POST /api/folder-renames/execute Content-Type: application/json { "artist_id": 104 }
- 第一步(生成计划):
- 检查 JDownloader 桥接状态:
- 调用
GET /api/netdisk/connection,确认返回connected: true且handshaked: true。
- 调用
- 检索待派发的网盘链接:
- 方式 1(来自创作者订阅帖子):
- 调用
GET /api/pawchive/subscriptions查找画师对应的subscription_id; - 调用
GET /api/pawchive/posts?subscription_id={id}&state=external&limit=200(使用next_cursor翻页)获取所有包含外部网盘链接的帖子id。
- 调用
- 方式 2(来自画师本地
.txt文档):- 调用
GET /api/artists/{artist_id}/links或GET /api/file/text?path=...提取网盘 URL 与提取码/解压密码。
- 调用
- 方式 1(来自创作者订阅帖子):
- 派发下载任务至 JDownloader:
- 按订阅帖子 ID 批量派发:
POST /api/netdisk/jobs Content-Type: application/json { "post_ids": [501, 502], "force": false }
- 直接派发外部网盘链接与密码:
POST /api/netdisk/jobs Content-Type: application/json { "link": "https://mega.nz/file/xxxx#yyyy", "password": "optional_passcode", "force": false }
- 按订阅帖子 ID 批量派发:
- 查询任务状态与入库:
- 调用
GET /api/netdisk/jobs查看任务状态(registered、submitted、settled、confirmed)。 - 对已下载完成(
settled)的任务,可调用POST /api/netdisk/jobs/{task_id}/import自动解压并导入画师作品目录。
- 调用
Agent 可直接复用以下 Python 标准库函数调用任意接口:
import json
import os
import time
import urllib.error
import urllib.parse
import urllib.request
BASE_URL = os.environ.get("GALLERY_API_URL", "http://127.0.0.1:8899").rstrip("/")
def gallery_api(method: str, path: str, data=None, params=None, timeout: int = 60, max_retries: int = 3):
url = f"{BASE_URL}{path}"
if params:
qs = urllib.parse.urlencode({k: v for k, v in params.items() if v is not None})
if qs:
url = f"{url}?{qs}"
body = json.dumps(data).encode("utf-8") if data is not None else None
for attempt in range(1, max_retries + 1):
req = urllib.request.Request(url, data=body, method=method)
req.add_header("Accept", "application/json")
if body is not None:
req.add_header("Content-Type", "application/json")
try:
with urllib.request.urlopen(req, timeout=timeout) as resp:
raw = resp.read().decode("utf-8")
return json.loads(raw) if raw else None
except urllib.error.HTTPError as err:
# 写锁冲突(409)时自动轮询 /api/scan/state 直至 idle 后重试
if err.code == 409 and attempt < max_retries:
while True:
time.sleep(2.0)
state = gallery_api("GET", "/api/scan/state", max_retries=1) or {}
if state.get("state") in ("idle", None) and state.get("status") in ("idle", None):
break
continue
raise RuntimeError(f"HTTP {err.code} {path}: {err.read().decode('utf-8', 'replace')}")| 方法 | 路径 | 请求参数 / 载荷要点 |
|---|---|---|
GET |
/api/health |
返回 status, ok, degraded, initializing, hash_queue, backups |
GET |
/api/capabilities |
返回 read_only, write, media, ml 布尔能力标识 |
GET |
/api/logs/tail |
查询参数:source=ui|gallery|startup, lines=60(上限 2000 行 / 256 KiB) |
POST |
/api/backup |
立即触发一次 SQLite 在线备份 |
GET |
/api/operation-log, /api/operation-log/history |
查询近期操作日志、历史记录与错误摘要 |
| 方法 | 路径 | 请求参数 / 载荷要点 |
|---|---|---|
GET |
/api/items |
查询参数:artist_id, limit, offset, cursor, sort, media_type, folder, tags, tag_id, untagged, undated, inbox, duplicates_only, favorite_only, date_from, date_to, search, search_tags_only |
GET |
/api/items/{item_id} |
返回单件作品完整元数据与 tags[] |
PUT |
/api/items/{item_id}/favorite |
JSON:{"favorite": true|false} |
PUT |
/api/items/tags-by-name |
JSON:{"item_ids": [int], "tag_names": [str], "mode": "add"|"set"|"remove"} |
PUT |
/api/items/tags |
JSON:{"artist_id": int, "item_ids": [int], "tag_ids": [int], "mode": "add"|"set"|"remove"} |
PUT |
/api/items/date |
JSON:{"artist_id": int, "item_ids": [int], "manual_date": "YYYY-MM-DD"|"YYYY-MM"|null} |
POST |
/api/items/bundle |
JSON:{"artist_id": int, "item_ids": [int], "target_folder": str} |
POST / GET |
/api/items/dimensions/backfill, /status |
触发或查询缺失媒体宽高尺寸的后台补全任务 |
GET / POST |
/api/tags, /api/tags/search |
查询参数:artist_id, search, limit;新建传 {"artist_id": int, "name": str} |
PUT / DELETE |
/api/tags/{tag_id} |
删除传查询参数 ?artist_id={id};重命名传 {"artist_id": int, "name": str} |
POST |
/api/tags/propagate-hash |
将已有标签同步至同画师下相同 BLAKE3 哈希的副本 |
GET |
/api/artists, /{artist_id}, /{artist_id}/stats, /{artist_id}/folder-paths, /api/artists/duplicates |
画师列表、详情、统计覆盖率、目录路径列表与同名重复画师检测 |
GET / POST |
/api/artists/{artist_id}/links, /links/reindex |
获取或重新解析画师文本中的网盘链接与提取码 |
GET / POST / DELETE |
/api/artists/{artist_id}/profile-links, /profile-links/{link_id} |
管理画师社交主页与赞助订阅链接 |
GET |
/api/folders |
查询参数:artist_id={id},返回层级目录树与归档状态 |
PUT |
/api/folders/tags, /api/folders/tags-by-name |
JSON:{"artist_id": int, "folder": str, "tag_names": [str], "mode": "add"|"set"|"remove"} |
POST |
/api/folders/annotate |
JSON:{"artist_id": int, "folder": str, "tag_names"?: [str], "mode"?: str, "manual_date"?: str} |
POST / DELETE |
/api/folders/delete |
JSON:{"artist_id": int, "folder": str},将整个文件夹内的媒体安全移入回收站 |
| 方法 | 路径 | 请求参数 / 载荷要点 |
|---|---|---|
POST |
/api/scan, /api/scan/folder, /api/scan/stop |
增量扫描传 {"path": str} |
GET |
/api/scan/state, /ws/scan |
返回 "idle" 或 "scanning" 及进度详情 |
GET / POST |
/api/hash/status, /api/hash/run, /api/content-hash |
查询哈希队列深度、触发后台哈希批次或计算单文件 BLAKE3 |
GET / POST |
/api/move-candidates, /auto-resolve, /{id}/confirm, /{id}/ignore, /{id}/new |
查询或处理库外文件移动/重命名候选记录 |
GET / POST |
/api/folder-renames, /api/folder-renames/refresh |
查询参数 ?artist_id={id} 或 JSON {"artist_id": int} |
GET / PUT / POST |
/api/folder-renames/settings, /preview, /apply-template |
读取/修改命名模板(默认 {year}/{date} {tags})、预览或执行迁移 |
POST |
/api/folder-renames/confirm-all, /unconfirm-all, /execute, /execute-all |
JSON:{"artist_id": int},确认或执行目录归档计划 |
| 方法 | 路径 | 请求参数 / 载荷要点 |
|---|---|---|
GET |
/api/file/preview |
查询参数:item_id={id}&max_edge=800(或 path={path}&max=800) |
GET |
/api/file/text |
查询参数:path={file_path}(上限 512 KiB,返回 {"content": str}) |
GET |
/api/file, /api/file/stream |
原始媒体文件流(支持 ETag、304 与 206 分段请求) |
POST |
/api/archives/inspect |
JSON:{"item_id": int, "file_path"?: str, "password"?: str} |
POST |
/api/archives/extract |
JSON:{"item_id": int, "password"?: str, "target_mode": "current_folder"|"new_folder", "recycle_source": bool} |
GET |
/api/archives/entry |
预览或下载压缩包内单个条目 |
DELETE |
/api/file/delete |
查询参数:?path={file_path},两阶段安全移入回收站 |
GET / POST |
/api/recycle, /api/recycle/{entry_id}/restore, /api/recycle/clear |
查看回收站列表、原路还原文件及元数据快照或清空回收站 |
| 方法 | 路径 | 请求参数 / 载荷要点 |
|---|---|---|
GET / POST / DELETE |
/api/characters, /summary, /{character_id} |
搜索:?search={query};新建:{"name": str} |
POST |
/api/characters/{character_id}/references/upload |
Header:Content-Type: application/octet-stream,Body 为图片原始字节 |
GET / POST / DELETE |
/api/characters/{character_id}/references, /{ref_id}, /{ref_id}/verify, /verify-all, /discover-candidates |
查看、删除、挖掘候选参考图(verified=0)或审核转正(verified=1) |
POST / GET |
/api/characters/import-from-tags/jobs, /jobs/current, /jobs/{job_id}/cancel |
后台从已有单角色标签批量构建特征库 |
POST |
/api/items/{item_id}/character-recognition |
查询参数 ?top_k=5 及 JSON {"top_k": 5} |
POST |
/api/characters/clusters/discover |
JSON:{"artist_id": int, "min_similarity"?: 0.7174, "max_clusters"?: int} |
POST |
/api/characters/clusters/commit |
JSON:{"artist_id": int, "decisions": [...]} |
GET / PUT / POST |
/api/ml-runtime/status, /api/ml-runtime/settings, /api/ml-runtime/retry |
查询推理后端与模型下载进度、切换镜像源(official|china)或重试 |
| 方法 | 路径 | 请求参数 / 载荷要点 |
|---|---|---|
GET / POST / DELETE |
/api/pawchive/subscriptions, /{id}, /{id}/toggle, /{id}/mode, /{id}/summary, /{id}/posts |
创作者订阅增删改查、启停切换、覆盖率摘要与帖子列表 |
GET |
/api/pawchive/posts |
查询参数:subscription_id, state, day, artist_id, search, cursor, limit(≤200) |
POST |
/api/pawchive/check, /reconcile, /sync |
触发发现检查、本地目录核对或完整同步下载轮次 |
GET |
/api/netdisk/connection |
返回 connected, handshaked, state, session_id |
GET / POST |
/api/netdisk/jobs |
投递传 {"post_ids": [int], "force": bool} 或 {"link": str, "password"?: str, "force": bool} |
POST |
/api/netdisk/jobs/{task_id}/{action} |
action 支持 import(入库)、retry(重试)、cancel(取消) |