使用 Pixcall HTTP API

Pixcall 自带一个只监听本机的 HTTP API。只要 Pixcall 正在运行，你就可以用脚本、命令行工具或自己的应用读取当前资源库，也可以创建和整理文件、文件夹、画板与标签。

下面会用 curl 带你完成第一次调用。你不需要先了解 REST API；跟着复制命令，把示例中的占位符替换成自己的值即可。

先准备好 Pixcall

1. 保持 Pixcall 正在运行

HTTP 服务随 Pixcall 启动，并且只接受来自本机的请求。默认 API 地址是：

http://127.0.0.1:22510/api/v1

如果 22510 端口已经被占用，Pixcall 会自动尝试下一个可用端口。因此，实际使用时请以 偏好设置 > 开发者 > HTTP API 页面显示的 API URL 为准，不要只依赖默认地址。

2. 复制 API Key

在 Pixcall 中打开 偏好设置 > 开发者 > HTTP API，复制页面中的 API Key。

本文后面的示例使用以下占位符：

• <YOUR_API_KEY>：从 偏好设置 > 开发者 > HTTP API 页面复制的 API Key。
• <YOUR_API_URL>：从同一页面复制的 API URL。

看到这些占位符时，请替换成你自己的实际值。

API Key 由 HTTP API 和 MCP 服务共用。请像保护密码一样保管它：拥有 API Key 的人可以访问你本机上的 Pixcall API。重新生成 API Key 后，旧 Key 会立即失效，所有脚本和工具都需要换成新 Key。

为了避免在每条命令里重复输入，可以先在终端设置两个变量：

export PIXCALL_API_URL="http://127.0.0.1:22510/api/v1"
export PIXCALL_API_KEY="<YOUR_API_KEY>"

如果你复制的是设置页面里的实际 API URL，请直接替换上面的 PIXCALL_API_URL，或将其写成 export PIXCALL_API_URL="<YOUR_API_URL>"。

第一次调用：确认服务可用

/health 不需要 API Key，适合用来检查 Pixcall 的 HTTP 服务是否已经启动：

curl "$PIXCALL_API_URL/health"

正常会得到类似这样的 JSON：

{
  "object": "health",
  "status": "ok",
  "api_version": "v1"
}

如果这里无法连接，请先确认 Pixcall 正在运行，并检查 API URL 中的端口是否与设置页面一致。

认证：使用 Bearer API Key

除健康检查、应用信息和能力列表外，大多数接口都需要认证。请求头的格式固定为：

Authorization: Bearer <YOUR_API_KEY>

在 curl 中通常这样写：

curl \
  -H "Authorization: Bearer $PIXCALL_API_KEY" \
  "$PIXCALL_API_URL/current-library"

成功后会返回当前资源库的信息，例如资源库 ID、路径和状态。

小提示：API Key 前面是 Bearer ，中间有一个空格。不要把 API Key 直接拼到 URL 查询参数中，也不要把它提交到 Git 仓库或公开日志。

一条最短上手路径

查看 API 支持的能力

你可以先请求能力列表，了解当前版本支持哪些资源和操作：

curl "$PIXCALL_API_URL/capabilities"

响应中包含 resources，以及可以继续查看完整接口定义的 openapi_url。

列出资源库中的文件

curl \
  -H "Authorization: Bearer $PIXCALL_API_KEY" \
  "$PIXCALL_API_URL/entries?limit=20"

列表响应的核心字段是：

• data：当前页的数据。
• has_more：是否还有下一页。
• next_cursor：下一页使用的游标；没有下一页时通常为 null。

例如，继续读取下一页：

curl \
  -H "Authorization: Bearer $PIXCALL_API_KEY" \
  "$PIXCALL_API_URL/entries?limit=20&cursor=<上一页返回的 next_cursor>"

列表接口默认每页 50 条，limit 必须是 1 到 200 之间的整数。不要用页码推测下一页，请使用响应里的 next_cursor。

按名称或内容搜索

简单的文本搜索可以直接使用 q：

curl \
  -G \
  -H "Authorization: Bearer $PIXCALL_API_KEY" \
  --data-urlencode "q=旅行" \
  --data-urlencode "limit=20" \
  "$PIXCALL_API_URL/entries"

同样的 q 参数也可以用于文件夹、画板、标签和标签组列表。文件夹还支持 parent_id，标签还支持 group_id。

读取和修改资源

接口返回的每个资源都有自己的 id。拿到 ID 后，可以读取单个条目：

curl \
  -H "Authorization: Bearer $PIXCALL_API_KEY" \
  "$PIXCALL_API_URL/entries/<entry_id>"

