皮皮虾热榜监测 API 教程

用 Python 读取一次皮皮虾热榜快照:选择榜单预览或一个榜型,校验响应,保留精确 ID,并正确解释每日指标。

深色电影质感画面:皮皮虾热榜解析成排名的条目卡,汇入 Agent 内核

拿到一份热榜,不等于已经监测到趋势。接入前先选:需要看看有哪些榜单预览,还是已经选定一个榜型,要读它的条目?如果把所有榜混成一张排名表,“今日神评点赞”很容易被当成视频播放量;长 ID 一旦经过浮点数,还可能让后续比较认错帖子。

本次 2026-11-08 修订核对免费 inspect 与公开参考样本,没有执行新的业务请求。2026-09-27 UTC 的原实测证据继续保留。先完成一个有明确边界的读取;是否定时轮询、如何跨次比较,应在看清数据后另行决定。

先说结论

  • 榜单列表 pipixia/app/hot-search-board-list 发送 {};详情 pipixia/app/hot-search-board-detail 发送一个整数 block_type。
  • 只读 outputs[0].data,检查整数 status_code 为零,再区分 data.boards 与 data.board。
  • item_info 必须与 today_digg_num、today_show_num 一起解释;缺失和 null 都不能填成零。
  • 保留精确 item_id_str;应用内“完整榜单”链接不是 API 游标,一次快照也不能证明上涨或下跌。

沿用封面是概念插画,名称、卡片、排名和计数只是示意,不是本次验证的用户或测量结果;图中监控和 Agent 动作链并未由当前单次请求流程执行。

先选一次要读什么

手头信息选择端点请求体业务位置
想查看榜单预览榜单列表{}data.boards
已明确选定榜型榜单详情{"block_type":12}data.board.board_items

列表没有声明请求参数,不是关键词搜索。详情要求整数 block_type,12 是当前参考中的一个例子,不代表读取全部榜。所选详情 schema 没有 page、cursor、limit,不能为了得到“完整结果”自行加上这些字段。

旧说明提到 /fetch_hot_search_board_list,但 SandBase 当前路由是 /v1/api/pipixia/app/hot-search-board-list。不要把描述里的旧函数名直接拼成 URL。旧目录截图里的 GET 和目录路径也不是下面的执行方式:本例使用 API 页签的 POST 路由,请求体仅放操作参数,不加 model。

SandBase 皮皮虾目录页,在皮皮虾端点中列出 hot-search-board-list 能力 历史皮皮虾目录截图。图中的 GET 和目录路径只用于导航,当前执行方式以本文 POST 示例为准;不能凭旧图推断最新端点数量或可用性。

已有 Key、已连接 Agent 或新项目

已有 SandBase Key,就把 SANDBASE_API_KEY 配在本地运行环境或密钥管理器里。已经连接的 Agent 应复用配置,只选空请求列表或已知榜型详情,不要悄悄把两者都调一遍。密钥不放聊天正文,也不提交进代码库。

新项目可以把 SKILL.md、quickstart.md 和快速开始交给 Agent,再说明:“读取一次皮皮虾榜单快照,保留指标标签和缺失值,先展示返回字段,再讨论监控。”任务有明确交付物,也有清楚的停止点。

下面使用 Python requests。它先检查输入和凭据,再发送一次请求;设置连接与读取超时,拒绝跳转,不自动重试。网络错误和非法 JSON 的异常不会带出原响应、请求头或密钥。无需把一份完整业务响应贴到公共日志里才能排查失败。

单次请求与结构校验

Python
import os
import requests


