跳到导航

如何筛选小红书合作博主,并核对受众和近期案例?

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

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

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

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

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

1. 明确条件和调用范围

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

2. 免费 Inspect,再取一页候选

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

先在 Inspect 结果里确认嵌套筛选与价格,批准后再执行收费请求。下面的请求按笔记关键词检索“咖啡”相关博主,粉丝区间只是示例:

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。要叠加地区和报价条件,见筛选条件;已有种子账号时,可以从相似发现开始。

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 调用两个动作:

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 列出了画像已明确的分布字段,不保证每位创作者都返回每个字段。实际响应带有估计值时,保留估计含义;受众画像不等于真假粉鉴定。

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

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

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 补写。

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

6. 交付名单并记录成本

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

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

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

合作案例参数 · 自然流量口径 · 小红书问题索引

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

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

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

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

[{"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 的公开响应字段结构。

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 节补画像。围绕活动需要,记录实际返回的地区或兴趣分组、原值和可确认的数据日期。城市分布和兴趣分布各自描述不同的人群。需要判断“上海且对咖啡感兴趣”的联合人群时,等拿到对应资料再判断。读法见受众画像问答。

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

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。原值保留;同行百分位不是受众占比;原文没有命名的完播率、互动率字段,导出脚本不虚构。每位入围博主多一次表现请求,单价见价格页。

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

[{"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 和混合口径,缺指标留空,并记录原始证据的哈希。每位博主绑定到实际请求清单,脚本不假设未声明的返回身份字段。

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 节保留表现数据的日期、内容类型和推广条件。页面上的成长、服务或成本模块先列成待核列,实际响应有同口径值时才填。例如合作要求受众在本地,就先确认地域证据和近期案例,再补其他材料。