Aller au contenu principal

API d’estimation de l’âge par image

Envoyez une image pour détecter les personnes et les visages, puis estimer leur âge avec un pourcentage de confiance pour chaque détection.

URL de base​

https://api.genderrecognition.com

Point de terminaison​

POST /v1/image-gender/api/age

En-têtes​

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

Corps de la requête​

ChampTypeObligatoireDescription
filefileYesImage JPEG, PNG, WebP, BMP ou GIF. Taille maximale : 10 Mo.

Exemple​

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

Réponse réussie​

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

Champs de la réponse​

ChampTypeDescription
successbooleantrue si l’image a été traitée avec succès.
detectionsarrayUne entrée pour chaque visage détecté avec une estimation de l’âge.
detections[].agenumberÂge estimé pour cette détection. La valeur peut être décimale.
detections[].probabilityintegerPourcentage de confiance, de 0 à 100. See note below.
remainingRequestsintegerNombre de requêtes API restantes après déduction de cette requête réussie.

probability correspond au niveau de confiance du modèle dans la classification du genre de cette détection. Cette valeur est réutilisée comme niveau de confiance affiché : le modèle ne calcule pas de score distinct pour l’estimation de l’âge. Une valeur probability élevée indique que le modèle est sûr de son estimation du genre, et non que la valeur age est exacte.

Seules les détections pour lesquelles le modèle a établi une classification du genre avec suffisamment de confiance sont incluses. Un visage dont la prédiction est ambiguë ou impossible à associer est omis de detections, même si une personne ou un visage a bien été détecté visuellement. Le tableau detections peut donc contenir moins d’éléments que l’image ne comporte de visages.

Aucune détection​

Le traitement peut réussir sans trouver de visage pour lequel le modèle dispose d’une prédiction suffisamment fiable. Une requête est tout de même consommée :

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

Réponses d’erreur​

Clé API manquante — 401 Unauthorized​

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

Clé API invalide — 404 Not Found​

{
  "error": "Invalid API key"
}

Erreur du service d’authentification — 500 Internal Server Error​

{
  "error": "Internal server error"
}

Fichier manquant — 400 Bad Request​

Le champ multipart doit s’appeler file.

{
  "error": "No file uploaded"
}

Champ multipart inattendu — 400 Bad Request​

Cette réponse est renvoyée si le fichier est envoyé dans un champ autre que file, ou si plusieurs fichiers sont envoyés dans le champ prévu pour un seul fichier.

{
  "error": "Unexpected field"
}

Type de fichier invalide — 400 Bad Request​

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

Fichier trop volumineux — 400 Bad Request​

{
  "error": "File too large"
}

Image impossible à décoder — 400 Bad Request​

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

Si l’image envoyée est invalide, le service de prédiction peut également renvoyer un autre message de validation 400, au même format { "error": "..." }.

Fichier trop volumineux pour le service de prédiction — 413 Payload Too Large​

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

Quota dépassé — 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."
  }
}

Les offres payantes utilisent la même structure de réponse, avec des limites, des dates de réinitialisation et des conseils de mise à niveau propres à l’offre.

Quota modifié pendant le traitement — 400 Bad Request​

Le quota est vérifié avant la prédiction et déduit après le traitement réussi. Si une autre requête simultanée consomme le quota restant entre ces deux étapes, la déduction peut renvoyer :

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

Échec du traitement — 500 Internal Server Error​

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

Si le service de prédiction en amont renvoie une erreur interne plus précise, son message peut apparaître dans le champ error, avec la même structure.

Remarques​

  • Envoyez une seule image dans le champ multipart nommé file.
  • Une requête n’est déduite qu’après le succès du service de prédiction.
  • age peut être une valeur décimale ; probability est un pourcentage entier, et non un nombre décimal compris entre 0 et 1.
  • probability indique le niveau de confiance de la classification du genre, et non celui de l’estimation de l’âge : aucun score de confiance propre à l’âge n’est fourni.
  • Un tableau detections vide correspond à un résultat réussi, et non à une erreur.
  • Les prédictions sont des estimations du modèle et ne doivent pas être considérées comme des attributs d’identité vérifiés.