# Determinare il genere da nomi cinesi

> Prova i nomi cinesi con GenderAPI.io V2. Scopri come parti brevi, suddivisione dei nomi completi, caratteri originali e contesto CN influiscono sui risultati del set di dati e dell'IA.

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

Last reviewed: 2026-09-28

## Distinguere tra input Unicode e suddivisione dei nomi completi

Puoi inviare un nome cinese come testo Unicode senza convertirlo prima in caratteri latini. La ricerca attuale controlla parti normalizzate; un nome completo cinese scritto senza spazi non viene suddiviso automaticamente in cognome e nome proprio. 王静怡 è quindi un unico candidato e non una ricerca garantita di 静怡.

Per i caratteri cinesi comuni degli esempi, l'attuale filtro dei candidati del set di dati salta le parti di uno o due caratteri. Un nome proprio breve può essere un input valido e comunque non produrre alcun candidato. Il normale fallback IA può ancora interpretare il valore inviato originariamente; una richiesta basata solo sul set di dati mantiene il risultato sconosciuto.

La normalizzazione Unicode NFKC non offre una conversione generale tra cinese semplificato e tradizionale e non riconduce una grafia latina a un unico nome cinese originale. Conserva la grafia inviata e verifica la corrispondenza restituita. La posizione del cognome, l'alfabeto o la romanizzazione non bastano per trarre conclusioni sul genere o sul paese di una persona.

| Esempio di input | Che cosa rappresenta | Che cosa controllare |
| --- | --- | --- |
| `王静怡` | Nome completo senza spazi | Un solo candidato nel set di dati. L'analisi attuale non separa il cognome. |
| `静怡` | Nome proprio di due caratteri | Viene saltato dal limite di lunghezza del filtro dei candidati; il fallback IA può interpretare il valore originale. |
| `王 静怡` | Parti brevi separate | Uno spazio in più non aggira il limite di lunghezza. Entrambe le parti dell'esempio sono troppo brevi per la ricerca nel set di dati. |
| `Wang Jingyi` | Input in caratteri latini | Viene trattato come un valore a sé e suddiviso in parti proprie. Non è garantito che venga ricondotto ai caratteri originali o alla stessa voce. |

## Scegliere consapevolmente il contesto del paese CN

La demo invia country: CN (Cina). L'API non sceglie il paese in base all'alfabeto in cui è scritto il nome. Nella tua integrazione usa un contesto del paese noto e pertinente oppure ometti country. Non trasformare questo valore di esempio in un valore predefinito per tutti i record.

Per ogni candidato, la ricerca sceglie la voce specifica del paese, se esiste, e altrimenti considera la voce globale. Seleziona poi il candidato disponibile con il conteggio totale memorizzato più alto. L'ambito effettivo della corrispondenza è indicato in data.match.scope e data.match.country. Una voce specifica del paese con frequenze in parità non viene sostituita automaticamente dal risultato globale; se il fallback è attivo, può essere usata invece l'IA.

data.input.country descrive il contesto inviato nella richiesta. data.country e data.country_source descrivono l'associazione con un paese restituita e la sua origine. Sono campi diversi e non indicano né la cittadinanza né l'origine etnica né il luogo di residenza.

