# Określanie płci na podstawie chińskich imion

> Wypróbuj chińskie imiona z GenderAPI.io V2. Dowiedz się, jak krótkie składniki, podział imienia i nazwiska, oryginalne znaki i kontekst CN wpływają na wyniki ze zbioru danych i AI.

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

Last reviewed: 2026-09-28

## Odróżnij dane wejściowe w Unicode od podziału imienia i nazwiska

Chińskie imię możesz wysłać jako tekst Unicode bez zamiany na alfabet łaciński. Obecne wyszukiwanie sprawdza znormalizowane składniki; nie dzieli automatycznie chińskiego imienia i nazwiska zapisanego bez spacji na nazwisko i imię. 王静怡 jest więc jednym kandydatem, a nie gwarantowanym wyszukiwaniem 静怡.

W przypadku popularnych znaków chińskich z tych przykładów obecny filtr kandydatów w zbiorze danych pomija składniki jedno- i dwuznakowe. Krótkie imię może być prawidłowymi danymi wejściowymi, a mimo to nie dać kandydata. Standardowe przejście na AI może nadal ocenić oryginalną przesłaną wartość; tryb tylko ze zbiorem danych zachowuje wynik unknown.

Normalizacja Unicode NFKC nie zapewnia ogólnej konwersji między chińskim uproszczonym a tradycyjnym i nie przypisuje zapisu łacińskiego do jednego oryginalnego chińskiego imienia. Zachowaj przesłany zapis i sprawdź zwrócone dopasowanie. Pozycja nazwiska, pismo ani latynizacja nie wystarczą, aby wnioskować o płci lub kraju danej osoby.

| Przykładowe dane wejściowe | Co przedstawia | Co sprawdzić |
| --- | --- | --- |
| `王静怡` | Imię i nazwisko zapisane bez spacji | Jeden kandydat w zbiorze danych. Obecny parser nie oddziela nazwiska. |
| `静怡` | Dwuznakowe imię | Pomijane przez filtr długości kandydatów; przejście na AI może ocenić oryginalną wartość. |
| `王 静怡` | Rozdzielone krótkie składniki | Dodanie spacji nie omija filtra długości. Oba składniki z przykładu są za krótkie do wyszukiwania w zbiorze danych. |
| `Wang Jingyi` | Dane wejściowe w alfabecie łacińskim | Traktowane jako odrębna wartość, dzielona na własne składniki. Nie ma gwarancji, że zostanie dopasowana do oryginalnych znaków ani do tego samego rekordu. |

## Świadomie wybierz kontekst kraju CN

Demo wysyła country: CN (Chiny). API nie wybiera tego kraju na podstawie pisma, w którym zapisano imię. W swojej integracji używaj znanego i odpowiedniego kontekstu kraju albo pomiń country. Nie zamieniaj tego przykładu w wartość domyślną dla wszystkich rekordów.

Dla każdego kandydata wyszukiwanie wybiera rekord dla danego kraju, jeśli istnieje, a w przeciwnym razie sprawdza rekord globalny. Następnie wybiera dostępnego kandydata o największej zapisanej łącznej liczbie wystąpień. Rzeczywisty zakres dopasowania sprawdzisz w data.match.scope i data.match.country. Rekord kraju z równymi liczbami wystąpień nie jest automatycznie zastępowany wynikiem globalnym; jeśli włączony jest fallback, zamiast tego może zostać użyta AI.

data.input.country opisuje kontekst wysłany w zapytaniu. data.country i data.country_source opisują zwrócone powiązanie z krajem i jego pochodzenie. To różne pola; nie dowodzą one obywatelstwa, pochodzenia etnicznego ani miejsca zamieszkania.

