跳到主要内容

图像性别识别 API

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

基础 URL​

https://api.genderrecognition.com

端点​

POST /v1/image-gender/api

请求标头​

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" \
  -H "apiKey: YOUR_API_KEY" \
  -F "file=@people.jpg"

成功响应​

{
  "success": true,
  "detections": [
    {
      "category": "face",
      "gender": "female",
      "probability": 99
    },
    {
      "category": "person",
      "gender": "male",
      "probability": 94
    }
  ],
  "remainingRequests": 2999
}

响应字段​

字段类型说明
successboolean图像处理成功时为 true。
detectionsarray每个检测到且获得预测的人脸或未匹配人物对应一项。
detections[].categoryface | person人脸与人物匹配时为 face；仅检测到身体时为 person。
detections[].gendermale | female该检测结果的性别预测。
detections[].probabilityinteger置信度百分比，范围为 0–100。
remainingRequestsinteger本次成功请求扣除后剩余的 API 请求数。

当人脸和身体属于同一个人时，响应中只会包含一个 face 检测项，而不会分别列出人脸和人物。

未检测到目标​

即使没有找到可用的人脸或人物，处理也可能成功。这仍会消耗一次请求：

{
  "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 gender prediction failed"
}

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

说明​

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