Facebook ID/用户名档案检测 API：批量画像

按数字 ID、用户名（vanity）或主页链接检测 Facebook 个人主页与公共主页（Page），返回头像（转存为永久链接）、数字 ID、规范用户名、显示姓名、简短简介，以及粉丝数和“正在讨论”数。本产品只读取登出状态下可见的公开 Facebook 主页：不登录，不采集好友数据。不存在、已停用或登出访客不可见的主页返回未开通。该任务采用标准的异步批量处理流程。

输入格式

每行一个 Facebook 标识，上传一个文本文件。支持以下形式：

• 数字主页 ID，如 4
• 用户名（vanity），如 zuck 或 @zuck；由字母、数字和点组成，1–50 个字符，不区分大小写
• 主页链接，如 facebook.com/zuck、facebook.com/profile.php?id=100003012457235 或 facebook.com/people/<Name>/<ID>

非主页类的 facebook.com 链接（groups、pages、login 等路径）会被判为无效条目并拒绝。

4
zuck
@Meta
https://www.facebook.com/profile.php?id=100003012457235
https://www.facebook.com/people/Mark-Zuckerberg/4/

创建任务

POST https://api.checknumber.ai/v1/tasks

curl --location 'https://api.checknumber.ai/v1/tasks' \
--header 'X-API-Key: YOUR_API_KEY' \
--form 'file=@"./input.txt"' \
--form 'task_type="facebook_profile"'

接口返回任务 ID，请保存该 ID 用于轮询任务状态。

上传响应

{
  "task_id": "d4g8o46p2jvh04o9uolg",
  "status": "pending",
  "total": 5000,
  "estimated_amount": {
    "amount": "1.500000",
    "currency": "USD"
  },
  "message": "Task created successfully"
}

查询任务状态

POST https://api.checknumber.ai/v1/gettasks

curl --location 'https://api.checknumber.ai/v1/gettasks' \
--header 'X-API-Key: YOUR_API_KEY' \
--form 'task_id="d4g8o46p2jvh04o9uolg"'

轮询直到 status 变为 exported。不要把 pending 或 processing 当作已完成。

处理中响应

{
  "task_id": "d4g8o46p2jvh04o9uolg",
  "status": "processing",
  "total": 5000,
  "success": 2500,
  "failure": 0
}

已导出响应

{
  "task_id": "d4g8o46p2jvh04o9uolg",
  "status": "exported",
  "total": 5000,
  "success": 5000,
  "failure": 0,
  "result_url": "https://example-link-to-results.zip",
  "actual_amount": {
    "amount": "1.500000",
    "currency": "USD"
  }
}

结果字段

结果 CSV 按以下顺序包含这些列：username,activated,avatar,fb_id,fb_username,name,image,tagline,followers,talking_about。

字段	说明	示例
username	提交的标识（ID、用户名或主页链接），原样返回。	4
activated	是否拿到了公开主页（yes/no）。no 表示主页不存在、已停用或登出访客不可见；Facebook 对这三种情况显示同一个“内容不可用”页面，无法区分。	yes
avatar	头像转存到 fb.waavatar.xyz 的永久链接。activated 为 no 时为空。	https://fb.waavatar.xyz/ins/62e8bb6110133ef3115f55454ff66c4d.jpg
fb_id	从页面解析出的 Facebook 数字主页 ID。	4
fb_username	Facebook 显示的规范用户名（vanity）；仅有 ID 的主页为空。	zuck
name	显示姓名。	Mark Zuckerberg
image	Facebook 自身带签名的 CDN 头像链接，几天内会过期；需要长期链接请使用 avatar。	https://scontent.xx.fbcdn.net/v/…jpg?…&oe=…
tagline	页面描述中的简短简介，可能为空。	Bringing the world closer together.
followers	粉丝数；公共主页（Page）为“赞”数。整数，未显示时为空。	121439077
talking_about	Facebook 的“正在讨论”数。整数，未显示时为空。	918893

示例行：

username,activated,avatar,fb_id,fb_username,name,image,tagline,followers,talking_about
4,yes,https://fb.waavatar.xyz/ins/62e8bb6110133ef3115f55454ff66c4d.jpg,4,zuck,Mark Zuckerberg,https://scontent.xx.fbcdn.net/v/....jpg?...&oe=...,Bringing the world closer together.,121439077,918893
zzqqxxjjkk993827a,no,,,,,,,,

个人主页和公共主页（Page）均支持。例如 Meta 解析为 fb_id 100080376596424，其 followers 为该 Page 的赞数。

结果文件处理

任务导出后再从 result_url 下载文件。下游处理时请保留返回的列名。

响应字段

字段	说明
created_at	任务创建时间。
updated_at	任务状态最近更新时间。
task_id	任务唯一标识。
status	pending、processing、exported 或 failed。
total	处理的输入总数。
success	成功处理的条数。
failure	处理失败的条数。
result_url	任务导出后的下载链接。
actual_amount	最终结算金额（可用时返回）。
estimated_amount	创建任务时返回的预估金额。

状态码

状态码	说明
200	请求成功。
202	任务创建成功并已预扣费用。
400	文件无效、任务类型不支持或有效条目过少。
401	API Key 缺失或无效。
402	账户余额不足。
403	该产品对您的账户不可用（已下线或仅白名单）；请联系客服。
404	任务不存在。
413	上传文件过大。
500	服务器内部错误，请稍后重试。
503	产品暂时不可用（维护中暂停）；不会扣费，请稍后重试。

使用说明

• 任务为异步执行，请用任务 ID 轮询状态。
• 价格：每 10,000 个标识 $3。按提交数量计费：每个提交的标识都计费，无论是否找到主页。每个任务最低按 500 个标识计费，不足 500 的任务按 500 计。
• 结果反映检测时的公开主页状态。不使用缓存，每次提交都会重新检测。
• 上传前请确认产品的输入限制。
• 失败的行会体现在导出结果和任务计数中。
• 以上字段基于当前线上样本，上游页面结构变化时可能调整。