Pinterest Pins
Pinterest Pin 是带有标题、说明文字、创作者信息、图片或视频引用、分类、标签和可见互动的公开视觉内容。这些记录可用于归档选定内容、研究创意与主题、核对来源，并按采集时间比较公开信号。
主要特性
- 支持 Pin 直达 URL 与短链可处理一个或多个公开 Pinterest /pin/{id} URL 或 pin.it 短链，采集范围只包含提交的 Pin。
- 内容与创作者字段关联在同一条记录中返回 Pin 标题、正文、来源 URL、公开创作者身份、主页 URL 以及标准化图片或视频引用。
- 带观察时间的可见指标将可用点赞数、评论数和创作者粉丝数与 collected_at 一同返回，为会变化的公开数值保留快照时间。
- Pin 分类信息在 extra 中分别保留可用的 post_type、categories 和 hashtags，便于分析形式与主题，不与 Pin 正文混合。
参数
| 参数 | 必填 | 描述 |
|---|---|---|
urls | 必填 | 必填的公开 Pinterest /pin/{id} URL 或 pin.it 短链列表；其他 Pinterest 路径和非 Pinterest 域名会被拒绝。 |
如何使用
提交需要处理的公开 Pin，跟踪异步任务，再通过 cursor 分页读取标准化 Pin 记录。
- 准备一个或多个公开 Pinterest /pin/{id} URL 或 pin.it 短链。
- 将链接作为 urls 提交到 /v1/pinterest/pins，并保存 task_id。
- 轮询 /v1/tasks/{task_id}，直到处理成功或返回失败。
- 读取 data.results.items；has_more 为 true 时，使用 next_cursor 请求下一页。
curl -X POST "https://api.socq.ai/v1/pinterest/pins" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://www.pinterest.com/pin/123456789/"]}'
# 轮询 GET /v1/tasks/{task_id}
# 读取 data.results.items，并在 has_more 为 true 时继续使用 next_cursor最佳使用场景
- 选定 Pin 归档： 为明确的 URL 列表保存 Pin ID、来源 URL、标题、正文、创作者字段、媒体引用和发布时间。
- 创意与主题研究： 利用媒体类型、post_type、categories、hashtags、标题和正文，比较选定 Pin 的形式与主题。
- 采集时信号比较： 结合可见点赞数、评论数和创作者粉丝信息进行比较，并用 collected_at 标记每次观察时间。
使用建议
- 每项都应使用公开 /pin/{id} URL 或 pin.it 链接；主页、搜索、ideas 等其他 Pinterest 路径不符合此 endpoint 的输入规则。
- 直达链接和短链可能指向同一 Pin 时，应按返回的 id 去重。
- 媒体、created_at、categories、hashtags、post_type 和单项指标并非每条公开 Pin 都会提供，下游应按可选字段处理。
- 将 collected_at 与可见指标一同保存，以便把后续运行结果解释为不同时间的采集快照。
相关 API
需要其他类型的 Pinterest 公开数据时，可以使用以下 API。
- Pinterest User Pins API — 通过主页 URL 和每个主页的结果上限发现公开 Pin，返回标准化内容、创作者、媒体、时间和可见指标。
- Pinterest Profiles API — 通过主页 URL 获取公开身份、简介、图片、网站、可见账号数量和采集上下文。
- Pinterest Search API — 通过文本 query 和结果上限搜索公开 Pin，返回标准化内容、创作者、媒体、分类、时间和可见指标。