> 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.

# 怎样把小红书合作需求变成博主筛选条件，再得到可审核名单？

> 将小红书合作需求拆解为 xiaohongshu.pgy.get_blogger_list 的 blogger、fans、coop 与 flags 嵌套条件，用 pgy_candidates.py 导出前 5000 条可见候选，并明确活跃度与回复率字段边界。

要把合作需求变成可审核的博主名单，用 `xiaohongshu.pgy.get_blogger_list` 按合作条件筛蒲公英博主列表。内容方向和博主所在地放在 `blogger` 下，粉丝规模和地区放在 `fans` 下，图文或视频报价放在 `coop` 下。先取一页看方向，再为入选账号核对真实作品。

例如一轮上海的美妆图文合作，先按内容方向、博主所在地、粉丝范围和图文报价范围缩小名单。如果真正的要求是上海受众，就用 `fans.location` 条件，而不是只看博主所在地。

## 从brief到输入，先分清这几件事

| 需求        | 输入位置                                | 评审时继续看什么       |
| --------- | ----------------------------------- | -------------- |
| 内容做哪类主题   | `blogger.content_tag`               | 近期作品是否真的符合主题   |
| 博主所在地     | `blogger.location`                  | 是否满足本次拍摄或活动条件  |
| 粉丝数量与所在地  | `fans.count`、`fans.location`        | 与受众brief逐项核对   |
| 图文或视频合作报价 | `coop.pic_price`、`coop.video_price` | 返回报价、单位与实际合作条件 |
| 近期合作行业    | `coop.industry`                     | 具体案例和品牌上下文     |

调用 `data:xiaohongshu.pgy.get_blogger_list` 时，条件分别放进 `blogger`、`fans`、`coop` 对象，不要把所有字段平铺到顶层。第一次先看一页是否符合方向，再决定要不要扩大采集。

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

> 按这个图文合作brief找一页候选，保留账号ID、实际报价和来源。说明哪些筛选代表博主条件、哪些代表粉丝条件，再为相关账号列出要核对的近期作品与资料。

返回的记录只是候选，不等于适合合作。每位候选都保留“为什么选、还缺什么”，让后续的内容、画像和案例核对有明确目标。

## 一个可修改的筛选请求

下面请求里的数字只是输入示例，不是行业推荐标准。执行前先用 Inspect 核对当前合同和价格。

```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.pgy.get_blogger_list","params":{"blogger":{"content_tag":["美妆"],"location":["上海"]},"fans":{"count":{"min":10000,"max":50000}},"coop":{"pic_price":{"max":5000}},"column":"fansCount","sort":"desc","page_num":1,"page_size":20}}' \
  -o xiaohongshu-creators-page-1.json
```

## 容易混淆的几组条件

| 你要筛什么       | 对应输入                                            |
| ----------- | ----------------------------------------------- |
| 博主所在地       | `blogger.location` 字符串数组                        |
| 粉丝所在地       | `fans.location` 字符串数组，不是作者所在地                   |
| 按博主笔记关键词搜索  | `keyword`，`search_type: 1`，也是默认模式               |
| 按昵称搜索       | `keyword`，`search_type: 0`                      |
| 图文报价 / 视频报价 | `coop.pic_price` / `coop.video_price` 的 min/max |
| 最近合作行业      | `coop.industry`，例如合同枚举 `美妆个护` 或 `3c及电器`         |

`blogger.content_tag` 是内容分类，`coop.industry` 是合作行业，“数码博主”不等于“最近合作过 3c 品牌”。`blogger.content_tag` 的 schema 只给出字符串和部分示例，没有完整枚举，不要声称已经掌握全部分类值。筛选没有结果时，先检查各条件的交集，不要立即判定整个平台没有匹配的博主。

### 美妆和数码怎么筛？

做护肤合作时，先用已核对的美妆内容标签，项目要求近期有美妆商单时再加 `coop.industry: "美妆个护"`。招数码测评博主时，用「手机测评」查笔记关键词，需要近期有相关商单时再加 `coop.industry: "3c及电器"`。两份名单各自保存筛选条件，再看实际作品，确认博主做的是护肤试用还是设备测评。标签值没核对过时，先走关键词路线。

## 能导出全部达人库吗？

不能。`page_num` 取 1–250，`page_size` 取 1–20，合同说明只开放前 5000 条。翻页时保持相同的条件、排序和范围；结果在翻页期间变化仍可能造成重复。列表路径为 `data.data.kols`，博主键为 `userId`；按下方候选指南直接导出，不使用 `data.items`。

