SocQ 最早的 Pinterest 接口用于读取主页、单个 Pin、用户的 Pin 和搜索结果。2026-11-17 又上线了 3 个接口,工作层级不同:画板和话题。画板体现品牌或创作者如何组织灵感;话题则显示有多少人搜索某个想法,以及其下有哪些更细分的方向。
本文说明每个新接口返回什么、请求怎么写、价格多少,以及三者如何配合使用。如果你在整体对比 Pinterest 数据服务商,请参见 7 款最佳 Pinterest 采集 API。
快速回答: 带上
Authorization: Bearer $SOCQ_API_KEY,把 Pinterest 主页、画板或灵感页 URL 放进urls,发送到POST /v1/pinterest/user-boards、/board或/topic。轮询GET /v1/tasks/{task_id}直到status为succeeded,再读取data.results.items。三个接口均为每条结果 0.5 credits(按每 credit $0.005 计为 $0.0025),没有基础费用。
3 个新的 Pinterest 接口
| 接口 | 返回内容 | 输入 | 价格 |
|---|---|---|---|
| User Boards | 主页的公开画板,含名称、简介、封面、所有者、创建日期,以及 Pin、关注者、分区和协作者数量 | 主页 URL | 每个画板 0.5 credits($0.0025) |
| Board Pins | 画板中的 Pin,按画板顺序排列,含描述、保存者、原尺寸图片和 Pin 链接 | 画板 URL | 每个 Pin 0.5 credits($0.0025) |
| Topic | 话题的月搜索量及 Pinterest 推荐的细分话题 | 灵感页 URL | 每个话题 0.5 credits($0.0025) |
Pinterest User Boards:审视一个主页
Pinterest User Boards API 列出 Pinterest 主页上的全部公开画板。每个画板包含名称、简介、封面图、所有者、创建日期,以及 Pin、关注者、分区和协作者数量,另有 is_collaborative 标记,表示其他账号能否向画板添加 Pin。审视竞品的 Pinterest 或按主题筛选创作者时,这是第一步调用:各项计数能看出账号在哪些主题上投入、哪些合集真正有人关注。
curl -X POST "https://api.socq.ai/v1/pinterest/user-boards" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"urls": ["https://www.pinterest.com/marthastewart/"],
"results_limit": 25
}'
使用 https://www.pinterest.com/username/ 形式的主页 URL。results_limit 按每个主页分别生效,默认 25,可取 1 到 500。画板计数位于 metrics 下:pins_count、followers_count、sections_count 和 collaborators_count。参见 User Boards 文档。
Pinterest Board Pins:采集画板里的内容
Pinterest Board Pins API 按画板展示的顺序返回画板内的 Pin。每个 Pin 包含标题或描述、保存它的账号、原尺寸图片(media 下另有缩略图和尺寸)以及 Pin URL。把它指向你所在领域的精选画板即可收集参考图片,跟踪竞品不断往季节性画板里添加什么,或一次性构建情绪板数据集。
curl -X POST "https://api.socq.ai/v1/pinterest/board" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"urls": ["https://www.pinterest.com/lizmrodgers/moms-night/"],
"results_limit": 50
}'
使用 /{username}/{board}/ 形式的画板 URL。results_limit 按每个画板分别生效,默认 50,可取 1 到 1,000。参见 Board Pins 文档。
Pinterest Topic:Pinterest 上的关键词研究
Pinterest Topic API 帮你在为某个话题制作内容之前评估其规模。每个灵感页返回 Pinterest 公布的月搜索量(search_count)和其下推荐的细分话题(related_topics,每项含名称、简短标签和自己的灵感页 URL),例如人们与主题组合搜索的风格、场合和材质。
curl -X POST "https://api.socq.ai/v1/pinterest/topic" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"urls": ["https://www.pinterest.com/ideas/home-decor/935249274030/"]
}'
使用 /ideas/{topic}/{id}/ 形式的灵感页 URL。每个话题返回一行。由于每个细分话题都带有自己的 URL,可以把这些 URL 再传回同一接口,对比各个长尾方向的需求。参见 Topic 文档。
三个接口如何配合
典型的竞品或细分领域研究会把它们串联起来:
- 对竞品主页调用 User Boards,看哪些画板的关注者和 Pin 最多。
- 对重要画板调用 Board Pins,收集其中的图片和描述。
- 对这些主题的灵感页调用 Topic,确认月搜索需求并找到细分方向。
单个 Pin、用户自己的 Pin 或关键词搜索结果,请使用更早上线的 Pins、User Pins 和 Search 接口。全部 Pinterest 接口见 Pinterest 平台页。
认证与异步任务流程
每个请求都携带 API key 和 JSON 内容类型:
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
每次提交都会启动一个后台任务:
submit -> task_id -> queued -> running -> succeeded
\-> failed
提交响应返回 data.task_id 和 data.status。用同一个 key 轮询任务:
curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=50" \
-H "Authorization: Bearer $SOCQ_API_KEY"
任务处于 queued、running 或 failed 时,响应只包含任务元数据;failed 时读取 error_message。任务为 succeeded 时,同一响应会带上第一页标准化记录,位于 data.results.items。limit 默认 50,最大 500。若 has_more 为 true,把 results.next_cursor 作为 cursor 传入即可读取下一页。只需要几列时,fields 最多接受 50 个以逗号分隔的字段或点路径,例如画板可用 name,metrics.followers_count。
客户端超时不会取消任务,因此请用同一个 task_id 继续查询,不要重新提交而为重复采集付费。不想轮询的话,可以在提交请求中加入 callback_url;任务结束时 SocQ 会发送一次带任务摘要的 POST,之后再从任务接口读取记录。
典型任务的费用
- 列出一个主页的 25 个画板:25 × 0.5 = 12.5 credits,$0.0625。
- 从一个画板采集 1,000 个 Pin:500 credits,$2.50。
- 查询 20 个话题:10 credits,$0.05。
由于 results_limit 按每个主页或每个画板分别生效,包含多个 URL 的请求可能为每个 URL 都返回这么多行。设置上限时请考虑 URL 数量。
常见问题
User Boards 会返回私密或秘密画板吗?
不会。它只列出主页上的公开画板。
Topic 的搜索量是什么意思?
search_count 是 Pinterest 为该灵感页公布的月搜索量。updated_at 是 Pinterest 最近一次刷新该话题的时间。
能在一次请求中获取多个画板的 Pin 吗?
可以。把多个画板 URL 放进 urls。results_limit 对每个画板分别生效,每返回一个 Pin 计 0.5 credits。
画板为空时会收费吗?
没有基础费用,只对返回的画板、Pin 或话题计费。
在哪里查看 Pinterest 的价格?
每个接口的落地页都会显示费率,价格页 列出了 SocQ 每个 API 的当前 credit 费率。