跳到主要内容

图像年龄估算 API

上传图像以检测人物和人脸，并为每个检测结果预测年龄及置信度百分比。

基础 URL​

https://api.genderrecognition.com

端点​

POST /v1/image-gender/api/age

请求标头​

apiKey: YOUR_API_KEY
Content-Type: multipart/form-data

请求正文​

字段类型必填说明
filefile是JPEG、PNG、WebP、BMP 或 GIF 图像。最大大小：10 MB。

示例​

curl -X POST "https://api.genderrecognition.com/v1/image-gender/api/age" \
  -H "apiKey: YOUR_API_KEY" \
  -F "file=@people.jpg"

成功响应​

{
  "success": true,
  "detections": [
    {
      "age": 27.4,
      "probability": 99
    },
    {
      "age": 41.2,
      "probability": 94
    }
  ],
  "remainingRequests": 2999
}

响应字段​

字段类型说明
successboolean图像处理成功时为 true。
detectionsarray每个检测到并获得年龄预测的人脸对应一项。
detections[].agenumber该检测结果的年龄预测值，可以包含小数。
detections[].probabilityinteger置信度百分比，范围为 0–100。 See note below.
remainingRequestsinteger本次成功请求扣除后剩余的 API 请求数。

此处的 probability 是模型对该检测结果的性别分类置信度，并被用作报告的置信度值；模型不会为年龄估算单独生成置信度分数。因此，较高的 probability 表示模型对性别判断更有把握，并不代表 age 更准确。

仅包含模型能够明确判断性别的检测结果。即使图像中检测到了人物或人脸，如果性别预测不明确或无法匹配，该人脸也会从 detections 中省略。因此，detections 中的项目可能少于图像中的人脸数量。

未检测到目标​

即使未找到能够可靠预测的人脸，处理也可能成功。这仍会消耗一次请求：

{
  "success": true,
  "detections": [],
  "remainingRequests": 2999
}

错误响应​

缺少 API 密钥 — 401 Unauthorized​

{
  "error": "API key is required"
}

API 密钥无效 — 404 Not Found​

{
  "error": "Invalid API key"
}

身份验证服务错误 — 500 Internal Server Error​

{
  "error": "Internal server error"
}

缺少文件 — 400 Bad Request​

multipart 表单字段必须命名为 file。

{
  "error": "No file uploaded"
}

意外的 multipart 字段 — 400 Bad Request​

上传文件的字段名不是 file，或通过单文件字段发送了多个文件时，会返回此响应。

{
  "error": "Unexpected field"
}

文件类型无效 — 400 Bad Request​

{
  "error": "Invalid file type. Allowed formats: JPEG, PNG, WEBP, BMP, GIF"
}

文件过大 — 400 Bad Request​

{
  "error": "File too large"
}

无法解码图像 — 400 Bad Request​

{
  "error": "Could not decode image"
}

上传的图像无效时，预测服务也可能返回其他 400 验证消息。响应结构仍为 { "error": "..." }。

预测服务拒绝过大的文件 — 413 Payload Too Large​

{
  "error": "Uploaded file exceeds the 10MB size limit"
}

配额已用尽 — 400 Bad Request​

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "You have exceeded your free tier limit of 50 requests.",
    "detailedMessage": "Insufficient remaining requests. Required: 1, Available: 0",
    "details": {
      "limit": 50,
      "used": 50,
      "reset_date": "2026-07-01T00:00:00.000Z"
    },
    "suggested_action": "Please upgrade to a premium plan to continue using the API."
  }
}

付费计划使用相同的响应结构，但限额、重置日期和升级指引会根据计划而异。

处理期间配额发生变化 — 400 Bad Request​

系统会在预测前检查配额，并在处理成功后扣除用量。如果另一并发请求在这两个操作之间用完了剩余配额，扣除时可能返回：

{
  "error": "Insufficient remaining requests. Required: 1, Available: 0"
}

处理失败 — 500 Internal Server Error​

{
  "error": "Image age prediction failed"
}

如果上游预测服务返回更具体的内部错误，其消息可能会以相同结构出现在 error 字段中。

说明​

  • 使用名为 file 的 multipart 字段，且只发送一张图像。
  • 只有预测服务成功返回后才会扣除一次请求。
  • age 可以是小数；probability 是整数百分比，不是 0 到 1 之间的小数。
  • probability 反映的是性别分类置信度，而非年龄估算的置信度；系统没有单独的年龄置信度分数。
  • detections 数组为空表示请求成功，并非错误。
  • 预测结果由模型估算，不应视为经过核实的身份属性。