修改条目的名称、描述或链接时使用 PATCH：

curl -X PATCH \
  -H "Authorization: Bearer $PIXCALL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"假期照片","description":"2026 年假期整理"}' \
  "$PIXCALL_API_URL/entries/<entry_id>"

创建文件夹的例子：

curl -X POST \
  -H "Authorization: Bearer $PIXCALL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"待整理"}' \
  "$PIXCALL_API_URL/folders"

如果需要放入指定父文件夹，可以传入 parent_id：

{
  "name": "2026 年照片",
  "parent_id": "<父文件夹 ID>"
}

修改和删除操作会直接影响 Pixcall 资源库。尤其是 DELETE 是永久删除；如果只是暂时移除条目，优先使用 POST /entries/{id}/trash，需要时再使用 POST /entries/{id}/restore 恢复。

上传文件

POST /entries 使用 multipart/form-data 上传文件。最小请求需要 name 和 file_content：

curl -X POST \
  -H "Authorization: Bearer $PIXCALL_API_KEY" \
  -F "name=说明.txt" \
  -F "file_content=@./说明.txt" \
  "$PIXCALL_API_URL/entries"

还可以附带以下字段：

• parent_id：目标父文件夹 ID；不填写时使用资源库根目录。
• description：文件描述。
• link：关联链接。
• tag_ids：要添加的标签 ID；需要添加多个标签时重复这个字段。
• rating：评分。
• thumb_content：缩略图文件。

例如：

curl -X POST \
  -H "Authorization: Bearer $PIXCALL_API_KEY" \
  -F "name=海边.jpg" \
  -F "parent_id=<文件夹 ID>" \
  -F "file_content=@./海边.jpg" \
  -F "description=周末拍摄" \
  -F "tag_ids=<标签 ID>" \
  -F "rating=5" \
  "$PIXCALL_API_URL/entries"

上传接口支持较大的文件，但上传仍会占用本机资源。建议先从小文件开始验证脚本，再处理批量或大文件。

接口速查

所有接口都挂在 $PIXCALL_API_URL 下。需要认证的接口都要带 Authorization 请求头。

用途	方法	路径
检查服务	GET	/health
查看应用信息	GET	/app
查看能力列表	GET	/capabilities
查看当前资源库	GET	/current-library
查看当前选中的条目或标签	GET	/selection/entries、/selection/tags
列出、上传条目	GET、POST	/entries
搜索或统计条目	POST	/entries/search、/entries/count
查看、修改、删除条目	GET、PATCH、DELETE	/entries/{id}
获取条目路径或链接	GET	/entries/{id}/path、/entries/{id}/links
添加或移除条目标签	POST、DELETE	/entries/{id}/tags、/entries/{id}/tags/{tag_id}
移入废纸篓或恢复	POST	/entries/{id}/trash、/entries/{id}/restore
列出、创建文件夹	GET、POST	/folders
查看、修改文件夹	GET、PATCH	/folders/{id}
列出、创建画板	GET、POST	/boards
查看、修改、删除画板	GET、PATCH、DELETE	/boards/{id}
查看画板中的条目	GET	/boards/{id}/entries
列出、创建标签	GET、POST	/tags
查看、修改、删除标签	GET、PATCH、DELETE	/tags/{id}
统计标签	POST	/tags/count
列出、创建标签组	GET、POST	/tag_groups
查看、修改、删除标签组	GET、PATCH、DELETE	/tag_groups/{id}

OpenAPI 文档

完整的请求字段、响应结构和错误码可以直接从运行中的服务获取：

curl "$PIXCALL_API_URL/openapi.yaml"

也可以在 Pixcall 的 偏好设置 > 开发者 > HTTP API 页面复制 OpenAPI specification 地址，用 Swagger UI、Postman 或其他 API 工具导入。

常见问题

返回 401 Unauthorized

通常是没有传 Authorization 请求头，或者 API Key 已经失效。请确认格式如下，并重新从 Pixcall 设置页面复制：

Authorization: Bearer <YOUR_API_KEY>

返回 400 Bad Request

检查 JSON 字段名、字段类型和查询参数。列表接口的 limit 只能是 1 到 200；请求体也不接受未定义的字段。

返回 404 Not Found

确认路径中的资源 ID 属于当前资源库，并且没有把完整 URL 重复拼接。例如，如果 PIXCALL_API_URL 已经是 .../api/v1，请求路径只需要写 /entries，不要再写一次 /api/v1。

脚本突然无法连接

确认 Pixcall 仍在运行，并重新查看设置页面里的 API URL。Pixcall 重启后端口通常保持不变，但如果端口被其他程序占用，服务可能会选择下一个可用端口。