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

按用户名（ID）或主页链接检测 Instagram 账号，返回最新一张含人脸的帖图原图（转存，不裁剪）、姓名、帖子数、粉丝数、关注数，以及账号是否私密、是否认证。不存在的账号返回未开通；私密账号返回已开通和资料字段，但不含头像。该任务采用标准的异步批量处理流程。

输入格式

每行一个 Instagram 用户名（ID），上传一个文本文件。支持 username、@username 或完整的 instagram.com/<username> 链接，匹配不区分大小写。

也支持提交数字 Instagram ID（pk），会自动解析成用户名。

cristiano
@zuck
https://www.instagram.com/natgeo/
1367088262

创建任务

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

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

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

上传响应

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

查询任务状态

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

curl --location 'https://api.numberchecker.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.100000",
    "currency": "USD"
  }
}

结果字段

字段	说明	示例
username	提交的用户名或主页链接，原样返回。	cristiano
activated	是否为该 ID 拿到了头像图（yes/no）。账号存在但没有可用帖图（私密、无帖子、无人脸、图太小）以及不存在的 ID 都是 no。只有 yes 的行计费。	yes
avatar	最新一张含人脸的帖图原图（不裁剪）转存到 ins.waavatar.xyz 的公开链接，长期有效。只交付长或宽大于 500 px 的图片，不使用账号头像。没有这类图片（私密、无帖子、无人脸）时为空。	https://ins.waavatar.xyz/ins/ec966a0f864e4aba1fd2899dce2c3fed.jpg
visibility	Instagram 账号是否私密：private 或 public；账号不存在时为空。	public
ig_username	解析出的 Instagram 用户名（提交的是数字 ID 时同样返回）；账号不存在时为空。	villavicenciopaul
full_name	主页显示的姓名。	Cristiano Ronaldo
posts	帖子数。	4138
followers	粉丝数。	679725371
following	关注数。	636
verified	账号是否有认证标识（yes/no）。	yes

结果文件处理

任务导出后再从 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 轮询状态。
• 上传前请确认产品的输入限制。
• 失败的行会体现在导出结果和任务计数中。
• 交付的是整张帖图（不裁剪），分辨率为登出状态下 Instagram 提供的 640 档；只有检测到的人脸区域大于 250 px 时才交付。
• 以上字段基于当前线上样本，上游导出结构变化时可能调整。