API 文档

实时头像检测 API：一个手机号，一次请求，同一次响应返回

核心是单号实时查询：向 /api/v1/check 提交一个标识，service_type 取 ws_avatar（手机号）或 email_avatar（邮箱地址）。账号有没有公开头像、有的话图片地址是什么，都在同一次响应里返回，不需要轮询，也不需要回调。同一把 API Key 也可以一次提交最多 100 个标识做同步查询。

获取 API Key 查看快速接入

API 接口POST

/api/v1/check

X-API-Key 请求头code · msg · data

最后更新：2026 年 9 月 18 日service_type=ws_avatar | email_avatar读取 data.avatar_url

API 速览主接口是单号实时检测；多号、异步批量和余额接口共用同一份 API Key 约定，并统一使用 code / msg / data 响应结构。

快速接入

1.在设置中创建 API Key。
2.通过 GET /api/v1/balance 查询当前余额。
3.向 /api/v1/check 提交一个标识，或向 /api/v1/batch-check 一次提交最多 100 个。
4.读取同步响应中的 data.avatar 与 data.avatar_url。

认证

使用在设置中创建的 API Key，并随每次请求一起发送。

X-API-Key: sk_your_api_key

妥善保管你的 API Key

请始终从你的服务端发起请求；持有该 Key 的任何人都可以消耗你的账户余额。

产品与返回字段

ws_avatarWhatsApp 头像画像查一个手机号在 WhatsApp 上有没有公开头像，取回图片地址，并读出这张头像的画像属性。

email_avatar邮箱头像画像查一个邮箱账号有没有公开头像，并读出它的画像属性。覆盖 Gmail、Yandex、Mail.ru。

image_profile图片画像识别上传任意一张图，得到它的画像属性：估计年龄、性别、图片类型、发色与肤色。

ws_avatar

WhatsApp 头像画像

查一个手机号在 WhatsApp 上有没有公开头像，取回图片地址，并读出这张头像的画像属性。

单号检测

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_avatar", "identifier": "+14155552671" }'

账号存在

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

账号不存在

{
  "code": 0,
  "msg": "ok",
  "data": {
    "service_type": "ws_avatar",
    "identifier": "+14155550000",
    "registered": false,
    "avatar": false,
    "avatar_url": "",
    "extra": {
      "profile_available": false,
      "category": "",
      "gender": "",
      "age": "",
      "skin_color": "",
      "hair_color": ""
    }
  }
}

字段类型说明

registeredboolean该手机号是否注册了 WhatsApp。

avatarboolean是否设置了公开头像。

avatar_urlstring公开头像的图片地址；未设置头像时为空字符串。

extra.profile_availablebooleanWhether portrait attributes were produced this time. Read it together with avatar: false/false means there is no avatar to analyse, true/false means the avatar could not be recognized.

extra.categorystringWhat the picture is: individual portrait, group photo, game avatar, cartoon avatar, landscape, pet avatar or object.

extra.genderstringmale, female or unknown.

extra.agenumberEstimated age, accurate to about 3 years and clamped to 0-80. Empty when no gender was determined — there is no placeholder number.

extra.skin_colorstringDescriptive skin tone, for example white, east_asian or hispanic. Treat it as an open set.

extra.hair_colorstringDescriptive hair colour, for example black, brown, blond or gray white. Treat it as an open set.

多号检测

计费：按手机号计算

请求中的每个手机号独立计费，单次最多提交 100 个手机号。只有成功完成检测的手机号才会消耗余额。如果余额不足以覆盖整批手机号的最高可能费用，请求会在处理前直接拒绝。

一次请求最多提交 100 个手机号，结果按提交顺序返回。

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_avatar", "identifiers": ["+14155552671", "+14155550000"] }'

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

字段类型说明

existsboolean该手机号是否得到了结果。为 false 表示手机号格式错误、结果无法判定或本次检测失败；为 false 时，以下字段均不出现。

registeredboolean该账号在对应平台上是否存在。仅在 exists 为 true 时出现，含义与单号查询一致。

