> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# 同事发来小红书短链，怎样读笔记、找评论里的真实问题？

> 从已有分享链接或笔记ID出发，按阅读、评论和回复任务选择最短步骤，保存来源，分清xsec_token和网页签名。

要研究同事发来的小红书笔记，把原分享链接作为 `share_text` 传给与任务对应的 App 动作。读描述用 `xiaohongshu.app_v2.get_image_note_detail` 或 `xiaohongshu.app_v2.get_video_note_detail`；看讨论，直接用 `xiaohongshu.app_v2.get_note_comments` 查这篇笔记的一级评论。已经拿到核对过的笔记编号时，改传 `note_id`。

比如同事发来一篇咖啡机清洁教程，想知道用户卡在哪一步。已经读过教程时，直接从评论开始，保存问题原句和评论里提到的机型。需要核对教程本身写了什么时，再查笔记详情。

## 手里的链接或编号该放哪里？

| 已有材料                                                       | 下一步                     |
| ---------------------------------------------------------- | ----------------------- |
| `xiaohongshu.com` 笔记长链，或 `xhslink.com` / `xhslink.cn` 分享短链 | 放进所选App动作的 `share_text` |
| 已保存搜索结果中的 `note.id`                                        | 直接作为 `note_id`，复用这份结果   |
| `/explore/` 或 `/discovery/item/` 后的笔记编号                    | 按原始文本保存为 `note_id`      |
| 用户主页链接、用户编号、小红书号                                           | 用于账号研究；先选出目标笔记，再研究这篇的评论 |

短链末尾的短码不是笔记编号。笔记编号和用户编号可能长得相似，判断时看编号来自哪一类页面。原链接里的查询参数随链接一起保留，不需要自己生成访问令牌。

## 按这次要完成的事选择

| 你要做什么          | action                                     | 定位输入                     |
| -------------- | ------------------------------------------ | ------------------------ |
| 读图文笔记的描述与图片信息  | `xiaohongshu.app_v2.get_image_note_detail` | `share_text` 或 `note_id` |
| 了解视频笔记的描述与详情   | `xiaohongshu.app_v2.get_video_note_detail` | `share_text` 或 `note_id` |
| 找这篇笔记评论中的疑问和经验 | `xiaohongshu.app_v2.get_note_comments`     | `share_text` 或 `note_id` |

给目标笔记选一个定位输入：有准确 ID 就用 ID，只有分享链接就用链接；已知图文或视频类型时，选对应的详情动作。详情动作返回的描述只是文本，不识别图片内容，也不转写视频；任务需要这些材料时另行补充。

下面以读取图文详情为例，把 `<note_share_link>` 换成真实笔记链接：

```bash
curl -sS https://api.beatapi.io/v1/social-data/call \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"action":"xiaohongshu.app_v2.get_image_note_detail","params":{"share_text":"<note_share_link>"}}' \
  -o xiaohongshu-note.json
```

## 拿到结果后，怎样继续？

1. **确认就是这篇。** 图文详情位于 `data.data[].note_list[]`，视频详情位于 `data.data[]`。对照标题、作者和原链接，保存目标笔记的 `id`；返回多篇时选出对应的笔记对象。
2. **保留能回看的来源。** 记录原链接、确认的笔记ID、查询时间和 `request_id`。同一篇的后续观察按笔记ID关联，分享短链仍可作为来源保留。
3. **围绕问题读评论。** 评论中的 `note_id` 指所属笔记，`id` 指这条评论本身。整理“观众原话—涉及步骤/条件—需要补充的回答”，不要只统计清洁、难用等关键词。
4. **有歧义再补回复。** 用 `xiaohongshu.app_v2.get_note_sub_comments` 查回复时，把一级评论的 `id` 作为 `comment_id` 传入。回复里的 `target_comment.id` 可能指向另一条回复，所以要保留父子上下文。后续分页按返回的游标继续。

比如“这个刷子所有机型都能用吗”归入兼容性待回答项；“我这台不用拆这一步”是带机型背景的经验，先保留原句和上下文再判断。缺少原句或目标笔记对不上时，先补材料，不要生成看似完整的结论。导出步骤见[笔记评论研究指南](/zh/guides/xiaohongshu-note-comments)。

把任务交给已接入工具的助手时，可以这样写：

> 研究这条分享链接对应的咖啡机清洁教程。已有描述可复用，优先读评论，整理大家卡住的步骤、适用条件和待回答问题。每项附原句、所属笔记和必要回复；说明本次读到的范围，再列出值得补读的讨论。

## 为什么有的动作还要xsec_token？

App 动作和 Web 详情动作的输入不同。上面三个 App 动作不需要另外提供 `xsec_token`；`xiaohongshu.web_v3.fetch_note_detail` 则同时要求 `note_id` 和 `xsec_token`。按所选动作声明的输入传参。

