B站弹幕分析API调用限制与用量边界详解
适用场景
当需要批量分析B站视频弹幕中的高频重复弹幕、热门梗词汇以及整体情感倾向（正向/负向/中性）时，可使用B站弹幕分析API。该接口接收视频BV号或AV号，返回结构化的弹幕摘要和情感评分，适用于内容运营、社区监控、舆情分析等场景。开发者需重点关注调用限制与用量边界，以避免因超频或超时导致任务失败。
接口能力边界
QPS限制：2次/秒
该接口单用户每秒最多发起2次请求。若短时间内超过此阈值，服务端会返回错误码（通常为429或自定义频率限制错误）。建议在代码中实现本地令牌桶或队列限流，配合指数退避重试策略。
超时参数：timeout（单位：秒）
请求体中可选timeout字段，默认值依赖服务端配置，素材示例中设为15秒。该参数控制API等待B站上游响应与内部处理的最大时长。若视频弹幕量极大（如数万条），默认超时可能不足，可适当调高至30秒，但需平衡用户体验与连接池占用。建议根据目标视频时长与弹幕密度动态调整。
page_mode：all vs first
first：仅抓取视频第一页（通常为前几百条弹幕），适合快速预览，响应快，消耗配额少。all：抓取全部分P的所有弹幕，数据完整但耗时与弹幕总量成正比，需注意超时和QPS配额。
若视频有多P（多集），选择all会依次拉取每个分P；每P的抓取过程可能内部发起多次请求，但整体计入单次API调用。开发者应在业务可接受的精度下优先使用first以降低延迟。
limit参数：返回热词/重复弹幕数量
limit控制danmaku_summary.top_repeat_comments和top_terms中返回的条目数，例如设为10则返回前10条高频。该参数与调用配额无关，仅影响响应体大小。
请求参数与鉴权
Header
| 参数名 | 必填 | 类型 | 说明 |
|---|---|---|---|
| X-API-Key | 是 | string | 用户身份凭证，需在管理后台获取 |
| Content-Type | 是 | string | 固定为application/json |
Body（JSON对象）
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| video | string | 是 | BV号或AV号，如BV1w8RBBUEYy |
| limit | number | 否 | 高频弹幕/热词返回数量，默认值以文档为准 |
| timeout | number | 否 | 超时秒数，建议15-30 |
| page_mode | string | 否 | all或first，默认值以文档为准 |
注意：AV号需转换为纯数字字符串，如av123456应传123456，但建议统一使用BV号避免歧义。
curl请求示例
# 将 YOUR_API_KEY 替换为真实密钥 export APIZERO_API_KEY="your_key_here" 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"该示例请求抓取 BV1w8RBBUEYy 的全部弹幕，返回前10条高频重复弹幕与前10个热词。成功时返回JSON，失败时HTTP状态码非200。
返回字段详解
成功响应（HTTP 200）
{ "code": 0, "msg": "成功", "request_id": "req_abc123", "data": { "danmaku_summary": { "total_count": 1500, "top_meme": "哈哈哈哈", "top_repeat_comments": [ { "count": 120, "text": "哈哈哈哈" } ], "top_terms": [ { "count": 200, "term": "牛逼" } ] }, "sentiment_summary": { "average_score": 0.72, "label": "positive" }, "video": { "bvid": "BV1w8RBBUEYy", "title": "视频标题", "duration": 300 } } }| 字段路径 | 类型 | 说明 |
|---|---|---|
| code | number | 业务状态码，0为成功 |
| msg | string | 状态消息 |
| request_id | string | 请求唯一标识，用于排查问题 |
| data.danmaku_summary.total_count | number | 本请求拉取的弹幕总数 |
| data.danmaku_summary.top_meme | string | 出现次数最多的单条弹幕 |
| data.danmaku_summary.top_repeat_comments | array | 重复频率排名列表，每项含text和count |
| data.danmaku_summary.top_terms | array | 热词/梗排名列表，每项含term和count |
| data.sentiment_summary.average_score | float | 综合情感得分，范围0~1，越高越正向 |
| data.sentiment_summary.label | string | 情感分类标签：positive/negative/neutral |
| data.video.bvid | string | 请求的BV号 |
| data.video.title | string | 视频标题 |
| data.video.duration | number | 视频时长（秒） |
注意：total_count表示成功抓取的弹幕条数，若因超时截断可能小于实际弹幕总数，但情感分析与热词仍基于已抓取的数据计算。
常见错误处理
| 错误场景 | 可能原因 | 建议 |
|---|---|---|
| HTTP 401 | API密钥无效或未传 | 检查X-API-Key头部是否正确 |
| HTTP 429 | QPS超过2次/秒 | 加入本地限流，每次请求至少间隔500ms |
| HTTP 400 | 请求体格式错误或字段缺失 | 校验video必填，确保JSON合法 |
| 业务code非0 | 内部处理失败，如BV号不存在、超时、B站接口异常 | 查看msg字段，重试或更换视频ID |
| 响应为空数据 | 视频无弹幕或page_mode导致无内容 | 确认视频是否已关闭弹幕，尝试first模式 |
| 超时异常 | timeout设置过短或视频弹幕量极大 | 增加timeout值，若持续超时可联系服务商 |
工程化注意事项
- 并发控制：由于QPS仅为2，若需批量分析多个视频，应使用单线程顺序调用或控制并发数为1~2，配合定时器保证间隔≥500ms。
- 超时策略：设置合理的超时，建议客户端超时比
timeout参数多5秒以覆盖网络延迟。使用context或TimeoutMiddleware防止请求挂死。 - 重试机制：对网络错误和429响应采用指数退避（如1s、2s、4s），最多重试3次，避免加重服务端压力。
- 日志与监控：记录每次请求的
request_id、耗时、返回码，以便追踪调用量异常。 - 缓存结果：对于热门视频，弹幕内容短期内变化不大，可将结果缓存（如TTL=10分钟），减少重复调用。
- 分P处理：若视频有多个分P且只需主P数据，使用
page_mode: first可显著提升速度与成功率。
参考文档
- 官方文档页：https://apizero.cn/aidocs/bili-danmaku
- 原始接口描述：https://apizero.cn/aidocs/bili-danmaku/raw.md
注意：使用前请确认已获取有效的API密钥，并遵守接口的QPS限制。本文不提供SLA声明，具体可用性与性能以实际调用为准。