# Estimer le genre à partir de noms chinois

> Testez des noms chinois avec GenderAPI.io V2. Comprenez l’effet des éléments courts, de la segmentation du nom complet, des caractères d’origine et du contexte CN sur les résultats du jeu de données et de l’IA.

Canonical HTML: https://www.genderapi.io/fr/determine-gender-from-chinese-names

Last reviewed: 2026-09-28

## Distinguez la saisie Unicode de la segmentation du nom

Vous pouvez envoyer un nom chinois en texte Unicode, sans le convertir en alphabet latin. La recherche actuelle interroge des éléments normalisés ; elle ne sépare pas automatiquement le nom de famille et le prénom d’un nom complet chinois écrit sans espace. 王静怡 constitue donc un seul candidat, et non une recherche garantie de 静怡.

Pour les caractères chinois courants de ces exemples, les éléments d’un ou deux caractères sont écartés par le filtre actuel de candidats du jeu de données. Un prénom court peut être une saisie valide sans produire de candidat. Le repli IA standard peut encore évaluer la valeur d’origine envoyée ; le mode jeu de données seul conserve un résultat unknown.

La normalisation Unicode NFKC n’assure pas de conversion générale entre chinois simplifié et traditionnel, et ne relie pas une orthographe latine à un nom chinois d’origine unique. Conservez l’écriture envoyée et vérifiez la correspondance renvoyée. La position du nom de famille, l’écriture ou la romanisation ne suffisent pas à déduire le genre ou le pays d’une personne.

| Exemple d’entrée | Ce qu’il représente | Points à vérifier |
| --- | --- | --- |
| `王静怡` | Nom complet sans espace | Un seul candidat pour le jeu de données. L’analyseur actuel ne sépare pas le nom de famille. |
| `静怡` | Prénom de deux caractères | Écarté par le filtre de longueur des candidats ; le repli IA peut évaluer la valeur d’origine. |
| `王 静怡` | Éléments courts séparés | Ajouter un espace ne contourne pas le filtre de longueur. Les deux éléments de l’exemple sont trop courts pour la recherche dans le jeu de données. |
| `Wang Jingyi` | Saisie en alphabet latin | Traitée comme une valeur distincte, découpée en ses propres éléments. Rien ne garantit qu’elle corresponde aux caractères d’origine ou au même enregistrement. |

## Choisissez le contexte pays CN à bon escient

La démonstration envoie country: CN (Chine). L’API ne choisit pas ce pays à partir de l’écriture du nom. Dans votre intégration, utilisez un contexte pays connu et pertinent, ou omettez country. Ne transformez pas cet exemple en valeur par défaut pour toutes vos fiches.

Pour chaque candidat, la recherche privilégie l’enregistrement propre au pays s’il existe et, à défaut, consulte l’enregistrement global. Elle retient ensuite le candidat disponible ayant l’effectif enregistré le plus élevé. Vérifiez la portée réelle de la correspondance avec data.match.scope et data.match.country. Un enregistrement de pays à effectifs égaux n’est pas remplacé automatiquement par le résultat global ; si fallback est activé, l’IA peut être utilisée à la place.

data.input.country décrit le contexte envoyé dans la requête. data.country et data.country_source décrivent une association de pays renvoyée et son origine. Ce sont des champs différents ; ils ne prouvent ni la citoyenneté, ni l’origine ethnique, ni la résidence.

