皮皮虾公开数据 API | SandBase

皮皮虾是一个中文幽默短视频社区,热门段子、“神评”和爆款视频在这里冒得很快——热榜、关键词搜索和帖子流可以映射到趋势研究、梗监测和内容分析等场景。可要用程序去拿这些数据,通常意味着逆向 App、周旋于 token,而且 App 一变你就得重写一遍采集器。

SandBase 的皮皮虾公开数据 API 免去了这些前置成本。它通过普通的 REST 端点读取皮皮虾公开的热榜、搜索结果、用户和帖子——只用一个 SandBase API 密钥,不需要登录皮皮虾、也不需要 SDK。端点 API 参考是每个参数和响应信封的权威来源。参考只保证信封本身;下面的业务负载字段名来自我实际跑的调用(测试于 2026-09-27,UTC),是示意性的、仅供观测——并非文档保证——所以请以真实响应为准核对,因为负载会随时间变化。

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

先说结论

• 一套 API 即可读取皮皮虾公开的热榜、关键词搜索、用户资料和帖子。
• 本文的 Model API 端点用 POST /v1/api/pipixia/<path> 调用——只传该端点的参数,无 SDK,一个 SANDBASE_API_KEY。
• 端点以自然标识为入口:搜索用 keyword,用户用 user_id(以字符串传)。
• 只返回公开、只读数据。你这边无需发帖、无需平台登录、不涉及私有数据;用 SandBase API 密钥鉴权即可。

你需要哪种皮皮虾 API?

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

皮皮虾 API 能取到什么

目录建立在一个 app 面上。按用途分组:

• 热榜 — 热搜榜列表和某个榜的详情。
• 搜索 — 跨帖子和用户的关键词搜索。
• 用户 — 公开用户信息、他们的帖子列表,以及粉丝/关注列表。
• 帖子与话题 — 帖子详情、帖子统计和话题详情。

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

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

皮皮虾提供什么,SandBase 补什么

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

快速上手:第一次调用

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

读取热搜榜列表。在我的测试里该端点接受空 JSON body,但端点的线上参考才是权威的请求契约——它生成的示例可能包含一个 model 字段,所以动手前请以参考为准确定确切 body:

import os
import requests

