B站视频评论与弹幕分析 API 教程 | SandBase

从已知 BV 号准备一次 B站视频或评论请求,检查错误与额度边界,并回看有日期的评论、弹幕样本;不自动翻页。

暗色电影感渲染:玻璃视频屏上划过弹幕光点,汇入分叉的评论气泡,再流入 Agent 核心

拿到 BV 号之后,先明确你要查的是视频资料,还是观众评论。两者用不同接口,不必为了看一页评论就跑完整条采集链路。本次接入示例只发起一笔 SandBase 请求,检查平台信封和 B站业务状态后就停止。2026-10-01 的评论、楼中楼与弹幕实验保留为历史证据,不代表今天重新验证了一套爬取程序。

先说结论

  • 已知 BV 号查视频资料,用 web/one-video;取首屏评论,用 app/video-comments。
  • 评论请求的 bv_id 与 av_id 二选一,mode=3 为热度,mode=2 为时间顺序。
  • 先读取 outputs[0].data,再检查历史响应中观察到的 B站 code 与 data 包装;缺失值保留未知。
  • 2026-11-08 检查的两个端点基础价均为 $0.001,符合组织每日共享 100 次免费额度条件;本轮没有查询剩余额度。

先选接口,再让 Agent 接入

你现在有什么需求选择与参数
已有 BV 号,想核对视频资料视频详情:必填字符串 bv_id
已知视频,想读一页观众评论视频评论:bv_id 或数字字符串 av_id 二选一,再选 mode

从公开视频地址中复制 BV 标识,例如 BV19uhb6mEWd,不要把整条 URL 填进 bv_id。这两个请求都可以直接使用 BV 号,不需要额外调用转换接口。评论 Schema 的描述要求两个标识二选一,但没有通过 required 数组强制,因此示例会在本地检查。

当前评论接口的 next_offset 是整数,默认 1。示例显式填写首屏值,不计算续页游标,不展开楼中楼,也不获取弹幕或调用模型。热评按热度筛选,不代表全体观众意见;改成时间排序,也只是改变样本顺序。

  • **已经创建 key:**放进本机 SANDBASE_API_KEY 环境变量或密钥管理器,不要发到 Agent 聊天或提交到源码。
  • **Agent 已连接 SandBase:**复用已有连接,让它搜索 Bilibili 并 inspect 选定工具的当前参数、价格。
  • **从零开发:**把 setup Skill、Markdown Quickstart、BV 号和研究问题一起交给 Agent,先准备一笔请求并说明费用,再决定执行。

可以这样布置任务:“通过 SandBase 准备一次 BV19uhb6mEWd 的首屏热评查询,复用现有连接,先检查当前契约与价格,把请求给我确认。不要自动重试、翻页或调用 LLM。”

一次请求,出错就停下来检查

2026-11-08 inspect 显示,两个端点的 base_price 都是 0.001,free_quota 为组织内符合条件的 API 共享每日 100 次,在 UTC 00:00 重置。这里只确认资格,没有确认你的剩余额度,也不承诺这次调用一定免费成功。执行前应核对当前价格与账户使用情况;超时也不能证明服务端没有执行。

先运行 python -m pip install requests,在本地配置 key,把代码保存为 bilibili_first_request.py。运行 python bilibili_first_request.py 会发送一次可能计费的请求。末尾的 video 和 comments 是两种独立选择,不要为了接入就各跑一次。这里使用 Model API 的 POST /v1/api/bilibili/...,不是历史目录展示的 GET /apis/v1/...。

Python
import os
import re
import requests