[从筛选结果建立候选名单](/zh/guides/xiaohongshu-creator-shortlist) · [找相似博主](/zh/faq/xiaohongshu-similar-creators)

来源：免费 Inspect `data:xiaohongshu.pgy.get_blogger_list`。返回的报价不代表最终成交价。

## 筛完能直接导出吗？

可以。[候选指南](/zh/guides/xiaohongshu-creator-shortlist)提供固定路径的导出器：按 `data.data.kols` 与 `userId` 解析已保存页面，直接生成去重 CSV、全部观察记录 JSONL 和逐页覆盖报告。`total` 是翻页上限，不是命中人数；空页、失败、重复和报价变化分别保留。导出器不猜 `data.items`，候选 CSV 也不代表已核实合作意愿。

## 怎么优先筛出回复邀约快、保持活跃的博主？

找候选时，传 `coop.reply_48h_ratio.min: 80`、`flags.exclude_low_active: true`，并按 `inviteReply48hNumRatio` 降序排列。`coop.reply_48h_ratio` 按 **0 到 100 的百分点**填写：`80` 表示 80%，不是 `0.8`。80% 只是示例门槛，不是所有行业的通用标准。博主低活跃筛选和粉丝活跃指标针对的不是同一人群。

把下面的请求保存为 `responsive-creators-request.json`，把关键词改成这次投放的真实主题：

```json
{"action":"xiaohongshu.pgy.get_blogger_list","params":{"keyword":"咖啡","search_type":1,"coop":{"reply_48h_ratio":{"min":80}},"flags":{"exclude_low_active":true},"column":"inviteReply48hNumRatio","sort":"desc","page_num":1,"page_size":20}}
```

价格确认、采集获批后，保存一份完整响应和实际 HTTP 状态：

```bash
curl -sS https://api.beatapi.io/v1/social-data/call   -H "Authorization: Bearer $BEATAPI_API_KEY"   -H 'Content-Type: application/json'   --data-binary @responsive-creators-request.json   -o responsive-creators-page-1.json -w '%{http_code}\n'
```

建立 `responsive-manifest.json`，内容是只含一条记录的数组：该请求的精确 `action` 和 `params`、实际 HTTP 状态、带时区的真实采集时间，以及 `response_file: "responsive-creators-page-1.json"`。格式与[候选库指南](/zh/guides/xiaohongshu-creator-shortlist)第 7 节相同。用第 7 节完整的 `pgy_candidates.py` 在本地导出：

```bash
python3 pgy_candidates.py responsive-manifest.json responsive-review
```

先看覆盖报告，再看候选 CSV：网关错误、内部业务失败、空值列表都不是空候选集。`pgy_candidates.py` 保留请求的筛选条件、原始字节、时间戳和每一次博主记录。交付的是**在这些条件下返回的候选名单**，不是逐人独立核验的回复百分比，也不是“好联系”徽标。不要补猜 `invite_reply_rate`、`active_days_7d`、`is_active`、`easy_to_reach` 列。继续翻页时保持全部条件和排序不变，页码连续递增，不超过辅助脚本的五页上限；遇到空页、重复页、错误或达到获批上限时停止。

列表费用按实际页数和[价格页](https://beatapi.io/zh/pricing)的当前单价计算。`pgy_candidates.py` 每批最多处理 5 页；去重后的人数可能少于返回的位置数。历史 48 小时回复条件用来挑选下一步评审对象，不保证本次回复或档期。

## 每位博主的精确活跃天数、回复率能直接导出吗？

不能。`data:xiaohongshu.pgy.get_blogger_data_summary` 的说明把近七天活跃和 48 小时邀约回复列为服务指标，`business: 0` 是日常笔记口径，`1` 是合作笔记口径。但公开说明**没有给出服务指标的 JSON 键和数值比例**，也没有证实“好联系”“活跃”徽标字段；当前响应结构也不提供这些字段映射。所以本页只做到从筛选到候选库，不提供逐人的徽标或活跃指标导出。不要反复购买空概览，也不要把活跃粉丝比例改名为博主活跃度。

排邀约计划时，人工复核候选人的近期内容和实际合作状态，在自己的投放表里记录活动截止日和获准发送邀约后的实际回复。本次观察到的回复与平台的历史筛选标准分开记录。本页脚本不发送任何邀约。