微博公开数据 API | SandBase

微博是中国公众舆论、明星新闻和热门话题最先冒头的地方,这让它的热搜榜、帖子流和资料数据在社交聆听、市场调研和 agent 工作流里格外有价值。但想用程序拿到这些数据,通常得逆向一个移动端 app、轮换 cookie,还要在网站每次改版时重建爬虫。

SandBase 的微博公开数据 API 把这层搭建成本去掉了。它通过普通 REST 端点读取微博公开的热搜、搜索结果、帖子和用户资料——一把 SandBase API key,不用微博登录,也不用 SDK。端点 API 参考是每个参数和响应信封的权威来源;下面展示的业务载荷字段名只是一个示例结构、并非保证的 schema,请以你所调端点的一份真实响应为准核对。

这不是新浪微博的官方开放平台。 如果你需要已认证的成员操作或一份授权的数据协议,请用微博官方 API;当你的流程需要的是公开、只读的数据(调研、监测)时,用 SandBase。想直接试?领取 SandBase API key,再浏览微博端点。

先说结论

• 一个 API 读取微博公开的热搜、搜索结果、帖子、评论和用户资料。
• 本文的 Model API 端点用 POST /v1/api/weibo/<path> 调用——只传该端点的参数,不用 SDK,一把 SANDBASE_API_KEY。
• 端点以自然标识为入参:用户用 uid,帖子用 status_id/mid/id,搜索用 query/keyword。
• 它只返回公开、只读数据。不能发帖、你这边不用登录、也拿不到私密或仅粉丝可见的数据;鉴权用 SandBase API key。

你到底需要哪个微博 API?

你的需求	选择	原因
发帖、以成员身份操作,或用账号授权数据	微博官方平台	成员和账号操作走微博官方。
读取公开的热搜、帖子或资料	SandBase 微博公开数据 API	普通 REST、一把 SandBase key、面向只读流程的结构化 JSON。
私密或仅粉丝可见的数据	都不适用于公开流程	这类数据不在本篇公开数据的范围内。

从微博 API 能拿到什么

整个目录横跨几个面(一个 app 面、一个 web 面,以及一个更新的 web-v2 面)。按用途归类:

• 热搜与趋势 —— 实时热搜榜和趋势排行。
• 搜索 —— 按关键词的实时搜索、话题搜索和高级搜索。
• 帖子 —— 单条帖子的详情、评论、转发和点赞。
• 用户 —— 按 uid 读取公开资料信息、时间线、视频和文章。

动手前请查每个端点的在线 API 参考,确认它所在的面和参数;可用性因端点而异。

SandBase 上的微博 API 页面——带标签的概览,加上端点列表,每个端点标有路径。

微博提供的 vs. SandBase 补上的

公开数据来自微博。SandBase 并不拥有或运营微博,它只是为符合条件的公开数据流程提供一个统一的 API 层。每一项能力变成一个稳定端点,鉴权收敛成一把 key,响应都是可预期的 JSON——于是 agent 可以沿着同一套约定串起”读热搜榜 → 搜一个话题 → 读作者的资料”,而不用再维护一个爬虫。

快速上手:第一次调用

SandBase 有不止一个 API 面。目录里可能会展示 /apis/v1/... 下的 GET 路径;本文用的是每个端点 API 参考里带厂商前缀的 Model API 路径。不要替换 HTTP 方法或 URL——按你所选端点的参考文档来。

读取实时热搜榜:

import os
import requests

