跳到导航

怎样从Instagram种子账号筛出有内容依据的合作候选?

要找与某个合适 Instagram 账号相似的创作者做合作,先写清合作要求,再以该账号为种子,用 creator.discover(按交付创作者计费)或 instagram.v2.fetch_similar_users(按请求计费)发现候选。用 creator_sheet.py 或 similar_sheet.py 把已保存响应导出为评审表,逐个查看候选的近期作品并写下具体入选理由。返回的账号列表只是起点,评审之后才决定谁值得继续沟通。

本指南以英语家用咖啡内容为例。换成你自己的产品场景时,每位入围者都要有实际内容依据。

先把合作要求写成可核对的条件

以最多三位英语家用咖啡内容创作者,供外联前评审为具体任务。先定条件,再看结果。下面的 brief 是示例,不是对真实账号的评价:

  • 必选:近期公开内容确实展示家用咖啡制作,记录两条相关作品的 URL、日期和适配理由。英语内容只是内容要求,不证明受众所在国家。
  • 必选:从记录的评审日期往前 30 天内,至少有一条相关作品。返回的 posts_count 是累计发帖数,不证明最近活跃。
  • 优选:返回的粉丝数在 10,000–100,000。粉丝范围是本次合作的选择,不是 API 的质量标准。粉丝数缺失时进入补查,不补零,也不直接淘汰。
  • 本阶段不必选:已发现的邮箱。没有邮箱不应淘汰内容合适的账号;有邮箱也不代表对方同意接收消息。报价和档期另行核实。

保留原导出 CSV 不变,另存一份评审副本。在副本里填写已有的 fit_reason、checks_needed,并自己增加 evidence_urls、reviewed_at、reviewer 三列。新增列是人工核查记录,不是 API 返回字段。保留原账号身份和 request_id,方便同事回溯每个决定。不要把推广品牌的地址写进创作者的“已验证联系方式”。

示意核查结果决定理由必须说明什么
两篇有日期的咖啡教程符合主题,其中一篇在评审时间窗内shortlist列出实际的两篇作品和评审日期;shortlist 只表示进入下一轮合作评审,不代表签约或外联授权。
简介提到咖啡,但近期作品尚未核查hold写清缺少什么内容证据、下一步查什么;不能用简介和累计发帖数认证活跃。
已查看的近期作品主题与 brief 不符reject引用与本次 brief 不符之处,不把对方标为“假达人”。
返回的是种子本人seed reference种子行作为参考单独保留,不计入新发现的候选。

最终交付原始响应和 request_id、未编辑的导出 CSV、填好的评审副本和一段决策说明。返回行、去重候选、种子行、入围/待查/淘汰账号和身份未明记录分别统计,每个候选只计一次。如果实际是一人入围、一人待查、一人淘汰,就照实写,不能写成“三位合格达人”。没有合格人选也是有效结果,不代表可以再付费查询一次。

复用到下一次活动时,brief 和评审日期随评审副本一起保存。联系前重新打开引用的主页和作品,数月前的 has_email 或互动数字不能当作当下的核验。整个流程止于有证据的评审表,不发送任何消息。

选择发现方式

你需要什么路线怎么继续
带可返回资料的创作者候选data:creator.discover按交付创作者计费,导出后核对内容与缺项
只要平台给的相似账号身份data:instagram.v2.fetch_similar_users按请求计费,先看主页和作品,再补需要的资料

先选一条路线;已有返回时直接从本地评审开始。下面分别给出两条路线的请求和评审表导出。

1. 选择种子并限定范围

记下种子账号名或主页链接,以及种子账号适合本次合作的理由:主题、语言、内容形式和已核对的受众要求。不要只因粉丝多就用无关的大号做种子。creator.discover 目前只接受 platform: instagram,不能换成 TikTok 或 YouTube 后假设有同样的相似账号查找。

2. 免费核对合同与计费单位

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

上面的 /v1/capabilities/inspect 调用免费。看返回的 pricing.unit,不只看金额:creator.discover 按 creator 计费,不同于按 request 计费的普通社媒动作。limit 范围是 1–6,决定请求多少个相关创作者,不等于金额上限;种子本人可能额外返回一行。

