# Utiliser GenderAPI.io V2 avec JavaScript et Node.js

> Appelez GenderAPI.io V2 depuis Node.js avec fetch natif. Téléchargez un module ES pour les requêtes unitaires et les lots mixtes, les réponses data/meta et les erreurs liées aux crédits.

Canonical HTML: https://www.genderapi.io/fr/integrations/javascript

Last reviewed: 2026-09-28

## Environnement d’exécution et exemple téléchargeable

Node.js 22+. Exemple d’intégration HTTP téléchargeable ; il ne s’agit pas d’un SDK publié séparément.

- [Télécharger l’exemple](https://www.genderapi.io/examples/v2/genderapi-v2.mjs)

## Gardez l’intégration sur votre serveur Node.js

Ce guide appelle l’endpoint GenderAPI.io V2 https://api.genderapi.io/api/v2/gender avec une clé API Bearer. Utilisez Node.js 22 ou une version ultérieure et téléchargez genderapi-v2.mjs dans votre projet. Ce module ES utilise fetch et AbortSignal.timeout intégrés ; aucun paquet npm n’est nécessaire. L’extension .mjs permet de l’importer depuis un autre module ES sans modifier package.json.

Définissez GENDERAPI_API_KEY dans l’environnement du serveur. Ne l’intégrez pas dans du JavaScript React, Vue ou exécuté dans le navigateur. Laissez votre propre serveur authentifier les utilisateurs de l’application et appeler GenderAPI.io. YOUR_API_KEY, dans l’exemple ci-dessous, n’est pas une clé valide ; importer le module ou l’exécuter sans option d’exécution explicite n’envoie aucune requête.

**Configurer votre environnement Node.js**

```bash
node --version
export GENDERAPI_API_KEY="YOUR_API_KEY"
```

- [Télécharger genderapi-v2.mjs](https://www.genderapi.io/examples/v2/genderapi-v2.mjs)
- [Vérifier votre clé avec l’endpoint de consommation gratuit](https://www.genderapi.io/fr/docs/v2/authentication#environment-setup)

## Envoyez une requête POST JSON avec une politique d’IA explicite

Enregistrez ce code sous single.mjs à côté du module téléchargé, puis exécutez node single.mjs. Il envoie les champs V2 type et value avec options.ai_mode: off. Lisez l’estimation dans response.data et les informations de requête et de facturation dans response.meta.

Une recherche terminée coûte 1 crédit, même lorsque gender vaut null ; le nom d’exemple ne garantit pas un résultat particulier.

Le module d’aide exige un mode d’IA explicite et une clé hexadécimale de 24 caractères, puis vérifie que meta.access.mode vaut api_key. Une réponse d’essai réussie déclenche une erreur d’incohérence d’accès au lieu de poursuivre silencieusement. Le serveur peut déjà avoir consommé un crédit d’essai avant que le module ne détecte cette incohérence.

**Recherche unitaire en Node.js**

```javascript
import { predict, GenderAPIError } from "./genderapi-v2.mjs";

try {
  const response = await predict({
    type: "name", value: "Alice", options: { ai_mode: "off" },
  });
  const result = response.data;
  console.log(result.result_status, result.gender);
  console.log(result.confidence, result.confidence_kind);
  console.log(response.meta.usage);
} catch (error) {
  if (!(error instanceof GenderAPIError)) throw error;
  // Do not log error.body: it can include the submitted value.
  console.error("Request failed:", error.code, error.requestId);
  process.exitCode = 1;
}
```

- [Tous les champs des requêtes unitaires](https://www.genderapi.io/fr/docs/v2/request-parameters)

## 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.

| Champ | Comment l’utiliser |
| --- | --- |
| `data.gender / data.result_status` | Utilisez male ou female uniquement lorsque le résultat est identified. Conservez la valeur JSON null lorsqu’il est unknown. |
| `data.name / data.match` | Vérifiez le nom renvoyé et le candidat retenu. Une correspondance partielle ne prouve pas que la valeur appartient à une personne portant ce prénom. |
| `data.confidence / data.confidence_kind` | La confiance est exprimée entre 0 et 1, ou vaut null. observed_frequency provient des effectifs enregistrés ; model_reported est un score fourni par l’IA. Évaluez vos seuils séparément pour chaque type. |
| `data.source / data.sample_count` | Distinguez dataset, ai et none. Les résultats de l’IA n’ont pas d’effectif enregistré. La taille de l’échantillon n’est pas une mesure d’exactitude. |
| `meta.access.mode` | Vérifiez la valeur api_key pour une intégration liée à un compte. Si la clé est absente ou non reconnue, l’essai partagé par IP peut être utilisé à la place. |
| `meta.usage` | Lisez charged_credits et billing_status. Un résultat unknown obtenu avec succès est facturé. L’absence de réponse ne prouve pas que la requête était gratuite. |

- [Champs de réponse et résultats inconnus](https://www.genderapi.io/fr/docs/v2/responses)
- [Exactitude et confiance](https://www.genderapi.io/fr/accuracy-methodology)
- [Sources des données et profil du jeu de données](https://www.genderapi.io/fr/data-provenance)

## 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.

**Recherche par lot en Node.js**

```javascript
import { predictBatch, GenderAPIError } from "./genderapi-v2.mjs";

const items = [
  { id: "row-1", type: "name", value: "Alice", options: { ai_mode: "off" } },
  { id: "row-2", type: "email", value: "alex@example.com", options: { ai_mode: "off" } },
  { id: "row-3", type: "username", value: "sample_handle", options: { ai_mode: "off" } },
];
try {
  const response = await predictBatch(items);
  for (const item of response.data) {
    if (item.error) {
      console.log(item.id, "failed", item.error.code);
    } else {
      console.log(item.id, item.data.result_status, item.data.gender);
    }
  }
  console.log(response.meta.summary, response.meta.usage);
  if (response.meta.summary.failed > 0) process.exitCode = 2;
} catch (error) {
  if (!(error instanceof GenderAPIError)) throw error;
  // error.body can retain an all-failed batch and billing details.
  console.error("Batch needs review:", error.code, error.requestId);
  process.exitCode = 1;
}
```

- [Entrées, résultats et facturation des lots](https://www.genderapi.io/fr/docs/v2/batch)

## 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 JavaScript exige toujours options.ai_mode. Pour l’inférence à partir de surnoms, envoyez forceToGenderize: true avec options: { ai_mode: 'fallback' }.

| Option de la requête | Comportement | Crédits par requête aboutie |
| --- | --- | --- |
| options.ai_mode: off | Interroge uniquement le jeu de données. | 1 crédit, unknown compris |
| options.ai_mode: fallback | Interroge d’abord le jeu de données, puis l’IA standard si aucun genre n’est trouvé. C’est le mode par défaut des requêtes individuelles. | 1 crédit au total, repli IA compris |
| options.ai_mode: always | Interroge directement l’IA. | 2 crédits |
| forceToGenderize: true | Interroge d’abord le jeu de données ; si aucun genre n’est trouvé, autorise l’IA à interpréter le sens d’un surnom ou d’un pseudonyme personnel, même sans prénom réel. | 1 crédit si le jeu de données résout la requête ; 2 au total si l’IA est utilisée |

- [Options d’IA et analyse des pseudonymes](https://www.genderapi.io/fr/docs/v2/ai-options)
- [Crédits et consommation](https://www.genderapi.io/fr/docs/v2/credits-and-usage)

## 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.

| Situation | Décision de l’application |
| --- | --- |
| unknown réussi | Conservez null, reason et usage. Il s’agit d’un résultat facturable terminé, pas d’une ligne en échec à relancer automatiquement. |
| Erreur de validation 422 | Corrigez l’entrée signalée par les champs Problem Details avant d’envoyer une nouvelle requête. |
| 401 / 403 | Vérifiez l’accès au compte ou les crédits disponibles. Renvoyer plusieurs fois la même requête ne résoudra pas la cause. |
| 429 | Respectez Retry-After s’il est présent. Vérifiez l’erreur et l’état de facturation, puis planifiez délibérément une tentative ultérieure. |
| Erreur réseau, délai dépassé ou réponse illisible | Notez que le résultat et le débit ne sont pas confirmés. Rapprochez l’état avant tout nouvel envoi ; le client ne peut pas annuler un traitement déjà terminé côté serveur. |
| billing_status: unconfirmed | charged_credits et remaining_credits peuvent valoir null. Contactez le support avec le request_id avant toute nouvelle tentative ; ne remplacez pas null par zéro. |
| Échec de certains éléments du lot | Enregistrez d’abord les éléments terminés. Examinez les éléments en échec et leur facturation ; renvoyez uniquement les échecs concernés, pas le lot entier. |

- [Problem Details et décisions de nouvelle tentative](https://www.genderapi.io/fr/docs/v2/errors-and-retries)
- [Crédits et confirmation de facturation](https://www.genderapi.io/fr/docs/v2/credits-and-usage)

## Comprenez le délai de fetch et les contrôles de réponse

Le délai par défaut est de 10 000 millisecondes via AbortSignal.timeout, lecture du corps de la réponse comprise. L’interruption côté client ne prouve pas que le traitement ou la facturation se sont arrêtés côté serveur. Le module désactive les redirections, distingue les échecs HTTP des réponses illisibles et ne relance jamais automatiquement.

Les tests de transport simulé couvrent les réponses réussies, les résultats unknown, les lots partiels, les replis d’identifiants et les erreurs. Ils n’exigent aucune prédiction réelle ni aucune opération sur les crédits ; ils ne mesurent ni la disponibilité ni la précision en production. Chaque commande de démonstration explicite ci-dessous envoie une requête facturable distincte.

**Démonstrations Node.js facultatives et explicites**

```bash
node genderapi-v2.mjs --run-single
# Run separately to submit another billable sample batch:
node genderapi-v2.mjs --run-batch
```

- [Référence Node.js fetch](https://nodejs.org/api/globals.html#fetch)
- [Référence Node.js AbortSignal.timeout](https://nodejs.org/api/globals.html#static-method-abortsignaltimeoutdelay)

## Puis-je coller ce code dans du JavaScript exécuté dans le navigateur ?

Gardez-le sur votre serveur. Un bundle exécuté dans le navigateur expose la clé API à ses utilisateurs. Depuis le navigateur, appelez votre propre backend authentifié et laissez ce backend envoyer la requête à GenderAPI.io.

## Un résultat inconnu consomme-t-il des crédits ?

Oui. Une recherche standard réussie coûte 1 crédit, même lorsque gender vaut null. Le repli IA standard est inclus dans ce crédit. Le mode always coûte 2 crédits ; forceToGenderize coûte 1 crédit lorsque le jeu de données résout la requête, ou 2 lorsque l’IA intervient.

## Cet exemple relance-t-il une requête en échec ?

Non. Chaque nouvelle requête est une opération indépendante. Examinez l’erreur, les résultats par élément et l’état de facturation avant de décider d’un nouvel envoi. L’absence de réponse ne prouve pas que la tentative précédente était gratuite.

## Dois-je installer un paquet ?

Non. Téléchargez l’exemple directement depuis ce guide GenderAPI.io. Il n’a aucune dépendance d’exécution tierce et n’est pas un SDK publié séparément sur pip ou npm. Relisez-le et adaptez-le à votre application ; la documentation GenderAPI.io V2 reste la référence du contrat d’API.

## Documentation de référence

- [Authentification GenderAPI.io V2](https://www.genderapi.io/fr/docs/v2/authentication)
- [Champs de réponse V2](https://www.genderapi.io/fr/docs/v2/responses)
- [Résultats et limites des lots](https://www.genderapi.io/fr/docs/v2/batch)
- [Référence des erreurs et des nouvelles tentatives](https://www.genderapi.io/fr/docs/v2/errors-and-retries)