B站弹幕分析API的QPS边界与超时参数用法
接口能力与适用场景
B站弹幕分析接口接收视频BV号或AV号，服务端拉取弹幕并完成高频重复弹幕、热词/梗、整体情感倾向的统计。从接口设计上看，它适合以下几类场景：
- 内容运营：快速了解视频弹幕中的高频梗与用户情绪；
- 二创选题：从热词中提取观众兴趣点，辅助内容策划；
- 舆情观察：批量分析特定UP主近期视频的弹幕情感走向。
对上述场景而言，单次请求返回的是聚合后的统计结果，而不是逐条弹幕原文，因此接口并不适合做实时弹幕流或逐条弹幕下载。
QPS 限制与并发边界
接口的QPS限制为2 次/秒，即每秒最多允许2个请求。换算成时间间隔，相邻两次请求的间隔至少应为500毫秒。超过该上限时，服务端可能返回限流状态码或直接拒绝请求，具体表现以官方文档为准。
需要特别注意的是，弹幕拉取与计算本身需要时间。即使QPS限制为2，实际单次请求耗时也可能因视频时长、弹幕数量、page_mode取值而变化。例如抓取全部分P与仅抓取第一页所处理的弹幕量差异较大，耗时也不同。因此不能简单用“QPS=2”反推单请求的最大耗时，建议以实际压测结果为准。
请求参数与鉴权方式
请求方法、地址
- 方法：
POST - 地址：
https://v1.apizero.cn/api/bili-danmaku
鉴权 Headers
根据接口文档，请求头需要携带Authorization字段，但在官方curl示例中出现的是X-API-Key。这可能是不同版本或网关的映射方式。接入时建议同时检查文档页与实际网关要求，以下列curl示例为基准。若使用SDK，则按SDK统一传参。
请求体字段
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| video | string | 是 | AV号或BV号，例如BV1w8RBBUEYy |
| limit | number | 否 | 返回高频弹幕/热词数量，示例中为10 |
| timeout | number | 否 | 超时秒数，示例中为15 |
| page_mode | string | 否 | all表示抓全部分P，first表示只抓第一页 |
其中limit影响的是返回结果中热词和高频弹幕的条目数，而非拉取弹幕的总量。page_mode则直接决定服务端需要爬取的分P范围，建议根据视频是否多P进行设置。
curl 接入示例
将下方命令中的$APIZERO_API_KEY替换为自己的密钥。注意请求体为JSON，Content-Type需要设置为application/json。
curl -sS \ -X POST \ -H 'X-API-Key: $APIZERO_API_KEY' \ -H 'Content-Type: application/json' \ -d '{"video": "BV1w8RBBUEYy", "limit": "10", "timeout": "15", "page_mode": "all"}' \ 'https://v1.apizero.cn/api/bili-danmaku'timeout参数的语义是告诉服务端最多执行多少秒；一旦超过该时间，服务端应中断处理并返回超时错误。客户端侧的连接超时、读取超时也需要单独设置，避免请求长时间挂起。
返回字段解读
成功时HTTP状态码为200，响应体为JSON：
{ "code": 0, "msg": "成功", "request_id": "req_abc123", "data": { "danmaku_summary": { "top_meme": "哈哈哈哈", "top_repeat_comments": [ { "count": 120, "text": "哈哈哈哈" } ], "top_terms": [ { "count": 200, "term": "牛逼" } ], "total_count": 1500 }, "sentiment_summary": { "average_score": 0.72, "label": "positive" }, "video": { "bvid": "BV1w8RBBUEYy", "duration": 300, "title": "视频标题" } } }字段含义说明：
| 字段 | 说明 |
|---|---|
| request_id | 请求唯一ID，排障时可向服务方提供 |
| danmaku_summary.top_meme | 弹幕中的高频梗或“名场面”文本 |
| danmaku_summary.top_repeat_comments | 重复次数最多的弹幕列表，text为内容、count为出现次数 |
| danmaku_summary.top_terms | 高频热词列表，term为词语、count为出现次数 |
| danmaku_summary.total_count | 参与分析的弹幕总数量 |
| sentiment_summary.average_score | 情感得分，取值范围通常在0~1之间 |
| sentiment_summary.label | 情感倾向，positive/negative/neutral |
| video.bvid、duration、title | 视频标识、时长、标题 |
注意：code为0表示业务成功，非0时需要结合msg判断错误类型。
常见错误与排查
| 现象 | 可能原因 | 处理建议 |
|---|---|---|
| 401 Unauthorized | API Key缺失或错误 | 检查请求头是否携带正确的密钥，确认X-API-Key与文档中鉴权字段是否一致 |
| 404 Not Found | 视频不存在，或AV/BV号格式错误 | 核对视频地址中的ID，确认视频未删除、未转私 |
| 408 Request Timeout | 弹幕量过大，或timeout设置过小 | 调大timeout，或将page_mode改为first |
| 429 Too Many Requests | 请求频率超过QPS | 增加请求间隔，或退避重试 |
| 5xx | 服务端临时异常 | 等待后重试，重试时注意退避 |
当请求失败时，配合request_id与响应中的msg可以更快定位问题。若文档页有错误码表，优先参照文档。未提及的错误码以文档为准。
工程化注意事项
- 客户端限速：单实例请求间距至少保留500ms；高并发场景下使用信号量或令牌桶控制速率，避免触发限流。
- 超时设置：
timeout参数并不是唯一的超时保护。客户端应同时设置连接超时与读取超时，建议读取超时略大于服务端timeout，例如服务端15秒时，客户端读取超时设为20秒。 - 缓存策略：高频弹幕、热词与情感极性在短时间内变化不大。对同一条视频的重复分析需求，可在本地缓存半小时或一小时，降低调用压力。
- 多P视频：若目标视频有多P且只需第一P，使用
page_mode=first；否则all会显著增加处理时间与超时风险。 - 数据使用边界：接口返回的是聚合结果，不包含弹幕用户信息。若用于研究或展示，注意数据的合规性，避免传播敏感词等。
参考文档
- 接口文档页：https://apizero.cn/aidocs/bili-danmaku
- 原始文档：https://apizero.cn/aidocs/bili-danmaku/raw.md