def first_request(task, block_type=None):
    if task not in ("list", "board"):
        raise ValueError("Choose list or board")
    if task == "list" and block_type is not None:
        raise ValueError("List takes no block_type")
    if task == "board" and type(block_type) is not int:
        raise ValueError("Choose one integer block_type")
    key = os.environ.get("SANDBASE_API_KEY", "").strip()
    if not key:
        raise ValueError("Set SANDBASE_API_KEY in the local environment")
    route = "hot-search-board-list" if task == "list" else "hot-search-board-detail"
    params = {} if task == "list" else {"block_type": block_type}
    try:
        response = requests.post(
            f"https://api.sandbase.ai/v1/api/pipixia/app/{route}",
            headers={"Authorization": f"Bearer {key}", "Content-Type": "application/json"},
            json=params, timeout=(10, 90), allow_redirects=False,
        )
        if not 200 <= response.status_code < 300:
            raise RuntimeError(f"HTTP {response.status_code}; request stopped")
        body = response.json()
    except ValueError:
        raise RuntimeError("Response was not valid JSON") from None
    except requests.RequestException:
        raise RuntimeError("Network request failed or timed out") from None
    if not isinstance(body, dict) or body.get("status") != "completed":
        raise RuntimeError("SandBase request did not complete")
    outputs = body.get("outputs")
    if not isinstance(outputs, list) or not outputs or not isinstance(outputs[0], dict):
        raise RuntimeError("Missing documented output")
    payload = outputs[0].get("data")
    if not isinstance(payload, dict):
        raise RuntimeError("Missing business object")
    if type(payload.get("status_code")) is not int or payload["status_code"] != 0:
        raise RuntimeError("Provider status was not integer zero")
    data = payload.get("data")
    if not isinstance(data, dict):
        raise RuntimeError("Missing provider data object")
    if task == "list":
        boards = data.get("boards")
        if not isinstance(boards, list):
            raise RuntimeError("Missing boards array")
    else:
        board = data.get("board")
        if not isinstance(board, dict):
            raise RuntimeError("Missing selected board object")
        if type(board.get("block_type")) is not int or board["block_type"] != block_type:
            raise RuntimeError("Returned board does not match selected type")
        boards = [board]
    for board in boards:
        if not isinstance(board, dict):
            raise RuntimeError("Malformed board entry")
        entries = board.get("board_items")
        if not isinstance(entries, list) or any(not isinstance(entry, dict) for entry in entries):
            raise RuntimeError("Missing or malformed board_items array")
    return payload


if __name__ == "__main__":
    result = first_request("list")
    print("Provider data fields:", sorted(result["data"]))

想独立读取详情时,把最后的赋值改成 result = first_request("board", 12),保留后面的 print。不要在列表调用后直接追加详情,除非你确实决定发两次请求。代码使用严格整数检查,是因为 Python 中 False 可以与零比较相等,而 True 也属于整数子类;这些布尔值不应被误认成合法榜型或成功状态。

当前 parser 接受空 boards 或空 board_items 数组。字段缺失、null、字符串、非对象成员、运行未完成和 provider 失败都会报错,不伪装成“成功但没有内容”。详情还检查返回的整数 block_type 是否等于选择值,避免把另一榜的数据归到当前记录。校验后返回原业务对象,不补造 item ID、标题、评论或计数。

SandBase 皮皮虾 hot-search-board-list API 参考,展示响应结构 历史榜单列表参数与信封参考。图中旧示例的 model 字段不属于当前空请求体。旧图的空业务示例不能证明缺少 boards 也算成功;本文根据公开参考样本检查实际集合位置。

原实测记录与当前参考分开读

原运行 139c58b8-a1e1-49ac-8e16-16a3b5254f34 记录于 2026-09-27 UTC。以下截断信封逐字保留,包括字符串计数和省略号 ID;它不是刚执行的结果,省略号也不能拿去请求帖子。

JSON
{
  "id": "139c58b8-a1e1-49ac-8e16-16a3b5254f34",
  "status": "completed",
  "model": "pipixia/app/hot-search-board-list",
  "outputs": [
    {
      "data": {
        "status_code": 0,
        "data": {
          "boards": [
            {
              "block_type": 12,
              "board_items": [
                { "item_info": "今日神评点赞", "today_digg_num": "4375", "item": { "item_id_str": "…" } }
              ]
            }
          ]
        }
      }
    }
  ]
}

2026-11-08 阅读的公开 README 样本同样展示整数 status_code 零和 data 对象:列表使用 boards,详情使用 board。所选条目的 item_info 为“今日神评点赞”,today_digg_num 为 1915,today_show_num 为 null。这些是保存的参考值,不是本轮测量;样本里的时间戳也不是本文作者刚刚查询的时间。

