Referencia

AvatarLookup Referencia de la API

Todos los endpoints comparten una clave API y un saldo.

Elemento	Valor
URL base	https://avatarlookup.com
Cabecera de autenticación	X-API-Key: sk_your_api_key
Estructura de la respuesta	{ code, msg, data }

Los precios no se indican aquí; cada producto se factura por verificación correcta. Ver precios

Autenticación

Use una clave API creada en Configuración y envíela con cada solicitud.

Cabecera de autenticación

X-API-Key: sk_your_api_key

Mantenga su clave API en secretoLlame siempre a este endpoint desde su servidor. Cualquiera que tenga la clave puede gastar su saldo.

Verificaciones síncronas

POST/api/v1/checkPOST/api/v1/batch-checkPOST/api/v1/image/profile

Envíe un identificador, o hasta 100 en una sola solicitud, y lea el resultado en la misma respuesta. Sin sondeos ni callbacks. Un resultado indeterminado devuelve 422 con el código 42200 y no se cobra. Una solicitud múltiple conserva el orden de entrada, factura cada identificador de forma independiente y dispone de 300 segundos para finalizar; si no lo hace, falla la solicitud completa y se reembolsan todos los cargos. El análisis de perfil de imágenes usa su propio endpoint, /api/v1/image/profile, y recibe una imagen en lugar de un identificador.

Parámetros

Campo	Tipo	Descripción
`service_type`	string	Código de producto, uno de los productos indicados a continuación.
`identifier`	string	Verificación individual: un identificador. El servidor lo normaliza.
`identifiers`	string[]	Verificación múltiple: de 1 a 100 identificadores. La respuesta conserva este orden.
`file`	file	Análisis de perfil de imágenes: una imagen de retrato (carga multipart). No hay `identifier`.

Productos de este grupo

Análisis de perfil de imágenesimage_profileSuba cualquier imagen y obtenga sus atributos de retrato: edad estimada, género, tipo de imagen, color de cabello y tono de piel.Página del producto
Análisis de avatares de WhatsAppws_profileCompruebe si un número tiene avatar de WhatsApp, obtenga la URL de la imagen y lea los atributos de retrato de ese avatar.Página del producto
Análisis de avatares de emailemail_profileCompruebe si una cuenta de email tiene avatar y lea sus atributos de retrato. Cubre Gmail, Yandex y Mail.ru.Página del producto

Análisis de perfil de imágenes

image_profileimagen

Suba cualquier imagen y obtenga sus atributos de retrato: edad estimada, género, tipo de imagen, color de cabello y tono de piel.

Verificación individual

POST/api/v1/image/profile

Solicitud

curl -X POST "https://avatarlookup.com/api/v1/image/profile" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=image_profile \
  -F file=@portrait.jpg

Respuesta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "service_type": "image_profile",
    "identifier": "img:7013df96c540904a4b7ba295e9162ab2",
    "category": "individual portrait",
    "age": 39,
    "gender": "male",
    "skin_color": "white",
    "hair_color": "brown"
  }
}

Campos de la respuesta

Campo	Tipo	Descripción
`identifier`	string	Huella de la imagen enviada, derivada de su contenido. La misma imagen siempre produce el mismo valor.
`category`	string	Qué es la imagen: individual portrait, group photo, game avatar, cartoon avatar, landscape, pet avatar o object. unknown cuando no se ha podido obtener un retrato.
`age`	integer	Edad estimada como número entero, con una precisión de unos 3 años y limitada al rango 0-80. Se omite cuando no se ha podido estimar (por ejemplo, cuando no se determinó el género).
`gender`	string	male, female o unknown.
`skin_color`	string	Tono de piel descriptivo, por ejemplo white, east_asian o hispanic. Trátelo como un conjunto abierto; unknown cuando no se ha determinado.
`hair_color`	string	Color de cabello descriptivo, por ejemplo black, brown, blond o gray white. Trátelo como un conjunto abierto; unknown cuando no se ha determinado.

Análisis de avatares de WhatsApp

ws_profileteléfono

Compruebe si un número tiene avatar de WhatsApp, obtenga la URL de la imagen y lea los atributos de retrato de ese avatar.

Verificación individual

POST/api/v1/check

Solicitud

curl -X POST "https://avatarlookup.com/api/v1/check" \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "service_type": "ws_profile", "identifier": "+17253100591" }'

