Saltar al contenido principal

API de género por imagen

Envía una imagen para detectar personas y rostros y estimar el género con un porcentaje de confianza para cada detección.

URL base​

https://api.genderrecognition.com

Endpoint​

POST /v1/image-gender/api

Encabezados​

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

Cuerpo de la solicitud​

CampoTipoObligatorioDescripción
filefileSíImagen JPEG, PNG, WebP, BMP o GIF. Tamaño máximo: 10 MB.

Ejemplo​

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

Respuesta correcta​

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

Campos de respuesta​

CampoTipoDescripción
successbooleantrue when the image was processed successfully.
detectionsarrayUna entrada por cada rostro detectado o persona sin rostro asociado que tenga una predicción.
detections[].categoryface | personface cuando se asocia un rostro a una persona; person cuando solo se detecta el cuerpo.
detections[].gendermale | femaleGénero estimado en esta detección.
detections[].probabilityintegerPorcentaje de confianza de 0 a 100.
remainingRequestsintegerSolicitudes API restantes tras descontar esta solicitud completada correctamente.

Cuando un rostro y un cuerpo pertenecen a la misma persona, la respuesta incluye una sola detección face, en lugar de entradas separadas para el rostro y la persona.

No se detectaron elementos​

El procesamiento puede completarse sin encontrar un rostro o una persona válidos. Aun así, se consume una solicitud:

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

Respuestas de error​

Falta la clave API — 401 Unauthorized​

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

Clave API no válida — 404 Not Found​

{
  "error": "Invalid API key"
}

Error del servicio de autenticación — 500 Internal Server Error​

{
  "error": "Internal server error"
}

Falta el archivo — 400 Bad Request​

El campo multipart debe llamarse file.

{
  "error": "No file uploaded"
}

Campo multipart inesperado — 400 Bad Request​

Esta respuesta se devuelve cuando el archivo se envía con un campo distinto de file o cuando se envía más de un archivo en el campo para un solo archivo.

{
  "error": "Unexpected field"
}

Tipo de archivo no válido — 400 Bad Request​

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

Archivo demasiado grande — 400 Bad Request​

{
  "error": "File too large"
}

No se pudo decodificar la imagen — 400 Bad Request​

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

Si la imagen enviada no es válida, el servicio también puede devolver otro mensaje de validación 400, con el mismo formato { "error": "..." }.

Rechazo por tamaño del servicio de predicción — 413 Payload Too Large​

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

Cuota excedida — 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."
  }
}

Los planes de pago usan la misma estructura de respuesta, con límites, fechas de reinicio y recomendaciones de mejora específicos de cada plan.

La cuota cambió durante el procesamiento — 400 Bad Request​

La cuota se comprueba antes de la predicción y se descuenta cuando el procesamiento termina correctamente. Si otra solicitud simultánea consume la cuota restante entre ambas operaciones, el descuento puede devolver:

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

Error de procesamiento — 500 Internal Server Error​

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

Si el servicio de predicción devuelve un error interno más específico, su mensaje puede aparecer en el campo error, con la misma estructura de respuesta.

Notas​

  • Envía una sola imagen mediante el campo multipart llamado file.
  • La solicitud solo se descuenta si el servicio de predicción responde correctamente.
  • probability es un porcentaje entero, no un decimal entre 0 y 1.
  • Un arreglo detections vacío es un resultado correcto, no un error.
  • Las predicciones son estimaciones del modelo; no deben considerarse atributos de identidad verificados.