Referência

AvatarLookup Referência da API

Todos os endpoints compartilham uma chave de API e um saldo.

Item	Valor
URL base	https://avatarlookup.com
Cabeçalho de autenticação	X-API-Key: sk_your_api_key
Envelope da resposta	{ code, msg, data }

Os preços não são listados aqui; todos os produtos são cobrados por verificação bem-sucedida. Ver preços

Autenticação

Use uma chave de API criada em Configurações e envie-a em todas as solicitações.

Cabeçalho de autenticação

X-API-Key: sk_your_api_key

Mantenha sua chave de API em segredoSempre chame este endpoint a partir do seu servidor. Qualquer pessoa que tenha a chave pode gastar seu saldo.

Verificações síncronas

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

Envie um identificador, ou até 100 em uma única solicitação, e leia o resultado na mesma resposta. Sem polling, sem callbacks. Um resultado indeterminado retorna 422 com code 42200 e não é cobrado. Uma solicitação múltipla mantém a ordem de entrada, cobra cada identificador de forma independente e tem 300 segundos para terminar — se não terminar, a solicitação inteira falha e todas as cobranças são reembolsadas. A análise de imagem usa um endpoint próprio, /api/v1/image/profile, e recebe uma imagem em vez de um identificador.

Parâmetros

Campo	Tipo	Descrição
`service_type`	string	Código do produto, um dos produtos listados abaixo.
`identifier`	string	Verificação única: um identificador. O servidor o normaliza.
`identifiers`	string[]	Verificação múltipla: de 1 a 100 identificadores. A resposta preserva esta ordem.
`file`	file	Análise de imagem: uma imagem de retrato (envio multipart). Não há `identifier`.

Produtos deste grupo

Análise de perfil por imagemimage_profileEnvie qualquer imagem e receba seus atributos de retrato: idade estimada, gênero, tipo de imagem, cor do cabelo e tom de pele.Página do produto
Análise de foto de perfil do WhatsAppws_profileVerifique se um número tem foto de perfil no WhatsApp, obtenha a URL da imagem e leia os atributos de retrato dessa foto.Página do produto
Análise de foto de perfil de e-mailemail_profileVerifique se uma conta de e-mail tem foto de perfil e leia seus atributos de retrato. Cobre Gmail, Yandex e Mail.ru.Página do produto

Análise de perfil por imagem

image_profileimagem

Envie qualquer imagem e receba seus atributos de retrato: idade estimada, gênero, tipo de imagem, cor do cabelo e tom de pele.

Verificação única

POST/api/v1/image/profile

Solicitação

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

Resposta

