小红书笔记详情API接口基础解析：数据结构与调用方式
小红书笔记详情 API 接口基础解析：数据结构与调用方式
小红书笔记详情 API 是面向官方合作方 / 授权开发者提供笔记核心数据的标准化接口，主要用于合规场景下的内容展示、数据分析（需授权）等需求。该接口的设计围绕数据标准化、权限管控、内容合规三大核心，其数据结构与调用方式具有鲜明的内容社区属性。
一、接口基础信息
1. 接口访问前提
- 权限限制：小红书笔记详情 API不对外开放，仅对通过企业资质审核的合作方（如品牌服务商、合规内容平台）开放，个人开发者无法申请。
- 调用协议：支持
HTTPS协议，保障数据传输安全；高并发场景可申请gRPC协议支持。 - 请求方式：以
GET为主（只读查询），部分带用户个性化参数的请求支持POST。 - 数据格式：默认返回
JSON格式，支持Protobuf二进制格式（需申请开通，传输效率更高）。
2. 核心鉴权方式
小红书 API 采用双重鉴权机制，防止非法调用：
- 基础鉴权：
AppKey + AppSecret签名机制- 开发者通过官方平台获取
AppKey（应用标识）和AppSecret（密钥）。 - 请求时需对参数按规则排序，通过
HMAC-SHA256算法生成签名（sign参数），服务端校验签名有效性。 - 签名参数必须包含
timestamp（时间戳），且时间戳与服务器时间偏差不超过 ±5 分钟，防止重放攻击。
- 开发者通过官方平台获取
- 用户级鉴权：
OAuth2.0令牌机制- 若需获取笔记的个性化数据（如用户是否点赞、收藏该笔记），需通过用户授权获取
access_token，并在请求头中携带。
- 若需获取笔记的个性化数据（如用户是否点赞、收藏该笔记），需通过用户授权获取
二、核心数据结构
小红书笔记详情 API 返回的数据结构包含基础信息、内容信息、互动信息、作者信息四大模块，字段设计兼顾内容展示与合规要求。以下是标准化的 JSON 数据结构示例及字段说明：
json
{ "code": 0, "msg": "success", "data": { "note_id": "648a7b2f0000000012345678", // 笔记唯一标识 "title": "夏日清爽穿搭指南 | 平价T恤分享", // 笔记标题 "desc": "这几件T恤真的巨舒服！均价50r，学生党冲...", // 笔记短描述 "content": "<p>哈喽姐妹们👋 今天给大家分享...</p>", // 富文本详情（HTML格式） "create_time": 1719984000, // 发布时间（时间戳） "update_time": 1719985200, // 最后更新时间 "note_type": "normal", // 笔记类型：normal-普通笔记/video-视频笔记/live-直播回放 "category": "fashion", // 内容分类：fashion-时尚/food-美食/beauty-美妆等 "tags": ["夏日穿搭", "平价T恤", "学生党"], // 笔记标签 "media": { // 媒体资源 "images": [ // 图片列表（图文笔记） "https://xxx.xiaohongshu.com/xxx/1.jpg", "https://xxx.xiaohongshu.com/xxx/2.jpg" ], "video": { // 视频信息（视频笔记） "play_url": "https://xxx.xiaohongshu.com/xxx/video.mp4", "cover_url": "https://xxx.xiaohongshu.com/xxx/cover.jpg", "duration": 15.5 // 视频时长（秒） } }, "author": { // 作者信息（脱敏处理） "user_id": "12345678", // 作者ID "nickname": "穿搭小能手", // 作者昵称 "avatar": "https://xxx.xiaohongshu.com/xxx/avatar.jpg", // 头像 "level": 5, // 作者等级 "is_verified": true // 是否为认证用户 }, "interaction": { // 互动数据 "like_count": 12580, // 点赞数 "collect_count": 3620, // 收藏数 "comment_count": 890, // 评论数 "share_count": 120 // 分享数 }, "location": { // 地理信息（可选） "name": "上海市徐汇区", "latitude": 31.197, "longitude": 121.436 }, "status": "published", // 笔记状态：published-已发布/draft-草稿/deleted-已删除 "is_commercial": false // 是否为商业笔记 } } 关键字段说明
| 模块 | 核心字段 | 字段用途 |
|---|---|---|
| 基础信息 | note_id、title | 笔记唯一标识与核心标题，用于内容定位 |
| 内容信息 | content、media | 笔记正文（富文本）与媒体资源（图片 / 视频），是内容展示的核心 |
| 作者信息 | author（脱敏） | 仅返回公开信息，隐藏手机号、精确地址等隐私数据 |
| 互动信息 | like_count 等 | 反映笔记热度，用于数据分析与内容推荐 |
| 合规字段 | is_commercial、status | 标识商业笔记与内容状态，防止违规内容传播 |
三、接口调用方式
1. 标准请求示例
（1）请求 URL
plaintext
https://openapi.xiaohongshu.com/v2/note/detail （2）请求参数
分为公共参数（所有接口必填）和业务参数（当前接口必填）：
| 参数类型 | 参数名 | 说明 |
|---|---|---|
| 公共参数 | app_key | 应用唯一标识（官方分配） |
| 公共参数 | sign | 签名值（通过 AppSecret 生成） |
| 公共参数 | timestamp | 当前时间戳（秒级） |
| 公共参数 | access_token | 用户授权令牌（非必填，仅个性化查询需要） |
| 业务参数 | note_id | 笔记 ID（必填，需查询的笔记唯一标识） |
（3）请求头示例
plaintext
Headers: { "Content-Type": "application/json", "User-Agent": "Xiaohongshu-OpenAPI-SDK/1.0.0" } （4）签名生成逻辑（Python 伪代码）
python
运行
import hashlib import hmac import time def generate_sign(app_secret, params): # 1. 按参数名ASCII升序排序 sorted_params = sorted(params.items(), key=lambda x: x[0]) # 2. 拼接为key=value格式的字符串 sign_str = "&".join([f"{k}={v}" for k, v in sorted_params]) # 3. 拼接AppSecret并生成HMAC-SHA256签名 sign = hmac.new(app_secret.encode("utf-8"), sign_str.encode("utf-8"), hashlib.sha256).hexdigest() return sign # 调用示例 params = { "app_key": "your_app_key", "note_id": "648a7b2f0000000012345678", "timestamp": str(int(time.time())) } sign = generate_sign("your_app_secret", params) params["sign"] = sign 2. 响应处理
（1）成功响应
返回 code=0，data 字段包含完整的笔记详情数据，示例见上文数据结构部分。
（2）常见错误响应
| 错误码 | 错误信息 | 原因分析与解决方案 |
|---|---|---|
| 1001 | app_key invalid | AppKey 无效，检查是否为官方分配的有效密钥 |
| 1002 | sign verify failed | 签名错误，检查签名算法、参数排序是否正确 |
| 1003 | request frequency limit | 调用频率超限，降低请求 QPS 或申请提升限额 |
| 2001 | note_id invalid | 笔记 ID 不存在或已被删除 |
| 2002 | permission denied | 无权限访问该笔记（如私密笔记） |
四、接口调用限制与合规要求
- 频率限制
- 单
AppKey有日调用限额和秒级 QPS 限制（如基础版 1000 次 / 日、10QPS），超出限制返回1003错误。 - 禁止批量抓取笔记数据，仅允许按需查询单条笔记详情。
- 单
- 数据用途限制
- 调用所得数据仅允许用于合作场景内的展示，禁止用于爬虫、竞品分析、数据贩卖等违规用途。
- 引用笔记内容时需注明 “来源小红书”，并遵守平台版权规则。
- 隐私合规
- 不得存储或传播作者的脱敏信息，不得通过接口数据反向识别用户身份。
是否需要我为你整理小红书笔记详情 API 的 Python 调用完整代码，或者补充不同笔记类型（图文 / 视频）的数据结构差异说明？