def first_request(task, *, bv_id=None, av_id=None, mode=3):
    if bv_id is not None and (not isinstance(bv_id, str) or
                             not re.fullmatch(r"BV[0-9A-Za-z]{10}", bv_id)):
        raise ValueError("Supply a BV identifier, not a video URL")
    if av_id is not None and (not isinstance(av_id, str) or
                             not re.fullmatch(r"[0-9]+", av_id)):
        raise ValueError("Supply av_id as a numeric string")
    if task == "video":
        if bv_id is None or av_id is not None:
            raise ValueError("Video details require bv_id only")
        path, params = "web/one-video", {"bv_id": bv_id}
    elif task == "comments":
        if (bv_id is None) == (av_id is None):
            raise ValueError("Choose exactly one of bv_id or av_id")
        if type(mode) is not int or mode not in (2, 3):
            raise ValueError("Use mode 3 for hot or 2 for time order")
        params = {"bv_id": bv_id} if bv_id is not None else {"av_id": av_id}
        params.update({"mode": mode, "next_offset": 1})
        path = "app/video-comments"
    else:
        raise ValueError("Choose video or comments")
    key = os.environ.get("SANDBASE_API_KEY", "").strip()
    if not key:
        raise RuntimeError("Set SANDBASE_API_KEY locally")
    try:
        response = requests.post(f"https://api.sandbase.ai/v1/api/bilibili/{path}",
            headers={"Authorization": f"Bearer {key}"}, json=params,
            timeout=(10, 90), allow_redirects=False)
        if not 200 <= response.status_code < 300:
            raise RuntimeError(f"SandBase HTTP {response.status_code}; inspect before retrying")
        body = response.json()
    except ValueError:
        raise RuntimeError("SandBase returned invalid JSON") from None
    except requests.RequestException:
        raise RuntimeError("Request failed; check run history before retrying") from None
    if not isinstance(body, dict) or body.get("status") != "completed":
        raise RuntimeError("SandBase run did not complete; inspect status and error")
    outputs = body.get("outputs")
    if not isinstance(outputs, list) or not outputs or not isinstance(outputs[0], dict):
        raise RuntimeError("Missing outputs[0]")
    payload = outputs[0].get("data")
    if not isinstance(payload, dict):
        raise RuntimeError("Missing object at outputs[0].data")
    # The Bilibili wrapper was observed in the dated response below.
    if type(payload.get("code")) is not int or payload["code"] != 0:
        raise RuntimeError("Bilibili failed or omitted its success code")
    data = payload.get("data")
    if not isinstance(data, dict):
        raise RuntimeError("Missing Bilibili data object; do not infer zero activity")
    return data


if __name__ == "__main__":
    # Choose ONE request. Change video to comments for the first hot-comment page.
    data = first_request("video", bv_id="BV19uhb6mEWd")
    print("Data keys:", sorted(data))

SandBase 状态完成,不代表 B站业务成功。helper 还要求 B站返回整数 code=0,并在业务 data 中提供对象。这一层结构有下方带日期的响应作为依据,但不能推导出所有业务字段都有保证。代码只打印键名,不输出评论者身份或凭据;空对象保持为空,缺失的计数不会改成零。

这次修订核对了接口契约,并做了 Python 离线测试,没有新增付费业务查询。5xx、连接失败或空结果都不会触发自动重试。先检查运行状态和错误,再决定下一步;应用程序正式依赖 stat、replies 或 cursor 之前,仍需检查一份经批准取得的真实响应。

历史证据:2026-10-01

以下截图、run ID 和观察来自原实验。五张旧图保留作上下文,图中价格、字段与旧导航不是当前报价。原来的多次调用 Python 已归档到仓库证据,自动重试与双信封逻辑注明过时;上方单次请求才是当前接入起点。

SandBase B站 API 目录页,列出 B站端点并标注 Free(API Free Week 期间)状态 历史截图(2026-10-01):SandBase 上的 B站目录页:共显示 38 个端点,形式是 GET /apis/v1/bilibili/...;右侧选中的“Get video playurl”状态为 Available、Free。本教程调用的是 Model API 的 POST /v1/api/bilibili/... 路由。截图摄于 API Free Week 期间,Free 是当时的标价;活动已结束,截图不能证明当前额度。本轮核对的两个端点见上方费用说明。

历史视频资料