`X-S`、`X-T`、`x-S-Common` 是直连网页客户端使用的签名头；笔记ID、链接访问令牌和 BeatAPI Key 各有各的用途。上述 App 动作只需常规 BeatAPI 鉴权和声明的定位参数，不需要网页签名库，也不需要复制浏览器 Cookie。[MediaCrawler客户端源码](https://github.com/NanmiCoder/MediaCrawler/blob/main/media_platform/xhs/client.py)展示的是 MediaCrawler 自己直连请求的签名方式，不是本流程的步骤。

## 链接打不开，下一步怎么处理？

先核对复制的链接确实指向目标笔记。手里有完整笔记链接或已确认的笔记 ID 时，改用链接或 ID 继续；否则保留原链接、返回消息和 `request_id`，把这篇笔记列为待补材料。返回结果的处理方法见[业务错误问答](/zh/faq/xiaohongshu-business-errors)。

按[价格页](https://beatapi.io/zh/pricing)的当前价格规划。只读评论的任务只计评论页；需要描述时才加详情查询，已有结果直接复用。

## 用本地小工具准备请求（可选）

保存下方的 `prepare_note_request.py`。已知内容类型时选对应类型，任务是评论研究时选 `comments`。`prepare_note_request.py` 接受一个 24 位十六进制笔记 ID，或列明分享域名上的一个完整 HTTPS URL；xiaohongshu.com 长链接必须带 `/explore/NOTE_ID` 或 `/discovery/item/NOTE_ID` 路径，主页和登录页不是笔记目标。脚本会拒绝整段分享文案、带账号密码的 URL、端口、片段和其他域名。脚本比 API 更严格，API 可能接受其他 share_text 格式。`prepare_note_request.py` 不联网、不展开短链，也不检查笔记是否存在。

```python
import json,os,pathlib,re,sys
from urllib.parse import urlsplit
kind,locator,output=sys.argv[1:4]
actions={'image':'get_image_note_detail','video':'get_video_note_detail','comments':'get_note_comments'}
if kind not in actions:raise SystemExit('Choose image, video or comments; do not auto-try both detail actions')
if re.fullmatch(r'[0-9a-fA-F]{24}',locator):
    params={'note_id':locator}
else:
    try:parsed=urlsplit(locator)
    except ValueError:raise SystemExit('Invalid URL')
    if (parsed.scheme!='https' or parsed.hostname not in {'xiaohongshu.com','www.xiaohongshu.com','xhslink.com','www.xhslink.com','xhslink.cn','www.xhslink.cn'}
        or parsed.username is not None or parsed.password is not None or parsed.fragment or not parsed.path.strip('/')
        or any(c.isspace() or ord(c)<32 or ord(c)==127 for c in locator)):
        raise SystemExit('Use one complete HTTPS share URL or a 24-character note ID, not copied headers or share prose')
    try:
        if parsed.port is not None:raise SystemExit('Do not supply an explicit port')
    except ValueError:raise SystemExit('Invalid URL port')
    if parsed.hostname in {'xiaohongshu.com','www.xiaohongshu.com'} and not re.fullmatch(r'/(?:explore|discovery/item)/[0-9a-fA-F]{24}/?',parsed.path):
        raise SystemExit('For a long URL use an explore or discovery/item note path, not a profile or login page')
    params={'share_text':locator}
os.umask(0o077)
with pathlib.Path(output).open('x',encoding='utf-8') as destination:
    json.dump({'action':'xiaohongshu.app_v2.'+actions[kind],'params':params},destination,ensure_ascii=False,indent=2)
print(output)
```

```bash
python3 prepare_note_request.py comments '0123456789abcdef01234567' note-request.json
```

示例里的 ID 只是示意，换成自己已核实的 ID，或用引号把真实 URL 作为一个参数传入。URL 可能含访问令牌，请求文件要私有保存，不要贴到公开工单。生成的文件只有 action/params，不含 API Key 或浏览器请求头，也不会覆盖已有文件。执行前核对所选动作和当前价格，再用通常的私有 Bearer 头提交文件：

```bash
curl -sS https://api.beatapi.io/v1/social-data/call   -H "Authorization: Bearer $BEATAPI_API_KEY"   -H 'Content-Type: application/json'   --data-binary @note-request.json -o note-response.json
```

只有上面这条 curl 会产生调用，不要用示例 ID 执行这条 curl。按上文步骤核对返回的动作和目标笔记身份，评论任务接着走完整的[评论导出流程](/zh/guides/xiaohongshu-note-comments)。短链后缀仍然不是笔记 ID；内容缺失时停下批次核查，不要自动改用另一个详情动作重试。