Справочник

AvatarLookup Справочник API

Все эндпоинты используют один ключ API и один баланс.

Параметр	Значение
Базовый URL	https://avatarlookup.com
Заголовок аутентификации	X-API-Key: sk_your_api_key
Обёртка ответа	{ code, msg, data }

Цены здесь не указаны; каждый продукт оплачивается за успешную проверку. Посмотреть цены

Аутентификация

Используйте ключ API, созданный в настройках, и передавайте его с каждым запросом.

Заголовок аутентификации

X-API-Key: sk_your_api_key

Храните ключ API в секретеВсегда вызывайте этот эндпоинт со своего сервера. Любой, у кого есть ключ, может расходовать ваш баланс.

Синхронные проверки

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

Отправьте один идентификатор или до 100 в одном запросе и получите результат в том же ответе. Без опроса и без обратных вызовов. Неопределённый результат возвращает 422 с кодом 42200 и не оплачивается. Множественный запрос сохраняет порядок входных данных, тарифицирует каждый идентификатор отдельно и должен завершиться за 300 секунд — иначе весь запрос завершается ошибкой, а все списания возвращаются. Для анализа изображений используется отдельный эндпоинт, /api/v1/image/profile, который принимает изображение вместо идентификатора.

Параметры

Поле	Тип	Описание
`service_type`	string	Код продукта — один из продуктов, перечисленных ниже.
`identifier`	string	Одиночная проверка: один идентификатор. Сервер нормализует его.
`identifiers`	string[]	Множественная проверка: от 1 до 100 идентификаторов. Ответ сохраняет этот порядок.
`file`	file	Анализ изображения: одно портретное изображение (загрузка multipart). Поле `identifier` отсутствует.

Продукты этой группы

Анализ профиля по изображениюimage_profileЗагрузите любое изображение и получите атрибуты портрета: оценку возраста, пол, тип изображения, цвет волос и тон кожи.Страница продукта
Анализ аватаров WhatsAppws_profileПроверьте, есть ли у номера аватар в WhatsApp, получите URL изображения и атрибуты портрета на этом аватаре.Страница продукта
Анализ аватаров emailemail_profileПроверьте, есть ли у почтового аккаунта аватар, и получите атрибуты портрета. Поддерживаются Gmail, Yandex и Mail.ru.Страница продукта

Анализ профиля по изображению

image_profileизображение

Загрузите любое изображение и получите атрибуты портрета: оценку возраста, пол, тип изображения, цвет волос и тон кожи.

Одиночная проверка

POST/api/v1/image/profile

Запрос

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

Ответ

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

Поля ответа

Поле	Тип	Описание
`identifier`	string	Отпечаток отправленного изображения, вычисленный по его содержимому. Одно и то же изображение всегда даёт одно и то же значение.
`category`	string	Что изображено: individual portrait, group photo, game avatar, cartoon avatar, landscape, pet avatar или object. unknown, если получить портрет не удалось.
`age`	integer	Оценка возраста целым числом с точностью примерно до 3 лет, в диапазоне 0–80. Отсутствует, если оценить не удалось (например, когда не определён пол).
`gender`	string	male, female или unknown.
`skin_color`	string	Описательный тон кожи, например white, east_asian или hispanic. Считайте набор значений открытым; unknown, если не определено.
`hair_color`	string	Описательный цвет волос, например black, brown, blond или gray white. Считайте набор значений открытым; unknown, если не определено.

Анализ аватаров WhatsApp

ws_profileтелефон

Проверьте, есть ли у номера аватар в WhatsApp, получите URL изображения и атрибуты портрета на этом аватаре.

Одиночная проверка

POST/api/v1/check

Запрос

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

Поля ответа