历史测试视频是科技媒体“科技美学”发布的公开速览视频《两分钟发布会 | 小米 18 Pro / Pro Max亮相…》(BV19uhb6mEWd,发布于 2026-09-23 UTC)。题名中的“两分钟”不是实际片长:响应 duration: 710 表示 11 分 50 秒。run id 11f78f98-533c-463e-8b1f-c8de5c165752 的 outputs[0].data 节选如下:

JSON
{
  "code": 0,
  "data": {
    "aid": 117321125400871,
    "bvid": "BV19uhb6mEWd",
    "cid": 42143190519,
    "title": "两分钟发布会 | 小米 18 Pro / Pro Max亮相 小米平板9 小米手环11 小米手表S5 还有咖啡机??",
    "owner": { "name": "科技美学" },
    "pubdate": 1790178608,
    "duration": 710,
    "pages": [{ "cid": 42143190519, "page": 1, "duration": 710 }],
    "stat": {
      "view": 247824, "like": 6310, "coin": 445, "favorite": 741,
      "share": 266, "reply": 2199, "danmaku": 1404
    }
  },
  "message": "OK"
}

这份历史样本中的计数是整数。stat.reply 告诉你评论量有多大,stat.danmaku 提供了当时弹幕计数的比较依据。cid 是唯一没法从链接里直接拿到的 id。one-video 已经把它带回来了,省掉一次 bilibili/web/video-parts 调用;我单独调了一次 video-parts(run f3862a4d-034b-451e-b924-c452af230b24),对这个单 P 视频返回的是同一个 cid。多 P 视频需要另行核对各分 P 的输入与请求预算。

bilibili/web/bv-to-aid 这次也没用上:后面用到的评论端点直接接受 bv_id,而 one-video 本来就会返回 aid。另外,这条视频的 tname(分区名)是空的。

SandBase B站 web one-video 端点 API 参考 历史截图(2026-10-01):bilibili/web/one-video 参考页(Get single video data):POST /v1/api/bilibili/web/one-video,只有一个必填字符串参数 bv_id。文档的响应示例里 outputs[0].data 是空对象。

历史评论翻页观察

我最开始用的是 bilibili/web/video-comments,参数是 bv_id 加页码 pn,后来因为它不稳定才换掉。第 1 页(run b1b5caeb-43f0-43de-b4e9-44f20245f03c)返回 20 条评论,page.count 为 2199;第 2 页(run fa847910-aa82-4166-b3b4-17cf5357f45d)一条都没有,page.count 变成 0。重试第 2 页(6f7e6258-f781-4ffb-b00b-a6b1bc168090)又正常了,第 3 页(139f2dca-660c-4fa9-9c25-d5caef347687)又是空的。空页和“已经翻到底”长得一模一样,用它翻页很难写对。

app 版端点稳定得多。第一页(run 98654147-fe5a-4a47-8a2a-b23282e23575)返回 20 条评论,外加一个 cursor 对象:

JSON
{
  "all_count": 2199,
  "is_begin": true,
  "is_end": false,
  "mode": 3,
  "name": "热门评论",
  "next": 2,
  "pagination_reply": { "next_offset": "CAEiAggC" },
  "support_mode": [2, 3]
}

这里有两个看起来都像游标的字段,只有一个符合参数定义。参考里 next_offset 是整数,把字符串 "CAEiAggC" 传过去,直接返回 HTTP 400:expected integer, but got string。改传 cursor.next 就对了:next_offset: 2(run 9706405a-a879-4769-a3b5-918945e400b0)返回 20 条新评论,rpid 和第一页没有重复,next 变成 3;next_offset: 3(run af057287-9ad9-44b6-b434-4bb7c0ae93b3)又是 20 条,next 为 4。这是当时的分页实验,本轮没有重新验证续页契约;当前示例在第一页后停止。

每条评论里观察到 rpid、like、rcount、ctime 和 content.message,另外还有一个 member 对象,装着评论者的昵称、头像和 mid。历史分析把身份相关字段全部丢掉,保留下来的一条长这样:

JSON
{ "rpid": "314848758273", "text": "哈哈,我花这钱来买安卓?哈哈哈哈哈", "likes": 92, "replies": 21 }