{
  "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 da resposta

Campo	Tipo	Descrição
`identifier`	string	Impressão digital da imagem enviada, derivada do seu conteúdo. A mesma imagem sempre gera o mesmo valor.
`category`	string	O que a imagem mostra: individual portrait, group photo, game avatar, cartoon avatar, landscape, pet avatar ou object. unknown quando não foi possível gerar um retrato.
`age`	integer	Idade estimada como número inteiro, com precisão de cerca de 3 anos e limitada a 0-80. Omitida quando não foi possível estimá-la (por exemplo, quando nenhum gênero foi determinado).
`gender`	string	male, female ou unknown.
`skin_color`	string	Tom de pele descritivo, por exemplo white, east_asian ou hispanic. Trate-o como um conjunto aberto; unknown quando não determinado.
`hair_color`	string	Cor do cabelo descritiva, por exemplo black, brown, blond ou gray white. Trate-a como um conjunto aberto; unknown quando não determinada.

Análise de foto de perfil do WhatsApp

ws_profiletelefone

Verifique se um número tem foto de perfil no WhatsApp, obtenha a URL da imagem e leia os atributos de retrato dessa foto.

Verificação única

POST/api/v1/check

Solicitação

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 da resposta

Campo	Tipo	Descrição
`registered`	boolean	Se o número está registrado no WhatsApp.
`avatar`	boolean	Se há foto de perfil definida.
`avatar_url`	string	URL da foto de perfil; string vazia quando nenhuma foto está definida.
`category`	string	O que a imagem mostra: individual portrait, group photo, game avatar, cartoon avatar, landscape, pet avatar ou object. unknown quando não foi possível gerar um retrato.
`age`	integer	Idade estimada como número inteiro, com precisão de cerca de 3 anos e limitada a 0-80. Omitida quando não foi possível estimá-la (por exemplo, quando nenhum gênero foi determinado).
`gender`	string	male, female ou unknown.
`skin_color`	string	Tom de pele descritivo, por exemplo white, east_asian ou hispanic. Trate-o como um conjunto aberto; unknown quando não determinado.
`hair_color`	string	Cor do cabelo descritiva, por exemplo black, brown, blond ou gray white. Trate-a como um conjunto aberto; unknown quando não determinada.

Verificação múltipla

POST/api/v1/batch-check

Solicitação

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

Resposta

{
  "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 da resposta

Campo	Tipo	Descrição
`exists`	boolean	Se este identificador gerou um resultado. false significa que o formato era inválido, o resultado foi indeterminado ou a verificação falhou; quando false, nenhum dos campos abaixo está presente.
`registered`	boolean	Se a conta existe nessa plataforma (para um endereço de e-mail: se ele é alcançável). Presente apenas quando exists é true, com o mesmo significado da consulta individual.
`avatar`	boolean	Se há foto de perfil definida.
`avatar_url`	string	URL da foto de perfil; string vazia quando nenhuma foto está definida.
`category`	string	O que a imagem mostra: individual portrait, group photo, game avatar, cartoon avatar, landscape, pet avatar ou object. unknown quando não foi possível gerar um retrato.
`age`	integer	Idade estimada como número inteiro, com precisão de cerca de 3 anos e limitada a 0-80. Omitida quando não foi possível estimá-la (por exemplo, quando nenhum gênero foi determinado).
`gender`	string	male, female ou unknown.
`skin_color`	string	Tom de pele descritivo, por exemplo white, east_asian ou hispanic. Trate-o como um conjunto aberto; unknown quando não determinado.
`hair_color`	string	Cor do cabelo descritiva, por exemplo black, brown, blond ou gray white. Trate-a como um conjunto aberto; unknown quando não determinada.

Análise de foto de perfil de e-mail

email_profilee-mail

Verifique se uma conta de e-mail tem foto de perfil e leia seus atributos de retrato. Cobre Gmail, Yandex e Mail.ru.

Verificação única

POST/api/v1/check

Solicitação

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 da resposta

Campo	Tipo	Descrição
`registered`	boolean	Se o endereço de e-mail é alcançável (pode receber mensagens).
`avatar`	boolean	Se há foto de perfil definida.
`avatar_url`	string	URL da foto de perfil; string vazia quando nenhuma foto de perfil está definida.
`category`	string	O que a imagem mostra: individual portrait, group photo, game avatar, cartoon avatar, landscape, pet avatar ou object. unknown quando não foi possível gerar um retrato.
`age`	integer	Idade estimada como número inteiro, com precisão de cerca de 3 anos e limitada a 0-80. Omitida quando não foi possível estimá-la (por exemplo, quando nenhum gênero foi determinado).
`gender`	string	male, female ou unknown.
`skin_color`	string	Tom de pele descritivo, por exemplo white, east_asian ou hispanic. Trate-o como um conjunto aberto; unknown quando não determinado.
`hair_color`	string	Cor do cabelo descritiva, por exemplo black, brown, blond ou gray white. Trate-a como um conjunto aberto; unknown quando não determinada.

Verificação múltipla

POST/api/v1/batch-check

Solicitação

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

Resposta

{
  "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 da resposta

Campo	Tipo	Descrição
`exists`	boolean	Se este identificador gerou um resultado. false significa que o formato era inválido, o resultado foi indeterminado ou a verificação falhou; quando false, nenhum dos campos abaixo está presente.
`registered`	boolean	Se a conta existe nessa plataforma (para um endereço de e-mail: se ele é alcançável). Presente apenas quando exists é true, com o mesmo significado da consulta individual.
`avatar`	boolean	Se há foto de perfil definida.
`avatar_url`	string	URL da foto de perfil; string vazia quando nenhuma foto de perfil está definida.
`category`	string	O que a imagem mostra: individual portrait, group photo, game avatar, cartoon avatar, landscape, pet avatar ou object. unknown quando não foi possível gerar um retrato.
`age`	integer	Idade estimada como número inteiro, com precisão de cerca de 3 anos e limitada a 0-80. Omitida quando não foi possível estimá-la (por exemplo, quando nenhum gênero foi determinado).
`gender`	string	male, female ou unknown.
`skin_color`	string	Tom de pele descritivo, por exemplo white, east_asian ou hispanic. Trate-o como um conjunto aberto; unknown quando não determinado.
`hair_color`	string	Cor do cabelo descritiva, por exemplo black, brown, blond ou gray white. Trate-a como um conjunto aberto; unknown quando não determinada.

Verificações assíncronas

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

Envie um arquivo e receba um ID de tarefa imediatamente; depois, consulte esse ID até que seja concluído com sucesso. A resposta de sucesso inclui result_url, o link para baixar o resultado. Existem apenas duas ações: enviar e consultar. Não consulte com frequência maior que uma vez a cada 30 segundos.

Parâmetros

Campo	Tipo	Descrição
`service_type`	string	Código do produto em massa, um dos produtos listados abaixo.
`country`	string	Código ISO 3166-1, como `US`. Obrigatório para tarefas de números: cada número deve incluir o código do país e pertencer a este país (os números que não atendem a isso são excluídos e não são cobrados); também define o roteamento. Em multipart, deve vir antes de `file`.
`file`	file	Um `.txt` ou `.csv` com um identificador por linha, até `max_file_bytes` (20MB por padrão).
`Idempotency-Key`	header	Opcional, até 128 caracteres. Reenviar a mesma chave retorna a tarefa original em vez de criar uma segunda.

Produtos deste grupo

Análise de foto de perfil do WhatsApp · Em massaws_profile_batchEnvie um arquivo inteiro de números: URL da foto de perfil do WhatsApp e o que a foto mostra — categoria, idade, gênero, tom de pele e cor do cabelo.Página do produto
Perfil por número do Telegram · Em massatg_profile_batchEnvie números: ID de usuário do Telegram, nome de usuário, dias de atividade e URL da foto de perfil, além de idade, gênero e tom de pele reconhecidos na foto.Página do produto
Perfil por nome de usuário do Telegram · Em massatg_username_profile_batchEnvie nomes de usuário do Telegram: ID de usuário, dias de atividade e URL da foto de perfil de cada conta.Página do produto
Perfil por número do Viber · Em massaviber_profile_batchEnvie números: ID de membro do Viber, dias de atividade e URL da foto de perfil, além de categoria, idade, gênero e tom de pele reconhecidos na foto.Página do produto
Perfil por número do MAX · Em massamax_profile_batchEnvie números: ID de usuário do MAX, URL da foto de perfil e gênero.Página do produto
Análise de foto de perfil do LINE · Em massaline_profile_batchEnvie números: ID de usuário do LINE e URL da foto de perfil, além de categoria, idade, gênero, tom de pele e cor do cabelo reconhecidos na foto.Página do produto
Perfil por número do Zalo · Em massazalo_profile_batchEnvie números: ID de usuário do Zalo e URL da foto de perfil, além de categoria, idade, gênero e tom de pele reconhecidos na foto.Página do produto
Verificação de foto de perfil de e-mail · Em massaemail_avatar_batchEnvie endereços Gmail, Yandex ou Mail.ru: se cada um é entregável e sua foto de perfil.Página do produto

Análise de foto de perfil do WhatsApp · Em massa

ws_profile_batchtelefone1.000–500.000 por tarefa

Envie um arquivo inteiro de números: URL da foto de perfil do WhatsApp e o que a foto mostra — categoria, idade, gênero, tom de pele e cor do cabelo.

Enviar uma tarefa

POST/api/v1/bulk-tasks

Solicitação

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

Resposta

{
  "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 a tarefa

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

Solicitação

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

Resposta

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

Colunas do resultado

Campo	exemplo:	Descrição
`identifier`	17253100591	O número enviado apenas em dígitos, com o código do país, sem sinal de mais nem espaços (ex.: 17253100591).
`activated`	true	Se o número está registrado no WhatsApp: true ou false. Quando não é true, todas as outras colunas dessa linha ficam vazias.
`avatar_url`	https://pps.waavatar.xyz/v/example.jpg	URL da foto de perfil; vazia quando a conta não tem foto de perfil.
`category`	individual portrait	O que a foto de perfil mostra: individual portrait, group photo, cartoon avatar, pet avatar, landscape, object etc.; unknown quando não pode ser reconhecida, vazio quando não há foto de perfil.
`age`	31	Idade estimada a partir da foto de perfil; vazia quando não pode ser estimada.
`gender`	male	Gênero estimado a partir da foto de perfil: male ou female; unknown quando não pode ser reconhecido, vazio quando não há foto de perfil.
`skin_color`	east_asian	Tom de pele estimado a partir da foto de perfil, por exemplo white, asian, east_asian; unknown quando não pode ser reconhecido, vazio quando não há foto de perfil.
`hair_color`	black	Cor do cabelo estimada a partir da foto de perfil, por exemplo black, brown; unknown quando não pode ser reconhecida, vazio quando não há foto de perfil.

Perfil por número do Telegram · Em massa

tg_profile_batchtelefone1.000–500.000 por tarefa

Envie números: ID de usuário do Telegram, nome de usuário, dias de atividade e URL da foto de perfil, além de idade, gênero e tom de pele reconhecidos na foto.

Enviar uma tarefa

POST/api/v1/bulk-tasks

Solicitação

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

Resposta

{
  "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 a tarefa

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

Solicitação

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

Resposta

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

Colunas do resultado

Campo	exemplo:	Descrição
`identifier`	17253100591	O número enviado apenas em dígitos, com o código do país, sem sinal de mais nem espaços (ex.: 17253100591).
`activated`	true	Se o número está registrado no Telegram: true ou false. Quando não é true, todas as outras colunas dessa linha ficam vazias.
`uid`	1234567890	ID de usuário do Telegram.
`username`	alex_kim	Nome de usuário; vazio quando a conta não tem um.
`activedays`	9	Dias desde que a conta foi vista pela última vez, como número inteiro — quanto menor, mais recente. Quando a conta oculta o horário exato em que foi vista por último, o Telegram revela apenas um intervalo, e o valor é uma aproximação: 0 (recentemente), 7 (na última semana), 30 (no último mês) ou 1000 (há muito tempo).
`avatar_url`	https://telegram.waavatar.xyz/v/example.jpg	URL da foto de perfil; vazia quando a conta não tem foto de perfil.
`age`	31	Idade estimada a partir da foto de perfil; vazia quando não pode ser estimada.
`gender`	male	Gênero estimado a partir da foto de perfil: male ou female; unknown quando não pode ser reconhecido, vazio quando não há foto de perfil.
`skin_color`	white	Tom de pele estimado a partir da foto de perfil, por exemplo white, asian, east_asian; unknown quando não pode ser reconhecido, vazio quando não há foto de perfil.

Perfil por nome de usuário do Telegram · Em massa

tg_username_profile_batchnome de usuário1.000–500.000 por tarefa

Envie nomes de usuário do Telegram: ID de usuário, dias de atividade e URL da foto de perfil de cada conta.

Enviar uma tarefa

POST/api/v1/bulk-tasks

Solicitação

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

Resposta

{
  "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 a tarefa

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

Solicitação

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

Resposta

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

Colunas do resultado

Campo	exemplo:	Descrição
`identifier`	alex_kim	O nome de usuário enviado, sem @ ou t.me/ (por exemplo, alex_kim).
`activated`	true	Se o nome de usuário pertence a uma conta existente do Telegram: true ou false. Quando não é true, todas as outras colunas dessa linha ficam vazias.
`uid`	1234567890	ID de usuário do Telegram; pode ficar vazio mesmo para uma conta existente.
`activedays`	9	Dias desde que a conta foi vista pela última vez, como número inteiro — quanto menor, mais recente. Quando a conta oculta o horário exato em que foi vista por último, o Telegram revela apenas um intervalo, e o valor é uma aproximação: 0 (recentemente), 7 (na última semana), 30 (no último mês) ou 1000 (há muito tempo). Pode ficar vazio quando a conta não revela nenhuma informação de visto por último.
`avatar_url`	https://cdn5.telesco.pe/file/example.jpg	URL da foto de perfil; vazia quando a conta não tem foto de perfil.

Perfil por número do Viber · Em massa

viber_profile_batchtelefone1.000–500.000 por tarefa

Envie números: ID de membro do Viber, dias de atividade e URL da foto de perfil, além de categoria, idade, gênero e tom de pele reconhecidos na foto.

Enviar uma tarefa

POST/api/v1/bulk-tasks

Solicitação

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

Resposta

{
  "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 a tarefa

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

Solicitação

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

Resposta

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

Colunas do resultado

Campo	exemplo:	Descrição
`identifier`	17253100591	O número enviado apenas em dígitos, com o código do país, sem sinal de mais nem espaços (ex.: 17253100591).
`activated`	true	Se o número está registrado no Viber: true ou false. Quando não é true, todas as outras colunas dessa linha ficam vazias.
`uid`	A5qCVDb3jPU=	ID de membro do Viber.
`activedays`	3	Dias desde que a conta esteve online pela última vez — quanto menor, mais recente.
`avatar_url`	https://viber.waavatar.xyz/v/example.jpg	URL da foto de perfil; vazia quando a conta não tem foto de perfil.
`category`	individual portrait	O que a foto de perfil mostra: individual portrait, group photo, cartoon avatar, pet avatar, landscape, object etc.; unknown quando não pode ser reconhecida, vazio quando não há foto de perfil.
`age`	31	Idade estimada a partir da foto de perfil; vazia quando não pode ser estimada.
`gender`	male	Gênero estimado a partir da foto de perfil: male ou female; unknown quando não pode ser reconhecido, vazio quando não há foto de perfil.
`skin_color`	white	Tom de pele estimado a partir da foto de perfil, por exemplo white, asian, east_asian; unknown quando não pode ser reconhecido, vazio quando não há foto de perfil.

Perfil por número do MAX · Em massa

max_profile_batchtelefone1.000–500.000 por tarefa

Envie números: ID de usuário do MAX, URL da foto de perfil e gênero.

Enviar uma tarefa

POST/api/v1/bulk-tasks

Solicitação

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

Resposta

{
  "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 a tarefa

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

Solicitação

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

Resposta

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

Colunas do resultado

Campo	exemplo:	Descrição
`identifier`	17253100591	O número enviado apenas em dígitos, com o código do país, sem sinal de mais nem espaços (ex.: 17253100591).
`activated`	true	Se o número está registrado no MAX: true ou false. Quando não é true, todas as outras colunas dessa linha ficam vazias.
`uid`	343064807	ID de usuário do MAX.
`avatar_url`	https://i.oneme.ru/i?r=example	URL da foto de perfil; vazia quando a conta não tem foto de perfil.
`gender`	male	Gênero da conta: male ou female; vazio quando desconhecido.

Análise de foto de perfil do LINE · Em massa

line_profile_batchtelefone2.000–500.000 por tarefa

Envie números: ID de usuário do LINE e URL da foto de perfil, além de categoria, idade, gênero, tom de pele e cor do cabelo reconhecidos na foto.

Enviar uma tarefa

POST/api/v1/bulk-tasks

Solicitação

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

Resposta

{
  "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 a tarefa

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

Solicitação

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

Resposta

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

Colunas do resultado

Campo	exemplo:	Descrição
`identifier`	17253100591	O número enviado apenas em dígitos, com o código do país, sem sinal de mais nem espaços (ex.: 17253100591).
`activated`	true	Se o número está registrado no LINE: true ou false. Quando não é true, todas as outras colunas dessa linha ficam vazias.
`uid`	u5158553776c28d9164035c4fd0a07cd4	ID de usuário do LINE.
`avatar_url`	https://profile.line-scdn.net/example	URL da foto de perfil; vazia quando a conta não tem foto de perfil.
`category`	individual portrait	O que a foto de perfil mostra: individual portrait, group photo, cartoon avatar, pet avatar, landscape, object etc.; unknown quando não pode ser reconhecida, vazio quando não há foto de perfil.
`age`	31	Idade estimada a partir da foto de perfil; vazia quando não pode ser estimada.
`gender`	male	Gênero estimado a partir da foto de perfil: male ou female; unknown quando não pode ser reconhecido, vazio quando não há foto de perfil.
`skin_color`	east_asian	Tom de pele estimado a partir da foto de perfil, por exemplo white, asian, east_asian; unknown quando não pode ser reconhecido, vazio quando não há foto de perfil.
`hair_color`	black	Cor do cabelo estimada a partir da foto de perfil, por exemplo black, brown; unknown quando não pode ser reconhecida, vazio quando não há foto de perfil.

Perfil por número do Zalo · Em massa

zalo_profile_batchtelefone1.000–500.000 por tarefa

Envie números: ID de usuário do Zalo e URL da foto de perfil, além de categoria, idade, gênero e tom de pele reconhecidos na foto.

Enviar uma tarefa

POST/api/v1/bulk-tasks

Solicitação

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

Resposta

{
  "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 a tarefa

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

Solicitação

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

Resposta

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

Colunas do resultado

Campo	exemplo:	Descrição
`identifier`	17253100591	O número enviado apenas em dígitos, com o código do país, sem sinal de mais nem espaços (ex.: 17253100591).
`activated`	true	Se o número está registrado no Zalo: true ou false. Quando não é true, todas as outras colunas dessa linha ficam vazias.
`uid`	452114152	ID de usuário do Zalo.
`avatar_url`	https://s160-ava-talk.zadn.vn/example.jpg	URL da foto de perfil; vazia quando a conta não tem foto de perfil.
`category`	individual portrait	O que a foto de perfil mostra: individual portrait, group photo, cartoon avatar, pet avatar, landscape, object etc.; unknown quando não pode ser reconhecida, vazio quando não há foto de perfil.
`age`	31	Idade estimada a partir da foto de perfil; vazia quando não pode ser estimada.
`gender`	male	Gênero estimado a partir da foto de perfil: male ou female; unknown quando não pode ser reconhecido, vazio quando não há foto de perfil.
`skin_color`	asian	Tom de pele estimado a partir da foto de perfil, por exemplo white, asian, east_asian; unknown quando não pode ser reconhecido, vazio quando não há foto de perfil.

Verificação de foto de perfil de e-mail · Em massa

email_avatar_batche-mail1.000–500.000 por tarefa

Envie endereços Gmail, Yandex ou Mail.ru: se cada um é entregável e sua foto de perfil.

Enviar uma tarefa

POST/api/v1/bulk-tasks

Solicitação

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

Resposta

{
  "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 a tarefa

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

Solicitação

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

Resposta

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

Colunas do resultado

Campo	exemplo:	Descrição
`identifier`	alex.kim@gmail.com	O endereço enviado, em letras minúsculas.
`activated`	true	Se o endereço é entregável nesse provedor — se pode receber mensagens: true ou false. Quando não é true, todas as outras colunas dessa linha ficam vazias.
`avatar`	true	Se há foto de perfil definida: true ou false. avatar_url ainda pode ficar vazia quando a imagem não está disponível.
`avatar_url`	https://lh3.googleusercontent.com/a/example	A URL da foto de perfil; vazia quando nenhuma URL está disponível.

Saldo

GET/api/v1/balance

Lê o saldo atual da conta em micros de USD. Somente leitura: não cria registro de verificação nem cobra nada.

Saldo

GET/api/v1/balance

Solicitação

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

Resposta

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

Concorrência, tempos limite e comportamento de novas tentativas

As consultas de fotos de perfil são síncronas. Use o code retornado para decidir se aceita o resultado ou tenta novamente mais tarde.

Campo	Descrição
`5 solicitações simultâneas por usuário`	As verificações únicas e múltiplas compartilham este limite, e uma solicitação múltipla conta como uma solicitação, independentemente de quantos identificadores ela contenha. Além disso, apenas uma verificação múltipla por conta é executada por vez; uma segunda é rejeitada até que a primeira termine. Atingir qualquer um dos limites retorna o code 42901 imediatamente, sem cobrança, com um cabeçalho Retry-After — reenvie assim que uma solicitação em andamento terminar.
`60s para única, 300s para múltipla`	Exceder o tempo limite retorna o code 50400, sem cobrança. Uma verificação múltipla que excede o tempo falha por completo — sem resultados parciais, e o valor total é reembolsado.
`Uma verificação múltipla aceita até 100 identificadores`	Os resultados preservam a ordem e a quantidade do envio. Uma verificação múltipla por conta é executada por vez; envie o próximo lote depois que o anterior retornar.

Códigos de erro

Código	Descrição
`40000`	Tipo de serviço não suportado ou campos da solicitação conflitantes
`40001`	Corpo JSON inválido
`40002`	Identificador inválido
`40100`	Chave de API ausente ou inválida
`40200`	Saldo insuficiente
`42200`	Não foi possível determinar o identificador neste momento. Nenhum dado é retornado e a solicitação não é cobrada
`42900`	Uma cota de uso foi esgotada ou há pedidos não concluídos demais
`42901`	Todas as cinco vagas de solicitações simultâneas estão ocupadas ou já há uma verificação múltipla em execução nesta conta; envie depois que uma solicitação em andamento terminar. A solicitação rejeitada não é cobrada e inclui um cabeçalho Retry-After
`50303`	O serviço está no limite da capacidade agora; sem cobrança. Aguarde os segundos indicados em Retry-After e reenvie a mesma solicitação
`50400`	A verificação não terminou dentro do tempo limite e não é cobrada; tente novamente. O tempo esgotado de um lote faz o lote inteiro falhar e reembolsa o valor total
`50300`	Manutenção do serviço de validação