一、接口基础信息
接口地址：POST https://http://o0b.cn/ibrad
协议：HTTPS
数据格式：JSON
默认限流：单应用 QPS=1（企业资质可申请提额至 QPS20~50）
单页上限：page_size 最大 20 条，游标分页
二、请求头公共参数（必传）
| Header 参数 | 是否必填 | 说明 |
|---|---|---|
| Content-Type | 是 | application/json |
| X-AppKey | 是 | 开放平台应用 Key |
| Authorization | 是 | Bearer {access_token} 授权令牌，2 小时过期 |
三、业务请求 Body 全入参
| 参数名 | 类型 | 必填 | 取值 / 说明 |
|---|---|---|---|
| note_id | string | ✅是 | 32 位笔记唯一 ID，笔记链接提取 |
| cursor | string | ❌否 | 分页游标；空 = 第一页；下一页取返回 data.cursor |
| page_size | int | ❌否 | 单页条数，范围 1~20，默认 20 |
| sort | string | ❌否 | hot：热门排序（点赞高优先）；time：最新时间排序 |
| need_sub_comment | bool | ❌否 | true 返回楼中楼子评论；false 只展示一级评论 |
四、完整返回 JSON 结构 + 全输出字段
# coding:utf-8
"""
Compatible for python2.x and python3.x
requirement: pip install requests
"""
from __future__ import print_function
import requests
#API url=https://console.open.onebound.cn/console/?i=Brad
# 请求示例 url 默认请求参数已经做URL编码
url = "https://api-gw.cn/smallredbook/item_review/?key=<您自己的apiKey>&secret=<您自己的apiSecret>&num_iid=670202b0000000002a032d2d&cursor="
headers = {
"Accept-Encoding": "gzip",
"Connection": "close"
}
if __name__ == "__main__":
r = requests.get(url, headers=headers)
json_obj = r.json()
print(json_obj)1. 外层公共字段
| 字段 | 说明 |
|---|---|
| code | 0 = 成功；429 = 限流；401=token 失效；403 = 权限不足；10001 = 笔记不存在 |
| msg | 错误 / 成功描述文本 |
2. data 分页汇总字段
| 字段 | 说明 |
|---|---|
| total_comment | 笔记总评论数 |
| has_more | 是否存在下一页评论（true 继续翻页） |
| cursor | 下一页请求游标，循环传入 cursor 参数翻页 |
3. 一级评论 comments 核心字段
| 字段 | 业务用途（AI / 舆情分析） |
|---|---|
| comment_id | 评论唯一主键，数据去重 |
| content | 评论文本，情感分析、关键词提取核心 |
| create_time | 时间戳，转换日期做时序趋势统计 |
| like_count | 评论热度权重，筛选高互动优质评论 |
| reply_count | 楼中楼总量 |
| is_top | 是否置顶评论，置顶优先展示 |
| user.user_id | 用户唯一标识 |
| user.nickname | 用户昵称（平台脱敏，无完整隐私） |
| user.avatar | 用户头像地址（防盗链，后端代理中转展示） |
| user.is_official | 是否品牌官方账号评论 |
| reply_comments | 子评论数组，多层对话提取 |
4. 子评论 reply_comments 字段
sub_comment_id、content、create_time、like_count、user 用户信息
五、高并发批量提取完整方案（生产可用）
1. 限流瓶颈与扩容方案
- 默认 QPS=1，大批量采集必 429 限流；
- 方案 A：企业认证 + 提交数据采集用途，申请 QPS 提升至 20~50；
- 方案 B：多应用多 AppKey 分流，多 token 轮询分摊流量；
2. 高并发架构设计
- 任务分层
- 调度层：消息队列（RabbitMQ/Kafka）存放待采集 note_id，削峰填谷；
- 采集工作池：aiohttp 异步协程，多 token 轮询负载均衡；
- 存储层：MySQL/ClickHouse 批量入库，批量插入减少 IO；
- 缓存层：Redis 缓存已采集完成笔记 ID、有效 token，避免重复请求。
- 单 token 严格控制并发≤QPS 上限，使用令牌桶限流；
- 失败请求指数退避重试：1s→2s→4s→8s，最多重试 3 次；
- 429 限流捕获后 sleep 3~5s 再重试。
3. 分页采集核心逻辑（游标循环，无重复）
def fetch_all_comments(note_id): cursor = "" all_comments = [] while True:
resp = api_request(note_id, cursor) if resp.code != 0: break data = resp.data
all_comments.extend(data.comments) if not data.has_more: break
cursor = data.cursor return all_comments
关键点：绝对不能用数字页码分页，小红书仅支持 cursor 游标分页，页码分页会丢失 / 重复数据。
4. 性能优化关键点
- 缓存策略
- Redis 缓存已完整拉取完毕的 note_id，24 小时内不重复全量采集；
- 热门笔记增量采集：只拉取最新 cursor 之后新增评论，无需从头遍历；
- 入库前过滤广告、空白评论、重复文本；
- 只保留 AI 分析所需核心字段，丢弃头像、冗余用户信息减少存储；
- 后台定时刷新 access_token，失效自动切换备用 token 池；
- 多账号 token 池哈希分配不同笔记，分散限流压力。
六、高频报错 & 避坑（并发采集必看）
code:429 rate limit限流
解决：令牌桶控流、多 AppKey 分流、错峰批量采集；code:401 token invalid
解决：token 自动续期，维护 token 可用池；- 评论数据重复 / 缺失
解决：只用 cursor 分页，禁止 page 页码；入库以 comment_id 唯一索引去重； - 图片头像前端无法展示
解决：后端服务代理图片链接，自定义签名校验，适配小程序 / H5； - 大批量采集账号封禁风险
合规底线：仅使用官方开放 API，禁止前端爬虫逆向抓页面；采集数据仅限自有业务舆情分析，禁止倒卖。
七、适配 AI 项目拓展建议
- 批量拉取评论 content，导入大模型做情感分类、差评关键词挖掘；
- 结合 create_time 时序数据，分析产品口碑波动；
- 关联笔记接口标题、品类，实现类目下全网评论舆情监控。