{
  "code": 0,
  "msg": "ok",
  "data": {
    "service_type": "ws_profile",
    "identifier": "+17253100591",
    "registered": true,
    "avatar": true,
    "avatar_url": "https://pps.whatsapp.net/v/example.jpg",
    "category": "individual portrait",
    "age": 39,
    "gender": "male",
    "skin_color": "white",
    "hair_color": "brown"
  }
}

Campos de la respuesta

Campo	Tipo	Descripción
`registered`	boolean	Si el número está registrado en WhatsApp.
`avatar`	boolean	Si hay un avatar configurado.
`avatar_url`	string	URL del avatar; cadena vacía cuando no hay ninguna foto configurada.
`category`	string	Qué es la imagen: individual portrait, group photo, game avatar, cartoon avatar, landscape, pet avatar o object. unknown cuando no se ha podido obtener un retrato.
`age`	integer	Edad estimada como número entero, con una precisión de unos 3 años y limitada al rango 0-80. Se omite cuando no se ha podido estimar (por ejemplo, cuando no se determinó el género).
`gender`	string	male, female o unknown.
`skin_color`	string	Tono de piel descriptivo, por ejemplo white, east_asian o hispanic. Trátelo como un conjunto abierto; unknown cuando no se ha determinado.
`hair_color`	string	Color de cabello descriptivo, por ejemplo black, brown, blond o gray white. Trátelo como un conjunto abierto; unknown cuando no se ha determinado.

Verificación múltiple

POST/api/v1/batch-check

Solicitud

curl -X POST "https://avatarlookup.com/api/v1/batch-check" \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "service_type": "ws_profile", "identifiers": ["+17253100591", "+14155550000", "12345"] }'

Respuesta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "service_type": "ws_profile",
    "total": 3,
    "succeeded": 2,
    "failed": 1,
    "results": [
      {
        "identifier": "+17253100591",
        "exists": true,
        "registered": true,
        "avatar": true,
        "avatar_url": "https://pps.whatsapp.net/v/example.jpg",
        "category": "individual portrait",
        "age": 39,
        "gender": "male",
        "skin_color": "white",
        "hair_color": "brown"
      },
      {
        "identifier": "+14155550000",
        "exists": true,
        "registered": false,
        "avatar": false,
        "avatar_url": "",
        "category": "unknown",
        "gender": "unknown",
        "skin_color": "unknown",
        "hair_color": "unknown"
      },
      {
        "identifier": "12345",
        "exists": false
      }
    ]
  }
}

Campos de la respuesta

Campo	Tipo	Descripción
`exists`	boolean	Si este identificador produjo un resultado. false significa que el formato no era válido, que el resultado fue indeterminado o que la verificación falló; cuando es false, no está presente ninguno de los campos siguientes.
`registered`	boolean	Si la cuenta existe en esa plataforma (para una dirección de email: si es accesible). Solo está presente cuando exists es true, con el mismo significado que en la consulta individual.
`avatar`	boolean	Si hay un avatar configurado.
`avatar_url`	string	URL del avatar; cadena vacía cuando no hay ninguna foto configurada.
`category`	string	Qué es la imagen: individual portrait, group photo, game avatar, cartoon avatar, landscape, pet avatar o object. unknown cuando no se ha podido obtener un retrato.
`age`	integer	Edad estimada como número entero, con una precisión de unos 3 años y limitada al rango 0-80. Se omite cuando no se ha podido estimar (por ejemplo, cuando no se determinó el género).
`gender`	string	male, female o unknown.
`skin_color`	string	Tono de piel descriptivo, por ejemplo white, east_asian o hispanic. Trátelo como un conjunto abierto; unknown cuando no se ha determinado.
`hair_color`	string	Color de cabello descriptivo, por ejemplo black, brown, blond o gray white. Trátelo como un conjunto abierto; unknown cuando no se ha determinado.

Análisis de avatares de email

email_profilecorreo electrónico

Compruebe si una cuenta de email tiene avatar y lea sus atributos de retrato. Cubre Gmail, Yandex y Mail.ru.

Verificación individual

POST/api/v1/check

Solicitud

curl -X POST "https://avatarlookup.com/api/v1/check" \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "service_type": "email_profile", "identifier": "alex.kim@gmail.com" }'

