Pinterest User Pins API

Pinterest User Pins

主要特性

• 按主页发现 Pin接受一个或多个公开 Pinterest 主页 URL，返回与每个输入主页相关联的 Pin 记录，而不是主页资料。
• 控制每个主页的采集深度results_limit 分别应用于每个主页 URL，默认值为 100，可设置为 1 到 2,000。
• 标准化 Pin、作者与媒体记录以一致结构返回 Pin ID、URL、标题、正文、公开作者字段以及图片或视频引用。
• 互动与来源上下文在来源提供时保留可见点赞数、评论数、创作者粉丝数、发布时间、collected_at、分类字段和 discovery_input。

参数

如何使用

提交公开 Pinterest 主页 URL 和每个主页的结果上限，跟踪异步任务，再通过 cursor 分页读取标准化 Pin。

1. 准备一个或多个只有单段主页路径的公开 Pinterest 主页 URL。
2. 将 urls 和可选 results_limit POST 到 /v1/pinterest/user-pins，并保存返回的 task_id。
3. 轮询 /v1/tasks/{task_id}，直到任务成功或返回失败。
4. 读取 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