Поле	Тип	Описание
`registered`	boolean	Зарегистрирован ли номер в WhatsApp.
`avatar`	boolean	Установлен ли аватар.
`avatar_url`	string	URL аватара; пустая строка, если фото не установлено.
`category`	string	Что изображено: individual portrait, group photo, game avatar, cartoon avatar, landscape, pet avatar или object. unknown, если получить портрет не удалось.
`age`	integer	Оценка возраста целым числом с точностью примерно до 3 лет, в диапазоне 0–80. Отсутствует, если оценить не удалось (например, когда не определён пол).
`gender`	string	male, female или unknown.
`skin_color`	string	Описательный тон кожи, например white, east_asian или hispanic. Считайте набор значений открытым; unknown, если не определено.
`hair_color`	string	Описательный цвет волос, например black, brown, blond или gray white. Считайте набор значений открытым; unknown, если не определено.

Множественная проверка

POST/api/v1/batch-check

Запрос

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

Ответ

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

Поля ответа

Поле	Тип	Описание
`exists`	boolean	Дал ли этот идентификатор результат. false означает, что формат недопустим, результат не определён или проверка не удалась; при false ни одно из полей ниже не возвращается.
`registered`	boolean	Существует ли аккаунт на этой платформе (для адреса email — доступен ли он). Присутствует только при exists = true и имеет то же значение, что и при одиночной проверке.
`avatar`	boolean	Установлен ли аватар.
`avatar_url`	string	URL аватара; пустая строка, если фото не установлено.
`category`	string	Что изображено: individual portrait, group photo, game avatar, cartoon avatar, landscape, pet avatar или object. unknown, если получить портрет не удалось.
`age`	integer	Оценка возраста целым числом с точностью примерно до 3 лет, в диапазоне 0–80. Отсутствует, если оценить не удалось (например, когда не определён пол).
`gender`	string	male, female или unknown.
`skin_color`	string	Описательный тон кожи, например white, east_asian или hispanic. Считайте набор значений открытым; unknown, если не определено.
`hair_color`	string	Описательный цвет волос, например black, brown, blond или gray white. Считайте набор значений открытым; unknown, если не определено.

Анализ аватаров email

email_profileemail

Проверьте, есть ли у почтового аккаунта аватар, и получите атрибуты портрета. Поддерживаются Gmail, Yandex и Mail.ru.

Одиночная проверка

POST/api/v1/check

Запрос

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

Поля ответа

Поле	Тип	Описание
`registered`	boolean	Доступен ли адрес email (может ли он получать почту).
`avatar`	boolean	Установлен ли аватар.
`avatar_url`	string	URL аватара; пустая строка, если аватар не установлен.
`category`	string	Что изображено: individual portrait, group photo, game avatar, cartoon avatar, landscape, pet avatar или object. unknown, если получить портрет не удалось.
`age`	integer	Оценка возраста целым числом с точностью примерно до 3 лет, в диапазоне 0–80. Отсутствует, если оценить не удалось (например, когда не определён пол).
`gender`	string	male, female или unknown.
`skin_color`	string	Описательный тон кожи, например white, east_asian или hispanic. Считайте набор значений открытым; unknown, если не определено.
`hair_color`	string	Описательный цвет волос, например black, brown, blond или gray white. Считайте набор значений открытым; unknown, если не определено.

Множественная проверка

POST/api/v1/batch-check

Запрос

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

Ответ

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

Поля ответа

Поле	Тип	Описание
`exists`	boolean	Дал ли этот идентификатор результат. false означает, что формат недопустим, результат не определён или проверка не удалась; при false ни одно из полей ниже не возвращается.
`registered`	boolean	Существует ли аккаунт на этой платформе (для адреса email — доступен ли он). Присутствует только при exists = true и имеет то же значение, что и при одиночной проверке.
`avatar`	boolean	Установлен ли аватар.
`avatar_url`	string	URL аватара; пустая строка, если аватар не установлен.
`category`	string	Что изображено: individual portrait, group photo, game avatar, cartoon avatar, landscape, pet avatar или object. unknown, если получить портрет не удалось.
`age`	integer	Оценка возраста целым числом с точностью примерно до 3 лет, в диапазоне 0–80. Отсутствует, если оценить не удалось (например, когда не определён пол).
`gender`	string	male, female или unknown.
`skin_color`	string	Описательный тон кожи, например white, east_asian или hispanic. Считайте набор значений открытым; unknown, если не определено.
`hair_color`	string	Описательный цвет волос, например black, brown, blond или gray white. Считайте набор значений открытым; unknown, если не определено.