{
  "code": 0,
  "msg": "ok",
  "data": {
    "service_type": "email_profile",
    "identifier": "alex.kim@gmail.com",
    "registered": true,
    "avatar": true,
    "avatar_url": "https://lh3.googleusercontent.com/a/example",
    "category": "individual portrait",
    "age": 39,
    "gender": "male",
    "skin_color": "white",
    "hair_color": "brown"
  }
}

Campos de la respuesta

Campo	Tipo	Descripción
`registered`	boolean	Si la dirección de email es accesible (puede recibir correo).
`avatar`	boolean	Si hay un avatar configurado.
`avatar_url`	string	URL del avatar; cadena vacía cuando no hay ningún avatar configurado.
`category`	string	Qué es la imagen: individual portrait, group photo, game avatar, cartoon avatar, landscape, pet avatar o object. unknown cuando no se ha podido obtener un retrato.
`age`	integer	Edad estimada como número entero, con una precisión de unos 3 años y limitada al rango 0-80. Se omite cuando no se ha podido estimar (por ejemplo, cuando no se determinó el género).
`gender`	string	male, female o unknown.
`skin_color`	string	Tono de piel descriptivo, por ejemplo white, east_asian o hispanic. Trátelo como un conjunto abierto; unknown cuando no se ha determinado.
`hair_color`	string	Color de cabello descriptivo, por ejemplo black, brown, blond o gray white. Trátelo como un conjunto abierto; unknown cuando no se ha determinado.

Verificación múltiple

POST/api/v1/batch-check

Solicitud

curl -X POST "https://avatarlookup.com/api/v1/batch-check" \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "service_type": "email_profile", "identifiers": ["alex.kim@gmail.com", "no.such.user@gmail.com", "not-an-email"] }'

Respuesta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "service_type": "email_profile",
    "total": 3,
    "succeeded": 2,
    "failed": 1,
    "results": [
      {
        "identifier": "alex.kim@gmail.com",
        "exists": true,
        "registered": true,
        "avatar": true,
        "avatar_url": "https://lh3.googleusercontent.com/a/example",
        "category": "individual portrait",
        "age": 39,
        "gender": "male",
        "skin_color": "white",
        "hair_color": "brown"
      },
      {
        "identifier": "no.such.user@gmail.com",
        "exists": true,
        "registered": false,
        "avatar": false,
        "avatar_url": "",
        "category": "unknown",
        "gender": "unknown",
        "skin_color": "unknown",
        "hair_color": "unknown"
      },
      {
        "identifier": "not-an-email",
        "exists": false
      }
    ]
  }
}

Campos de la respuesta

Campo	Tipo	Descripción
`exists`	boolean	Si este identificador produjo un resultado. false significa que el formato no era válido, que el resultado fue indeterminado o que la verificación falló; cuando es false, no está presente ninguno de los campos siguientes.
`registered`	boolean	Si la cuenta existe en esa plataforma (para una dirección de email: si es accesible). Solo está presente cuando exists es true, con el mismo significado que en la consulta individual.
`avatar`	boolean	Si hay un avatar configurado.
`avatar_url`	string	URL del avatar; cadena vacía cuando no hay ningún avatar configurado.
`category`	string	Qué es la imagen: individual portrait, group photo, game avatar, cartoon avatar, landscape, pet avatar o object. unknown cuando no se ha podido obtener un retrato.
`age`	integer	Edad estimada como número entero, con una precisión de unos 3 años y limitada al rango 0-80. Se omite cuando no se ha podido estimar (por ejemplo, cuando no se determinó el género).
`gender`	string	male, female o unknown.
`skin_color`	string	Tono de piel descriptivo, por ejemplo white, east_asian o hispanic. Trátelo como un conjunto abierto; unknown cuando no se ha determinado.
`hair_color`	string	Color de cabello descriptivo, por ejemplo black, brown, blond o gray white. Trátelo como un conjunto abierto; unknown cuando no se ha determinado.

Verificaciones asíncronas

POST/api/v1/bulk-tasksGET/api/v1/bulk-tasks/{id}

Suba un archivo y obtenga al instante un ID de tarea; después, consulte ese ID hasta que se complete correctamente. La respuesta correcta incluye result_url, el enlace de descarga del resultado. Solo existen dos acciones: enviar y consultar. No sondee más de una vez cada 30 segundos.

Parámetros

