Utiliser GenderAPI.io V2 avec Python

Préparez un projet Python côté serveur

Ce guide appelle l’endpoint GenderAPI.io V2 https://api.genderapi.io/api/v2/gender avec une clé API Bearer. Utilisez Python 3.10 ou une version ultérieure et téléchargez genderapi_v2.py dans votre projet. L’exemple utilise urllib.request et json de la bibliothèque standard de Python ; aucun paquet pip n’est nécessaire.

Définissez GENDERAPI_API_KEY dans l’environnement de votre serveur. YOUR_API_KEY, dans l’exemple ci-dessous, n’est pas une clé valide. Ne placez pas vos vrais identifiants dans des fichiers versionnés, des notebooks partagés ou des applications côté client. Importer le module ou l’exécuter sans option de démonstration n’envoie aucune requête.

python3 --version
export GENDERAPI_API_KEY="YOUR_API_KEY"

• Télécharger genderapi_v2.py →
• Vérifier votre clé avec l’endpoint de consommation gratuit →

Envoyez une requête explicite limitée au jeu de données

Enregistrez le code suivant sous single.py à côté du fichier téléchargé, puis exécutez python3 single.py. Le module d’aide envoie type: name, value: Alice et options.ai_mode: off en JSON. Lisez l’estimation dans data et les informations de requête et de facturation dans meta.

Un appel réussi consomme 1 crédit, y compris pour un résultat unknown ; le nom d’exemple ne garantit pas une prédiction. make_item accepte name, email ou username et exige un mode d’IA explicite. N’ajoutez country que si vous disposez d’un contexte pertinent.

Le module d’aide exige une clé API hexadécimale de 24 caractères avant l’envoi. Cela valide le format, pas l’existence de la clé. Il rejette aussi les réponses réussies en mode d’essai par IP comme une incohérence d’accès ; ce contrôle a lieu après la réponse et ne peut pas annuler un crédit d’essai déjà consommé.

from genderapi_v2 import GenderAPIError, make_item, predict

try:
    response = predict(make_item("name", "Alice", ai_mode="off"))
except GenderAPIError as error:
    # Record a reference; do not log the whole error response.
    print("Request failed:", error.request_id)
    raise SystemExit(1)
else:
    result = response["data"]
    print(result["result_status"], result["gender"])
    print(result["confidence"], result["confidence_kind"])
    print(response["meta"]["usage"])

• Tous les champs des requêtes unitaires →

Conservez le résultat avec ses éléments de preuve

Une association déduite n’équivaut pas au genre déclaré par la personne. Conservez séparément la valeur d’origine, les éléments de preuve renvoyés et les informations fournies par la personne elle-même. unknown est un résultat valide : ne le transformez pas en une catégorie devinée dans votre application.

• Champs de réponse et résultats inconnus →
• Exactitude et confiance →
• Sources des données et profil du jeu de données →

Traitez un lot mixte en conservant l’identifiant de chaque ligne

GenderAPI.io V2 utilise POST https://api.genderapi.io/api/v2/gender/batch pour les lots mixtes : jusqu’à 50 éléments avec une clé de compte, ou 10 en mode d’essai par IP. Ces exemples exigent une clé de compte. Attribuez à chaque élément un id stable et unique ainsi qu’un mode d’IA explicite. Un lot peut combiner des noms, des adresses e-mail et des noms d’utilisateur, avec un contexte country facultatif pour chaque élément.

Lisez chaque élément de data ainsi que le récapitulatif meta.summary. Une réponse HTTP 200 peut contenir des erreurs d’éléments ; un lot entièrement en échec peut renvoyer une réponse Problem de premier niveau contenant les résultats. Les résultats unknown réussis sont comptés dans succeeded. index et id permettent de rattacher chaque résultat à la bonne ligne source.

