Pinterest API 开发者指南（2026）
PinterestAPI开发者

Pinterest API 开发者指南（2026）

Pinterest API 能发布哪些内容、试用权限与标准权限有何区别、创建 Pin 的调用流程， 以及每个层级适用的速率限制。

Pinterest API v5 确实可以帮你创建 Pin，包括视频 Pin，但前提是你的应用通过了审核。在此之前，你的应用处于试用权限状态，期间创建的每一个 Pin 和看板都是仅创建者本人可见的沙盒对象。这一点决定了这个 API 对你是否有用，因此把它放在开头说明，而不是埋在权限范围的某个小节里。

Pinterest API 到底能发布什么内容？

它可以在已授权账户名下的看板上创建 Pin：图片 Pin 和视频 Pin，包含标题、描述和目标链接。这是一个发布型 API，而不是浏览型 API，并且仅限于已授权你的应用的账户。

评估时需要关注的几个限制：

限制对你意味着什么
试用权限是默认层级你的应用创建的 Pin 和看板都是沙盒对象，仅创建者本人可见
标准权限需要通过审核你需要提交一段使用该 API 的应用录屏，包括 OAuth 流程
视频 Pin 需要单独的上传步骤视频字节在进入 Pin 创建调用前，要先经过媒体注册和上传流程
各层级的速率限制不同试用权限按每个应用每天计算，标准权限按每个应用每个用户每分钟计算

因此，如果只是自己账户使用的内部工具，可以一直停留在试用权限。但代表客户发布内容的产品不行，因为试用权限下的 Pin 永远不会对外可见。

注： 本文数据截至 2026 年 9 月，核对自 developers.pinterest.com。各平台随时可能在不通知的情况下调整这些规则。

Pinterest 应用审核需要什么条件，要花多长时间？

你先注册应用，获得试用权限批准，然后申请升级到标准权限。Pinterest 的文档说明，升级要求你的应用已获得试用权限批准、符合开发者指南，并且需要提交一段应用通过 Pinterest API 完成某项操作的录屏，录屏中要能看到用户认证流程。终端调用或 Postman 的屏幕录像也是可接受的形式。

Pinterest 提到的最常见拒绝原因是：演示没有展示 OAuth 流程，或者没有展示应用内实际接入 Pinterest 的效果。

关于耗时：Pinterest 表示标准权限升级申请会“定期审核”，做出决定后会通过邮件通知你。它建议预留几天时间。官方没有公布具体的处理时长，因此你在别处看到的任何具体天数都只能当作猜测。把发布日期建立在“未知”之上，而不是某个承诺的服务时限之上。

认证模型本身就是常规的 OAuth 2.0：把用户重定向到 Pinterest，用授权码换取访问令牌和刷新令牌，按账户存储这两个令牌，并在过期前刷新。这部分没有什么特别之处。特别的地方在于前面那道审核关卡。

创建一个 Pin 的实际调用流程是什么？

如果图片 Pin 来自一个公开 URL，只需要一次调用。视频 Pin 则需要四个步骤，因为字节数据必须先注册、上传并处理完成，Pin 才能引用它。

  1. 注册媒体上传。 调用 POST /v5/media 并指定媒体类型。响应中会返回媒体标识符、上传 URL 和一组表单参数。
  2. 上传字节数据。 向该上传 URL 发送一个 multipart 表单，先把返回的参数作为表单字段发送，文件放在最后。这是一种类似 S3 的预签名表单提交，而不是 Pinterest 自身的接口，所以它的错误响应是 XML 格式，而不是 JSON。
  3. 轮询媒体状态。 反复读取媒体记录，直到处理成功为止。上传返回 2xx 状态码并不代表视频已经可用。
  4. 创建 Pin。 调用 POST /v5/pins，引用处理完成的媒体，加上看板、标题、描述和链接。
# 1. register
curl -X POST https://api.pinterest.com/v5/media \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"media_type":"video"}'

# 2. upload the bytes to the returned upload_url,
#    sending every returned upload parameter as a form field first
curl -X POST "$UPLOAD_URL" \
  -F key="$KEY" -F policy="$POLICY" -F "x-amz-signature=$SIG" \
  -F file=@clip.mp4

# 3. poll until the media reports a succeeded status
# 4. create the pin referencing that media id

