小红书笔记详情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 调用完整代码 ，或者补充不同笔记类型（图文 / 视频）的数据结构差异说明？