按交付单位估算费用

当前单价看价格页。creator.discover 按返回的创作者条目计费:limit:3 请求三个相似候选,种子本人可能额外返回一行,估算时把种子行也算上;成功的空结果按一个单位的最低额计费。后面的本地去重和评审不改变已交付条目的费用。

3. 只发现一小批候选

确认价格和计费单位后,把 <seed_handle> 换成选定的种子账号。下面的请求要三个相似候选,费用另需计入可能返回的种子行:

mkdir creator-query && \
curl --fail-with-body -sS https://api.beatapi.io/v1/social-data/call \
-H "Authorization: Bearer $BEATAPI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"action":"creator.discover","params":{"platform":"instagram","seed":"<seed_handle>","limit":3}}' \
-D creator-query/response.headers \
-o creator-query/instagram-creator-candidates.json

先检查 status 和 request_id。已发布的输出把候选放在 data[],不是 data.items。部分字段可能缺失或为 null;保留原始 JSON,不要把缺失的互动率填 0 再排到最后。种子账号本身返回时,按返回的身份和 discovered_via 认出种子行,不算作新发现的候选。

4. 先看证据,再做合作判断

  • handle、profile_url、bio 用于核对实际账号和内容,不要只看 lead_score。
  • followers、posts_count 说明规模和发帖数量,不证明粉丝真实或合作效果。
  • engagement_rate_pct、avg_likes 保留原值和缺失,不混用百分比和小数率。
  • email 和 has_email 只是发现的线索,不证明邮箱归属、可达性或允许发送。关联网站上的邮箱也可能属于创作者推广的品牌,不是创作者本人。
  • 地区、报价、档期、内容相关性等合作条件需要实际来源支持;没有对应证据的条件留在待查列。

候选表里默认的 review 只表示待审核,不是通过审核。人工查看近期内容,填写 fit_reason、checks_needed,再标记保留或不选;缺数据的候选不自动判为低质量。没有授权时,不为所有候选补查联系信息,不发送邮件或私信。

给团队交候选表时,入选理由写到作品层。例如「两条近期视频都展示了雨天步行,适合通勤鞋试穿」并附链接。另一位候选只有室内走秀,就写「待补户外试穿案例」。联系状态这一列留给已核对的公开资料。

5. 从已保存响应导出审核表

把下面的脚本保存为 creator_sheet.py,执行 python3 creator_sheet.py creator-query/instagram-creator-candidates.json <original_seed_handle> creator-review。creator_sheet.py 不访问网络,生成 creators.csv 与 coverage.json,保留稳定 ID、缺失值、原始来源,并区分种子行。联系信息一律标为 not_verified,脚本不做任何外联。完全相同的重复记录合并为一行,内容冲突时停止处理,已有输出目录不会被覆盖。

交接时保留原始查询时间和参数。空结果仍会生成表头和零候选的覆盖记录,空结果的查询同样计费。邮箱核验或外联是后续的独立任务,发现结果不自动授权这些任务。

