> 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 筛选小红书合作博主，用 pgy_candidates.py 按 userId 去重导出候选库，再仅为人工入围博主补充详情、粉丝画像、合作案例与表现数据。

要做小红书合作名单，先用 `data:xiaohongshu.pgy.get_blogger_list` 按内容、地区和报价筛一页蒲公英博主列表。再用候选返回的 `userId`，按第 4、5 步给入选博主补画像与合作案例。最后交一张名单，每行说明博主为什么入选、证据在哪、还有什么要确认。

例如你要在上海做线下咖啡机体验，先看每位博主是否能到场、是否有图文教程经验、报价是否在预算内。内容合适但粉丝地区还没核对的候选，先标「待补画像」。两位报价相近时，再看谁的历史案例更接近真实使用场景。档期、最终报价和使用权到蒲公英的合作流程确认。 [蒲公英官方站](https://pgy.xiaohongshu.com/)

## 合作名单的每一列从哪里取？

| 要做的决定        | 本流程里的证据                   | 下一步                                                             |
| ------------ | ------------------------- | --------------------------------------------------------------- |
| 哪些博主符合需求？    | 已存候选页的真实 userId、实际返回报价与指标 | 用第 7 节的导出脚本导出名单，再审核内容匹配；列表靠前不代表推荐背书                             |
| 受众是否匹配？      | 单独查询的博主粉丝分布               | [核对画像证据](/zh/faq/xiaohongshu-audience-quality)，分布不证明每个粉丝或买家的身份  |
| 博主合作过相关品牌吗？  | 筛选后的合作案例及原始 brandName     | [导出审核案例](/zh/faq/xiaohongshu-sponsored-notes)，缺标签留未知，同笔记证据冲突就停下 |
| 自然与全部流量如何区分？ | 明确的流量开关和对齐笔记 ID           | [比较已说明的口径](/zh/faq/xiaohongshu-organic-traffic)，无法匹配的观察单列       |
| 我们这次投放后来怎样？  | 固定名单、观察时间、公开及蒲公英指标导出      | [形成有限范围复盘](/zh/faq/xiaohongshu-report-availability)，不冒充完整归因报告   |
| 某主题的兴趣有变化吗？  | 独立关键词指数请求及返回日期            | [读取关键词趋势](/zh/faq/xiaohongshu-keyword-index)，指数不是搜索人数或销量        |

预算里分别记录数据请求、博主合作付款和推广费用。本页的请求次数只用于估算取数费用。

## 1. 明确条件和调用范围

先定内容类型、地区、粉丝范围和报价范围。博主所在地不等于粉丝所在地，内容分类也不等于近期合作行业。第一次可以只取一页候选，再选一位博主查看详情、画像和一页案例；首轮范围用来控制花费，不是质量阈值。

## 2. 免费 Inspect，再取一页候选

```bash
curl -sS https://api.beatapi.io/v1/capabilities/inspect \
  -H 'Content-Type: application/json' \
  -d '{"reference":"data:xiaohongshu.pgy.get_blogger_list"}'
```

先在 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":{"keyword":"咖啡","search_type":1,"fans":{"count":{"min":10000,"max":50000}},"page_num":1,"page_size":20}}' \
  -o creator-candidates-page-1.json
```

search_type 1 按笔记关键词找博主，不是昵称精确匹配；按昵称查询时改成 0。要叠加地区和报价条件，见[筛选条件](/zh/faq/xiaohongshu-creator-filters)；已有种子账号时，可以从[相似发现](/zh/faq/xiaohongshu-similar-creators)开始。

## 3. 检查原始结果后保存候选

公开目录没有发布完整输出 schema，但响应结构已明确列表路径为 `data.data.kols`、博主键为 `userId`，第 7 节提供按固定路径导出已存页面的脚本。用真实 `userId` 去重，保留输入条件、排序、页次、采集时间和 `request_id`。只有昵称的记录不凭空拼 ID，缺失指标留空。

继续分页时，保持条件与排序不变，page_num 从 1 递增，page_size 不超过 20。最多允许 250 页、可见前 5000 条，不代表整个达人库。遇到重复整页、错误或达到批准页数就停止。

## 4. 只核对选中账号的详情和受众

扩展前，分别免费 Inspect `data:xiaohongshu.pgy.get_blogger_detail` 与 `data:xiaohongshu.pgy.get_blogger_fans_profile`。确认价格后，用候选结果里实际核对过的 user_id 调用两个动作：

```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_detail","params":{"user_id":"<selected_user_id>"}}' \
  -o selected-creator-detail.json

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_fans_profile","params":{"user_id":"<selected_user_id>"}}' \
  -o selected-creator-audience.json
```

详情和画像请求与列表导出分开进行。受众 FAQ 列出了画像已明确的分布字段，不保证每位创作者都返回每个字段。实际响应带有估计值时，保留估计含义；受众画像不等于[真假粉鉴定](/zh/faq/xiaohongshu-audience-quality)。

## 5. 检查合作案例，而不只看账号总数

免费 Inspect `data:xiaohongshu.pgy.get_blogger_notes`，确认后取一页合作笔记：

```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_notes","params":{"user_id":"<selected_user_id>","note_type":3,"order_type":1,"page_number":1,"page_size":8}}' \
  -o selected-creator-sponsored-notes.json
```

note_type 3 表示合作笔记，默认 advertise_switch 1 含全部流量。要评估自然内容表现时，另外指定自然流量口径，不把商单与推广流量混为一谈。保留原始案例，人工检查内容相关性；未取得的来源或指标不让 AI 补写。

如果同一项目还要在抖音找人，另外走[星图和抖音合作资料](/zh/guides/douyin-creator-collaboration-review)。总表用「平台 + 达人 ID」定位候选，分别保存两个平台的图文或视频报价、受众口径和作品来源。同一个人跨平台出现时可以关联，合作条件仍按平台分别核对。

## 6. 交付名单并记录成本

本地表建议列：user_id、入选条件、实际返回的资料、案例来源、受众证据、缺失/待确认事项。谈判前必须再次确认报价，不让一个预估分数掩盖缺失证据。

一页候选加一位博主的详情、画像和一页案例，共 4 次平台调用；按[价格页](https://beatapi.io/zh/pricing)的现价逐项相加。对 M 位博主都执行后三步是 1 + 3M 次，后续翻页与模型分析另计。候选页每页 20 人只是一次调用，不等于核对了 20 人的全部信息。

第 7 节的导出脚本自动导出已核对路径的字段，画像扩展与内容相关性仍需分别人工审核。错误页不能当空候选；失败后先检查本地已保存的响应，避免无目的重查。

[合作案例参数](/zh/faq/xiaohongshu-sponsored-notes) · [自然流量口径](/zh/faq/xiaohongshu-organic-traffic) · [小红书问题索引](/zh/faq/xiaohongshu)

## 7. 已保存候选页如何直接导出达人库？

BeatAPI 直接保留蒲公英响应信封，博主列表位于 `data.data.kols[]`，按 `userId` 去重。`pgy_candidates.py` 使用已明确的 `name`、`redId`、`location`、粉丝数、图文/视频报价、阅读/互动中位数和图文预估 CPM，不套用第三方归一化字段。该请求合同不需要 `view=full`。数值原样保留，不改写成保效果承诺或最终商谈价。

以上面的咖啡筛选为例，筛选和排序保持不变，`pgy_candidates.py` 最多接受五页。单价见[价格页](https://beatapi.io/zh/pricing)。五页最多返回 100 个位置，扣除过滤和重复后不保证 100 位博主。遇到失败、重复或空页先停下，核查已保存的结果；空页不证明整个目录没有候选。`total` 的文档定义是翻页上限，不是命中数。

为实际保存的完整响应建立清单，只添加确实请求过的连续页，填真实 HTTP 状态和带时区的采集时间。下面的条目只示范格式，不是实测记录：

```json
[{"action":"xiaohongshu.pgy.get_blogger_list","params":{"keyword":"咖啡","search_type":1,"fans":{"count":{"min":10000,"max":50000}},"page_num":1,"page_size":20},"http_status":200,"collected_at":"2026-11-16T10:00:00Z","response_file":"creator-candidates-page-1.json"}]
```

把下面的脚本保存为 `pgy_candidates.py`。`pgy_candidates.py` 不联网，限制本轮最多五页且筛选保持一致，保留真实的网关 error 信封和蒲公英内部失败，按 `userId` 去重，并另存每次原始观察，报价变化不会被悄悄丢弃。依据：`xiaohongshu.pgy.get_blogger_list` 的公开响应字段结构。

```python
import csv,datetime,hashlib,json,pathlib,sys
manifest,target=map(pathlib.Path,sys.argv[1:3])
entries=json.loads(manifest.read_text(encoding="utf-8"))
if not isinstance(entries,list) or not 1<=len(entries)<=5:raise ValueError("This review helper accepts 1-5 recorded pages")
columns=["name","redId","location","fansNum","picturePrice","videoPrice","clickMidNum","interMidNum","estimatePictureCpm"]
creators={};pages=[];blobs=[];request_ids=set();filters=None;previous_time=None;signatures=set();observations=[]
def cell(value):
    if value is None:return ""
    text=value if isinstance(value,str) else json.dumps(value,ensure_ascii=False,separators=(",",":"))
    return "'"+text if text.lstrip().startswith(("=","+","-","@")) or text.startswith(("\t","\r","\n")) else text
for page_index,entry in enumerate(entries,1):
    if entry.get("action")!="xiaohongshu.pgy.get_blogger_list":raise ValueError("Wrong manifest action")
    params=entry["params"]
    if params.get("page_num")!=page_index or type(params.get("page_num")) is not int:raise ValueError("Record consecutive pages starting at 1")
    if params.get("page_size")!=20 or type(params.get("page_size")) is not int:raise ValueError("This helper keeps page_size=20")
    current={key:value for key,value in params.items() if key!="page_num"}
    if filters is None:filters=current
    if current!=filters:raise ValueError("Keep every filter and sort unchanged")
    stamp=entry["collected_at"];dt=datetime.datetime.fromisoformat(stamp.replace("Z","+00:00"))
    if dt.tzinfo is None or (previous_time is not None and dt<=previous_time):raise ValueError("Use increasing timezone-aware request times")
    previous_time=dt
    http=entry.get("http_status")
    if type(http) is not int or not 100<=http<=599:raise ValueError("Actual HTTP status required")
    source=pathlib.Path(entry["response_file"])
    if not source.is_absolute():source=manifest.parent/source
    raw=source.read_bytes();r=json.loads(raw);error=r.get("error")
    if error is not None:
        if not isinstance(error,dict) or http<400:raise ValueError("Invalid error envelope")
        request_id=error.get("request_id")
    else:
        if http!=200 or r.get("action")!="xiaohongshu.pgy.get_blogger_list" or r.get("status")!="succeeded":raise ValueError("Unexpected success response")
        request_id=r.get("request_id")
    if not isinstance(request_id,str) or not request_id.strip() or request_id in request_ids:raise ValueError("Distinct request IDs required")
    request_ids.add(request_id)
    filename="page-"+str(page_index)+".json";digest=hashlib.sha256(raw).hexdigest();blobs.append((filename,raw))
    page={"page_num":page_index,"params":params,"request_id":request_id,"collected_at":stamp,"http_status":http,
          "source_file":str(source),"archived_file":filename,"sha256":digest,"state":"gateway_failed","records":0}
    if error is not None:page["error_code"]=error.get("code")
    else:
        envelope=r.get("data")
        if not isinstance(envelope,dict):raise ValueError("Missing PGY envelope")
        if envelope.get("success") is False:page["state"]="pgy_business_failed"
        elif envelope.get("success") is not True:raise ValueError("Explicit PGY success required")
        elif envelope.get("data") is None:page["state"]="no_payload"
        else:
            data=envelope["data"]
            if not isinstance(data,dict) or not isinstance(data.get("kols"),list):raise ValueError("Expected documented kols array")
            ids=[]
            for position,creator in enumerate(data["kols"]):
                if not isinstance(creator,dict):raise ValueError("Invalid creator object")
                uid=creator.get("userId")
                if not isinstance(uid,str) or not uid.strip() or "<" in uid or ">" in uid:raise ValueError("Real userId required")
                ids.append(uid)
                observations.append({"userId":uid,"page_num":page_index,"item_index":position,"request_id":request_id,"creator":creator})
                if uid not in creators:
                    creators[uid]={"userId":uid,**{key:creator.get(key) for key in columns},"first_page":page_index,
                                   "first_request_id":request_id,"first_collected_at":stamp,"observation_count":0,
                                   "review_decision":"","fit_evidence":"","quote_rechecked_at":""}
                creators[uid]["observation_count"]+=1
            signature=tuple(ids)
            page.update({"state":"empty" if not ids else "available","records":len(ids),
                         "repeated_ordered_ids":bool(ids) and signature in signatures,"reported_total":data.get("total")})
            if ids:signatures.add(signature)
    pages.append(page)
report={"pages":pages,"filters":filters,"unique_creator_ids":len(creators),"returned_occurrences":len(observations),
        "deduplication":"First observation retained in CSV; all variants preserved in observations.jsonl",
        "coverage":"Only recorded pages, not entire directory. reported_total is not the candidate count."}
target.mkdir()
with (target/"creators.csv").open("x",encoding="utf-8-sig",newline="") as output:
    writer=csv.DictWriter(output,fieldnames=["userId",*columns,"first_page","first_request_id","first_collected_at","observation_count","review_decision","fit_evidence","quote_rechecked_at"])
    writer.writeheader();writer.writerows({key:cell(value) for key,value in row.items()} for row in creators.values())
with (target/"observations.jsonl").open("x",encoding="utf-8") as output:
    for row in observations:output.write(json.dumps(row,ensure_ascii=False)+"\n")
for filename,raw in blobs:(target/filename).write_bytes(raw)
(target/"coverage.json").write_text(json.dumps(report,ensure_ascii=False,indent=2),encoding="utf-8")
print(str(target/"creators.csv"))
```

运行 `python3 pgy_candidates.py creator-manifest.json creator-library-1`。先看 coverage.json：逐页状态、哈希、请求 ID、返回次数和唯一博主数都在 coverage.json 里。失败页不当作成功的空页；没有 JSON 的网络失败另写采集日志，不伪造结果行。pgy_candidates.py 拒绝覆盖已有输出目录。

再打开 creators.csv，核对内容相关性后填写 review_decision 和 fit_evidence。字段保持返回时的表示：嵌套值保存成 JSON 文本，缺值留空。CSV 以首次观察为基准，observation_count 与 observations.jsonl 保留重复和后续变化；没验证单位和格式前，不把文本报价当数字排序。只有真正入围的 ID 才再查画像和案例；导出不联系创作者，也不承诺合作预算。多个关键词分别保存证据包，保留每次搜索条件后再按 userId 合并。

### 怎样一起看报价、受众和近期案例？

为上海咖啡活动找图文合作时，先选确实写过到店体验的博主，再看候选表中的 `picturePrice`。考虑视频方案时另列 `videoPrice`。每行记录博主 ID、合作形式、报价原值、已确认的币种和单位、取得时间和案例。只比较口径相同的报价，资料不齐时标出要补的条件。

对入围博主按第 4 节补画像。围绕活动需要，记录实际返回的地区或兴趣分组、原值和可确认的数据日期。城市分布和兴趣分布各自描述不同的人群。需要判断“上海且对咖啡感兴趣”的联合人群时，等拿到对应资料再判断。读法见[受众画像问答](/zh/faq/xiaohongshu-audience-quality)。

例如一位博主有到店案例、可比较的图文价和相关地域证据，可以保留。另一位博主作品也合适，但只有视频价格，就在图文方案里写“待补图文价”。把入选理由、来源和要补的条件一起交给团队。

## 8. 只给人工入围的 ID 补数据表现证据

审阅候选 CSV 后，在入围行的 review_decision 填精确值 shortlist，其他行不动。`join_pgy_performance.py` 读取 shortlist 选择，但不请求接口，也不修改原名单。已获准查表现时，调用 xiaohongshu.pgy.get_blogger_notes_rate，显式传 business/date_type/note_type/advertise_switch；同一对比组的全部候选使用同一口径。

数据表现原文已明确 data.data.impMedian、readMedian、interactionMedian、impMedianBeyondRate。原值保留；同行百分位不是受众占比；原文没有命名的完播率、互动率字段，导出脚本不虚构。每位入围博主多一次表现请求，单价见[价格页](https://beatapi.io/zh/pricing)。

把每份真实请求与响应的对应关系存进 performance-manifest.json，填真实 HTTP 状态和时间。下面的条目只示范格式，不是实测证据：

```json
[{"action":"xiaohongshu.pgy.get_blogger_notes_rate","params":{"user_id":"YOUR_SHORTLISTED_ID","business":1,"date_type":1,"note_type":3,"advertise_switch":0},"http_status":200,"collected_at":"2026-11-16T10:00:00Z","response_file":"creator-performance.json"}]
```

把下面的脚本保存为 join_pgy_performance.py。脚本生成以 userId 为键的配套表现表，入围但还没查询、或已保存请求失败的博主都保留；脚本拒绝未入围的 ID 和混合口径，缺指标留空，并记录原始证据的哈希。每位博主绑定到实际请求清单，脚本不假设未声明的返回身份字段。

```python
import csv,datetime,hashlib,json,pathlib,sys
roster,manifest,target=map(pathlib.Path,sys.argv[1:4])
with roster.open(encoding="utf-8-sig",newline="") as f:all_rows=list(csv.DictReader(f))
selected={}
for row in all_rows:
    if row.get("review_decision")!="shortlist":continue
    uid=row.get("userId")
    if not uid or not uid.strip() or uid in selected:raise ValueError("Distinct shortlisted userId required")
    selected[uid]=row
if not selected:raise ValueError("Mark at least one reviewed creator as shortlist")
entries=json.loads(manifest.read_text(encoding="utf-8"))
if not isinstance(entries,list):raise ValueError("Manifest must be an array")
metrics=["impMedian","readMedian","interactionMedian","impMedianBeyondRate"]
observed={};scope=None;request_ids=set();evidence=[]
for entry in entries:
    if entry.get("action")!="xiaohongshu.pgy.get_blogger_notes_rate":raise ValueError("Wrong action")
    params=entry["params"];uid=params.get("user_id")
    if uid not in selected or uid in observed:raise ValueError("Only one result per shortlisted ID")
    if set(params)!={"user_id","business","date_type","note_type","advertise_switch"}:raise ValueError("Record every scope explicitly")
    for key,values in {"business":(0,1),"date_type":(1,2),"note_type":(1,2,3),"advertise_switch":(0,1)}.items():
        if type(params[key]) is not int or params[key] not in values:raise ValueError("Invalid scope")
    current={key:value for key,value in params.items() if key!="user_id"}
    if scope is None:scope=current
    if current!=scope:raise ValueError("Do not compare different content, time or traffic scopes")
    stamp=entry["collected_at"]
    if datetime.datetime.fromisoformat(stamp.replace("Z","+00:00")).tzinfo is None:raise ValueError("Timezone required")
    http=entry.get("http_status")
    if type(http) is not int or not 100<=http<=599:raise ValueError("Record HTTP status")
    path=pathlib.Path(entry["response_file"])
    if not path.is_absolute():path=manifest.parent/path
    raw=path.read_bytes();r=json.loads(raw);error=r.get("error")
    if error is not None:
        if not isinstance(error,dict) or http<400:raise ValueError("Invalid error envelope")
        rid=error.get("request_id")
    else:
        if http!=200 or r.get("action")!=entry["action"] or r.get("status")!="succeeded":raise ValueError("Unexpected response")
        rid=r.get("request_id")
    if not isinstance(rid,str) or not rid.strip() or rid in request_ids:raise ValueError("Distinct request IDs required")
    request_ids.add(rid)
    values={key:None for key in metrics};state="gateway_failed"
    if error is None:
        envelope=r.get("data")
        if not isinstance(envelope,dict):raise ValueError("PGY envelope required")
        if envelope.get("success") is False:state="pgy_business_failed"
        elif envelope.get("success") is not True:raise ValueError("Explicit PGY success required")
        elif envelope.get("data") is None:state="no_payload"
        else:
            data=envelope["data"]
            if not isinstance(data,dict):raise ValueError("Expected performance object")
            values={key:data.get(key) for key in metrics}
            state="available" if all(value is not None for value in values.values()) else "partial_metrics"
    observed[uid]={"userId":uid,"performance_state":state,**values,"performance_request_id":rid,"performance_collected_at":stamp}
    evidence.append({"userId":uid,"params":params,"request_id":rid,"source_file":str(path),"sha256":hashlib.sha256(raw).hexdigest(),"http_status":http})
rows=[]
for uid in selected:
    rows.append(observed.get(uid,{"userId":uid,"performance_state":"not_requested",**{key:None for key in metrics},"performance_request_id":"","performance_collected_at":""}))
def cell(value):
    if value is None:return ""
    text=value if isinstance(value,str) else json.dumps(value,ensure_ascii=False,separators=(",",":"))
    return "'"+text if text.lstrip().startswith(("=","+","-","@")) or text.startswith(("\t","\r","\n")) else text
target.mkdir()
with (target/"performance.csv").open("x",encoding="utf-8-sig",newline="") as f:
    writer=csv.DictWriter(f,fieldnames=list(rows[0]));writer.writeheader();writer.writerows({key:cell(value) for key,value in row.items()} for row in rows)
(target/"evidence.json").write_text(json.dumps({"scope":scope,"records":evidence,"shortlisted":len(selected),"requested":len(observed),"identity_binding":"Actual request manifest, not independently returned creator identity"},ensure_ascii=False,indent=2),encoding="utf-8")
print(str(target/"performance.csv"))
```

运行 `python3 join_pgy_performance.py creator-library-1/creators.csv performance-manifest.json creator-performance-review-1`。把原名单、请求清单和原响应与 performance.csv、evidence.json 一起留存。空清单会把全部入围博主标为 not_requested，not_requested 不代表“没有表现”；缺结果的博主仍在审核分母里。

示例口径是合作内容、近 30 天、图文 + 视频、仅自然流量，不与默认的日常内容/全部流量记录直接混排。阅读中位数不是投放总触达，同行百分位不保证适合你的产品，缺字段不是零。核对内容适配、档期和商业条件后，再另行决定是否联系。依据：`xiaohongshu.pgy.get_blogger_notes_rate` 的公开输出合同；`join_pgy_performance.py` 仅在本地运行，不发起表现查询，也不联系博主。

## 达人页的资料按什么顺序核对？

选合作候选时，先看候选表中可确认的 `picturePrice`、`videoPrice` 和案例。入围后用同一博主的 `user_id` 取详情和粉丝画像，按第 8 节保留表现数据的日期、内容类型和推广条件。页面上的成长、服务或成本模块先列成待核列，实际响应有同口径值时才填。例如合作要求受众在本地，就先确认地域证据和近期案例，再补其他材料。