Pour les traitements volumineux, découpez les entrées en groupes de 50 éléments au maximum et envoyez-les d’abord l’un après l’autre. Enregistrez chaque réponse et sa consommation avant de passer au groupe suivant. Arrêtez-vous en cas d’erreur de transport, d’accès au compte ou de facturation non confirmée, et rapprochez l’état du groupe en cours. N’ajoutez de la concurrence qu’après avoir vérifié les limites de votre compte ; la taille maximale d’un lot ne garantit pas un débit.

from genderapi_v2 import GenderAPIError, make_item, predict_batch

items = [
    make_item("name", "Alice", ai_mode="off", item_id="row-1"),
    make_item("email", "alex@example.com", ai_mode="off", item_id="row-2"),
    make_item("username", "sample_handle", ai_mode="off", item_id="row-3"),
]
try:
    response = predict_batch(items)
except GenderAPIError as error:
    # Retained error.response can include batch results and billing.
    print("Batch needs review:", error.request_id)
    raise SystemExit(1)
else:
    for item in response["data"]:
        if "error" in item:
            print(item["id"], "failed", item["error"]["code"])
        else:
            result = item["data"]
            print(item["id"], result["result_status"], result["gender"])
    print(response["meta"]["summary"])
    print(response["meta"]["usage"])
    if response["meta"]["summary"]["failed"]:
        raise SystemExit(2)

• Entrées, résultats et facturation des lots →

Choisissez quand utiliser l’IA

forceToGenderize est facultatif pour les noms, les adresses e-mail et les noms d’utilisateur. Lorsqu’il est activé, omettez ai_mode ou utilisez fallback : la combinaison avec off ou always renvoie une erreur 422. Un solde de départ positif suffit pour lancer une requête, même si le débit final fait passer le solde en dessous de zéro.

L’analyse des pseudonymes peut renvoyer un genre avec name: null. Elle peut aussi renvoyer unknown. Ni le repli IA standard ni l’analyse des pseudonymes ne garantissent une réponse correcte ou non nulle.

Le module d’aide Python exige toujours ai_mode. Pour autoriser l’inférence à partir de surnoms, utilisez make_item('username', 'prenses', ai_mode='fallback', force_to_genderize=True). Le module convertit force_to_genderize en champ JSON forceToGenderize.

• Options d’IA et analyse des pseudonymes →
• Crédits et consommation →

Décidez de la marche à suivre après un échec

Les exemples envoient chaque opération une seule fois. Ils ne relancent jamais automatiquement : un nouvel envoi est une nouvelle opération facturable. Un délai dépassé ou une erreur de connexion signifie que le client n’a pas reçu de réponse complète ; cela ne prouve pas que le serveur s’est arrêté ni qu’aucun crédit n’a été débité.

Conservez le request_id renvoyé et l’état de facturation avec l’enregistrement de votre traitement. L’objet d’erreur conserve la réponse pour une inspection contrôlée, mais il peut contenir l’entrée d’origine : n’écrivez pas l’objet complet, la réponse ni la clé API dans les journaux courants.

• Problem Details et décisions de nouvelle tentative →
• Crédits et confirmation de facturation →

Comprenez le comportement réseau de cet exemple

Le délai de 10 secondes d’urllib s’applique aux opérations de socket bloquantes ; ce n’est pas une limite garantie pour la durée totale de la requête. L’exemple désactive les redirections HTTP, analyse les réponses JSON réussies et conserve les réponses HTTP Problem. Il ne relance jamais automatiquement.

Les tests locaux utilisent des réponses de transport simulées pour les succès, les résultats unknown, les lots partiels, l’accès au compte et les échecs. Ils vérifient la logique de contrôle de l’exemple ; ils ne mesurent ni la disponibilité de l’API en production, ni la précision des inférences, ni la latence. Chaque commande de démonstration explicite ci-dessous envoie une requête facturable distincte.

python3 genderapi_v2.py --demo single
# Run separately to submit another billable sample batch:
python3 genderapi_v2.py --demo batch

• Référence Python urllib.request →
• Référence Python HTTPError →

Questions fréquentes