Campo	Tipo	Descripción
`service_type`	string	Código de producto masivo, uno de los productos indicados a continuación.
`country`	string	Código ISO 3166-1, como `US`. Obligatorio para las tareas de números: cada número debe incluir su código de país y pertenecer a este país (los que no lo cumplan se excluyen y no se cobran); también selecciona el enrutamiento. En multipart debe ir antes de `file`.
`file`	file	Un archivo `.txt` o `.csv` con un identificador por línea, de hasta `max_file_bytes` (20MB por defecto).
`Idempotency-Key`	header	Opcional, hasta 128 caracteres. Repetir la misma clave devuelve la tarea original en lugar de crear una segunda.

Productos de este grupo

Análisis de avatares de WhatsApp · Masivows_profile_batchSuba 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).Página del producto
Perfil de números de Telegram · Masivotg_profile_batchSuba 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.Página del producto
Perfil de nombres de usuario de Telegram · Masivotg_username_profile_batchSuba nombres de usuario de Telegram: ID de usuario, días de actividad y URL del avatar de cada cuenta.Página del producto
Perfil de números de Viber · Masivoviber_profile_batchSuba 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.Página del producto
Perfil de números de MAX · Masivomax_profile_batchSuba números: ID de usuario de MAX, URL del avatar y género.Página del producto
Análisis de avatares de LINE · Masivoline_profile_batchSuba 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.Página del producto
Perfil de números de Zalo · Masivozalo_profile_batchSuba 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.Página del producto
Verificación de avatares de email · Masivoemail_avatar_batchSuba direcciones de Gmail, Yandex o Mail.ru: si cada una admite entrega y su avatar.Página del producto

Análisis de avatares de WhatsApp · Masivo

ws_profile_batchteléfono1000–500.000 por tarea

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).

Enviar una tarea

POST/api/v1/bulk-tasks

Solicitud

curl -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

Respuesta

{
  "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"
  }
}

Consultar la tarea

GET/api/v1/bulk-tasks/{id}

Solicitud

curl "https://avatarlookup.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Respuesta

{
  "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"
  }
}

Columnas del resultado

Campo	ejemplo:	Descripción
`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.

Perfil de números de Telegram · Masivo

tg_profile_batchteléfono1000–500.000 por tarea

Suba 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.

Enviar una tarea

POST/api/v1/bulk-tasks

Solicitud

curl -X POST "https://avatarlookup.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=tg_profile_batch \
  -F country=US \
  -F file=@numbers.txt

Respuesta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "tg_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"
  }
}

Consultar la tarea

GET/api/v1/bulk-tasks/{id}

Solicitud

curl "https://avatarlookup.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Respuesta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "tg_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"
  }
}

Columnas del resultado

Campo	ejemplo:	Descripción
`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 Telegram: true o false. Cuando no es true, todas las demás columnas de esa fila quedan vacías.
`uid`	1234567890	ID de usuario de Telegram.
`username`	alex_kim	Nombre de usuario; vacío cuando la cuenta no tiene.
`activedays`	9	Días desde la última vez que se vio la cuenta, como número entero; cuanto menor, más reciente. Cuando la cuenta oculta su hora exacta de última conexión, Telegram solo revela un intervalo y el valor es una aproximación: 0 (recientemente), 7 (en la última semana), 30 (en el último mes) o 1000 (hace mucho tiempo).
`avatar_url`	https://telegram.waavatar.xyz/v/example.jpg	URL del avatar; vacía cuando la cuenta no tiene 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`	white	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.

Perfil de nombres de usuario de Telegram · Masivo

tg_username_profile_batchnombre de usuario1000–500.000 por tarea

Suba nombres de usuario de Telegram: ID de usuario, días de actividad y URL del avatar de cada cuenta.

Enviar una tarea

POST/api/v1/bulk-tasks

Solicitud

curl -X POST "https://avatarlookup.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=tg_username_profile_batch \
  -F file=@usernames.txt

Respuesta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "tg_username_profile_batch",
    "status": "processing",
    "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"
  }
}

Consultar la tarea

GET/api/v1/bulk-tasks/{id}

Solicitud

curl "https://avatarlookup.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Respuesta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "tg_username_profile_batch",
    "status": "success",
    "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"
  }
}

Columnas del resultado

