Pinterest 公开数据 API | SandBase

Pinterest 是一台视觉发现引擎——人们在这里筹划家装、穿搭、食谱和旅行。这让它成为趋势研究、电商灵感和创意规划的丰富信号。可要用程序去拿这些数据,通常意味着跟无头浏览器较劲,而且站点一变你就得重写采集器。

SandBase 的 Pinterest 公开数据 API 把这些前置成本换成了普通 REST。它通过简单端点读取 Pinterest 公开的搜索结果、用户 board 和 board 上的 pin——一个 SandBase API 密钥,不需要登录 Pinterest、也不需要 SDK。端点 API 参考是每个参数和响应结构的权威来源;下面的字段名来自我实际跑的调用(测试于 2026-09-27,UTC),仅作为一次观测到的结构展示——请以真实响应为准核对,因为负载会随时间变化。

这不是 Pinterest 官方 API。 当你需要经过授权的会员操作,或需要有正式授权协议的数据时,请走 Pinterest 官方开发者平台。当你的工作流需要用于研究和监测的公开、只读数据时,用 SandBase。想上手?获取 SandBase API 密钥,然后浏览 Pinterest 端点。

先说结论

• 一套 API 即可读取 Pinterest 公开的搜索结果、用户 board 和 board 上的 pin。
• 每个端点都是 POST /v1/api/pinterest/<path>——只传该端点的参数,无 SDK,一个 SANDBASE_API_KEY。
• 端点以自然输入为入口:搜索用 query,用户 board 用 handle,board 或 pin 用 url。
• 只返回公开、只读数据。无需发帖、无需平台登录、不涉及私有数据;用 SandBase API 密钥鉴权即可。

关于这个端点响应结构的说明

大多数 SandBase 端点返回一个 outputs 数组。而这个 Pinterest 面返回的是单个 output 对象(注意是单数),与 id、model、status 并列。在一次 completed 运行里,我看到 output 带一个 success 布尔、一个结果列表(pins 或 boards)和一个用于翻页的 cursor。因为目录里各端点结构不同,动手前请始终以你所调用端点的线上参考核对确切信封。

你需要哪种 Pinterest API?

你的需求	选择	原因
发帖、保存 pin,或以会员身份操作	Pinterest 官方平台	会员和账号级操作应通过 Pinterest 直接进行。
读取公开的搜索、board 或 pin	SandBase Pinterest 公开数据 API	普通 REST、一个 SandBase 密钥、结构化 JSON,面向只读工作流。
私有或仅账号可见的数据	两种公开方案都不适用	这类数据不在本篇公开数据指南范围内。

Pinterest API 能取到什么

按用途分组:

• 搜索 — 关键词搜索,返回公开 pin。
• 用户 board — 给定 handle 的公开 board。
• Board — 一个 board 上的 pin,用它的 url 定位。
• Pin — 单条 pin 的数据,用它的 url 定位。

动手前请以每个端点的线上 API 参考为准核对参数;可用性因端点而异。

SandBase 上的 Pinterest API 页面——带标签的概览和端点列表,每个端点都标了路径。

Pinterest 提供什么,SandBase 补什么

公开数据来自 Pinterest。SandBase 并不拥有或运营 Pinterest,它为符合条件的公开数据工作流提供一层统一的 API。每个能力都成为一个稳定端点,鉴权收敛为单个密钥,响应回来是可预测的 JSON——于是 Agent 可以沿着”从关键词到一组 pin”、或”从 handle 到它的 board”这样一条约定链式走,而不用维护采集器。

快速上手:第一次调用

SandBase 暴露不止一个 API 面。目录里可能显示 /apis/v1/... 下的 GET 路径;本文使用每个端点 API 参考上标注的带厂商前缀的 Model API 路径。不要擅自改动 HTTP 方法或 URL——以你所选端点的参考为准。

按关键词搜索公开 pin:

import os
import requests