avatarboolean是否设置了公开头像。

avatar_urlstring公开头像的图片地址；未设置头像时为空字符串。

extra.categorystringWhat the picture is: individual portrait, group photo, game avatar, cartoon avatar, landscape, pet avatar or object.

extra.genderstringmale, female or unknown.

extra.agenumberEstimated age, accurate to about 3 years and clamped to 0-80. Empty when no gender was determined — there is no placeholder number.

extra.skin_colorstringDescriptive skin tone, for example white, east_asian or hispanic. Treat it as an open set.

extra.hair_colorstringDescriptive hair colour, for example black, brown, blond or gray white. Treat it as an open set.

email_avatar

邮箱头像画像

查一个邮箱账号有没有公开头像，并读出它的画像属性。覆盖 Gmail、Yandex、Mail.ru。

单号检测

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_avatar", "identifier": "alex.kim@gmail.com" }'

账号存在

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

账号不存在

{
  "code": 0,
  "msg": "ok",
  "data": {
    "service_type": "email_avatar",
    "identifier": "no.such.user@gmail.com",
    "registered": false,
    "avatar": false,
    "avatar_url": "",
    "provider": "",
    "extra": {
      "profile_available": false,
      "category": "",
      "gender": "",
      "age": "",
      "skin_color": "",
      "hair_color": ""
    }
  }
}

字段类型说明

registeredboolean该服务商下是否存在这个账号。

avatarboolean是否设置了公开头像。

avatar_urlstring公开头像的图片地址；未设置头像时为空字符串。

providerstring按域名判断出的邮箱服务商：gmail、yandex 或 mailru。

extra.categorystringWhat the picture is: individual portrait, group photo, game avatar, cartoon avatar, landscape, pet avatar or object.

extra.genderstringmale, female or unknown.

extra.agenumberEstimated age, accurate to about 3 years and clamped to 0-80. Empty when no gender was determined — there is no placeholder number.

extra.skin_colorstringDescriptive skin tone, for example white, east_asian or hispanic. Treat it as an open set.

extra.hair_colorstringDescriptive hair colour, for example black, brown, blond or gray white. Treat it as an open set.

多号检测

计费：按手机号计算

一次请求最多提交 100 个手机号，结果按提交顺序返回。

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_avatar", "identifiers": ["alex.kim@gmail.com", "no.such.user@gmail.com"] }'

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

字段类型说明

existsboolean该手机号是否得到了结果。为 false 表示手机号格式错误、结果无法判定或本次检测失败；为 false 时，以下字段均不出现。

registeredboolean该账号在对应平台上是否存在。仅在 exists 为 true 时出现，含义与单号查询一致。

avatarboolean是否设置了公开头像。

avatar_urlstring公开头像的图片地址；未设置头像时为空字符串。

providerstring按域名判断出的邮箱服务商：gmail、yandex 或 mailru。

extra.categorystringWhat the picture is: individual portrait, group photo, game avatar, cartoon avatar, landscape, pet avatar or object.

extra.genderstringmale, female or unknown.

extra.agenumberEstimated age, accurate to about 3 years and clamped to 0-80. Empty when no gender was determined — there is no placeholder number.

extra.skin_colorstringDescriptive skin tone, for example white, east_asian or hispanic. Treat it as an open set.

extra.hair_colorstringDescriptive hair colour, for example black, brown, blond or gray white. Treat it as an open set.

image_profile

图片画像识别

上传任意一张图，得到它的画像属性：估计年龄、性别、图片类型、发色与肤色。

单号检测

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

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

字段类型说明

identifierstring提交图片的指纹，由图片内容算出。同一张图恒定是同一个值。

extra.categorystringWhat the picture is: individual portrait, group photo, game avatar, cartoon avatar, landscape, pet avatar or object.

extra.genderstringmale, female or unknown.

extra.agenumberEstimated age, accurate to about 3 years and clamped to 0-80. Empty when no gender was determined — there is no placeholder number.