import csv
import json
import sys
from decimal import Decimal, InvalidOperation
from pathlib import Path
from urllib.parse import urlsplit
source, seed, output = sys.argv[1:]
def handle(value):
value = value.strip()
if "://" in value:
url = urlsplit(value)
if url.hostname not in ("instagram.com", "www.instagram.com"):
raise SystemExit("Use an Instagram seed profile")
value = url.path.strip("/")
value = value.lstrip("@").lower()
if not value or "/" in value or any(not (c.isalnum() or c in "._") for c in value):
raise SystemExit("Use the original seed handle or profile URL")
return value
seed_handle = handle(seed)
raw = json.loads(Path(source).read_text(encoding="utf-8"))
if raw.get("status") != "succeeded" or raw.get("action") != "creator.discover" or not raw.get("request_id"):
raise SystemExit("Expected successful creator.discover with request provenance")
items = raw.get("data")
if not isinstance(items, list):
raise SystemExit("Expected the published data array")
def metric(value, integer=False):
if value is None:
return ""
try:
if isinstance(value, bool):
raise InvalidOperation
n = Decimal(str(value))
if not n.is_finite() or n < 0 or (integer and n != n.to_integral_value()):
raise InvalidOperation
return int(n) if integer else str(n)
except InvalidOperation:
raise SystemExit("Invalid numeric metric")
rows, seen, duplicates = [], {}, 0
for item in items:
if not isinstance(item, dict) or item.get("platform") not in (None, "instagram"):
raise SystemExit("Unexpected creator record/platform")
normalized = handle(item["handle"]) if item.get("handle") else ""
profile_handle = handle(item["profile_url"]) if item.get("profile_url") else ""
if normalized and profile_handle and normalized != profile_handle:
raise SystemExit("Creator handle and profile URL identify different accounts")
normalized = normalized or profile_handle
user_id = item.get("user_id")
if user_id is not None and not isinstance(user_id, str):
raise SystemExit("Preserve platform user IDs as strings")
aliases = (["id:" + user_id] if user_id else []) + (["handle:" + normalized] if normalized else [])
if not aliases:
raise SystemExit("No stable creator identity")
previous = [seen[key] for key in aliases if key in seen]
if previous:
if any(record != item for record in previous):
raise SystemExit("Conflicting duplicate creator records")
duplicates += 1
continue
for key in aliases:
seen[key] = item
is_seed = normalized == seed_handle if normalized else None
email = item.get("email")
if email is not None and not isinstance(email, str):
raise SystemExit("Unexpected email field type")
row = {"user_id": user_id or "", "handle": item.get("handle"), "name": item.get("name"),
"profile_url": item.get("profile_url"), "bio": item.get("bio"),
"followers": metric(item.get("followers"), True), "posts_count": metric(item.get("posts_count"), True),
"engagement_rate_pct": metric(item.get("engagement_rate_pct")), "avg_likes": metric(item.get("avg_likes")),
"email": email, "has_email_reported": item.get("has_email"), "contact_verification": "not_verified",
"discovered_via": item.get("discovered_via"), "is_seed": is_seed,
"decision": "identity_review" if is_seed is None else ("seed_reference" if is_seed else "review"), "fit_reason": "", "checks_needed": "",
"source_file": source, "request_id": raw["request_id"]}
rows.append(row)
folder = Path(output)
folder.mkdir(exist_ok=False)
columns = ["user_id", "handle", "name", "profile_url", "bio", "followers", "posts_count", "engagement_rate_pct", "avg_likes", "email", "has_email_reported", "contact_verification", "discovered_via", "is_seed", "decision", "fit_reason", "checks_needed", "source_file", "request_id"]
with (folder / "creators.csv").open("x", encoding="utf-8-sig", newline="") as file:
writer = csv.DictWriter(file, fieldnames=columns)
writer.writeheader()
for row in rows:
writer.writerow({k: ("'" + v if isinstance(v, str) and v.lstrip().startswith(("=", "+", "-", "@")) else v) for k, v in row.items()})
(folder / "coverage.json").write_text(json.dumps({"returned_records": len(items), "unique_records": len(rows),
"duplicate_records": duplicates, "identified_seed_records": sum(v["is_seed"] is True for v in rows),
"review_candidates": sum(v["is_seed"] is False for v in rows), "unresolved_seed_identity": sum(v["is_seed"] is None for v in rows), "emails_verified": 0, "messages_sent": 0,
"scope": "candidate discovery, not audience authenticity or campaign performance proof"}, indent=2), encoding="utf-8")

依据:已发布的 creator.discover 与 instagram.v2.fetch_similar_users 合同;本页示例不是付费发现的结果。

另一条路径:只审核平台推荐相似账号,不自动追加资料补全

只需要账号身份和私密、认证标记时,单独使用按请求计费的 instagram.v2.fetch_similar_users,输入 username 或 user_id。instagram.v2.fetch_similar_users 不提供上文 creator.discover 的指标和联系方式补全。先免费 Inspect,再选一条路线,不要两条都付费。返回的 count 不是种子账号的粉丝数,这个动作也没有下一页输入。

{"action":"instagram.v2.fetch_similar_users","params":{"username":"<reviewed_seed_username>"}}

