用于个人资料图片的年龄与性别估算 API：请求、读取、存储
上传个人资料图片，在获取属性前读取图片类型，并将年龄和性别输出存储为标记后的估算值，以供联系人数据审核使用。
本指南旨在指导开发人员如何发送个人资料图片进行分析，并将年龄、性别及其他外貌特征输出作为算法估算值进行处理。
年龄与性别估算 API 可接收一张图片，并针对图片中显示的人物返回算法猜测结果。AvatarLookup 通过“图片人像解析”提供此功能：开发人员将 JPEG、PNG、WebP 或 GIF 文件作为 multipart form data 上传至已记录的图片分析端点，即可获得同步响应，内容涵盖图片类型；若图片中包含人物，还会返回预估的性别、年龄、发色和肤色。该结果是对图片本身的描述，而非对账户或其背后人物的描述。请将所有属性视为支持联系人数据审核的估算值，在存储时进行相应标记，并避免将其用于影响人员访问权限、定价或资格的决策中。
年龄与性别估算 API 的返回内容，以及大多数指南忽略的细节
大多数针对此主题排名的页面都是供应商列表。它们展示了包含人脸框、年龄数字和性别评分的示例响应，并承诺准确性。但它们很少解释开发人员在第一周就会遇到的三个问题：当图片不是肖像照时会发生什么、年龄估算的误差范围有多大，以及如何存储输出结果以确保后续不会将其误认为事实。
AvatarLookup 的“图片人像解析”功能旨在回答有关图片的问题。第一个输出是图片类型：人物照片，或其他类型（如徽标、插图、物体或动物）。当出现人物时，分析结果会增加外貌估算值。该结果携带的是从图片内容中提取的指纹，而非账户标识符，因此响应中没有任何内容将图片与电话号码、电子邮件地址或特定个人关联起来。
这种设计非常适合联系人数据团队。CRM 或支持工具中通常已经存储了客户或合作伙伴提供的头像，此时有用的问题通常是“这是什么类型的图片”，而不是“这是谁”。
发送个人资料图片：已记录的 multipart 上传
已记录的 API 路由为单次同步调用。无需创建任务，也不涉及轮询循环。
- 选择您已持有的文件。 典型的输入包括从 CRM 导出的头像、附加到支持工单的图片，或合作伙伴目录中的图像。
- 先进行本地验证。 仅接受 JPEG、PNG、WebP 或 GIF 格式，并在文件离开您的系统前拒绝超过规定大小限制的文件。本地检查可节省往返时间，并使您的日志更易于阅读。
- 以 multipart form data 形式上传至 API 文档中列出的图片分析端点，并使用您的 API 凭据。请遵循该处的请求参考，而非直接复制文章中的参数。
- 将结果存储在您的记录键旁边，并附上分析日期和图片来源。
请仅针对 multipart 上传进行构建。Base64 和图片 URL 有效载荷不属于已记录的 API 合约范畴，因此依赖它们的代码可能会失效。网站工具确实接受公共图片 URL，这在工程师编写代码前分析人员想要测试几张图片时非常方便。
对于动画 GIF，请在您的一侧决定哪一帧代表头像，如果您的审核流程需要可预测的输入，请将其转换为静态图像。该选择属于您的流水线，而非 API 的范畴。
读取结果：先看图片类型，再看属性
请分层读取每个结果，并在集成上线前为每种结果映射后续步骤。
| 结果 | 含义 | 建议处理方式 |
|---|---|---|
| 包含属性的人物照片 | 模型估算了外貌属性 | 存储为估算值；仅用于分类筛选 |
| 非人物图片（徽标、卡通、宠物、物体） | 关于图片的确定性结论 | 将记录标记为非肖像头像 |
| 包含部分未知属性的人物照片 | 模型无法估算这些值 | 保留已知值；其他留空，不要猜测 |
| 服务错误或无法读取的图片 | 未完成结果 | 记录日志，检查文件，若文件有效则稍后重发 |
计费遵循相同的拆分原则。已完成的结果均需计费，包括非人物图片或包含未知属性的图片，因为分析过程产生了结果。服务错误、无法读取的图片或无字段的响应不计费。按调用记录结果类别，可使财务和工程部门从同一日志中核对使用情况。
非人物结果在实践中通常最有用。个人联系记录中的徽标或供应商资料上的卡通图片，是提示数据管理员查看该记录的明确信号。
年龄估算的准确性及存储方式
独立测试表明了为何估算值需要标签。美国国家标准与技术研究院（NIST）正在进行一项持续的人脸分析技术评估（针对年龄估算），并报告了跨人口统计群体和图像条件下的平均绝对误差。其发布的结果显示，不同算法之间存在较大差异，且对图像质量和主体年龄等因素较为敏感。个人资料图片带来了额外的问题：滤镜、高压缩率、旧照片和裁剪后的合影。
一种能保持输出诚实性的存储模式：
- 将字段命名为估算值，例如
estimated_age_band（预估年龄段）和estimated_gender（预估性别），切勿使用age（年龄）或gender（性别）。 - 在下游工具中优先使用年龄段而非单一数字，以便审核人员看到的是范围，而非虚假的精确度。
- 保留来源信息：分析日期、图片来源以及随结果返回的指纹。
- 在图片更改时重新分析，而不是将旧的估算值沿用到新头像上。
- 将估算值与客户提供的数据分开，确保声明的出生日期永远不会被模型输出覆盖。
年龄与性别估算 API 的适用与不适用场景
适用场景通常是风险较低且可逆的：整理大量的头像积压数据、标记个人联系记录中的非肖像图片、抽取异常记录进行人工审核，或发现从未被替换的占位符图片。在这些情况下，最终决定由人工做出，错误的估算只会增加一点审核时间。
不适用场景是那些会改变个人权限或费用的决策。根据预估年龄或性别来批准、拒绝、排名或定价，筛选申请人，追踪个人，以及为未预期的个人建立画像，这些都超出了负责任的使用范围。外貌估算并非人口统计学事实，模型对人脸的解读并不能代表个人的自我认同。
法律背景同样重要。英国监管机构关于生物识别数据的指南解释了处理人物图像何时会进入生物识别和特殊类别领域，其他司法管辖区也存在类似规则。团队在为真实的联系人数据开启图片分析功能前，应记录其目的、保留期限和审核流程。
常见问题解答
团队如何在集成前自行测试准确性？
组建一个经过授权的小型样本集，使其看起来像生产数据：真实的头像尺寸、压缩率、滤镜，以及肖像和非肖像的混合。通过网站工具或测试脚本运行，然后让两名审核人员将输出结果与他们所见的内容进行对比。衡量图片类型在多大程度上是有用的，以及年龄段在多大程度上明显偏离，并根据这些证据设定您的审核规则。
API 可以分析来自 URL 的图片而不是上传的文件吗？
已记录的 API 路由采用 multipart 文件上传。网站工具支持公共图片 URL，这适用于对少量图片进行手动检查。对于自动化流水线，请将图片下载到您自己的系统，验证类型和大小，然后上传文件。这也为您提供了所分析内容的稳定副本，当有人质疑估算结果时，这会很有帮助。
团队应如何处理响应中的未知属性？
将“未知”视为一种正常的、已完成的回答。保留已估算的属性，将未知属性留空，不要用其他字段的默认值或猜测值进行填充。报告仪表板应将“未知”与“错误”分开统计，因为两者需要不同的后续处理：未知值通常反映图片本身，而错误则指向文件或服务问题。
了解更多
选择符合您工作流程下一步的产品信息。