指标必须连同标签一起保存。今日某条神评的点赞,不等于帖子累计获赞,更不等于视频播放。today_show_num 是另一种量,不能取“哪个数字非空”就统一叫互动量。旧代码用 digg or plays 展示,会在零值时切到另一字段,也会丢掉数值究竟代表什么的信息。

ID、榜型和观测范围缺一不可

有 item_id_str 时保留原字符串。公开保存样本的数值 item_id 在浏览器展示中出现精度损失,把已舍入的数字再转回字符串不能找回原位数。如果没有精确字符串 ID,应标记身份不可用,不要凭临时编号去关联记录。保留原响应,后续才能区分源字段缺失与自己的加工结果。

每条记录还要带 block_type 和可用的榜名。数组位置只表示该榜这一次快照中的位置,不是全平台热度排名。同一帖子可能出现在多个榜,仅用 item ID 当字典键会让一个榜覆盖另一个榜。以后比较至少要保持榜型、精确 ID、采集时间和指标定义一致;未出现的条目不能被分配一个虚构的末位排名。

评论和指标可以为 null。没有 god_comment 不表示帖子零评论,只表示该榜条目没提供高亮评论。city_name 是评论显示的地区标签,不足以证明作者住址或受众分布。本 helper 不把这些字段转成人口统计结论,也不以默认零值掩盖未知。

SandBase 皮皮虾 hot-search-board-detail API 参考,展示其请求与响应结构 历史榜单详情参考,展示 block_type。当前流程只选择一个榜并检查返回榜型,没有验证续页,也不自动打开列表中的全部榜单。

“完整榜单”不是续页参数

样本中的 has_more_text 和 has_more_schema 用于应用内导航,不是经验证的 API 游标。不要把 bds 链接塞进 cursor,也不要自行递增 offset。当前详情输入只有 block_type,本教程在快照返回后停止,不承诺取尽所有条目。

预览深度和榜内成员可能随请求变化。某帖子下一次没有出现,能支持的是“这一份快照未观察到”,不能直接写成已删除、互动清零或跌到榜尾。要做告警,先定义可比较的取样间隔,并处理失败或缺失的采样。本轮没有新时间序列,也没有声称实际观察到趋势。

先算清轮询的请求量

2026-11-08 免费 inspect 显示,两个端点标价均为 $0.001,符合组织内合格 API 每日共享 100 次额度,00:00 UTC 重置。资格不等于剩余额度,本轮没查余额或实际账单,不能承诺免费成功。额度重置时间也不代表皮皮虾“今日”指标的日期边界。

选择一个端点就是一次请求;独立选择列表和详情才是两次,未考虑额度时标价合计 $0.002。定时监控会按执行次数累加;自动重试、逐榜查询、帖子统计都会增加调用。当前 helper 遇到失败就停,让你先判断原因,再决定额外请求是否值得。

旧监控代码如何保留

所有原 Python 在历史归档逐字保存并附哈希。它包括宽松状态检查、空对象回退、仅按 item ID 的排名字典和轮询骨架。这些用于记录旧实验,不是当前运行指引。正文以一次选定请求替代旧主流程,不把不确定性悄悄归一化掉。

封面和头像的签名 URL 只是数据,可能过期;读取 URL 不等于已经下载。本任务不自动抓全部媒体、不请求帖子详情或统计,更不调用增加播放量的操作。SandBase 提供公开读取的接入层,不因此获得账号操作权限或第三方媒体的转载许可。

常见问题

需要登录皮皮虾吗? 所选请求使用 SandBase Key,不要求皮皮虾登录。这不代表可以访问私有或账号授权数据,本文没有涉及这些能力。

block_type 可以写字符串“12”吗? 当前 schema 要求整数,JSON 中写数字 12。Python 示例会在发请求前拒绝字符串和布尔值。

列表和详情能共用一套业务路径吗? 不能。它们共用 SandBase 信封和整数 provider 状态,但列表是 data.boards,详情是 data.board。必须按任务检查,不能把缺字段默认成空列表。

怎样继续做监控? 先保存一份有效快照和它的上下文,再决定比较口径、间隔与预算。皮皮虾 API 总览提供所选入口;本修订没有启动定时任务,也没有声称完成多轮实测。

觉得有用?分享给更多人