Campo	ejemplo:	Descripción
`identifier`	alex_kim	El nombre de usuario enviado, sin @ ni t.me/ (p. ej. alex_kim).
`activated`	true	Si el nombre de usuario pertenece a una cuenta de Telegram existente: true o false. Cuando no es true, todas las demás columnas de esa fila quedan vacías.
`uid`	1234567890	ID de usuario de Telegram; puede estar vacío incluso en una cuenta existente.
`activedays`	9	Días desde la última vez que se vio la cuenta, como número entero; cuanto menor, más reciente. Cuando la cuenta oculta su hora exacta de última conexión, Telegram solo revela un intervalo y el valor es una aproximación: 0 (recientemente), 7 (en la última semana), 30 (en el último mes) o 1000 (hace mucho tiempo). Puede estar vacío cuando la cuenta no revela ninguna información de última conexión.
`avatar_url`	https://cdn5.telesco.pe/file/example.jpg	URL del avatar; vacía cuando la cuenta no tiene avatar.

Perfil de números de Viber · Masivo

viber_profile_batchteléfono1000–500.000 por tarea

Suba 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.

Enviar una tarea

POST/api/v1/bulk-tasks

Solicitud

curl -X POST "https://avatarlookup.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=viber_profile_batch \
  -F country=US \
  -F file=@numbers.txt

Respuesta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "viber_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"
  }
}

Consultar la tarea

GET/api/v1/bulk-tasks/{id}

Solicitud

curl "https://avatarlookup.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Respuesta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "viber_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"
  }
}

Columnas del resultado

Campo	ejemplo:	Descripción
`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 Viber: true o false. Cuando no es true, todas las demás columnas de esa fila quedan vacías.
`uid`	A5qCVDb3jPU=	ID de miembro de Viber.
`activedays`	3	Días desde la última conexión de la cuenta; cuanto menor, más reciente.
`avatar_url`	https://viber.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`	white	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.

Perfil de números de MAX · Masivo

max_profile_batchteléfono1000–500.000 por tarea

Suba números: ID de usuario de MAX, URL del avatar y género.

Enviar una tarea

POST/api/v1/bulk-tasks

Solicitud

curl -X POST "https://avatarlookup.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=max_profile_batch \
  -F country=US \
  -F file=@numbers.txt

Respuesta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "max_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"
  }
}

Consultar la tarea

GET/api/v1/bulk-tasks/{id}

Solicitud

curl "https://avatarlookup.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Respuesta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "max_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"
  }
}

Columnas del resultado

Campo	ejemplo:	Descripción
`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 MAX: true o false. Cuando no es true, todas las demás columnas de esa fila quedan vacías.
`uid`	343064807	ID de usuario de MAX.
`avatar_url`	https://i.oneme.ru/i?r=example	URL del avatar; vacía cuando la cuenta no tiene avatar.
`gender`	male	Género de la cuenta: male o female; vacío cuando se desconoce.

Análisis de avatares de LINE · Masivo

line_profile_batchteléfono2000–500.000 por tarea

Suba 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.

Enviar una tarea

POST/api/v1/bulk-tasks

Solicitud

curl -X POST "https://avatarlookup.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=line_profile_batch \
  -F country=US \
  -F file=@numbers.txt

Respuesta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "line_profile_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 2027,
    "total": 2027,
    "invalid_cnt": 0,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 0,
    "preparing": true,
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Consultar la tarea

GET/api/v1/bulk-tasks/{id}

Solicitud

curl "https://avatarlookup.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Respuesta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "line_profile_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 2027,
    "total": 2000,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 24,
    "preparing": false,
    "success_cnt": 1980,
    "failure_cnt": 20,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Columnas del resultado

Campo	ejemplo:	Descripción
`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 LINE: true o false. Cuando no es true, todas las demás columnas de esa fila quedan vacías.
`uid`	u5158553776c28d9164035c4fd0a07cd4	ID de usuario de LINE.
`avatar_url`	https://profile.line-scdn.net/example	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.

Perfil de números de Zalo · Masivo

zalo_profile_batchteléfono1000–500.000 por tarea

Suba 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.

Enviar una tarea

POST/api/v1/bulk-tasks

Solicitud

curl -X POST "https://avatarlookup.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=zalo_profile_batch \
  -F country=US \
  -F file=@numbers.txt

Respuesta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "zalo_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"
  }
}

Consultar la tarea

GET/api/v1/bulk-tasks/{id}

Solicitud

curl "https://avatarlookup.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Respuesta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "zalo_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"
  }
}

