Telegram 用户名头像检测 API

通过 Telegram 用户名批量获取开通状态、昵称和头像。本产品直接使用用户名，不使用手机号。

输入格式

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

OpenAI
@Telegram
t.me/durov

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

创建任务

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

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

参数	类型	必填	说明
file	file	是	文本文件，每行一个 Telegram 用户名
task_type	string	是	固定为 tg_username_avatar

创建成功返回 HTTP 202：

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

查询任务状态

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

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

结果文件

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

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

字段	说明	示例
username	上传文件中的用户名原格式	t.me/durov
activated	Telegram 用户名是否开通	yes、no
nickname	Telegram 昵称	Pavel Durov
avatar	头像链接；无头像时为空	https://example.com/avatar.jpg

结果不包含 type 和 members 字段。

任务状态响应

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