Асинхронные проверки

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

Загрузите файл и сразу получите id задачи, затем проверяйте этот id, пока задача не завершится успешно. Успешный ответ содержит result_url — ссылку для скачивания результата. Действий всего два: отправка и проверка. Опрашивайте не чаще одного раза в 30 секунд.

Параметры

Поле	Тип	Описание
`service_type`	string	Код массового продукта — один из продуктов, перечисленных ниже.
`country`	string	Код ISO 3166-1, например `US`. Обязателен для задач с номерами: каждый номер должен содержать код страны и относиться к этой стране (остальные номера исключаются и не оплачиваются); также определяет маршрутизацию. В multipart должен идти перед `file`.
`file`	file	Файл `.txt` или `.csv` с одним идентификатором на строку, размером до `max_file_bytes` (по умолчанию 20MB).
`Idempotency-Key`	header	Необязательный, до 128 символов. Повторная отправка с тем же ключом возвращает исходную задачу вместо создания новой.

Продукты этой группы

Анализ аватаров WhatsApp · массовая проверкаws_profile_batchЗагрузите целый файл номеров: URL аватара WhatsApp и что изображено на аватаре — категория, возраст, пол, тон кожи и цвет волос.Страница продукта
Профиль номера Telegram · массовая проверкаtg_profile_batchЗагрузите номера: ID пользователя Telegram, имя пользователя, дни активности и URL аватара, а также возраст, пол и тон кожи, распознанные по аватару.Страница продукта
Профиль имени пользователя Telegram · массовая проверкаtg_username_profile_batchЗагрузите имена пользователей Telegram: ID пользователя, дни активности и URL аватара для каждого аккаунта.Страница продукта
Профиль номера Viber · массовая проверкаviber_profile_batchЗагрузите номера: ID участника Viber, дни активности и URL аватара, а также категория, возраст, пол и тон кожи, распознанные по аватару.Страница продукта
Профиль номера MAX · массовая проверкаmax_profile_batchЗагрузите номера: ID пользователя MAX, URL аватара и пол.Страница продукта
Анализ аватаров LINE · массовая проверкаline_profile_batchЗагрузите номера: ID пользователя LINE и URL аватара, а также категория, возраст, пол, тон кожи и цвет волос, распознанные по аватару.Страница продукта
Профиль номера Zalo · массовая проверкаzalo_profile_batchЗагрузите номера: ID пользователя Zalo и URL аватара, а также категория, возраст, пол и тон кожи, распознанные по аватару.Страница продукта
Проверка аватаров email · массовая проверкаemail_avatar_batchЗагрузите адреса Gmail, Yandex или Mail.ru: доставляем ли каждый из них и его аватар.Страница продукта

Анализ аватаров WhatsApp · массовая проверка

ws_profile_batchтелефон1 000–500 000 на задачу

Загрузите целый файл номеров: URL аватара WhatsApp и что изображено на аватаре — категория, возраст, пол, тон кожи и цвет волос.

Отправка задачи

POST/api/v1/bulk-tasks

Запрос

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

Ответ

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

Проверка задачи

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

Запрос

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

Ответ

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

Столбцы результата

Поле	пример:	Описание
`identifier`	17253100591	Отправленный номер в виде цифр с кодом страны, без знака плюс и пробелов (например, 17253100591).
`activated`	true	Зарегистрирован ли номер в WhatsApp: true или false. Если значение не true, все остальные столбцы в этой строке остаются пустыми.
`avatar_url`	https://pps.waavatar.xyz/v/example.jpg	URL аватара; пусто, если у аккаунта нет аватара.
`category`	individual portrait	Что изображено на аватаре: individual portrait, group photo, cartoon avatar, pet avatar, landscape, object и т. д.; unknown, если распознать не удалось; пусто, если аватара нет.
`age`	31	Возраст, оценённый по аватару; пусто, если оценить не удалось.
`gender`	male	Пол, оценённый по аватару: male или female; unknown, если распознать не удалось; пусто, если аватара нет.
`skin_color`	east_asian	Тон кожи, оценённый по аватару, например white, asian, east_asian; unknown, если распознать не удалось; пусто, если аватара нет.
`hair_color`	black	Цвет волос, оценённый по аватару, например black, brown; unknown, если распознать не удалось; пусто, если аватара нет.