把成功的原始响应保存为 instagram-similar.json。下面的 similar_sheet.py 按已验证的 data.data.items 路径生成人工审核表:每行必须有返回的 ID 和用户名才能追溯,未知标记留空,标出种子账号并拒绝身份冲突。similar_sheet.py 不联网、不关注账号,也不发起联系。

import csv
import json
import re
import sys
from pathlib import Path
source, seed, output = sys.argv[1:4]
if not re.fullmatch(r"[A-Za-z0-9_.]+", seed):
raise SystemExit("Use the original plain seed username, not a URL or display name.")
raw = json.loads(Path(source).read_text(encoding="utf-8"))
if raw.get("status") != "succeeded" or raw.get("action") != "instagram.v2.fetch_similar_users":
raise SystemExit("Expected successful Instagram similar-users response.")
request_id = raw.get("request_id")
if not isinstance(request_id, str) or not request_id.strip():
raise SystemExit("Missing request_id.")
items = raw.get("data", {}).get("data", {}).get("items")
if not isinstance(items, list):
raise SystemExit("Expected data.data.items array.")
rows, by_id, by_handle = [], {}, {}
duplicates = 0
for item in items:
if not isinstance(item, dict):
raise SystemExit("Candidate must be an object.")
uid, handle = item.get("id"), item.get("username")
if not isinstance(uid, str) or not uid.strip() or uid != uid.strip() or uid in {"[redacted]", "[redacted-depth]"} or not isinstance(handle, str) or not re.fullmatch(r"[A-Za-z0-9_.]+", handle):
raise SystemExit("Candidate needs a returned user ID and valid username; keep the raw file for review.")
name = item.get("full_name")
if name is not None and not isinstance(name, str):
raise SystemExit("Invalid display name.")
flags = [item.get("is_private"), item.get("is_verified")]
if any(value is not None and type(value) is not bool for value in flags):
raise SystemExit("Account flags must be booleans or absent.")
identity = handle.lower()
comparable = [identity, name, *flags]
if uid in by_id:
if by_id[uid] != comparable:
raise SystemExit("Conflicting observations for the same user ID.")
duplicates += 1
continue
if identity in by_handle and by_handle[identity] != uid:
raise SystemExit("Same username is associated with conflicting user IDs.")
by_id[uid] = comparable
by_handle[identity] = uid
rows.append({"user_id": uid, "username": handle, "display_name": name,
"profile_url": f"https://www.instagram.com/{handle}/", "is_private": flags[0],
"is_verified": flags[1], "seed_username": seed, "is_seed": identity == seed.lower(),
"decision": "exclude_seed" if identity == seed.lower() else "review",
"fit_reason": "", "checks_needed": "", "source_file": source, "request_id": request_id})
folder = Path(output)
folder.mkdir(exist_ok=False)
columns = ["user_id", "username", "display_name", "profile_url", "is_private", "is_verified", "seed_username", "is_seed", "decision", "fit_reason", "checks_needed", "source_file", "request_id"]
with (folder / "similar-accounts.csv").open("x", encoding="utf-8-sig", newline="") as file:
writer = csv.DictWriter(file, fieldnames=columns)
writer.writeheader()
for row in rows:
writer.writerow({key: ("'" + value if isinstance(value, str) and value.lstrip().startswith(("=", "+", "-", "@")) else value) for key, value in row.items()})
(folder / "coverage.json").write_text(json.dumps({"returned_records": len(items), "unique_accounts": len(rows), "duplicates": duplicates,
"seed_accounts": sum(row["is_seed"] for row in rows), "messages_sent": 0,
"scope": "similarity recommendations, not followers, audience verification or verified contacts"}, indent=2), encoding="utf-8")

命令里的种子用户名填本次 instagram.v2.fetch_similar_users 请求实际使用的值,不带 @,也不用主页 URL:

python3 similar_sheet.py instagram-similar.json '<reviewed_seed_username>' similar-review

查看每位候选的主页内容,填写 decision、fit_reason 和 checks_needed。私密账号不自动等于不合适,但这一行不提供查看其私密内容的权限;认证标记也不证明受众质量。联系方式或受众字段没有出现,是 instagram.v2.fetch_similar_users 不提供,不是零;只对选中的候选在单独预算内补资料。