Saltar al contenido principal

API de edad por imagen

Envía una imagen para detectar personas y rostros y estimar la edad con un porcentaje de confianza para cada detección.

URL base​

https://api.genderrecognition.com

Endpoint​

POST /v1/image-gender/api/age

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

Respuesta correcta​

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

Campos de respuesta​

CampoTipoDescripción
successbooleantrue when the image was processed successfully.
detectionsarrayUna entrada por cada rostro detectado con una predicción de edad.
detections[].agenumberEdad estimada para esta detección. Puede incluir decimales.
detections[].probabilityintegerPorcentaje de confianza de 0 a 100. See note below.
remainingRequestsintegerSolicitudes API restantes tras descontar esta solicitud completada correctamente.

probability refleja la confianza del modelo en la clasificación de género de esa detección. Este valor se reutiliza como nivel de confianza mostrado: el modelo no genera una puntuación de confianza independiente para la edad. Un valor alto de probability indica la certeza del modelo sobre el género de la persona, no sobre la precisión de age.

Solo se incluyen las detecciones en las que el modelo obtuvo una clasificación de género con suficiente confianza. Se omite de detections un rostro con una predicción de género ambigua o sin correspondencia, aunque se haya detectado visualmente a una persona o un rostro. Por ello, detections puede contener menos elementos que rostros haya en la imagen.

No se detectaron elementos​

El procesamiento puede completarse sin encontrar un rostro con una predicción fiable. 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 age 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.
  • age puede ser un valor decimal; probability es un porcentaje entero, no un valor decimal entre 0 y 1.
  • probability refleja la confianza de la clasificación de género, no la de la estimación de edad; no se proporciona una puntuación de confianza específica para la edad.
  • 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.