extra.skin_colorstringDescriptive skin tone, for example white, east_asian or hispanic. Treat it as an open set.

extra.hair_colorstringDescriptive hair colour, for example black, brown, blond or gray white. Treat it as an open set.

并发、超时与重试方式

头像检测采用同步响应，请根据返回码决定接收结果或稍后重试。

每个用户最多 5 个请求在处理单号检测与多号检测共用这个上限，一次多号请求算一个请求，与手机号数量无关。此外每个账号同时只能跑 1 个多号检测，第二个会被拒绝直到前一个结束。达到任一上限都会立即返回业务码 42901 并附带 Retry-After 响应头，不扣费，等已有请求结束后再提交即可。
单号 60 秒，多号 300 秒超过后返回业务码 50400，不计费；多号超时是整批失败，不返回部分结果，已扣费用全额退回。
多号单次最多 100 个手机号结果按提交顺序、同等长度返回。每个账号同时只跑 1 个多号检测，上一批返回后再提交下一批。

错误码

40000不支持的 service_type 或字段冲突

40001JSON 请求体无效

40002手机号无效

40100缺少或无效的 API Key

40200余额不足

42200暂时无法判定该手机号。不返回 data，且本次不计费

42900次数配额已用完，或未完成订单数超限

429015 个在处理的请求名额已满，或该账号已有一个多号检测在跑；已有请求结束后可再次提交，拒绝请求不扣余额，响应带 Retry-After

50303平台此刻处理中的检测已达上限，不扣费；按 Retry-After 的秒数等待后重新提交同一请求

50400本次检测未在超时预算内完成，不计费，可直接重试；批量超时为整批失败并全额退款

50300检测服务维护中

异步批量任务

上传号码文件后立刻拿到任务号，之后按任务号查询状态；成功后会给出结果压缩包的下载链接。

ws_profile_batchWhatsApp 头像 · 批量每个任务 1,000–100,000 个手机号$0.005 / 手机号
tg_profile_batchTelegram 资料 · 批量每个任务 1,000–100,000 个手机号$0.004 / 手机号
tg_username_profile_batchTelegram 用户名资料 · 批量每个任务 1,000–100,000 个用户名$0.004 / 用户名
viber_profile_batchViber 资料 · 批量每个任务 1,000–100,000 个手机号$0.008 / 手机号
max_profile_batchMAX 资料 · 批量每个任务 1,000–100,000 个手机号$0.008 / 手机号
line_profile_batchLINE 资料 · 批量每个任务 1,000–100,000 个手机号$0.008 / 手机号
zalo_profile_batchZalo 画像 · 批量每个任务 1,000–100,000 个手机号$0.008 / 手机号
email_avatar_batch邮箱头像 · 批量每个任务 1,000–100,000 个邮箱地址$0.003 / 邮箱地址

1. 提交文件

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

响应：任务已创建（status 为 processing）

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "ws_profile_batch",
    "status": "processing",
    "country": "US",
    "total": 1000,
    "created_at": "2026-09-08T09:30:00Z"
  }
}

2. 查询任务

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

响应：任务已完成（成功时带 result_url）

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "ws_profile_batch",
    "status": "success",
    "country": "US",
    "total": 1000,
    "success_cnt": 990,
    "failure_cnt": 10,
    "result_url": "https://…/result.zip",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

一行一个手机号。上传 .txt 或 .csv，每行一个 E.164 格式的手机号。随文件提交 `country`：它用于补全没带国家码的号码，文件也按它校验。
不提供逐号进度。status 只有 processing、success、failed 三种。大名单需要一段时间，轮询不要快于 30 秒一次。
计费方式。提交时按整份文件冻结。任务结束后只对真正检测到结果的手机号收费，其余退回；任务失败则全额退款。
结果文件有时效。下载链接是按需生成的，指向一个有时效的文件，请在任务完成后尽快下载。

准备好开始接入了吗？

准备好了吗？免费注册即可在几秒内获取 API Key。

创建免费账号