拍图猫文档图片包拉取
增量拉取已发布的图片包
图片包在网页上「发布」一次，就生成一条不可变的发布记录：版本号加一，当时的文档内容冻结成快照。你的上架工具按记录 id 增量拉，拿到快照和图片。两个接口都需要 documents:read 权限，下载图片另需 assets:read。
列出发布记录
GET /api/v1/image-pack-publications?since_id=0&limit=50| 参数 | 说明 |
|---|---|
since_id | 只返回 id 大于此值的记录，默认 0 |
limit | 每页条数，默认 50，最大 200 |
只返回当前账号的记录，按 id 升序。
{
"items": [
{
"id": 42,
"pack_id": "pk_xxxxxxxx",
"version": 3,
"style_code": "QS-2601",
"source_revision": 17,
"published_at": 1757600000000
}
],
"next_since_id": 42,
"reread_overlap": 50,
"dedupe_by": ["pack_id", "version"]
}| 字段 | 说明 |
|---|---|
id | 发布记录 id，全局递增，游标用它 |
pack_id | 图片包的主键。判断是否同一件商品按它 |
version | 这个包的第几次发布，从 1 起 |
style_code | 款号，展示用。店主可以改，也可能重复，不要当主键 |
source_revision | 冻结自草稿的第几次修订 |
published_at | 发布时间，毫秒时间戳 |
next_since_id | 下一轮的游标。没有新记录时原样返回你传的 since_id |
reread_overlap | 建议的重叠重读量，见下 |
dedupe_by | 去重键 |
增量拉取
照这三步做，不是建议，是契约：
- 记住返回的
next_since_id - 下一轮从
next_since_id - reread_overlap开始拉，不是从next_since_id - 按
(pack_id, version)去重
为什么要重叠重读：id 是数据库序列，两条并发发布可能后拿到 id 的先提交。你读到 101 就把游标推过去，100 才提交，它就永远被跳过了。重读最近 50 条把这个窗口堵上；去重让重复读到的记录无副作用。去重逻辑你的系统本来就得有（重试、重复拉取都要它），所以这等于零成本。
轮询节奏见限额。
读取一条发布记录
GET /api/v1/image-pack-publications/<id>返回上面的字段，外加 manifest：发布当时的文档快照，一个字没改，只在每张图上多挂一个 download_url。
{
"id": 42,
"pack_id": "pk_xxxxxxxx",
"version": 3,
"style_code": "QS-2601",
"source_revision": 17,
"published_at": 1757600000000,
"manifest": {
"schemaVersion": 3,
"blocks": [
{ "id": "b1", "type": "text", "content": "白底正面，突出面料纹理" },
{
"id": "b2",
"type": "images",
"items": [
{ "imageId": "img_xxxxxxxx", "download_url": "/api/file/xxxxxxxx.png" }
]
}
]
}
}快照结构
blocks 按店主排的顺序。块只有两种：
type | 字段 | 含义 |
|---|---|---|
text | content | 店主写给下游的话：这组图是什么、怎么用、注意什么 |
images | items[] | 图片列表，每项 imageId 和 download_url |
拍图猫不解释文字块的含义，也不给图片分类；读懂它、决定图放哪个位置，是你这一侧的事。
download_url 是相对路径，需要 assets:read 权限，用法见图片下载。已发布版本引用的图不会被自动清理；店主手动删掉的图 download_url 为 null，不会给一个必然 404 的地址。
早期（2026-09-10 前）发布的记录 schemaVersion 是 2，结构是 slots[].items[] 而不是 blocks。按 schemaVersion 分支即可，这些记录不会被改写。
不属于当前账号的记录返回 404。
在网页上核对
「开发者中心 → 发布流」列出你所有的发布记录，每条带一段可直接运行的 curl，用来对照你的系统拉到的是否一致。