Pinterest User Pins
Pinterest User Pins 是与公开主页相关联的视觉内容，包含标题、说明文字、创作者信息、媒体引用、分类、标签、时间和可见互动信号。这些内容与观察字段可用于主页 Pin 集合归档、视觉主题研究、来源核对和采集时比较。
主要特性
- 按主页发现 Pin接受一个或多个公开 Pinterest 主页 URL，返回与每个输入主页相关联的 Pin 记录，而不是主页资料。
- 控制每个主页的采集深度results_limit 分别应用于每个主页 URL，默认值为 100，可设置为 1 到 2,000。
- 标准化 Pin、作者与媒体记录以一致结构返回 Pin ID、URL、标题、正文、公开作者字段以及图片或视频引用。
- 互动与来源上下文在来源提供时保留可见点赞数、评论数、创作者粉丝数、发布时间、collected_at、分类字段和 discovery_input。
参数
| 参数 | 必填 | 描述 |
|---|---|---|
urls | 必填 | 必填的公开 Pinterest HTTP 或 HTTPS 主页 URL 列表；路径必须只有一个非保留段，Pin、search、ideas 和 pin.it URL 会被拒绝。 |
results_limit | 可选 | 每个主页 URL 最多请求的 Pin 数；默认值为 100，可设置为 1 到 2,000 的整数。 |
如何使用
提交公开 Pinterest 主页 URL 和每个主页的结果上限，跟踪异步任务，再通过 cursor 分页读取标准化 Pin。
- 准备一个或多个只有单段主页路径的公开 Pinterest 主页 URL。
- 将 urls 和可选 results_limit POST 到 /v1/pinterest/user-pins，并保存返回的 task_id。
- 轮询 /v1/tasks/{task_id}，直到任务成功或返回失败。
- 读取 data.results.items；has_more 为 true 时，使用返回的 next_cursor 请求下一页。
curl -X POST "https://api.socq.ai/v1/pinterest/user-pins" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://www.pinterest.com/example/"],"results_limit":100}'
# 轮询 GET /v1/tasks/{task_id}
# 读取 data.results.items，并在 has_more 为 true 时继续使用 next_cursor最佳使用场景
- 公开主页 Pin 集合归档： 为明确的主页 URL 保存 Pin ID、来源 URL、标题、正文、作者字段、媒体引用、时间和 discovery_input。
- 视觉与分类研究： 结合媒体类型、post_type、categories、hashtags、标题和正文，研究所选公开主页中反复出现的形式与主题。
- 跨主页信号比较： 结合可见点赞数、评论数和创作者粉丝信息比较不同主页集合，并用 collected_at 标记每次观察时间。
使用建议
- 提交路径只有一个主页段的公开 Pinterest URL；Pin 链接、pin.it 短链、搜索页和更深层路径无法通过主页校验。
- 按 urls 数量乘以 results_limit 计算请求深度和请求前 credits 预估，因为结果上限分别应用于每个主页。
- 将 discovery_input 和 collected_at 与每条 Pin 一同保存，使下游数据保留输入主页和观察时间。
- 媒体、created_at、categories、hashtags、source、作者信息和单项指标可能为空；没有返回分类时，不要推断 Pin 是由主页创建还是保存。
相关 API
需要其他类型的 Pinterest 公开数据时，可以使用以下 API。
- Pinterest Pins API — 从公开 Pin URL 获取标准化内容、创作者、媒体、分类、时间和可见指标。
- Pinterest Profiles API — 通过主页 URL 获取公开身份、简介、图片、网站、可见账号数量和采集上下文。
- Pinterest Search API — 通过文本 query 和结果上限搜索公开 Pin，返回标准化内容、创作者、媒体、分类、时间和可见指标。