Columnas del resultado

Campo	ejemplo:	Descripción
`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 Zalo: true o false. Cuando no es true, todas las demás columnas de esa fila quedan vacías.
`uid`	452114152	ID de usuario de Zalo.
`avatar_url`	https://s160-ava-talk.zadn.vn/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`	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.

Verificación de avatares de email · Masivo

email_avatar_batchcorreo electrónico1000–500.000 por tarea

Suba direcciones de Gmail, Yandex o Mail.ru: si cada una admite entrega y su avatar.

Enviar una tarea

POST/api/v1/bulk-tasks

Solicitud

curl -X POST "https://avatarlookup.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=email_avatar_batch \
  -F file=@emails.txt

Respuesta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "email_avatar_batch",
    "status": "processing",
    "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"
  }
}

Consultar la tarea

GET/api/v1/bulk-tasks/{id}

Solicitud

curl "https://avatarlookup.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Respuesta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "email_avatar_batch",
    "status": "success",
    "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"
  }
}

Columnas del resultado

Campo	ejemplo:	Descripción
`identifier`	alex.kim@gmail.com	La dirección enviada, en minúsculas.
`activated`	true	Si la dirección admite entrega en ese proveedor, es decir, si puede recibir correo: true o false. Cuando no es true, todas las demás columnas de esa fila quedan vacías.
`avatar`	true	Si hay un avatar configurado: true o false. avatar_url puede estar vacío aun así cuando la imagen no está disponible.
`avatar_url`	https://lh3.googleusercontent.com/a/example	La URL del avatar; vacía cuando no hay ninguna URL disponible.

Saldo

GET/api/v1/balance

Consulte el saldo actual de la cuenta en micros de USD. Solo lectura: no crea ningún registro de verificación ni cobra nada.

Saldo

GET/api/v1/balance

Solicitud

curl "https://avatarlookup.com/api/v1/balance" \
  -H "X-API-Key: sk_your_api_key"

Respuesta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "balance_micros": 12500000
  }
}

Concurrencia, tiempos de espera y comportamiento de reintento

Las consultas de avatares son síncronas. Use el código devuelto para decidir si acepta el resultado o lo reintenta más tarde.

Campo	Descripción
`5 solicitudes simultáneas por usuario`	Las verificaciones individuales y múltiples comparten este límite, y una solicitud múltiple cuenta como una sola solicitud, independientemente de cuántos identificadores contenga. Además, solo se ejecuta una verificación múltiple por cuenta a la vez; una segunda se rechaza hasta que termine la primera. Alcanzar cualquiera de los dos límites devuelve de inmediato el código 42901 sin cargo, junto con una cabecera Retry-After; vuelva a enviar cuando termine una solicitud en curso.
`60 s individual, 300 s múltiple`	Superar el límite de tiempo devuelve el código 50400 sin cargo. Una verificación múltiple que agota el tiempo falla en su totalidad: no hay resultados parciales y se reembolsa el importe completo.
`Una verificación múltiple admite hasta 100 identificadores`	Los resultados conservan el orden y la longitud del envío. Solo se ejecuta una verificación múltiple por cuenta a la vez; envíe el siguiente lote cuando el anterior haya devuelto sus resultados.

Códigos de error

Código	Descripción
`40000`	Tipo de servicio no compatible o campos de la solicitud en conflicto
`40001`	Cuerpo JSON no válido
`40002`	Identificador no válido
`40100`	Clave API ausente o no válida
`40200`	Saldo insuficiente
`42200`	No se ha podido determinar el identificador en este momento. No se devuelven datos y la solicitud no se cobra
`42900`	Se ha agotado una cuota de uso o hay demasiados pedidos sin finalizar
`42901`	Las cinco plazas de solicitudes en curso están ocupadas, o ya se está ejecutando una verificación múltiple en esta cuenta; envíe cuando termine una solicitud en curso. La solicitud rechazada no se cobra e incluye una cabecera Retry-After
`50303`	El servicio está al límite de su capacidad en este momento; no se cobra. Espere los segundos indicados en Retry-After y vuelva a enviar la misma solicitud
`50400`	La verificación no finalizó dentro de su tiempo de espera y no se cobra; reinténtela. Si se agota el tiempo de un lote, falla el lote completo y se reembolsa el importe total
`50300`	Mantenimiento del servicio de validación