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

> Wypróbuj japońskie imiona z GenderAPI.io V2. Poznaj krótkie składniki zapisane w kanji, możliwe odczytania, kontekst JP, przejście na AI i sposób zachowywania wyników unknown.

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

Last reviewed: 2026-09-28

## Nie ukrywaj niepewności zapisu i odczytania

Wyślij pisownię zapisaną w rekordzie: w kanji, kanie lub alfabecie łacińskim. V2 przyjmuje Unicode, ale nie gwarantuje, że różne odczytania lub zapisy zostaną dopasowane do równoważnego klucza w zbiorze danych. Wyszukiwanie nie zamienia kanji na odczytanie i nie oddziela nazwiska od imienia, gdy imię i nazwisko zapisano bez spacji.

W przypadku popularnych znaków japońskich z tych przykładów obecny filtr kandydatów pomija składniki jedno- i dwuznakowe. W wartości demonstracyjnej 葵 高橋 pomijane są oba składniki rozdzielone spacją. Standardowy fallback może przekazać AI pełną oryginalną wartość; zapytanie w trybie tylko ze zbiorem danych zachowuje wynik unknown z reason: no_name_candidate.

Usunięcie spacji tworzy innego kandydata, a nie niezawodne rozwiązanie problemu podziału. Zachowaj rzeczywiste dane wejściowe i sprawdź zwrócone source i match. Możliwe odczytanie, zwyczaj nadawania imion ani kontekst JP nie potwierdzają tożsamości płciowej danej osoby.

| Przykładowe dane wejściowe | Co przedstawia | Co sprawdzić |
| --- | --- | --- |
| `葵 高橋` | Rozdzielone krótkie składniki | Żaden z nich nie osiąga minimalnej długości wymaganej przez filtr dla tych znaków. Przejście na AI może nadal ocenić oryginalną wartość. |
| `高橋葵` | Imię i nazwisko zapisane bez spacji | Jeden kandydat; wyszukiwanie nie ustala, gdzie kończy się nazwisko. |
| `あおい` | Trzyznakowy przykład w kanie | Dzięki swojej długości może zostać kandydatem, ale nie oznacza to, że istnieje rekord ani że zostanie zwrócona płeć. |
| `Aoi Takahashi` | Dane wejściowe w alfabecie łacińskim | Mogą zostać ocenione odrębne składniki. Nie ustala to jednego oryginalnego zapisu i nie gwarantuje wybrania zamierzonego imienia. |

## Świadomie wybierz kontekst kraju JP

Demo wysyła country: JP (Japonia). 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": "JP",
  "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": "JP",
  "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\":\"JP\",\"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":"JP","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\":\"JP\",\"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\":\"JP\",\"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\":\"JP\",\"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 przykład 葵 高橋 wymaga przejścia na AI?

Oba składniki są za krótkie dla obecnego filtra kandydatów, dlatego tryb tylko ze zbiorem danych zwraca unknown z reason: no_name_candidate. Fallback może przekazać AI pełną oryginalną wartość, ale odpowiedź AI nie jest gwarantowana.

## Czy V2 ustala dokładne odczytanie japońskiego imienia?

Nie zapewnia zweryfikowanej usługi ustalania odczytań. Wyszukiwanie nie zamienia kanji na kanę i nie gwarantuje równoważnego wyniku dla zapisu latynizowanego. Zachowaj dane wejściowe i sprawdź zwrócone informacje, na których opiera się wynik.

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