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

# 怎样从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. 免费核对合同与计费单位

```bash
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，决定请求多少个相关创作者，不等于金额上限；种子本人可能额外返回一行。

### 按交付单位估算费用

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

## 3. 只发现一小批候选

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

```bash
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`，脚本不做任何外联。完全相同的重复记录合并为一行，内容冲突时停止处理，已有输出目录不会被覆盖。

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

```python
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` 不是种子账号的粉丝数，这个动作也没有下一页输入。

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

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

```python
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：

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

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