resp = requests.post(
    "https://api.sandbase.ai/v1/api/pinterest/search",
    headers={
        "Authorization": f"Bearer {os.environ['SANDBASE_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={"query": "home office setup"},
)
resp.raise_for_status()
body = resp.json()
if body.get("status") != "completed":
    error = body.get("error", {})
    raise RuntimeError(error.get("message", "Pinterest 请求未完成"))

# 这个面返回单个 `output` 对象(而不是 `outputs` 数组)。
output = body.get("output", {})
if output.get("success"):
    pins = output.get("pins", [])
    print(len(pins), "个 pin,cursor:", bool(output.get("cursor")))

curl -X POST https://api.sandbase.ai/v1/api/pinterest/search \
  -H "Authorization: Bearer $SANDBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "home office setup"}'

响应带一个 id、一个 status、model 名称,以及——在 completed 运行上——单个 output 对象,含一个 success 标记、一个结果列表和一个 cursor。failed 或 timeout 的运行则带 error,所以读取 output 前先按 status 分支判断。下面是我那次搜索调用的一段裁剪后的真实响应(搜索 run id bb49ff54-271a-403b-82c7-ca510922c580,测试于 2026-09-27,UTC)——数值会随时间变化,所以请把字段名当作观测到的,并对照真实响应核对:

{
  "id": "bb49ff54-271a-403b-82c7-ca510922c580",
  "model": "pinterest/search",
  "status": "completed",
  "output": {
    "success": true,
    "pins": [ { "id": "…", "title": {}, "url": "https://www.pinterest.com/pin/…" } ],
    "cursor": "…"
  }
}

响应结构因端点而异——请检查一次真实响应,并逐端点确定精确的字段路径。

端点 API 参考是每个参数名和响应路径的事实来源。

能力地图

能力	端点	输入	典型用途
搜索	pinterest/search	query	关键词 pin 发现
用户 board	pinterest/user-boards	handle	某用户的公开 board
Board	pinterest/board	url	一个 board 上的 pin
Pin	pinterest/pin	url	单条 pin 的数据

翻页用 output 里返回的 cursor;下一次请求把它传回去。确切参数名请读每个端点的结构。

Pinterest 端点列表的一角。

在 Agent 工作流中链式调用

因为每个端点共享同一套鉴权和一致的 output 信封,Agent 可以从一个 handle 走到它的 board、再走到 board 上的 pin,而不用为每个面单独写特例。一个常见的研究模式是这样:

1. 列出某用户的 board。 用一个 handle 调用 pinterest/user-boards;读 output.boards,每个都带一个 url。
2. 打开一个 board。 用一个 board url 调用 pinterest/board 读 output.pins。
3. 再搜更多。 用一个 query 调用 pinterest/search 扩大集合,用 output.cursor 翻页。

每一步都返回相同的 { id, status, model, output } 结构,所以你的 Agent 只需按 status 分支一次,并在每一步复用同一段读 JSON 的代码。

常见用例

Pinterest 搜索 API 做趋势发现

用一个 query 运行 pinterest/search 梳理某主题周边的 pin,再用返回的 cursor 翻页。输入:一个 query。输出:output.pins 加一个 cursor。端点:search。

Pinterest board API 做创作者研究

用 handle 调用 pinterest/user-boards 读某用户的公开 board,再用它的 url 调用 pinterest/board 打开一个 board。输入:一个 handle,再一个 board url。输出:output.boards,再 output.pins。端点:user-boards、board。

Pinterest pin API 做素材查询

用它的 url 调用 pinterest/pin 读单条 pin。输入:一个有效的 pin url。输出:该 pin 的数据。端点:pin。注意 pin url 必须指向一个存在的公开 pin。

为什么放在 API 层来做

你当然可以用无头浏览器指向 Pinterest、解析它的负载,但这条路很脆:站点会变,会话会轮换,你维护的是采集器而不是在做产品。通过一层统一 API 来读,意味着你的代码依赖的是有名字的 JSON 字段和单个响应信封,而不是某个页面内部实现。鉴权是一个密钥,而且因为每个端点都返回相同的 { id, status, model, output } 结构,重试、日志和错误处理都可以收进一个你写一次、处处复用的辅助函数里。

正是这种一致性让工作流对 Agent 而言可组合。把一个 query 换成另一个、把一个 handle 换成下一个,代码路径完全一样。在同一个辅助函数后面再加一个 board 读取,它也照样接上。实际的收益是:你的时间花在”数据对你的研究意味着什么”上,而不是花在维持一个采集器去追一个移动靶。当你需要的不止是单次读取时,在线上列表里查到合适的端点,并在接入前确认它的参数。

局限与边界

• 仅公开、只读数据。 不发帖、不保存、不涉及私有或仅账号可见的数据。
• 单 output 信封。 这个面返回一个带 success 标记的 output 对象——不是 outputs 数组。检查 success 并按 status 分支。
• pin 和 board 需要一个有效的 url。 pin url 必须指向一个存在的公开 pin;board url 来自一次 user-boards 结果。
• 速率与量级。 把响应当作尽力而为的读取;作为客户端侧的韧性措施,遇到 HTTP 429 等瞬时错误时按退避策略重试。
• 以线上参考核对端点。 可用性和字段可能变化;在依赖某个具体端点前先确认。
• 这不是 Pinterest 官方合作。 SandBase 提供对公开数据的统一访问;请就你的使用场景遵守 Pinterest 条款和适用规则。

常见问题

我需要 Pinterest 开发者应用或登录吗? 不需要。你用自己的 SANDBASE_API_KEY 向 SandBase 鉴权。这些读取端点不需要你这边有 Pinterest 账号或 OAuth。

为什么这个端点返回 output 而不是 outputs? 这个 Pinterest 面返回单个 output 对象,含一个 success 标记、一个结果列表和一个 cursor。其他 SandBase 端点可能返回 outputs 数组——请始终以你所调用端点的线上参考核对信封。

什么标识一次搜索、某用户的 board、一个 board 或一条 pin? query 驱动搜索,handle 驱动 user-boards,url 定位一个 board 或一条 pin。

我能读私有或仅账号可见的数据吗? 不能。这套 API 只返回公开数据。私有和账号授权内容不在范围内。

从一次搜索开始

创建一个 SandBase API 密钥,用一个 query 调用 search,在扩展到 board 和 pin 之前先检查返回的 output。准备好后:

• 获取 SandBase API 密钥
• 浏览 Pinterest 端点
• 打开 search API 参考