Aller au contenu principal

API de détection du genre par image

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

URL de base​

https://api.genderrecognition.com

Point de terminaison​

POST /v1/image-gender/api

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

Réponse réussie​

{
  "success": true,
  "detections": [
    {
      "category": "face",
      "gender": "female",
      "probability": 99
    },
    {
      "category": "person",
      "gender": "male",
      "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é ou personne non associée à un visage, avec une prédiction.
detections[].categoryface | personface lorsqu’un visage est associé à une personne ; person lorsqu’on ne dispose que du corps.
detections[].gendermale | femaleGenre estimé pour cette détection.
detections[].probabilityintegerPourcentage de confiance, de 0 à 100.
remainingRequestsintegerNombre de requêtes API restantes après déduction de cette requête réussie.

Lorsqu’un visage et un corps appartiennent à la même personne, la réponse contient une seule détection face, et non des entrées distinctes pour le visage et la personne.

Aucune détection​

Le traitement peut réussir sans trouver de visage ou de personne exploitable. 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 gender 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.
  • probability est un pourcentage entier, et non un nombre décimal entre 0 et 1.
  • 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.