Профиль номера Telegram · массовая проверка

tg_profile_batchтелефон1 000–500 000 на задачу

Загрузите номера: ID пользователя Telegram, имя пользователя, дни активности и URL аватара, а также возраст, пол и тон кожи, распознанные по аватару.

Отправка задачи

POST/api/v1/bulk-tasks

Запрос

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

Ответ

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

Проверка задачи

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

Запрос

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

Ответ

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

Столбцы результата

Поле	пример:	Описание
`identifier`	17253100591	Отправленный номер в виде цифр с кодом страны, без знака плюс и пробелов (например, 17253100591).
`activated`	true	Зарегистрирован ли номер в Telegram: true или false. Если значение не true, все остальные столбцы в этой строке остаются пустыми.
`uid`	1234567890	ID пользователя Telegram.
`username`	alex_kim	Имя пользователя; пусто, если у аккаунта его нет.
`activedays`	9	Сколько дней назад аккаунт был в сети в последний раз, целым числом — чем меньше, тем недавнее. Если аккаунт скрывает точное время последнего посещения, Telegram раскрывает только диапазон, и значение приблизительное: 0 (недавно), 7 (в течение недели), 30 (в течение месяца) или 1000 (давно).
`avatar_url`	https://telegram.waavatar.xyz/v/example.jpg	URL аватара; пусто, если у аккаунта нет аватара.
`age`	31	Возраст, оценённый по аватару; пусто, если оценить не удалось.
`gender`	male	Пол, оценённый по аватару: male или female; unknown, если распознать не удалось; пусто, если аватара нет.
`skin_color`	white	Тон кожи, оценённый по аватару, например white, asian, east_asian; unknown, если распознать не удалось; пусто, если аватара нет.

Профиль имени пользователя Telegram · массовая проверка

tg_username_profile_batchимя пользователя1 000–500 000 на задачу

Загрузите имена пользователей Telegram: ID пользователя, дни активности и URL аватара для каждого аккаунта.

Отправка задачи

POST/api/v1/bulk-tasks

Запрос

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

Ответ

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

Проверка задачи

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

Запрос

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

Ответ

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

Столбцы результата

Поле	пример:	Описание
`identifier`	alex_kim	Отправленное имя пользователя без @ и t.me/ (например, alex_kim).
`activated`	true	Принадлежит ли имя пользователя существующему аккаунту Telegram: true или false. Если значение не true, все остальные столбцы в этой строке остаются пустыми.
`uid`	1234567890	ID пользователя Telegram; может быть пустым даже для существующего аккаунта.
`activedays`	9	Сколько дней назад аккаунт был в сети в последний раз, целым числом — чем меньше, тем недавнее. Если аккаунт скрывает точное время последнего посещения, Telegram раскрывает только диапазон, и значение приблизительное: 0 (недавно), 7 (в течение недели), 30 (в течение месяца) или 1000 (давно). Может быть пустым, если аккаунт не раскрывает сведений о последнем посещении.
`avatar_url`	https://cdn5.telesco.pe/file/example.jpg	URL аватара; пусто, если у аккаунта нет аватара.

Профиль номера Viber · массовая проверка

viber_profile_batchтелефон1 000–500 000 на задачу

Загрузите номера: ID участника Viber, дни активности и URL аватара, а также категория, возраст, пол и тон кожи, распознанные по аватару.

Отправка задачи

POST/api/v1/bulk-tasks

Запрос

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

Ответ

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

Проверка задачи

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

Запрос

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

Ответ

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

Столбцы результата

