Skip to main content

Gender by Image API

Upload an image to detect people and faces and predict a gender with a confidence percentage for each detection.

Base URL​

https://api.genderrecognition.com

Endpoint​

POST /v1/image-gender/api

Headers​

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

Body​

FieldTypeRequiredDescription
filefileYesJPEG, PNG, WebP, BMP, or GIF image. Maximum size: 10 MB.

Example​

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

Successful response​

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

Response fields​

FieldTypeDescription
successbooleantrue when the image was processed successfully.
detectionsarrayOne entry for each detected face or unmatched person with a prediction.
detections[].categoryface | personface when a face is matched to a person; person when only a body is available.
detections[].gendermale | femalePredicted gender for the detection.
detections[].probabilityintegerConfidence percentage from 0 to 100.
remainingRequestsintegerAPI requests remaining after this successful request is deducted.

When a face and body belong to the same person, the response contains one face detection rather than separate face and person entries.

No detections​

Processing can succeed without finding a usable face or person. This still consumes one request:

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

Error responses​

Missing API key — 401 Unauthorized​

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

Invalid API key — 404 Not Found​

{
  "error": "Invalid API key"
}

Authentication service error — 500 Internal Server Error​

{
  "error": "Internal server error"
}

Missing file — 400 Bad Request​

The multipart field must be named file.

{
  "error": "No file uploaded"
}

Unexpected multipart field — 400 Bad Request​

This response is returned when the uploaded file uses a field name other than file, or when more than one file is sent using the single-file field.

{
  "error": "Unexpected field"
}

Invalid file type — 400 Bad Request​

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

File too large — 400 Bad Request​

{
  "error": "File too large"
}

Image cannot be decoded — 400 Bad Request​

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

The prediction service can also return another 400 validation message when the uploaded image is invalid. The response uses the same { "error": "..." } shape.

Prediction service size rejection — 413 Payload Too Large​

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

Quota exceeded — 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."
  }
}

Paid plans use the same response structure with plan-specific limits, reset dates, and upgrade guidance.

Quota changed during processing — 400 Bad Request​

Quota is checked before prediction and deducted after successful processing. If another concurrent request consumes the remaining quota between those operations, the deduction can return:

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

Processing failed — 500 Internal Server Error​

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

If the upstream prediction service returns a more specific internal error, its message can be returned in the error field with the same response shape.

Notes​

  • Send exactly one image using the multipart field named file.
  • A request is deducted only after the prediction service returns successfully.
  • probability is a whole-number percentage, not a decimal between 0 and 1.
  • An empty detections array is a successful result, not an error.
  • Predictions are model estimates and should not be treated as verified identity attributes.