Solicitud cURL
POST /api/v1/bulk-taskscurl -X POST "https://avatarlookup.com/api/v1/bulk-tasks" \
-H "X-API-Key: sk_your_api_key" \
-F service_type=ws_profile_batch \
-F country=US \
-F file=@numbers.txt
Producto masivo ws_profile_batch
Análisis de avatares de WhatsApp · Masivo
Suba un archivo completo de números: URL del avatar de WhatsApp y lo que muestra el avatar (categoría, edad, género, tono de piel y color de cabello).
Un complemento para listas grandes completas: para unos pocos identificadores, la verificación en tiempo real responde en la misma solicitud. Verificación en tiempo real →
Contrato de la API
Dos pasos: enviar el archivo y consultar la tarea
Al enviar se devuelve de inmediato un ID de tarea; consulte la tarea con ese ID y, cuando se complete correctamente, la respuesta incluirá el enlace de descarga del archivo de resultados. Cada solicitud se muestra con su propia respuesta.
1. Enviar el archivo
El ID de tarea se devuelve de inmediato con preparing en true mientras el archivo se prepara en segundo plano: se eliminan las líneas no válidas, los duplicados y, en las tareas de números, los números sin código de país o de otro país, que no se cobran. El saldo se reserva para las líneas enviadas y se liquida al completarse; la diferencia se reembolsa.
Respuesta: tarea creada
200 OK{
"code": 0,
"msg": "ok",
"data": {
"id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
"product": "ws_profile_batch",
"status": "processing",
"country": "US",
"submitted_lines": 1015,
"total": 1015,
"invalid_cnt": 0,
"no_code_cnt": 0,
"other_country_cnt": 0,
"duplicate_cnt": 0,
"preparing": true,
"created_at": "2026-09-08T09:30:00Z"
}
}2. Consultar la tarea
Sondee por ID de tarea. Cuando finaliza la preparación, submitted_lines = total + invalid_cnt + no_code_cnt + other_country_cnt + duplicate_cnt, donde total es lo que se verifica y se cobra. Una respuesta correcta incluye los recuentos de éxitos y fallos y el enlace de descarga del archivo de resultados; una tarea rechazada durante la preparación queda en failed con reason_detail y se reembolsa íntegramente.
Solicitud cURL
GET /api/v1/bulk-tasks/{id}curl "https://avatarlookup.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
-H "X-API-Key: sk_your_api_key"Respuesta: tarea finalizada
200 OK{
"code": 0,
"msg": "ok",
"data": {
"id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
"product": "ws_profile_batch",
"status": "success",
"country": "US",
"submitted_lines": 1015,
"total": 1000,
"invalid_cnt": 3,
"no_code_cnt": 0,
"other_country_cnt": 0,
"duplicate_cnt": 12,
"preparing": false,
"success_cnt": 990,
"failure_cnt": 10,
"result_url": "https://…/result.csv",
"created_at": "2026-09-08T09:30:00Z"
}
}Cómo se ejecuta
Qué ocurre con una tarea masiva
El modo masivo no es una versión ampliada del tiempo real: se envía una vez, se ejecuta en segundo plano y se recoge más tarde. No necesita mantener la página abierta; el estado de la tarea y los resultados permanecen en su panel.
01Suba el archivo
Un archivo .txt o .csv con un número por línea. Se transmite directamente; no se escribe nada en disco.
02Comprobación previa y reserva
Los problemas evidentes (un archivo vacío, un formato incorrecto, muy pocas líneas) se rechazan al subir el archivo. Después se reserva el saldo y el archivo se prepara en segundo plano: se eliminan las líneas duplicadas y no válidas y se comprueba la regla del país. Un archivo que falla en ese punto termina como tarea fallida y se reembolsa íntegramente; en caso contrario, solo se verifican las líneas restantes y la tarea se liquida al finalizar.
03Ejecución en segundo plano
La tarea se ejecuta por sí sola: puede cerrar la página si lo desea. Un fallo se notifica de inmediato y se reembolsa íntegramente.
04Descargue el resultado
Recoja el archivo en la página de verificación masiva. Solo paga por las entradas que realmente devolvieron un resultado; la diferencia se reembolsa.
Campos del resultado
Columnas del archivo de resultados
La descarga es un único archivo CSV con la tabla de resultados completa.
Columnas del archivo de resultados
identifier·17253100591— El número enviado como dígitos sin formato con el código de país, sin signo más ni espacios (p. ej., 17253100591).activated·true— Si el número está registrado en WhatsApp: true o false. Cuando no es true, todas las demás columnas de esa fila se dejan vacías.avatar_url·https://pps.waavatar.xyz/v/example.jpg— URL del avatar; vacía cuando la cuenta no tiene avatar.category·individual portrait— Qué muestra el avatar: individual portrait, group photo, cartoon avatar, pet avatar, landscape, object, etc.; unknown cuando no se puede reconocer y vacío cuando no hay avatar.age·31— Edad estimada a partir del avatar; vacía cuando no se puede estimar.gender·male— Género estimado a partir del avatar: male o female; unknown cuando no se puede reconocer y vacío cuando no hay avatar.skin_color·east_asian— Tono de piel estimado a partir del avatar, p. ej. white, asian, east_asian; unknown cuando no se puede reconocer y vacío cuando no hay avatar.hair_color·black— Color de cabello estimado a partir del avatar, p. ej. black, brown; unknown cuando no se puede reconocer y vacío cuando no hay avatar.
Ideal para
Cuándo recurrir a este producto
Segmentación de listas
activatedavatar_urlcategorySepare las listas grandes de WhatsApp en grupos utilizables, incompletos y pendientes de revisión antes de una campaña o de una importación al CRM.
Ejemplo: envíe los contactos con avatar y categoría de retrato a una cola de perfiles más completos.
Completado de avatares en el CRM
avatar_urlgenderAñada los enlaces de avatar devueltos y las señales de perfil a los registros de clientes existentes sin abrir cada número uno a uno.
Ejemplo: complete las fotos de contacto que faltan antes de que un equipo de ventas o de soporte actualice su espacio de trabajo.
Preparación de audiencias
categoryageskin_colorConvierta los resultados de avatar en una primera capa de perfil coherente para la revisión de audiencias y la segmentación posterior.
Ejemplo: cree una lista de revisión para registros de retrato, de foto de grupo y sin retrato.
Higiene de la base de datos
activatedavatar_urlhair_colorEncuentre los registros sin cuenta, sin avatar utilizable o con atributos incompletos para que sus datos de contacto sean más fáciles de mantener.
Ejemplo: envíe las filas sin resultado a limpieza y mantenga las URL de avatar válidas en la lista maestra.
Respuesta directa
¿Qué es la Análisis de avatares de WhatsApp masiva?
La consulta masiva de avatares de WhatsApp devuelve, para cada número registrado, la URL del avatar y los atributos reconocidos en él: categoría, edad, género, tono de piel y color de cabello, los mismos campos que el perfil de avatar de WhatsApp en tiempo real. La tarea se ejecuta en segundo plano; elija el país al que pertenecen los números al subir el archivo.
Límites claros
Límites de este producto
- Los resultados reflejan el momento en que se ejecutó la tarea. Los avatares cambian: vuelva a ejecutarla para obtener un estado actualizado; los resultados guardados nunca se actualizan automáticamente.
- No es una verificación de accesibilidad ni de actividad, ni una verificación de identidad.
- No se envía nada a los identificadores del archivo.
- Las columnas que se devuelven dependen de la plataforma. Se indican en esta página antes de que suba el archivo.
- Los enlaces de descarga caducan. Obtenga el archivo poco después de que termine la tarea; si un enlace caduca, vuelva a consultar la tarea para obtener uno nuevo.
Cuándo encaja el modo masivo
Cuándo merece la pena el modo masivo y cuándo es más rápido el tiempo real
| Verificación en tiempo real | Verificación masiva | |
|---|---|---|
| Cuántos identificadores | 1 identificador por verificación individual; varios por solicitud múltiple (los límites exactos figuran en la documentación de la API) | Una lista grande completa en una sola tarea: el intervalo de tamaño actual figura en la página de precios |
| Obtención de resultados | De inmediato: el endpoint individual y el múltiple responden en la misma respuesta; el panel los devuelve uno a uno | Descargue un archivo de resultados cuando termine la tarea |
| País | No hay que elegirlo: las consultas en tiempo real se envían de una en una, no agrupadas por país | Un país por tarea, seleccionado al subir el archivo y enviado con él |
| Formato del resultado | JSON, campos por elemento | Archivo de resultados (un CSV con la tabla completa) |
| Uso habitual | Validación de formularios, consultas de agentes, filtrado previo al envío | Depuración de listas, filtrado previo a campañas, limpieza de datos almacenados |
Preguntas frecuentes del producto
Acerca de Análisis de avatares de WhatsApp
¿Cuándo debo usar el modo masivo en lugar de una verificación en tiempo real?
Use el modo masivo para una lista grande completa. Para unos pocos identificadores, la verificación en tiempo real responde en la misma solicitud, sin tareas que programar.
¿Qué ocurre con los identificadores no válidos del archivo?
La comprobación previa descarta las líneas mal formadas, por lo que nunca entran en el recuento facturable. De los números restantes, tampoco se cobran los que el servicio de origen no pueda resolver. Solo paga por los números que realmente devuelven un resultado.
¿Cuánto tarda una tarea?
Depende del número de entradas y del producto. Puede cerrar la página después de enviarla; la tarea se ejecuta en segundo plano y el resultado le espera en la página de verificación masiva.
¿Se me reembolsa si falla?
Sí. Una tarea fallida se reembolsa íntegramente. Si la tarea se completa pero algunas entradas no devuelven nada, esa parte se reembolsa automáticamente. La diferencia entre el importe reservado y lo realmente cobrado siempre se devuelve.
Productos relacionados
Otros productos masivos
Perfil de números de Telegram · MasivoSuba números: ID de usuario de Telegram, nombre de usuario, días de actividad y URL del avatar, además de la edad, el género y el tono de piel reconocidos en el avatar.Perfil de nombres de usuario de Telegram · MasivoSuba nombres de usuario de Telegram: ID de usuario, días de actividad y URL del avatar de cada cuenta.
Perfil de números de Viber · MasivoSuba números: ID de miembro de Viber, días de actividad y URL del avatar, además de la categoría, la edad, el género y el tono de piel reconocidos en el avatar.
Perfil de números de MAX · MasivoSuba números: ID de usuario de MAX, URL del avatar y género.
Análisis de avatares de LINE · MasivoSuba números: ID de usuario de LINE y URL del avatar, además de la categoría, la edad, el género, el tono de piel y el color de cabello reconocidos en el avatar.
Perfil de números de Zalo · MasivoSuba números: ID de usuario de Zalo y URL del avatar, además de la categoría, la edad, el género y el tono de piel reconocidos en el avatar.
Verificación de avatares de email · MasivoSuba direcciones de Gmail, Yandex o Mail.ru: si cada una admite entrega y su avatar.Cree una cuenta para enviar una tarea masiva
Las verificaciones masivas y en tiempo real consumen el mismo saldo: no hay nada adicional que activar. Regístrese y suba su primer archivo en la página de verificación masiva.