Поле	пример:	Описание
`identifier`	17253100591	Отправленный номер в виде цифр с кодом страны, без знака плюс и пробелов (например, 17253100591).
`activated`	true	Зарегистрирован ли номер в Viber: true или false. Если значение не true, все остальные столбцы в этой строке остаются пустыми.
`uid`	A5qCVDb3jPU=	ID участника Viber.
`activedays`	3	Сколько дней назад аккаунт был в сети в последний раз — чем меньше, тем недавнее.
`avatar_url`	https://viber.waavatar.xyz/v/example.jpg	URL аватара; пусто, если у аккаунта нет аватара.
`category`	individual portrait	Что изображено на аватаре: individual portrait, group photo, cartoon avatar, pet avatar, landscape, object и т. д.; unknown, если распознать не удалось; пусто, если аватара нет.
`age`	31	Возраст, оценённый по аватару; пусто, если оценить не удалось.
`gender`	male	Пол, оценённый по аватару: male или female; unknown, если распознать не удалось; пусто, если аватара нет.
`skin_color`	white	Тон кожи, оценённый по аватару, например white, asian, east_asian; unknown, если распознать не удалось; пусто, если аватара нет.

Профиль номера MAX · массовая проверка

max_profile_batchтелефон1 000–500 000 на задачу

Загрузите номера: ID пользователя MAX, URL аватара и пол.

Отправка задачи

POST/api/v1/bulk-tasks

Запрос

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

Ответ

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

Проверка задачи

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

Запрос

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

Ответ

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

Столбцы результата

Поле	пример:	Описание
`identifier`	17253100591	Отправленный номер в виде цифр с кодом страны, без знака плюс и пробелов (например, 17253100591).
`activated`	true	Зарегистрирован ли номер в MAX: true или false. Если значение не true, все остальные столбцы в этой строке остаются пустыми.
`uid`	343064807	ID пользователя MAX.
`avatar_url`	https://i.oneme.ru/i?r=example	URL аватара; пусто, если у аккаунта нет аватара.
`gender`	male	Пол владельца аккаунта: male или female; пусто, если неизвестен.

Анализ аватаров LINE · массовая проверка

line_profile_batchтелефон2 000–500 000 на задачу

Загрузите номера: ID пользователя LINE и URL аватара, а также категория, возраст, пол, тон кожи и цвет волос, распознанные по аватару.

Отправка задачи

POST/api/v1/bulk-tasks

Запрос

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

Ответ

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

Проверка задачи

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

Запрос

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

Ответ

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

Столбцы результата

Поле	пример:	Описание
`identifier`	17253100591	Отправленный номер в виде цифр с кодом страны, без знака плюс и пробелов (например, 17253100591).
`activated`	true	Зарегистрирован ли номер в LINE: true или false. Если значение не true, все остальные столбцы в этой строке остаются пустыми.
`uid`	u5158553776c28d9164035c4fd0a07cd4	ID пользователя LINE.
`avatar_url`	https://profile.line-scdn.net/example	URL аватара; пусто, если у аккаунта нет аватара.
`category`	individual portrait	Что изображено на аватаре: individual portrait, group photo, cartoon avatar, pet avatar, landscape, object и т. д.; unknown, если распознать не удалось; пусто, если аватара нет.
`age`	31	Возраст, оценённый по аватару; пусто, если оценить не удалось.
`gender`	male	Пол, оценённый по аватару: male или female; unknown, если распознать не удалось; пусто, если аватара нет.
`skin_color`	east_asian	Тон кожи, оценённый по аватару, например white, asian, east_asian; unknown, если распознать не удалось; пусто, если аватара нет.
`hair_color`	black	Цвет волос, оценённый по аватару, например black, brown; unknown, если распознать не удалось; пусто, если аватара нет.

Профиль номера Zalo · массовая проверка

zalo_profile_batchтелефон1 000–500 000 на задачу

Загрузите номера: ID пользователя Zalo и URL аватара, а также категория, возраст, пол и тон кожи, распознанные по аватару.

Отправка задачи

POST/api/v1/bulk-tasks

Запрос

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

Ответ

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

Проверка задачи

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

Запрос

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

Ответ

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

Столбцы результата