- [Kontekst kraju i dopasowania](https://www.genderapi.io/pl/docs/v2/gender-from-name#country-evidence-workflow)

## Wyślij zapytanie V2 o imię ze swojej aplikacji

Ustaw zmienną GENDERAPI_API_KEY na swój istniejący klucz i uruchom przykład na swoim serwerze. Zapytanie jawnie włącza standardowe przejście na AI. Pokazuje format zapytania, a nie zmierzoną dokładność ani potwierdzone pokrycie. Aby korzystać tylko ze zbioru danych, użyj options.ai_mode: off.

Uruchamiaj te przykłady na swoim serwerze. Ustaw w środowisku procesu zmienną GENDERAPI_API_KEY na swój istniejący klucz API. Upewnij się, że meta.access.mode ma wartość api_key: nierozpoznany klucz może spowodować przejście na próbę dla adresu IP.

Każde zapytanie o prognozę, łącznie z ponownymi próbami, jest nową płatną operacją. Te przykłady nie ponawiają zapytań automatycznie. Przed wysłaniem kolejnego zapytania sprawdź status rozliczenia.

W przypadku odpowiedzi JSON z kodem HTTP 4xx i 5xx przykłady zachowują treść błędu i zwracają niezerowy kod wyjścia. Przed ponowną próbą sprawdź code, action i meta.usage.billing_status.

**cURL**

cURL 7.76+ w powłoce POSIX. Uruchom w terminalu.

```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+; wbudowany fetch. Zapisz jako example.mjs i uruchom 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+; biblioteka standardowa. Zapisz jako example.py i uruchom 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+ z rozszerzeniem cURL. Zapisz jako example.php i uruchom 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+; standardowy klient HTTP. Zapisz jako GenderApiExample.java i uruchom 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**

Aplikacja konsolowa .NET 8+. Użyj jako Program.cs w projekcie konsolowym, a następnie uruchom 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+; biblioteka standardowa. Zapisz jako main.go i uruchom 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)
    }
}
```

- [Parametry zapytań o imiona](https://www.genderapi.io/pl/docs/v2/gender-from-name)
- [Skonfiguruj klucz API](https://www.genderapi.io/pl/docs/v2/authentication)

## Przechowuj wynik razem z informacjami, na których się opiera

Wywnioskowane powiązanie nie jest płcią zadeklarowaną przez daną osobę. Przechowuj osobno oryginalne dane wejściowe, zwrócone informacje o dopasowaniu i dane przekazane przez samą osobę. Wynik unknown jest prawidłowym wynikiem; nie zamieniaj go w swojej aplikacji na zgadywaną kategorię.

| Pole | Jak z niego korzystać |
| --- | --- |
| `data.gender / data.result_status` | Używaj male lub female tylko wtedy, gdy wynik ma status identified. Gdy wynik jest unknown, zachowaj natywną wartość null z JSON. |
| `data.name / data.match` | Sprawdź zwrócone imię i wybranego kandydata. Dopasowanie fragmentu nie dowodzi, że dane wejściowe należą do osoby o tym imieniu. |
| `data.confidence / data.confidence_kind` | Pewność jest wyrażona w skali 0–1 albo ma wartość null. observed_frequency wynika z zapisanych liczb wystąpień; model_reported to wynik podany przez AI. Progi oceniaj osobno dla każdego rodzaju. |
| `data.source / data.sample_count` | Rozróżniaj dataset, ai i none. Wyniki AI nie mają zapisanej liczby próbek. Liczba próbek nie jest zmierzoną dokładnością. |
| `meta.access.mode` | W integracji z kontem sprawdź, czy wartość to api_key. Brakujący lub nierozpoznany klucz może zamiast tego korzystać ze wspólnej próby dla adresu IP. |
| `meta.usage` | Odczytaj charged_credits i billing_status. Udany wynik unknown jest płatny. Utrata odpowiedzi nie oznacza, że zapytanie było bezpłatne. |

- [Pola odpowiedzi i wyniki unknown](https://www.genderapi.io/pl/docs/v2/responses)
- [Dokładność i pewność wyników](https://www.genderapi.io/pl/accuracy-methodology)
- [Źródła danych i datowany profil bazy danych](https://www.genderapi.io/pl/data-provenance)

## Zdecyduj, kiedy korzystać z AI

forceToGenderize jest opcjonalne dla imion, adresów e-mail i nazw użytkowników. Gdy jest włączone, pomiń ai_mode lub użyj fallback; off i always są z nim sprzeczne i zwracają 422. Dodatnie saldo początkowe wystarcza do rozpoczęcia zapytania, nawet jeśli ostateczne obciążenie obniży saldo poniżej zera.

Tryb pseudonimów może zwrócić płeć razem z name: null. Może też zwrócić wynik unknown. Ani standardowe przejście na AI, ani analiza pseudonimów nie gwarantują poprawnej odpowiedzi ani wartości innej niż null.

| Opcja zapytania | Działanie | Kredyty za udane wyszukiwanie |
| --- | --- | --- |
| options.ai_mode: off | Korzysta tylko ze zbioru danych. | 1, także przy wyniku unknown |
| options.ai_mode: fallback | Najpierw sprawdza zbiór danych, a gdy nie zwróci on płci, korzysta ze standardowej AI. To ustawienie domyślne dla pojedynczych zapytań. | Łącznie 1, łącznie z przejściem na AI |
| options.ai_mode: always | Od razu korzysta z AI. | 2 |
| forceToGenderize: true | Najpierw sprawdza zbiór danych, a potem pozwala AI zinterpretować osobisty pseudonim lub alias, nawet bez prawdziwego imienia. | 1 za wynik rozstrzygnięty w zbiorze danych; łącznie 2, jeśli użyta zostanie AI |

- [Opcje AI i analiza pseudonimów](https://www.genderapi.io/pl/docs/v2/ai-options)
- [Kredyty i zużycie](https://www.genderapi.io/pl/docs/v2/credits-and-usage)

## Przetwarzaj listę imion bez utraty kontekstu

Wyślij do 50 elementów z kluczem API lub 10 w próbie dla adresu IP przez POST /api/v2/gender/batch. Nadaj elementom unikalne id i zachowaj oryginalną wartość każdego wiersza. Każdy element może mieć własne opcje kraju i AI; pomiń kraj, gdy jest nieznany.

W przeciwieństwie do pojedynczych zapytań, które domyślnie korzystają z trybu fallback, elementy partii domyślnie korzystają tylko ze zbioru danych. Ustaw options.ai_mode: fallback w każdym elemencie, który wymaga AI. Sprawdzaj każdy wynik, nawet po HTTP 200, zachowuj wyniki unknown i przed ponownym wysłaniem przejrzyj błędy oraz rozliczenie. Każdy udany standardowy element kosztuje 1 kredyt; jedno zapytanie HTTP z partią to nie jeden kredyt za prognozę.

- [Przykłady partii i częściowe błędy](https://www.genderapi.io/pl/docs/v2/batch#batch-application-workflow)
- [Obsługa wyników unknown w aplikacji](https://www.genderapi.io/pl/docs/v2/responses#application-decisions)

## Wiedz, co wysyłasz

Demo wysyła wpisaną wartość do GenderAPI.io dopiero po kliknięciu Analizuj. Jeśli zostanie użyta AI, przesłane type, value i kontekst kraju trafiają do skonfigurowanej usługi inferencji. Aby uzyskać prognozę wyłącznie ze zbioru danych, użyj w swojej integracji options.ai_mode: off bez forceToGenderize.

Polityka prywatności, umowa powierzenia przetwarzania danych i rejestr podmiotów przetwarzających opisują opublikowane zasady przetwarzania. Wynik jest wywnioskowanym powiązaniem; pierwszeństwo mają informacje przekazane przez samą osobę. Nie opieraj na nim decyzji, które mają istotne skutki dla danej osoby.

- [Polityka prywatności](https://www.genderapi.io/pl/privacy-policy)
- [Umowa powierzenia przetwarzania danych](https://www.genderapi.io/pl/data-processing-agreement)
- [Rejestr podmiotów przetwarzających](https://www.genderapi.io/pl/subprocessors)

## Dlaczego dwuznakowe chińskie imię może dać wynik unknown w trybie tylko ze zbiorem danych?

Obecny filtr kandydatów pomija składniki, których długość ciągu w JavaScript wynosi najwyżej dwa. W przypadku pokazanych tu znaków chińskich dwuznakowe imię jest prawidłowymi danymi wejściowymi, ale nie staje się kandydatem w zbiorze danych. Przejście na AI może ocenić oryginalną wartość.

## Czy V2 automatycznie oddziela chińskie nazwisko od imienia?

Wyszukiwanie w zbiorze danych nie dzieli chińskiego imienia i nazwiska zapisanego bez spacji. AI może wywnioskować imię z pełnej wartości, ale żadna z tych ścieżek nie gwarantuje wybrania zamierzonego imienia. Sprawdź source i match w odpowiedzi.

## Czy dla tej grupy imion opublikowano niezależną ocenę dokładności?

Ta strona nie publikuje takiej oceny. Przyjęcie danych wejściowych, pokazanie zapisanych liczb wystąpień ani zwrócenie wyniku pewności nie jest niezależnym pomiarem dokładności. Z metodologii dowiesz się, jakie informacje są dostępne i jakie pomiary nie zostały jeszcze opublikowane.

## Czy wynik bez prognozy zużywa kredyty?

Udany wynik unknown jest płatny. Standardowy tryb ze zbiorem danych lub fallback kosztuje łącznie 1 kredyt. Z forceToGenderize zapytanie kosztuje 1 kredyt, jeśli zbiór danych je rozstrzygnie, albo łącznie 2, jeśli użyta zostanie AI, także przy wyniku unknown. Błędy podlegają odrębnym zasadom rozliczania; sprawdź meta.usage.