跳转到内容

Telegram 用户名资料检测 API

通过 Telegram 用户名获取开通状态、昵称和头像，并对头像进行图像识别，输出性别、年龄和肤色。本产品直接使用用户名，不使用手机号。

输入格式

上传文本文件，每行一个 Telegram 用户名。支持 username、@username、t.me/username，也支持完整的 https://t.me/username 链接。

OpenAI
@Telegram
t.me/durov

有效用户名长度为 5–32 位，必须以字母开头，只能包含字母、数字和下划线。结果会保留上传时的拼写、大小写和前缀格式。

创建任务

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

curl --location 'https://api.numberchecker.ai/v1/tasks' \
--header 'X-API-Key: YOUR_API_KEY' \
--form 'file=@"./usernames.txt"' \
--form 'task_type="tg_username_profile"'
参数类型必填说明
filefile是文本文件，每行一个 Telegram 用户名
task_typestring是固定为 tg_username_profile

创建成功返回 HTTP 202：

{
  "task_id": "d7profile123example",
  "status": "pending",
  "total": 3,
  "message": "Task created successfully",
  "created_at": "2026-08-11T10:00:00Z"
}

查询任务状态

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="d7profile123example"'

当 status 为 exported 时，通过 result_url 下载 ZIP 结果包。

结果文件

ZIP 结果包包含 activated.txt、unregistered.txt、all.csv 和 result.xlsx。

all.csv 和 result.xlsx 包含以下字段：

字段说明示例
username上传文件中的用户名原格式@Telegram
activatedTelegram 用户名是否开通yes、no
nicknameTelegram 昵称Telegram
avatar头像链接；无头像时为空https://example.com/avatar.jpg
gender根据头像识别的性别；无法识别时为空male、female
age根据头像识别的年龄或年龄段；无法识别时为空25
skin_color根据头像识别的肤色；无法识别时为空light、dark

结果不包含 type 和 members 字段。图像识别字段为推断结果；没有头像或头像不适合识别时，相关字段可能为空。

任务状态响应

{
  "created_at": "2026-08-11T10:00:00Z",
  "updated_at": "2026-08-11T10:02:30Z",
  "task_id": "d7profile123example",
  "user_id": "YOUR_USER_ID",
  "status": "exported",
  "total": 3,
  "success": 3,
  "failure": 0,
  "result_url": "https://example.com/result.zip"
}