注： 我们未能在 Pinterest 官方 API 参考文档中核实 POST /v5/media 或 POST /v5/pins 的确切请求和响应字段名：这些页面的内容是客户端渲染的，抓取时没有返回文档文字。请在编写代码前先查阅 developers.pinterest.com 上的最新 API 参考，并把上面的字段名理解为流程的大致形状，而不是可以直接照抄的结构。

人们最容易跳过的是第三步。视频 Pin 还需要一张封面图，这又是一个需要单独生成和校验的素材。我们未能在可抓取的 v5 参考页面上核实具体的封面图要求，因此在据此开发之前，请先对照最新文档确认。如果你需要为这两种 Pin 调整图片尺寸，我们的 Pinterest 帖子尺寸指南列出了最新的尺寸规格。

Pinterest API 的速率限制是多少？

官方公布的限制在不同层级之间差异很大，这也是为什么试用权限无法预示生产环境下的实际表现。

层级官方公布的限制
试用所有 API 请求合计每天 1,000 次，按每个应用计算
标准所有 API 请求合计每秒 100 次，按每个应用每个用户计算

在这个统一限制之上，各个接口类别还有自己更窄的独立限制：读取、写入、分析和转化各自都有自己的额度，Pinterest 自己的文档也指出，所有速率限制都可能在不通知的情况下调整。请核对你调用的每个接口所属的类别，而不要想当然地套用统一的数字。

注： 本文数据截至 2026 年 9 月，核对自 developers.pinterest.com。各平台随时可能在不通知的情况下调整这些规则。

真正会耗费你三周时间的地方

不是创建 Pin 的那次调用，那只需要一个下午。真正耗时的地方在这里：

  • 审核。 试用权限下无法向客户发货，而且官方没有公布处理时长。尽早提交，并且要提交一段清楚展示 OAuth 流程的录屏，因为这正是官方点名的常见失败原因。
  • 令牌刷新。 刷新令牌会过期，撤销也可能悄无声息地发生。你需要为每个已连接账户存储一个刷新令牌、一个在过期前续期的任务，以及界面中“重新连接此账户”的状态。等第一个客户的令牌失效之后才开始做这件事，代价会高得多。
  • 媒体转码。 视频 Pin 意味着你要接受用户上传的任意格式、统一编码和容器格式、生成封面图，并把结果存放在上传步骤可以流式读取的地方。这是一条媒体处理流水线，而不只是一次 API 对接。
  • 异步失败处理。 预签名上传返回 2xx 只说明字节数据已经送达，并不代表视频已处理完成，也不代表 Pin 已经存在。你需要一个状态轮询器、一套能区分临时性失败和永久性失败的重试策略，以及一种可以是“处理中”而不只是“已发布”或“失败”的帖子状态。我们在社交媒体排期 API 指南中详细讨论过这种状态模型。

把以上四项乘以你要接入的每一个平台，这才是这项工程真正的规模。自建还是购买的对比一文给出了具体的数字。

简要总结

  • 试用权限是默认层级，产生的 Pin 是沙盒对象，仅创建者本人可见。标准权限需要经过审核，并提交一段展示 OAuth 流程的视频演示。官方没有公布处理时长。
  • 来自公开 URL 的图片 Pin 只需一次调用即可完成。视频 Pin 则需要注册、上传、轮询、创建，外加一张封面图。
  • 试用权限限制为每个应用每天 1,000 次请求。标准权限为每个应用每个用户每秒 100 次请求，下面还有更细分的按类别限制。
  • 真正的工程成本在于审核、令牌刷新、转码和异步失败处理，而不是发布调用本身。

一次做好，而不是每个平台都重做一遍

如果 Pinterest 只是你需要接入的众多平台之一，上面这些针对单个平台的工作，每一次都会以不同的形式重复出现：不同的审核门槛、不同的媒体处理流程、不同的配额模型。这正是我们的 API 存在的意义。BulkPublish 通过一个 REST 接口和一个统一的帖子模型，发布到 15 个平台，OAuth、令牌刷新、媒体处理和异步状态追踪都由我们负责。

开发者文档和 REST API 集成页面介绍了具体接口和帖子生命周期。如果你更想通过界面来排期 Pin，而不是直接对接任何一个 API,如何排期 Pinterest Pin一文介绍了这条路径，免费的 Pinterest 字符计数器可以帮你把标题和描述控制在限制以内。

相关内容