resp = requests.post(
    "https://api.sandbase.ai/v1/api/pipixia/app/hot-search-board-list",
    headers={
        "Authorization": f"Bearer {os.environ['SANDBASE_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={},
)
resp.raise_for_status()
body = resp.json()
if body.get("status") != "completed":
    error = body.get("error", {})
    raise RuntimeError(error.get("message", "皮皮虾请求未完成"))

# 在我的抓取里,负载是一个带 status_code、message 和 data 对象的上游对象。
# 参考并不保证这些业务字段,所以一切都防御式读取、并对照真实响应核对。
payload = body["outputs"][0]["data"]
if isinstance(payload, dict) and payload.get("status_code") not in (0, None):
    raise RuntimeError(payload.get("message", "上游错误"))
boards = payload.get("data", {}).get("boards", []) if isinstance(payload, dict) else []
print(len(boards), "个榜")

curl -X POST https://api.sandbase.ai/v1/api/pipixia/app/hot-search-board-list \
  -H "Authorization: Bearer $SANDBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

参考只保证信封:一个 id、一个 status、model 名称,以及——在 completed 运行上——一个 outputs 数组,其唯一元素在 data 下承载数据。failed 或 timeout 的运行则带 error 而没有 outputs,所以读取 outputs[0].data 前先根据 status 分支判断。信封以下的一切都是示意性的、并非文档保证:在我的抓取里(热榜 run id 08d73dd2-2498-47aa-8cdc-87056e1426d1,测试于 2026-09-27,UTC),负载是一个带 status_code、message 和 data 对象的上游对象。参考的业务负载示例是刻意留空的,所以请把这些字段名当作仅供观测,防御式检查 status_code == 0,并在依赖它们之前对照你自己的真实响应核对:

{
  "id": "08d73dd2-2498-47aa-8cdc-87056e1426d1",
  "status": "completed",
  "model": "pipixia/app/hot-search-board-list",
  "outputs": [
    {
      "data": {
        "status_code": 0,
        "message": "success",
        "data": {
          "boards": [
            { "board_items": [ { "item_info": "今日神评点赞", "today_digg_num": "4375" } ] }
          ]
        }
      }
    }
  ]
}

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

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

能力地图

能力簇	代表端点	典型用途
热榜	pipixia/app/hot-search-board-list	热门话题监测
榜详情	pipixia/app/hot-search-board-detail	读取某个榜的条目
搜索	pipixia/app/search	关键词内容发现
用户	pipixia/app/user-info	按 user_id 的公开用户信号
帖子详情	pipixia/app/post-detail	读取单条帖子

分页是每端点各自的、以参考为准——比如 Search 参考记录了一个可选 offset(取自上一次响应)加一个可选 search_type;user-post-list 参考记录了一个 cursor。请查阅每个端点的结构确定确切分页参数,不要假定共用同一套约定。

皮皮虾端点列表的一角,在 app 面上。

在 Agent 工作流中链式调用

因为每个端点共享同一套鉴权和同一个响应信封,Agent 可以从一个趋势一路走到一条帖子,而不用为每个面单独写特例。一个常见的内容研究模式是这样:

1. 读榜。 调用 pipixia/app/hot-search-board-list 拿到趋势榜,再挑出你关心的话题。
2. 搜关键词。 用一个 keyword 调用 pipixia/app/search 拉取匹配的帖子和用户,用参考里的可选 offset(取自上一次响应)翻页。
3. 读用户。 用一个 user_id(字符串)调用 pipixia/app/user-info,再调 pipixia/app/user-post-list 拿他们的帖子。user-info 参考说明 user_id 可从分享链接获得;在我的抓取里一条搜索结果也带了 user_id 字段——请就你的流程对照参考确认标识来源。

每一步都返回相同的 { id, status, model, outputs } 信封;在我的抓取里内层负载还带了一个 status_code,所以你的 Agent 可以按 status 分支、防御式检查 status_code,并在每一步复用同一段读 JSON 的代码。

常见用例

皮皮虾热榜 API 做趋势监测

按计划轮询 pipixia/app/hot-search-board-list 追踪趋势榜——每个榜带一列带互动计数器的条目。输入:无。输出:带条目的榜。端点:hot-search-board-list。

皮皮虾搜索 API 做内容发现

用一个关键词运行 pipixia/app/search 梳理某话题周边的帖子和用户,再用参考里的可选 offset 翻页。输入:一个关键词。输出:匹配结果。端点:search。

皮皮虾用户 API 做创作者研究

用 user_id 调用 pipixia/app/user-info 读取公开用户,再调 pipixia/app/user-post-list 拿他们的帖子。输入:一个 user_id(字符串)。输出:用户记录和帖子列表。端点:user-info、user-post-list。

为什么放在 API 层来做

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

正是这种一致性让工作流对 Agent 而言可组合。把热榜话题换成任意关键词、把一个 user_id 换成另一个,代码路径完全一样,连那个 status_code 检查都一样。再加第四个读取——比如某条帖子的详情——它也照样接在同一个辅助函数后面。实际的收益是:你的时间花在”数据对你的研究意味着什么”上,而不是花在维持一个采集器去追一个移动靶。当你需要的不止是单次读取时,在线上列表里查到合适的端点,并在接入前确认它的参数。

局限与边界

• 仅公开、只读数据。 不发帖、不关注、不涉及私有或仅账号可见的数据。
• 速率与量级。 把响应当作尽力而为的读取;作为客户端侧的韧性措施,遇到 HTTP 429 等瞬时错误时按退避策略重试。
• 参数与结构随上游面而定。 搜索用 keyword;user_id 是字符串;在我的抓取里上游把结果包在 { status_code, data, message } 里——这些业务字段不在参考保证之列,所以防御式检查 status_code == 0。分页是每端点各自的(比如 Search 参考记录了一个可选 offset)。先看一次真实响应、读一遍结构。
• 只读范围。 本文只覆盖读取端点。完整的皮皮虾目录可能列出写操作类端点(例如 increase-post-view-count);那些不在本文范围内,也不属于这个只读工作流。
• 以线上参考核对端点。 可用性和字段可能变化;在依赖某个具体端点前先确认。
• 这不是皮皮虾官方合作。 SandBase 提供对公开数据的统一访问;请就你的使用场景遵守皮皮虾条款和适用规则。

常见问题

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

什么标识一个用户或一次搜索? 搜索用 keyword,用户用 user_id(以字符串传)。user-info 参考说明 user_id 可从分享链接获得;在我的抓取里一条搜索结果也带了 user_id 字段——请就你的流程对照参考确认来源。

为什么 data 里还有一个 status_code? 皮皮虾把结果包在一个上游 { status_code, data, message } 对象里。读内层 data 前先检查 status_code == 0,再防御式读取业务字段。

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

从热榜开始

创建一个 SandBase API 密钥,调用 hot-search-board-list,在扩展到搜索、用户或帖子之前先检查返回的结构。准备好后:

• 获取 SandBase API 密钥
• 浏览皮皮虾端点
• 打开 hot-search-board-list API 参考