Rednote User Notes
Rednote 用户笔记是公开账号发布的内容，可包含正文、作者归属、媒体、发布时间和可见互动数量。结合这些内容与上下文字段，可以研究账号内容、梳理发布规律、比较媒体形式和分析特定时间点的互动表现。
主要特性
- 两种账号标识与明确优先级可提交受支持的 Rednote 用户地址或 user_id；两个字段同时存在时，使用显式 user_id。
- 采集一页账号笔记获取指定账号在一次来源请求中返回的公开笔记，不向调用方开放来源游标或自定义结果数量。
- 统一笔记与作者上下文以一致的 PostItem 结构返回笔记 ID、公开 URL、正文、作者身份、媒体引用、发布时间和采集时间。
- 可见互动快照保留可用的点赞、评论、分享和浏览数量，并通过 collected_at 标记可比较的观察时间。
参数
| 参数 | 必填 | 描述 |
|---|---|---|
url | 必填（至少一项） | 非空 Rednote 用户地址，解析后的 hostname 必须为 xiaohongshu.com、xhslink.com 或两者的子域名。接口不强制特定路径；user_id 为空且 URL 包含 /user/<identifier> 时使用该标识，否则保留受支持的 URL 作为账号地址。 |
user_id | 必填（至少一项） | 由 1 至 256 个 ASCII 字母、数字、冒号、下划线或连字符组成的 Rednote 用户标识。url 与 user_id 至少提供一个；两个字段同时存在时，显式 user_id 优先。 |
如何使用
提交一种受支持的 Rednote 账号标识，跟踪异步任务，再分页读取已存储的标准化笔记记录。
- 准备一个属于受支持主机的非空 Rednote 用户 URL，或一个有效 user_id；不需要的字段保持为空。
- 向 /v1/rednote/user-notes POST url 或 user_id，并保存返回的 task_id。
- 轮询 /v1/tasks/{task_id}，直到任务成功或返回失败。
- 读取 data.results.items；has_more 为 true 时继续使用 next_cursor。该游标只翻阅已存储记录，不会请求更多 Rednote 来源页。
curl -X POST "https://api.socq.ai/v1/rednote/user-notes" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"url\":\"$REDNOTE_USER_URL\"}"
# 轮询 GET /v1/tasks/{task_id}
# 读取 data.results.items；has_more 为 true 时沿 next_cursor 继续最佳使用场景
- 建立公开账号发布目录： 结合笔记 ID、公开 URL、正文、作者归属和发布时间，为返回的账号快照建立内容目录。
- 梳理内容形式： 比较账号笔记中可用的图片或视频引用、尺寸、缩略图和正文。
- 分析发布规律： 按 published_at 整理笔记，并结合正文和媒体审阅当前快照中的公开发布组合。
- 比较分时点互动表现： 比较可见点赞、评论、分享和浏览数量，并用 collected_at 将观察结果关联到采集时间。
使用建议
- 已有稳定 user_id 时优先使用它；该字段优先于 url，可避免两个账号地址之间的歧义。
- 提交 url 前校验 hostname 是否属于 xiaohongshu.com 或 xhslink.com；接口不要求特定路径。
- 受支持 URL 包含 /user/<identifier> 时，确认该路径指向目标账号，因为 user_id 为空时会使用此标识。
- 不要在提交请求中加入 results_limit 或来源 cursor；每个任务只发起一次来源请求并获取一页。
- 任务完成后，仅在 GET /v1/tasks/{task_id} 中使用 cursor 和 limit 翻阅存储结果；limit 默认 50，范围为 1 至 500。
- 正文、作者字段、媒体、发布时间、标签、提及和各项指标都可能为空；渲染公开文本前应进行安全转义。