回复数请用 rcount,别用 count。这条评论的 rcount 是 21,count 却是 47;历史楼中楼样本中的回复接口报出的总数是 21,和 rcount 一致。count 多出来的 26 是什么,从接口本身看不出来。

SandBase B站 app video-comments 端点 API 参考 历史截图(2026-10-01):bilibili/app/video-comments 参考页:可选的 av_id 或 bv_id(二选一)、mode(3 为热度,2 为时间,默认 3),以及整数类型的分页游标 next_offset,默认值为 1。

历史楼中楼样本

comment-reply 要传视频的 bv_id 和父评论的 rpid,pn 可选。上面那条 21 个回复的楼,第 1 页(run b3d5734d-0e61-4890-9cab-ab4e37b4800b)返回 20 条回复,page 为 {count: 21, num: 1, size: 20},另外有一个 root 对象装着父评论本身。第 2 页(run 54035a3e-044e-4bfa-8247-48a10125db05)却是空的,count 为 0,和 web 版评论接口的毛病一样;重试(1d3c6dc2-a2ba-4fd3-b883-bbd68c9b0c72)后 page.num 为 2、count 为 21,恢复正常。旧代码因此增加过重试,现行示例不再沿用:空值和缺失都应先检查,再决定是否发送另一笔请求。

clean_text 在回复里最有用。这一页 20 条回复里有 15 条以 回复 @某某 : 开头,等于把另一个用户的昵称写进了你的数据。去掉这个前缀,回复内容照样读得通(比如“iPhone Air,12G+256G,国行,常年5000左右…”),昵称就不进库了。

SandBase B站 web comment-reply 端点 API 参考 历史截图(2026-10-01):bilibili/web/comment-reply 参考页(Get reply to the specified comment):必填字符串 bv_id 和 rpid,可选整数页码 pn。

历史弹幕样本

这一步最出乎我意料。参考里 outputs[0].data 的类型写的是 object | array,而弹幕接口(run 3a0efcf1-8b87-43bd-a60f-b3393d4f8ce2)返回的是一段 123,221 个字符的 XML 字符串。节选:

XML
<i>
  <chatid>42143190519</chatid>
  <maxlimit>1500</maxlimit>
  <d p="99.22400,1,25,16777215,…">懂了:pro性能不足 max烫手</d>
  <d p="390.45500,5,25,16765698,…">我为什么要在手机背屏上弹吉他?</d>
</i>

每个 <d> 元素是一条弹幕,p 属性是逗号分隔的一串值。这条视频里第一个值始终落在 0.7 到 707.9 之间,正好在 710 秒的时长内,所以我把它当作播放时间(秒)来用。后面的字段里有一个看起来像发送者哈希的值。历史分析只保留时间和文本。

拿到之后先数一下条数。这条视频的 XML 里正好有 1,404 个 <d>,和 stat.danmaku 一致。换一条更早、弹幕更多的视频(BV1M1421t7hT,stat.danmaku 为 3,281),同一个接口只返回了 1,200 条,maxlimit 是 1,000(run 196f4179-b89e-457b-ae43-88828b7bef66)。所以弹幕多的视频,拿到的只是样本,别把它的条数当成视频的弹幕总数来报。

SandBase B站 web video-danmaku 端点 API 参考 历史截图(2026-10-01):bilibili/web/video-danmaku 参考页(Get Video Danmaku):只有一个必填字符串 cid。示例响应里 outputs[0].data 是空对象,而我实际调用拿到的是 XML 字符串。

历史汇总结果

我把这段代码完整跑了一遍,一共 11 次调用:one-video 一次(a8abc9c6-d802-410a-8e47-01192919cc77),热评三页(ca89f260-162e-429b-a9c4-2bb79ea01195、7bcadf99-7938-47d5-80fd-2a7505e0b9ca、647f6ca4-0535-46f2-a59b-ae913ef4373e),三条楼共六页回复(第一页是 d8fe09de-1123-4096-a067-33bab9194d8f),弹幕一次(e3c4c8af-d0b7-44ba-84b4-1c630fc8fc72)。