- [Contesto del paese e corrispondenze](https://www.genderapi.io/it/docs/v2/gender-from-name#country-evidence-workflow)

## Inviare una richiesta V2 per un nome dalla tua applicazione

Imposta GENDERAPI_API_KEY sulla tua chiave esistente ed esegui l'esempio sul tuo server. La richiesta attiva esplicitamente il normale fallback IA. Mostra il formato della richiesta, non un'accuratezza misurata o una copertura confermata. Per una previsione basata solo sul set di dati imposta options.ai_mode: off.

Esegui questi esempi sul tuo server. Imposta GENDERAPI_API_KEY nell'ambiente del processo con la tua chiave API esistente. Verifica che meta.access.mode sia api_key: una chiave non riconosciuta può portare alla prova IP.

Ogni richiesta di previsione è una nuova operazione a pagamento, anche quando è un nuovo tentativo. Questi esempi non riprovano automaticamente. Controlla lo stato dell'addebito prima di inviare un'altra richiesta.

Per le risposte JSON con HTTP 4xx e 5xx, il corpo dell'errore viene conservato e l'esempio termina con un codice di uscita diverso da zero. Controlla code, action e meta.usage.billing_status prima di riprovare.

**cURL**

cURL 7.76+ in una shell POSIX. Esegui nel terminale.

```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 integrato. Salva come example.mjs ed esegui 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+; libreria standard. Salva come example.py ed esegui 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+ con l'estensione cURL. Salva come example.php ed esegui 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. Salva come GenderApiExample.java ed esegui 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**

Applicazione console .NET 8+. Usalo come Program.cs in un progetto console, poi esegui 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+; libreria standard. Salva come main.go ed esegui 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)
    }
}
```

- [Parametri delle richieste per i nomi](https://www.genderapi.io/it/docs/v2/gender-from-name)
- [Configurare la chiave API](https://www.genderapi.io/it/docs/v2/authentication)

## Salvare il risultato insieme alle evidenze

Un'associazione dedotta non è il genere dichiarato da una persona. Salva separatamente l'input originale, le evidenze restituite e ciò che la persona ha dichiarato. Un risultato sconosciuto è un risultato valido e non dovrebbe diventare una categoria indovinata nella tua applicazione.

| Campo | Utilizzo |
| --- | --- |
| `data.gender / data.result_status` | Usa male o female solo con identified. In caso di risultato sconosciuto conserva il valore JSON null nativo. |
| `data.name / data.match` | Verifica il nome restituito e il candidato selezionato. Una corrispondenza su una sottostringa non dimostra che l'input appartenga a una persona con quel nome. |
| `data.confidence / data.confidence_kind` | La confidenza è su una scala da 0 a 1 oppure è null. observed_frequency si basa su frequenze memorizzate; model_reported è un valore fornito dall'IA. Valuta le soglie separatamente per ciascun tipo. |
| `data.source / data.sample_count` | Distingui tra dataset, ai e none. I risultati dell'IA non hanno una dimensione del campione memorizzata. Una dimensione del campione non è un valore di accuratezza misurato. |
| `meta.access.mode` | In un'integrazione con account verifica che venga riportato api_key. Le chiavi mancanti o non riconosciute possono invece usare la prova IP condivisa. |
| `meta.usage` | Leggi charged_credits e billing_status. Un risultato sconosciuto riuscito viene addebitato. Una risposta persa non dimostra che la richiesta sia stata gratuita. |

- [Campi della risposta e risultati sconosciuti](https://www.genderapi.io/it/docs/v2/responses)
- [Accuratezza e confidenza spiegate](https://www.genderapi.io/it/accuracy-methodology)
- [Fonti dei dati e profilo datato del database](https://www.genderapi.io/it/data-provenance)

## Decidere quando usare l'IA

forceToGenderize è facoltativo per nomi, indirizzi email e nomi utente. Quando è attivo, ometti ai_mode o usa fallback; off e always non possono essere combinati con questa opzione e restituiscono 422. Un saldo iniziale positivo basta per avviare una richiesta, anche se l'addebito finale rende il saldo negativo.

La modalità nickname può restituire un genere insieme a name: null. Può anche dare un risultato sconosciuto. Né il normale fallback IA né l'interpretazione dei nickname garantiscono una risposta corretta o un valore diverso da null.

| Opzione della richiesta | Comportamento | Crediti per una ricerca riuscita |
| --- | --- | --- |
| options.ai_mode: off | Usa solo il set di dati. | 1, anche per un risultato sconosciuto |
| options.ai_mode: fallback | Consulta prima il set di dati e poi usa la normale IA se non viene restituito un genere. È il valore predefinito per le richieste singole. | 1 in totale, fallback IA incluso |
| options.ai_mode: always | Usa direttamente l'IA. | 2 |
| forceToGenderize: true | Consulta prima il set di dati e poi lascia che l'IA interpreti un nickname personale o un alias, anche senza un vero nome proprio. | 1 per un risultato trovato nel set di dati; 2 in totale se viene usata l'IA |

- [Opzioni IA e interpretazione dei nickname](https://www.genderapi.io/it/docs/v2/ai-options)
- [Crediti e utilizzo](https://www.genderapi.io/it/docs/v2/credits-and-usage)

## Elaborare un elenco di nomi senza perdere il contesto

Invia fino a 50 elementi con una chiave API o 10 con la prova IP tramite POST /api/v2/gender/batch. Assegna a ogni elemento un id univoco e conserva il valore originale di ogni riga. Ogni elemento può avere opzioni proprie per il paese e l'IA; ometti il paese quando non è noto.

A differenza delle richieste singole, che usano il fallback per impostazione predefinita, gli elementi di un batch usano per impostazione predefinita solo il set di dati. Imposta options.ai_mode: fallback per ogni elemento che richiede l'IA. Controlla ogni risultato, anche dopo HTTP 200, conserva i risultati sconosciuti e verifica errori e addebito prima di un nuovo invio. Ogni elemento normale riuscito costa 1 credito; una richiesta HTTP batch non corrisponde a un credito per previsione.

- [Esempi di batch ed errori parziali](https://www.genderapi.io/it/docs/v2/batch#batch-application-workflow)
- [Gestire i risultati sconosciuti nell'applicazione](https://www.genderapi.io/it/docs/v2/responses#application-decisions)

## Sapere che cosa invii

La demo in tempo reale invia il valore inserito a GenderAPI.io solo quando lo invii tu. Se viene usata l'IA, type, value e il contesto del paese inviati vengono trasmessi al servizio configurato per le previsioni. Per una previsione basata solo sul set di dati, nella tua integrazione imposta options.ai_mode: off senza forceToGenderize.

L'informativa sulla privacy, l'accordo sul trattamento dei dati e l'elenco dei sub-responsabili descrivono le condizioni di trattamento pubblicate. Un risultato è un'associazione dedotta e ciò che una persona dichiara ha la precedenza. Non usarlo come base per decisioni con conseguenze rilevanti per una persona.

- [Informativa sulla privacy](https://www.genderapi.io/it/privacy-policy)
- [Accordo sul trattamento dei dati](https://www.genderapi.io/it/data-processing-agreement)
- [Sub-responsabili del trattamento](https://www.genderapi.io/it/subprocessors)

## Perché un nome proprio cinese di due caratteri può restare sconosciuto quando si usa solo il set di dati?

L'attuale filtro dei candidati salta le parti la cui lunghezza come stringa JavaScript è al massimo due. Per i caratteri cinesi mostrati qui, un nome proprio di due caratteri è un input valido, ma non diventa un candidato del set di dati. Il fallback IA può interpretare il valore originale.

## V2 separa automaticamente il cognome cinese dal nome proprio?

La ricerca nel set di dati non suddivide un nome completo cinese scritto senza spazi. L'IA può dedurre un nome proprio dall'intero valore, ma nessuna delle due strade garantisce che venga scelto il nome proprio previsto. Verifica source e match nella risposta.

## È stata pubblicata una valutazione indipendente dell'accuratezza per questo gruppo di nomi?

Questa pagina non pubblica una valutazione di questo tipo. L'accettazione dell'input, la visualizzazione delle frequenze memorizzate o la restituzione di un valore di confidenza non sono una misurazione indipendente dell'accuratezza. La metodologia indica quali dati sono disponibili e quali misurazioni non sono ancora state pubblicate.

## Un risultato senza previsione consuma crediti?

Un risultato sconosciuto riuscito viene addebitato. La modalità normale con il set di dati o con il fallback costa 1 credito in totale. Con forceToGenderize la richiesta costa 1 credito se il risultato proviene dal set di dati, oppure 2 in totale se viene usata l'IA, anche in caso di risultato sconosciuto. Per gli errori valgono regole di addebito separate; controlla meta.usage.