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.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="instagram_profile"'

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

上传响应

{
  "task_id": "d4g8o46p2jvh04o9uolg",
  "status": "pending",
  "total": 5000,
  "estimated_amount": {
    "amount": "1.250000",
    "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.250000",
    "currency": "USD"
  }
}

结果字段

字段	说明	示例
username	提交的用户名或主页链接，原样返回。	cristiano
activated	账号是否存在（no 表示没有该用户名）。	yes
avatar	从最新一张含人脸的帖子裁剪的人脸头像公开链接，转存在 ins.waavatar.xyz（长期有效）；未找到人脸、账号私密或没有帖子时为空。	https://ins.waavatar.xyz/ins/ec966a0f864e4aba1fd2899dce2c3fed.jpg
ig_username	解析出的 Instagram 用户名（提交的是数字 ID 时同样返回）；账号不存在时为空。	villavicenciopaul
full_name	主页显示的姓名。	Cristiano Ronaldo
posts	帖子数。	4138
followers	粉丝数。	679725371
following	关注数。	636
private	账号是否私密（yes/no）。	no
verified	账号是否有认证标识（yes/no）。	yes
face_status	人脸提取结果：ok（裁剪图大于 400 px）、ok_small（保留了较小的人脸）、no_face、no_640_face（没有 640 px 以上的帖子图）、private、empty（无帖子）、posts_missed。	ok

结果文件处理

任务导出后再从 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 轮询状态。
• 上传前请确认产品的输入限制。
• 失败的行会体现在导出结果和任务计数中。
• 头像取自公开帖子在登出状态下的分辨率（640 px），因此多数裁剪图小于 400 px，标记为 ok_small。
• 以上字段基于当前线上样本，上游导出结构变化时可能调整。