resp = requests.post(
    "https://api.sandbase.ai/v1/api/weibo/web-v2/hot-search",
    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", "Weibo request did not complete"))

# 参考文档保证的是信封(id/status/model/outputs[0].data);
# 下面的业务载荷字段随端点而定——用防御式读取,
# 并以一份真实响应核对确切路径。
data = body["outputs"][0]["data"]
board = data.get("realtime", []) if isinstance(data, dict) else []
for item in board[:5]:
    print(item.get("rank"), item.get("word"), item.get("num"))

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

每个响应都用同一个信封:一个 id、一个 status、model 名称,以及一个 outputs 数组,其中唯一一项在 data 下携带载荷。这个信封才是端点参考所保证的;data 内部的操作字段按端点各自记录,有些参考在没有可确认的安全示例时会把 data 展示为空。读 outputs[0].data 之前先判 status,并查每个端点的参考了解它的运行模式。下面是一个示例响应结构——请把字段名和数值当作示例、而非保证的 schema,以一份真实响应为准核对(载荷会变、数值也会随时间变):

{
  "id": "cb805c67-4817-4926-9639-24a15e694cc9",
  "status": "completed",
  "model": "weibo/web-v2/hot-search",
  "outputs": [
    {
      "data": {
        "realtime": [
          { "rank": 0, "word": "…", "note": "…", "num": 1172365 }
        ]
      }
    }
  ]
}

failed 或 timeout 的请求会带上 error 而没有 outputs,所以先判 status。不同端点的响应结构不一样——先看一份真实响应,再按端点逐一对准字段路径。

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

能力地图

能力簇	代表端点	典型用途
热搜	weibo/web-v2/hot-search	热门话题监测
实时搜索	weibo/web-v2/realtime-search	话题与关键词发现
用户资料	weibo/web-v2/user-basic-info	按 uid 的公开账号信号
帖子详情	weibo/app/status-detail	按 status_id 读单条帖子
帖子评论	weibo/app/status-comments	互动与情感分析输入

分页方式因端点而异——若干端点接受一个页码或游标类的请求参数。具体看每个端点的 schema。

微博端点列表的一部分,横跨 app、web 和 web-v2 三个面。

在 agent 工作流里串联调用

因为每个端点共用同一套鉴权和同一个响应信封,agent 可以从一个趋势走到一个作者,而不用为每个页面单独写特例。一个常见的社交聆听模式是这样:

1. 读榜。 调 weibo/web-v2/hot-search 拿实时热搜列表,再挑你关心的话题。
2. 搜话题。 用 query 调 weibo/web-v2/realtime-search 拉匹配的帖子。
3. 给作者建档。 用 uid 调 weibo/web-v2/user-basic-info,附上像昵称和粉丝数这样的账号上下文。

每一步都返回同样的 { id, status, model, outputs } 结构,所以你的 agent 只需判一次 status,读 JSON 的那段代码在每一步都能复用。

常见用例

用微博热搜 API 做趋势监测

按计划定时轮询 weibo/web-v2/hot-search 追踪实时榜单——每一项带一个排名关键词和一个热度数字。输入:无。输出:排名的热门话题列表。端点:hot-search。完整工作流看如何监测微博热搜。

用微博搜索 API 做话题发现

用一个 query 调 weibo/web-v2/realtime-search,围绕某话题挖出帖子。输入:query。输出:匹配帖子。端点:realtime-search。

用微博资料 API 做账号调研

用 weibo/web-v2/user-basic-info 读取公开资料,拿到像昵称和粉丝数这样的字段。输入:uid。输出:结构化的资料记录。端点:user-basic-info。

为什么在 API 层做这件事

你当然可以让无头浏览器去抓微博、解析 HTML,但那条路很脆:标记会变,移动端和网页端渲染不一样,你最后维护的是一堆选择器而不是在做功能。通过一个统一 API 读取,意味着你的代码依赖命名的 JSON 字段和一个统一的响应信封,而不是页面布局。鉴权是一把 key 而不是轮换 cookie;而且因为每个端点都返回同样的 { id, status, model, outputs } 结构,重试、日志和错误处理都集中在一个你写一次、到处复用的帮助函数里。

这种一致性正是让工作流对 agent 可组合的原因。把热搜话题换成任意关键词、把一个 uid 换成另一个,代码路径完全一样。再加第四次读取——比如某条帖子的评论——它就接在同一个判状态的帮助函数后面。实际的回报是:你把时间花在数据对你的调研或监测意味着什么上,而不是花在跟一个不断变化的目标较劲、维持爬虫存活上。当你需要的不止单次读取时,查线上列表找到合适的端点,接入前先确认它的参数。

边界与限制

• 只读、公开数据。 不能发帖、关注,也拿不到私密/仅粉丝可见的数据。
• 速率与量级。 把响应当作尽力而为的读取;作为客户端韧性措施,遇到 HTTP 429 这类瞬时错误时用退避重试。
• 参数与结构随上游而定。 标识各异(uid、status_id/mid/id、query/keyword);分页是各端点自己的请求参数。先看真实响应、读 schema。
• 对照在线参考确认端点。 可用性和字段可能变化;在依赖某个具体端点之前先确认。
• 这不是微博官方合作。 SandBase 只是提供对公开数据的统一访问;请遵守微博的条款以及你使用场景下适用的规则。

常见问题

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

用什么来标识用户或帖子? 用自然标识:用户用 uid,帖子用 status_id/mid/id。搜索用 query 或 keyword。

分页怎么做? 取决于端点——若干端点接受各自的页码或游标请求参数。具体看每个端点的 schema。

能读私密或仅粉丝可见的数据吗? 不能。这个 API 只返回公开数据。私密账号和仅粉丝可见的内容都不在范围内。

从热搜榜开始

创建一把 SandBase API key,调 hot-search,先看清返回的 schema,再扩展到搜索、帖子或资料。准备好之后:

• 领取 SandBase API key
• 浏览微博端点
• 打开 hot-search 的 API 参考