结果是:2,199 条评论里拉到 60 条热评;三条楼分别有 54、27、30 个回复,抽到 40、27、30 条;带问号的评论 9 条;1,404 条弹幕全部读到。

弹幕时间线明显前重后轻:第 1 分钟 210 条,第 2 分钟 184 条,第 10 分钟最少,只有 55 条,第 8 分钟又冒到 163 条。重复最多的弹幕是数字:“0” 出现 99 次,“2” 33 次,“1” 30 次。观众在回答什么,接口本身看不出来,但 “0” 集中在第 40 秒和第 460 秒附近,要看的话我会先跳到这两处。

下面是我读这 60 条评论的印象,不是统计出来的分布:价格是绝对的主线。点赞最多的一条(368 赞)认为厂商已经把国补算进了发布会定价,不少人拿价格和 iPhone 比,也有人质疑背屏和局部防窥到底有没有用。这只是对样本的编辑判断,不是情感占比测量;后续模型归纳应作为另一项明确授权的工作流。

原实验的证据范围(2026-10-01)

项目状态
POST /v1/api/bilibili/web/one-video,参数 bv_id参考文档已列明
POST /v1/api/bilibili/app/video-comments,参数 bv_id/av_id、mode、整数 next_offset参考文档已列明
POST /v1/api/bilibili/web/comment-reply,参数 bv_id、rpid、pn参考文档已列明
POST /v1/api/bilibili/web/video-danmaku,参数 cid参考文档已列明
信封 id / status / model / outputs[0].data参考文档已列明
上游外壳 {code, data, message},以及 stat、aid、cid、owner、pages仅实测观察
评论 rpid、like、rcount、content.message,cursor.next / is_end仅实测观察
回复 page.count / num / size 和 root仅实测观察
弹幕以 XML 字符串返回,p 第一个值为播放秒数仅实测观察
弹幕多的视频返回条数少于 stat.danmaku仅实测观察
web 版评论、回复接口偶发 count: 0 的空页仅实测观察

换一条视频时,先保留样本边界

做发布会复盘时,先看一份样本能回答什么,再决定下一页是否值得单独请求。保存 BV 号、获取时间、排序模式和完整参数。热评可以帮助发现值得调查的问题,但不能代表所有观众的态度,也不能证明视频为什么增长。按播放时刻分析弹幕,需要另行验证采集步骤,并使用实际数字时长。

分享研究结论前,去掉与问题无关的评论者身份,如 member、mid、头像,以及 回复 @昵称 : 前缀。点赞数、回复数和页面缺失都要与真实的零区分开;不能把接口错误当成空数据,再声称“没有人评论”。

常见问题

需要 B站 Cookie 吗? 本次两个 SandBase Schema 接收视频标识和评论选项,不需要提交 B站凭据。使用 SandBase key 鉴权;本教程不访问私有或账号绑定内容。

首笔请求免费吗? 两个端点符合组织每日共享 100 次免费额度资格,但本轮未查询余额或剩余额度;当前基础价均为 $0.001。执行前重查账户使用情况和价格。

能看最新的评论吗? 整数 mode=2 为时间顺序,默认 mode=3 为热度。首屏请求显式使用整数 next_offset=1。

空响应能证明没人评论吗? 不能。先检查执行状态和业务状态;缺失保留未知。即使热评请求成功,也不代表拿到了完整评论。

能直接复制旧响应里的字符串游标吗? 不能。当前输入类型是整数。2026-10-01 实验中字符串游标失败、cursor.next 成功,但本轮没有复测续页。实现翻页之前,要先核对一份真实响应。

更多端点见 B站 API 总览,UP 主相关任务可看 创作者研究教程。首次接入先限制为一条视频、一笔明确请求。

2026 年 SandBase Bilibili 枢纽的标价对比,见 2026 年最佳 Bilibili API:价格对比。

觉得有用?分享给更多人