API de Avatares de Telegram: Análisis Masivo de Perfiles

Consulta la información del avatar de las cuentas de Telegram asociadas a los números globales ingresados, incluido si la cuenta está activa, la URL de la foto de perfil, el género, la edad, el color de cabello y el color de piel.

Ejemplo para subir el archivo de detección:

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

Ejemplo para consultar el estado de la tarea:

curl --location 'https://api.checknumber.ai/v1/gettasks' \
--header 'X-API-Key: API-KEY' \
--form 'task_id="task_id"'

Respuesta cuando la carga del archivo fue exitosa:

{
    "task_id": "d4g8o46p2jvh04o9uolg",
    "status": "pending",
    "total": 2049,
    "estimated_amount": {
        "amount": "0.500000",
        "currency": "USD"
    },
    "message": "Task created successfully",
    "created_at": "2025-11-21T15:58:08.916446594Z"
}

Respuesta para el estado de procesamiento:

{
    "created_at": "2025-11-21T08:27:09.933Z",
    "updated_at": "2025-11-21T08:27:10.241Z",
    "task_id": "d4g24nep2jvh04o9uoh0",
    "user_id": "wfi7wGPS4B4PdtTMox5Y",
    "status": "processing",
    "total": 2049,
    "success": 1024,
    "failure": 0
}

Respuesta cuando la tarea está completada (incluye la URL de descarga):

{
    "created_at": "2025-11-21T08:27:09.933Z",
    "updated_at": "2025-11-21T08:27:10.241Z",
    "task_id": "d4g24nep2jvh04o9uoh0",
    "user_id": "wfi7wGPS4B4PdtTMox5Y",
    "status": "exported",
    "total": 2049,
    "success": 2049,
    "failure": 0,
    "result_url": "https://wapic.s3.ap-southeast-1.amazonaws.com/externalcheck/d4g24nep2jvh04o9uoh0/d4g24nep2jvh04o9uoh0.zip?X-Amz-Algorithm=AWS4-HMAC-SHA256...",
    "actual_amount": {
      "amount": "2.000000",
      "currency": "USD"
    }
}

URL de solicitud para subir archivo

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

Parámetros de solicitud para subir archivo

Parámetro	Descripción
file	file, Sube un archivo; cada línea debe contener un número en formato E.164
task_type	string, Tipo de tarea, establecer en “tg_avatar”

URL de solicitud para consultar estado

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

Parámetros de solicitud para consultar estado

Parámetro	Descripción
task_id	string, ID de tarea devuelto al crear la tarea

Campos del resultado

Campo	Descripción	Ejemplo
Number	Número de teléfono en formato E.164	+41798284651
telegram	Indica si el número tiene una cuenta activa de Telegram	sí, no
avatar	URL de la foto de perfil de Telegram	https://example.com/avatar.jpg
age	Rango de edad estimado según la foto de perfil	25
gender	Género detectado en la foto de perfil	hombre, mujer
category	Clasificación del tipo de foto de perfil	retrato individual, avatar de mascota, objeto, etc.
hair_color	Color de cabello detectado en la foto de perfil	negro, castaño, rubio, etc.
skin_color	Color de piel detectado en la foto de perfil	blanco, negro, etc.

Formato de respuesta

Campo	Descripción
created_at	Marca de tiempo de creación de la tarea
updated_at	Marca de tiempo de la última actualización del estado de la tarea
task_id	Identificador único de la tarea
user_id	ID del usuario
status	Estado de la tarea: pending: En cola y en espera processing: En procesamiento exported: Resultados disponibles para descargar failed: La tarea falló, el importe cobrado se reembolsa automáticamente
total	Total de números de teléfono procesados
success	Números identificados correctamente
failure	Números cuyo procesamiento falló
result_url	(Opcional) URL de descarga de los resultados cuando el estado es exported
actual_amount	(Opcional) Importe realmente cobrado, disponible cuando la tarea se liquida
estimated_amount	(Respuesta de creación) Importe estimado de la tarea; el cobro final se liquida al completarse

Códigos de estado

Estado	Descripción
200	free, Solicitud correcta (p. ej., consulta de estado)
202	charge, Tarea creada correctamente; se deduce el importe estimado
400	free, Solicitud incorrecta: parámetros o formato de archivo no válidos, tipo de tarea no admitido o entradas válidas por debajo del lote mínimo
401	free, Clave API ausente o no válida
402	free, Saldo insuficiente
404	free, Tarea no encontrada
413	free, Archivo subido demasiado grande
500	free, Error interno del servidor; inténtelo más tarde