- [Contexte pays et correspondances](https://www.genderapi.io/fr/docs/v2/gender-from-name#country-evidence-workflow)

## Envoyez une requête de nom V2 depuis votre application

Définissez GENDERAPI_API_KEY avec votre clé existante et exécutez l’exemple sur votre serveur. La requête active explicitement le repli IA standard. Elle illustre le format d’une requête, pas une exactitude mesurée ni une couverture démontrée. Pour utiliser uniquement le jeu de données, choisissez options.ai_mode: off.

Exécutez ces exemples sur votre serveur. Définissez GENDERAPI_API_KEY dans l'environnement du processus avec votre clé API existante. Vérifiez que meta.access.mode vaut api_key : une clé non reconnue peut basculer vers l'essai par IP.

Chaque requête de prédiction est une nouvelle opération facturable, y compris les nouvelles tentatives. Ces exemples ne réessaient pas automatiquement. Vérifiez le statut de facturation avant d'envoyer une autre requête.

Pour les réponses JSON HTTP 4xx et 5xx, les exemples conservent le corps de l'erreur et renvoient un code de sortie non nul. Vérifiez code, action et meta.usage.billing_status avant de réessayer.

**cURL**

cURL 7.76+ dans un shell POSIX. À exécuter dans votre terminal.

```bash
curl --silent --show-error --fail-with-body --max-time 30 \
  --request POST 'https://api.genderapi.io/api/v2/gender' \
  --header "Authorization: Bearer ${GENDERAPI_API_KEY:?Set GENDERAPI_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "name",
  "value": "王静怡",
  "country": "CN",
  "options": {
    "ai_mode": "fallback"
  }
}'
```

**JavaScript / Node.js**

Node.js 22+ ; fetch intégré. Enregistrez sous example.mjs et exécutez node example.mjs.

```javascript
// Server-side Node.js. Save as example.mjs.
const apiKey = process.env.GENDERAPI_API_KEY;
if (!apiKey) throw new Error("Set GENDERAPI_API_KEY");
const body = {
  "type": "name",
  "value": "王静怡",
  "country": "CN",
  "options": {
    "ai_mode": "fallback"
  }
};

const response = await fetch("https://api.genderapi.io/api/v2/gender", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(body),
  signal: AbortSignal.timeout(30_000),
  redirect: "error",
});
const raw = await response.text();
if (!(response.headers.get("content-type") ?? "").includes("json")) {
  throw new Error(`HTTP ${response.status}: expected JSON; request ID ${response.headers.get("x-request-id")}`);
}
const result = JSON.parse(raw); // Also accepts application/problem+json.
if (!response.ok) {
  console.error(`HTTP ${response.status}`, result);
  process.exitCode = 1; // A retry is a new operation; inspect billing first.
} else {
  console.log(JSON.stringify(result, null, 2));
  // For batches, inspect every item: HTTP 200 may contain item errors.
}
```

**Python**

Python 3.10+ ; bibliothèque standard. Enregistrez sous example.py et exécutez python3 example.py.

```python
import json
import os
import sys
import urllib.error
import urllib.request

api_key = os.environ.get("GENDERAPI_API_KEY")
if not api_key:
    raise RuntimeError("Set GENDERAPI_API_KEY")
body = json.loads("{\"type\":\"name\",\"value\":\"王静怡\",\"country\":\"CN\",\"options\":{\"ai_mode\":\"fallback\"}}")

class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        return None

request = urllib.request.Request(
    "https://api.genderapi.io/api/v2/gender",
    method="POST",
    data=json.dumps(body).encode("utf-8"),
    headers={
        "Authorization": "Bearer " + api_key,
        "Content-Type": "application/json",
    },
)
opener = urllib.request.build_opener(NoRedirect())
try:
    response = opener.open(request, timeout=30)
except urllib.error.HTTPError as error:
    response = error  # Keep the Problem Details body on non-2xx responses.
with response:
    status = response.status
    raw = response.read().decode("utf-8")
    if "json" not in response.headers.get("Content-Type", ""):
        raise RuntimeError(f"HTTP {status}: expected a JSON response")
    result = json.loads(raw)
print(json.dumps(result, indent=2), file=sys.stderr if status >= 300 else sys.stdout)
if not 200 <= status < 300:
    sys.exit(1)  # Inspect code, action and billing before retrying.
# For batches, inspect every item even when HTTP status is 200.
```

**PHP**

PHP 8+ avec l'extension cURL. Enregistrez sous example.php et exécutez php example.php.

```php
<?php
$apiKey = getenv('GENDERAPI_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set GENDERAPI_API_KEY');
}
$body = json_decode('{"type":"name","value":"王静怡","country":"CN","options":{"ai_mode":"fallback"}}', true, 512, JSON_THROW_ON_ERROR);

$ch = curl_init('https://api.genderapi.io/api/v2/gender');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_FOLLOWLOCATION => false,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($body, JSON_THROW_ON_ERROR),
]);
$raw = curl_exec($ch);
if ($raw === false) {
    throw new RuntimeException(curl_error($ch));
}
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$contentType = curl_getinfo($ch, CURLINFO_CONTENT_TYPE) ?: '';
curl_close($ch);
if (strpos($contentType, 'json') === false) {
    throw new RuntimeException("HTTP $status: expected a JSON response");
}
$result = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
$output = json_encode($result, JSON_PRETTY_PRINT | JSON_THROW_ON_ERROR) . PHP_EOL;
if ($status < 200 || $status >= 300) {
    fwrite(STDERR, $output); // Preserve the Problem Details body.
    exit(1);
}
echo $output;
// For batches, inspect every item; HTTP 200 can contain item errors.
```

**Java**

Java 17+ ; client HTTP standard. Enregistrez sous GenderApiExample.java et exécutez java GenderApiExample.java.

```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.time.Duration;

public class GenderApiExample {
    private static String requiredEnv(String name) {
        String value = System.getenv(name);
        if (value == null || value.isBlank()) throw new IllegalStateException("Set " + name);
        return value;
    }

    public static void main(String[] args) throws Exception {
        String apiKey = requiredEnv("GENDERAPI_API_KEY");
        String body = "{\"type\":\"name\",\"value\":\"王静怡\",\"country\":\"CN\",\"options\":{\"ai_mode\":\"fallback\"}}";
        HttpClient client = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(10))
            .followRedirects(HttpClient.Redirect.NEVER)
            .build();
        HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.genderapi.io/api/v2/gender"))
            .timeout(Duration.ofSeconds(30))
            .header("Authorization", "Bearer " + apiKey)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body, StandardCharsets.UTF_8))
            .build();
        HttpResponse<String> response = client.send(request,
            HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8));
        if (!response.headers().firstValue("content-type").orElse("").contains("json")) {
            throw new IllegalStateException("HTTP " + response.statusCode() + ": expected JSON");
        }
        // JSON text; parse with your application's JSON library when integrating.
        if (response.statusCode() < 200 || response.statusCode() >= 300) {
            System.err.println(response.body()); // Includes Problem Details.
            System.exit(1);
        }
        System.out.println(response.body());
        // For batches, inspect each item's data or error, including on HTTP 200.
    }
}
```

**C# / .NET**

Application console .NET 8+. Utilisez-le comme Program.cs dans un projet console, puis exécutez dotnet run.

```csharp
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

string RequiredEnv(string name) =>
    !string.IsNullOrWhiteSpace(Environment.GetEnvironmentVariable(name))
        ? Environment.GetEnvironmentVariable(name)!
        : throw new InvalidOperationException($"Set {name}");

var apiKey = RequiredEnv("GENDERAPI_API_KEY");
using var handler = new HttpClientHandler { AllowAutoRedirect = false };
using var client = new HttpClient(handler) { Timeout = TimeSpan.FromSeconds(30) };
using var request = new HttpRequestMessage(HttpMethod.Post, "https://api.genderapi.io/api/v2/gender");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", apiKey);
request.Content = new StringContent("{\"type\":\"name\",\"value\":\"王静怡\",\"country\":\"CN\",\"options\":{\"ai_mode\":\"fallback\"}}", Encoding.UTF8, "application/json");

using var response = await client.SendAsync(request);
var raw = await response.Content.ReadAsStringAsync();
if (!(response.Content.Headers.ContentType?.MediaType?.Contains("json") ?? false))
    throw new InvalidOperationException($"HTTP {(int)response.StatusCode}: expected JSON");
using var result = JsonDocument.Parse(raw);
if (!response.IsSuccessStatusCode)
{
    Console.Error.WriteLine(result.RootElement); // Preserve Problem Details.
    Environment.ExitCode = 1;
}
else
{
    Console.WriteLine(result.RootElement);
    // For batches, inspect every item even on HTTP 200.
}
```

**Go**

Go 1.22+ ; bibliothèque standard. Enregistrez sous main.go et exécutez go run main.go.

```go
package main

import (
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "os"
    "strings"
    "time"
)

func requiredEnv(name string) string {
    value := os.Getenv(name)
    if value == "" { panic("Set " + name) }
    return value
}

func run() error {
    apiKey := requiredEnv("GENDERAPI_API_KEY")
    body := "{\"type\":\"name\",\"value\":\"王静怡\",\"country\":\"CN\",\"options\":{\"ai_mode\":\"fallback\"}}"
    request, err := http.NewRequest("POST", "https://api.genderapi.io/api/v2/gender", strings.NewReader(body))
    if err != nil { return err }
    request.Header.Set("Authorization", "Bearer " + apiKey)
    request.Header.Set("Content-Type", "application/json")
    client := &http.Client{
        Timeout: 30 * time.Second,
        CheckRedirect: func(req *http.Request, via []*http.Request) error {
            return http.ErrUseLastResponse
        },
    }
    response, err := client.Do(request)
    if err != nil { return err }
    defer response.Body.Close()
    raw, err := io.ReadAll(response.Body)
    if err != nil { return err }
    if !strings.Contains(response.Header.Get("Content-Type"), "json") || !json.Valid(raw) {
        return fmt.Errorf("HTTP %d: expected a JSON response", response.StatusCode)
    }
    if response.StatusCode < 200 || response.StatusCode >= 300 {
        return fmt.Errorf("HTTP %d: %s", response.StatusCode, raw)
    }
    fmt.Println(string(raw))
    // For batches, inspect every item even on HTTP 200.
    return nil
}

func main() {
    if err := run(); err != nil {
        fmt.Fprintln(os.Stderr, err) // Keep Problem Details for error handling.
        os.Exit(1)
    }
}
```

- [Paramètres des requêtes de noms](https://www.genderapi.io/fr/docs/v2/gender-from-name)
- [Configurez votre clé API](https://www.genderapi.io/fr/docs/v2/authentication)

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

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

| 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)

## Traitez une liste de noms sans perdre son contexte

Envoyez jusqu’à 50 éléments avec une clé API, ou 10 avec l’essai par IP, via POST /api/v2/gender/batch. Attribuez des id uniques et conservez la valeur d’origine de chaque ligne. Chaque élément peut avoir ses propres options de pays et d’IA ; omettez le pays lorsqu’il est inconnu.

Contrairement aux requêtes individuelles, dont le mode par défaut est fallback, les éléments d’un lot utilisent par défaut uniquement le jeu de données. Définissez options.ai_mode: fallback sur chaque élément qui nécessite l’IA. Examinez chaque résultat, même après un HTTP 200, conservez les résultats unknown et vérifiez les erreurs et la facturation avant tout nouvel envoi. Chaque élément standard abouti consomme 1 crédit ; une requête HTTP de lot ne correspond pas à un seul crédit d’estimation.

- [Exemples de lots et erreurs partielles](https://www.genderapi.io/fr/docs/v2/batch#batch-application-workflow)
- [Gérer les résultats unknown dans votre application](https://www.genderapi.io/fr/docs/v2/responses#application-decisions)

## Comprenez ce que vous envoyez

L’outil n’envoie la valeur saisie à GenderAPI.io que lorsque vous cliquez sur Analyser. Si l’IA intervient, le service d’inférence configuré reçoit type, value et le contexte pays envoyé. Pour une estimation fondée uniquement sur le jeu de données, utilisez options.ai_mode: off sans forceToGenderize dans votre intégration.

La Politique de confidentialité, l’accord de traitement des données et la liste des sous-traitants décrivent les conditions publiées. Le résultat est une association déduite : donnez la priorité aux informations fournies par la personne. Ne l’utilisez pas comme fondement de décisions ayant des conséquences importantes pour quelqu’un.

- [Politique de confidentialité](https://www.genderapi.io/fr/privacy-policy)
- [Accord de traitement des données](https://www.genderapi.io/fr/data-processing-agreement)
- [Liste des sous-traitants](https://www.genderapi.io/fr/subprocessors)

## Pourquoi un nom chinois de deux caractères peut-il renvoyer unknown en mode jeu de données seul ?

Le filtre actuel de candidats écarte les éléments dont la longueur de chaîne JavaScript est inférieure ou égale à deux. Avec les caractères chinois présentés ici, un nom de deux caractères est une saisie valide, mais ne devient pas un candidat du jeu de données. Le repli IA peut évaluer la valeur d’origine.

## V2 sépare-t-il automatiquement le nom de famille chinois du prénom ?

La recherche dans le jeu de données ne segmente pas un nom complet chinois écrit sans espace. L’IA peut déduire un nom à partir de la valeur complète, mais aucune des deux voies ne garantit que le prénom attendu sera retenu. Vérifiez source et match dans la réponse.

## Une évaluation indépendante de l’exactitude est-elle publiée pour ce groupe de noms ?

Cette page ne publie pas une telle évaluation. Accepter une saisie, afficher des effectifs enregistrés ou renvoyer un score de confiance ne constitue pas une mesure indépendante de l’exactitude. Consultez la méthodologie pour connaître les éléments disponibles et les mesures qui restent à publier.

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

Un résultat unknown abouti est facturé. Le mode standard jeu de données ou fallback coûte 1 crédit au total. Avec forceToGenderize, la requête coûte 1 crédit si le jeu de données la résout, ou 2 au total si l’IA est utilisée, unknown compris. Les erreurs suivent des règles de facturation distinctes ; consultez meta.usage.