Поле	пример:	Описание
`identifier`	17253100591	Отправленный номер в виде цифр с кодом страны, без знака плюс и пробелов (например, 17253100591).
`activated`	true	Зарегистрирован ли номер в Zalo: true или false. Если значение не true, все остальные столбцы в этой строке остаются пустыми.
`uid`	452114152	ID пользователя Zalo.
`avatar_url`	https://s160-ava-talk.zadn.vn/example.jpg	URL аватара; пусто, если у аккаунта нет аватара.
`category`	individual portrait	Что изображено на аватаре: individual portrait, group photo, cartoon avatar, pet avatar, landscape, object и т. д.; unknown, если распознать не удалось; пусто, если аватара нет.
`age`	31	Возраст, оценённый по аватару; пусто, если оценить не удалось.
`gender`	male	Пол, оценённый по аватару: male или female; unknown, если распознать не удалось; пусто, если аватара нет.
`skin_color`	asian	Тон кожи, оценённый по аватару, например white, asian, east_asian; unknown, если распознать не удалось; пусто, если аватара нет.

Проверка аватаров email · массовая проверка

email_avatar_batchemail1 000–500 000 на задачу

Загрузите адреса Gmail, Yandex или Mail.ru: доставляем ли каждый из них и его аватар.

Отправка задачи

POST/api/v1/bulk-tasks

Запрос

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

Ответ

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

Проверка задачи

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

Запрос

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

Ответ

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

Столбцы результата

Поле	пример:	Описание
`identifier`	alex.kim@gmail.com	Отправленный адрес в нижнем регистре.
`activated`	true	Доставляем ли адрес у этого почтового сервиса — может ли он получать почту: true или false. Если значение не true, все остальные столбцы в этой строке остаются пустыми.
`avatar`	true	Установлен ли аватар: true или false. avatar_url может быть пустым, даже если аватар есть, когда изображение недоступно.
`avatar_url`	https://lh3.googleusercontent.com/a/example	URL аватара; пусто, если URL недоступен.

Баланс

GET/api/v1/balance

Получение текущего баланса аккаунта в микродолларах USD. Только чтение: запись о проверке не создаётся, списаний нет.

Баланс

GET/api/v1/balance

Запрос

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

Ответ

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

Параллельность, тайм-ауты и повторные попытки

Проверки аватаров синхронные. По возвращённому коду решайте, принять результат или повторить попытку позже.

Поле	Описание
`5 одновременных запросов на пользователя`	Одиночные и множественные проверки делят этот лимит, причём множественный запрос считается одним запросом независимо от количества идентификаторов в нём. Кроме того, для одного аккаунта одновременно выполняется только одна множественная проверка; вторая отклоняется, пока не завершится первая. При достижении любого из лимитов сразу возвращается код 42901 без списания и с заголовком Retry-After — отправьте запрос повторно, когда завершится один из выполняющихся.
`60 с для одиночной, 300 с для множественной`	При превышении лимита времени возвращается код 50400 без списания. Множественная проверка, превысившая время, завершается ошибкой целиком — без частичных результатов, вся сумма возвращается.
`Множественная проверка — до 100 идентификаторов`	Результаты сохраняют порядок и количество отправленных номеров. Для одного аккаунта одновременно выполняется одна множественная проверка; отправляйте следующий пакет после того, как вернётся предыдущий.

Коды ошибок

Код	Описание
`40000`	Неподдерживаемый тип сервиса или конфликтующие поля запроса
`40001`	Недопустимое тело JSON
`40002`	Недопустимый идентификатор
`40100`	Ключ API отсутствует или недействителен
`40200`	Недостаточно средств на балансе
`42200`	Сейчас не удалось определить результат для идентификатора. Данные не возвращаются, запрос не оплачивается
`42900`	Исчерпана квота использования или слишком много незавершённых заказов
`42901`	Все пять слотов одновременных запросов заняты, или в этом аккаунте уже выполняется множественная проверка; отправьте запрос после завершения одного из выполняющихся. Отклонённый запрос не оплачивается и содержит заголовок Retry-After
`50303`	Сервис сейчас работает на пределе мощности; списания нет. Подождите указанное в Retry-After число секунд и отправьте тот же запрос повторно
`50400`	Проверка не завершилась за отведённое время и не оплачивается; повторите её. Превышение времени пакета приводит к ошибке всего пакета и полному возврату суммы
`50300`	Техобслуживание сервиса проверки