桌面 HTTP API

PicList 桌面应用提供上传、心跳和相册删除接口。后台必须保持 PicList 运行；独立服务器部署使用 Core HTTP 服务。

开启服务

在设置的高级选项中启用上传 API，配置监听地址和端口。默认端口为 36677。仅本机使用时将监听地址设置为 127.0.0.1。

当端口已占用时，应用可能检测已有 PicList 服务或尝试后续端口。连接失败时以日志中实际监听端口为准。

接口一览

方法	路径	用途
GET / POST	/heartbeat	服务可用性检查
GET	/ 或 /upload	浏览器接口说明
POST	/upload	上传文件、路径、URL 或剪贴板
POST	/delete	使用桌面上传元数据删除对应文件与相册记录

curl http://127.0.0.1:36677/heartbeat

返回 {"success":true,"result":"alive"} 表示服务可达，但不表示图床已配置正确。

上传文件

curl -X POST "http://127.0.0.1:36677/upload?picbed=aws-s3-plist&configName=Docs" \
  -F "file=@./image.png"

picbed 使用图床 ID，configName 是已保存的配置名。均省略时使用当前默认目标。3.6 的本次目标选择不会修改持久化默认配置。

JSON 路径与 URL

curl -X POST "http://127.0.0.1:36677/upload" \
  -H "Content-Type: application/json" \
  -d '{"list":["/absolute/path/image.png","https://example.com/photo.jpg"]}'

路径必须在运行 PicList 的电脑上存在。Windows JSON 中反斜杠需要转义，可改用正斜杠路径。空列表或没有列表会触发剪贴板上传。

成功响应

{
  "success": true,
  "result": ["https://images.example.com/image.png"]
}

示例省略了 fullResult。桌面服务还会返回用于相册与删除的完整元数据；它可能包含敏感信息，应私下保存。检查 success 与结果数量，不要仅检查 HTTP 状态码。

远端访问与认证

远程上传使用设置中的上传密钥，并通过 key 查询参数发送。回环请求会由应用内部跳过密钥要求。该密钥不是整个 API 的统一权限体系：不要据此假定所有路由都受保护，也不要把服务直接暴露到不受信任网络。

代理访问时，确认代理的认证、监听范围和请求日志不会泄露密钥。

完成收尾后再报告成功

3.6 可能在远端已写入文件后，因保存相册或执行成功阶段脚本等步骤失败而返回：

{
  "success": false,
  "stage": "finalization",
  "finalizationId": "EXAMPLE_FINALIZATION_ID",
  "message": "Remote upload completed. Retry with finalizationId to finish without uploading again."
}

保留该 ID，发送 POST /upload?finalizationId=EXAMPLE_FINALIZATION_ID 完成已有任务的收尾，而不是再次传入文件。

删除接口

POST /delete 接受 {"list":[...]}，其中对象来自桌面上传响应的 fullResult。保留原始 isEncrypted 和 EncryptedData 等元数据，不能仅发送 URL 字符串或自己猜测删除字段。

删除可能使已发布的图片失效。先核对对象与目标，并检查响应中的成功、失败信息；Core 服务不提供此桌面删除接口。