Telegram 用户名开通检测 API

批量检测 Telegram 用户名是否已注册并处于开通状态。本产品直接使用用户名，不使用手机号。

输入格式

上传文本文件，每行一个 Telegram 用户名，支持以下格式：

OpenAI
@Telegram
t.me/durov
https://t.me/example_user

有效用户名长度为 5–32 位，必须以字母开头，只能包含字母、数字和下划线。Telegram 用户名不区分大小写。

结果文件会保留上传时的拼写、大小写和前缀格式。等价的重复用户名只检测一次，结果保留首次出现的有效格式。

创建任务

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

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

创建成功返回 HTTP 202：

{
  "task_id": "d7abc123example",
  "status": "pending",
  "total": 4,
  "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="d7abc123example"'

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

结果文件

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

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

字段	说明	示例
username	上传文件中的用户名原格式	@OpenAI
activated	Telegram 用户名是否开通	yes、no

任务状态响应

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