深入解析B站用户动态API：调用限制、参数详解与工程化实践
适用场景
B站用户动态API允许开发者通过公开接口获取指定用户的最新动态列表，包括视频投稿、图文、纯文本、转发等多种类型，并附带发布时间、点赞/评论/转发统计等数据。典型使用场景包括：
- 个人站点或博客展示自己的B站最新动态
- 内容监控与分析工具，定时采集目标UP主动态
- 第三方社交平台或机器人转发B站动态
- 数据归档与历史备份（需注意合规性）
需要特别注意的是，该接口适用于非恶意、低频次的数据获取场景，大规模商业爬取或超量调用既违反B站用户协议，也容易触发API服务端的限流机制。
接口能力边界
- 数据源：B站官方公开API，通过第三方代理服务封装（此处为
v1.apizero.cn） - 请求方法：GET
- QPS限制：5次/秒，即单API Key每秒最多发起5次请求，超出后将返回HTTP 429状态码
- 返回数据量：每次请求返回指定用户的最新动态列表，
data.count字段表示本次返回的动态数量（最大数量以文档为准，实际测试约为20条左右，建议查看文档页确认） - 数据实时性：由于存在多层缓存，动态发布时间与实际请求时间之间可能有几分钟延迟，不适合强实时场景
- 区域与网络：仅支持中国大陆网络访问，海外节点可能因DNS或防火墙问题失败
请求参数与鉴权
请求URL
GET https://v1.apizero.cn/api/bili-dynamic查询参数
| 参数名 | 类型 | 必填 | 描述 | 示例值 |
|---|---|---|---|---|
| uid | string | 是 | B站用户UID（纯数字字符串） | 208259 |
说明：
uid参数必须为纯数字，不可包含字母或特殊符号。如果传入非法格式，API会返回400错误。
鉴权方式
请求时需要在HTTP头部添加X-API-Key字段，值为申请到的API密钥。密钥由API服务平台提供，需妥善保管，不要泄露到公开仓库或客户端代码中。
请求示例（curl）
以下是一个可复制的curl请求示例，请将$APIZERO_API_KEY替换为你自己的密钥：
curl -sS \ -X GET \ -H "X-API-Key: $APIZERO_API_KEY" \ "https://v1.apizero.cn/api/bili-dynamic?uid=208259"执行成功后，返回JSON格式数据。如果未设置API Key或Key无效，将返回401错误。
返回字段解读
响应结构
{ "code": 0, "msg": "成功", "data": { "count": 5, "list": [ { "dynamic_id": "8xxx", "stats": { "comments": 100, "forwards": 50, "likes": 1000 }, "text": "...", "type": "DYNAMIC_TYPE_AV" } ], "uid": "208259" } }字段说明
| 字段路径 | 类型 | 描述 |
|---|---|---|
| code | int | 业务状态码，0表示成功，非0表示失败 |
| msg | string | 状态描述文本 |
| data.count | int | 本次返回的动态数量 |
| data.uid | string | 请求的UID回显 |
| data.list[].dynamic_id | string | 动态唯一ID，可用于后续接口（如动态详情） |
| data.list[].type | string | 动态类型枚举，常见值：DYNAMIC_TYPE_AV（视频）、DYNAMIC_TYPE_DRAW（图文）、DYNAMIC_TYPE_WORD（纯文本）、DYNAMIC_TYPE_FORWARD（转发） |
| data.list[].text | string | 动态文本内容（可能包含换行符和表情符号，注意转义） |
| data.list[].stats.comments | int | 评论数 |
| data.list[].stats.forwards | int | 转发数 |
| data.list[].stats.likes | int | 点赞数 |
提示：除了上述示例字段外，实际返回中可能还包含
timestamp（发布时间）、origin（转发来源）等字段，以原始文档为准。
常见错误与排查
| HTTP状态码 | code | msg（示例） | 原因与排查步骤 |
|---|---|---|---|
| 400 | 1001 | 参数错误 | 检查uid是否为空、是否包含非数字字符 |
| 401 | 1002 | 未授权 | API Key缺失或错误；检查请求头X-API-Key是否正确传递 |
| 429 | 1003 | 请求过于频繁 | 超过QPS限制（5/s）；需降低请求频率或使用令牌桶限流 |
| 500 | 9999 | 服务器内部错误 | 服务端临时异常，可等待几秒后重试 |
排查建议：
- 使用
curl -v查看详细请求与响应头 - 若收到429，实现指数退避重试（如等待1s、2s、4s…）
- 若持续500，检查网络是否为纯大陆IP，或联系API服务支持
工程化注意事项
1. 本地限流保护
由于QPS为5，客户端需要主动控制请求频率，避免突发请求被限流。推荐使用令牌桶算法：
import time import requests from threading import Lock class TokenBucket: def __init__(self, rate, capacity): self.rate = rate # 每秒填充令牌数 self.capacity = capacity # 桶容量 self.tokens = capacity self.last_refill = time.time() self.lock = Lock() def consume(self, tokens=1): with self.lock: now = time.time() elapsed = now - self.last_refill self.tokens = min(self.capacity, self.tokens + elapsed * self.rate) self.last_refill = now if self.tokens >= tokens: self.tokens -= tokens return True return False bucket = TokenBucket(5, 5) # 每秒5个，桶容量5 def fetch_dynamic(uid): while not bucket.consume(): time.sleep(0.05) resp = requests.get( "https://v1.apizero.cn/api/bili-dynamic", params={"uid": uid}, headers={"X-API-Key": "YOUR_KEY"} ) return resp.json()2. 缓存策略
对于相同UID的请求结果，设置一个合适的缓存时间（如60秒），避免在短时间内重复拉取相同数据。可以使用内存缓存（如Python的cachetools）或Redis。
3. 错误重试与退避
对非400/401的错误（429、5xx）进行重试，最多重试3次，每次间隔递增（1s, 2s, 4s）。对于400/401错误不要重试，直接记录日志。
4. 日志与监控
记录每次请求的URL、耗时、状态码、返回code。当失败率（code非0或网络错误）超过阈值时发送告警。建议使用结构化日志（如JSON格式）方便后续分析。
5. 合规使用
- 只获取你自己账号或公开UP主的动态，不要尝试爬取隐私数据（如私信）
- 遵守B站开发者协议，不以任何形式出售数据
- 对获取的数据做脱敏处理（如去掉用户ID后缀？）
参考文档
- 接口文档页：https://apizero.cn/aidocs/bili-dynamic
- 原始文档（Raw Markdown）：https://apizero.cn/aidocs/bili-dynamic/raw.md