# Sukupuolen arviointi kiinalaisista nimistä

> Kokeile kiinalaisia nimiä GenderAPI.io V2:ssa. Katso, miten lyhyet nimen osat, koko nimen jakaminen, alkuperäiset merkit ja maakonteksti CN vaikuttavat tietoaineiston ja tekoälyn tuloksiin.

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

Last reviewed: 2026-09-30

## Erota Unicode-syöte nimen jakamisesta osiin

Voit lähettää kiinalaisen nimen Unicode-tekstinä muuttamatta sitä latinalaisiksi kirjaimiksi. Tietoaineiston haku etsii nykyisin normalisoituja nimen osia; se ei jaa yhtenäistä kiinalaista koko nimeä automaattisesti sukunimeksi ja etunimeksi. 王静怡 on siksi yksi ehdokas eikä taattu haku nimellä 静怡.

Näiden esimerkkien yleisillä kiinalaisilla merkeillä tietoaineiston nykyinen ehdokassuodatin ohittaa yhden tai kahden merkin mittaiset nimen osat. Lyhyt etunimi voi olla kelvollinen syöte, mutta siitä ei silti välttämättä muodostu ehdokasta tietoaineistoon. Tavallinen tekoäly varalla voi silti arvioida alkuperäisen lähetetyn arvon; tila, jossa käytetään vain tietoaineistoa, säilyttää tuntemattoman tuloksen.

Unicode-normalisointi NFKC ei tee yleistä muunnosta yksinkertaistetun ja perinteisen kiinan välillä eikä johda latinalaista kirjoitusasua takaisin yhteen tiettyyn kiinalaiseen nimeen. Säilytä lähetetty kirjoitusjärjestelmä ja tarkista palautettu osuma. Älä päättele henkilön sukupuolta tai maata pelkästään sukunimen sijainnista, kirjoitusjärjestelmästä tai latinalaistuksesta.

| Esimerkkisyöte | Mitä se kuvaa | Mitä kannattaa tarkistaa |
| --- | --- | --- |
| `王静怡` | Yhtenäinen koko nimi | Yksi ehdokas tietoaineistossa. Nykyinen jäsennys ei erota sukunimeä. |
| `静怡` | Kahden merkin etunimi | Tietoaineiston ehdokkaiden pituussuodatin ohittaa sen; tekoäly varalla voi arvioida alkuperäisen arvon. |
| `王 静怡` | Lyhyet nimen osat välilyönnillä | Välilyönti ei ratkaise pituussuodattimen ongelmaa. Esimerkin molemmat nimen osat ovat liian lyhyitä tietoaineiston hakuun. |
| `Wang Jingyi` | Latinalaisin kirjaimin kirjoitettu syöte | Käsitellään omana syötteenään ja jaetaan omiin nimen osiinsa. Ei ole taattua, että se johtaa takaisin alkuperäisiin merkkeihin tai samaan tietueeseen. |

## Valitse maakonteksti CN harkiten

Reaaliaikainen demo lähettää arvon country: CN (Kiina). API ei valitse tätä maata sen perusteella, millä kirjoitusjärjestelmällä nimi on kirjoitettu. Käytä integraatiossasi tunnettua ja asiaankuuluvaa maakontekstia tai jätä country pois; älä tee tästä esimerkkiarvosta oletusarvoa kaikille tietueille.

Tietoaineiston haku suosii kunkin ehdokkaan kohdalla olemassa olevaa maakohtaista tietuetta ja muuten arvioi globaalin tietueen. Sen jälkeen valitaan käytettävissä oleva ehdokas, jonka tallennettu kokonaismäärä on suurin. Osuman todellisen laajuuden näet kentistä data.match.scope ja data.match.country. Monitulkintaista maakohtaista tietuetta ei korvata automaattisesti globaalilla tuloksella; fallback voi sen sijaan käyttää tekoälyä.

data.input.country kuvaa pyynnön kontekstia. data.country ja data.country_source kuvaavat palautettua yhteyttä. Ne ovat eri kenttiä, eivätkä ne määritä kansalaisuutta, etnistä taustaa tai asuinpaikkaa.

- [Maakonteksti ja osumat dokumentaatiossa](https://www.genderapi.io/fi/docs/v2/gender-from-name#country-evidence-workflow)

## Lähetä kiinalainen nimi V2:lla

Suorita pyyntö palvelimellasi niin, että GENDERAPI_API_KEY on asetettu nykyiseen avaimeesi. Esimerkki ottaa tavallisen tekoälyn varalla käyttöön erikseen. Se näyttää, miltä pyyntö näyttää, eikä se ole mitattu ennuste tai mitattu kattavuus. Käytä asetusta options.ai_mode: off, jos haluat käyttää vain tietoaineistoa.

Suorita esimerkit palvelimellasi. Aseta prosessin ympäristömuuttujan GENDERAPI_API_KEY arvoksi nykyinen API-avaimesi. Varmista, että meta.access.mode on api_key: tunnistamaton avain voi siirtää pyynnön IP-kokeiluun.

Jokainen ennustepyyntö on uusi laskutettava toiminto, myös uudelleenyritys. Nämä esimerkit eivät yritä uudelleen automaattisesti. Tarkista laskutuksen tila ennen uuden pyynnön lähettämistä.

HTTP 4xx- ja 5xx-JSON-vastauksissa esimerkit säilyttävät virherungon ja palauttavat nollasta poikkeavan poistumiskoodin. Tarkista code, action ja meta.usage.billing_status ennen uutta yritystä.

**cURL**

cURL 7.76+ POSIX-komentotulkissa. Suorita päätteessä.

```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+; sisäänrakennettu fetch. Tallenna nimellä example.mjs ja suorita 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+; standardikirjasto. Tallenna nimellä example.py ja suorita 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+ cURL-laajennuksella. Tallenna nimellä example.php ja suorita 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+; standardikirjaston HTTP-asiakas. Tallenna nimellä GenderApiExample.java ja suorita 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**

.NET 8+ -konsolisovellus. Käytä konsoliprojektissa nimellä Program.cs ja suorita sitten 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+; standardikirjasto. Tallenna nimellä main.go ja suorita 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)
    }
}
```

- [Nimipyyntöjen parametrit](https://www.genderapi.io/fi/docs/v2/gender-from-name)
- [Määritä todennus](https://www.genderapi.io/fi/docs/v2/authentication)

## Säilytä tulos ja sen perusteet yhdessä

Päätelty yhteys ei ole henkilön itse ilmoittama sukupuoli. Säilytä alkuperäinen syöte, palautetut perusteet ja henkilön itse antamat tiedot erillään. Tuntematon tulos on kelvollinen tulos, eikä siitä pidä tehdä sovelluksessasi arvattua luokkaa.

| Kenttä | Miten sitä käytetään |
| --- | --- |
| `data.gender / data.result_status` | Käytä arvoa male tai female vain, kun tulos on identified. Säilytä alkuperäinen JSON null -arvo, kun tulos on unknown. |
| `data.name / data.match` | Tarkista palautettu nimi ja valittu ehdokas. Osuma merkkijonon osaan ei todista, että syöte kuuluu henkilölle, jolla on kyseinen etunimi. |
| `data.confidence / data.confidence_kind` | Luottamusarvo on väliltä 0–1 tai null. observed_frequency perustuu tallennettuihin määriin; model_reported on tekoälyn pistemäärä. Arvioi kynnysarvot kummallekin tyypille erikseen. |
| `data.source / data.sample_count` | Erota arvot dataset, ai ja none. Tekoälytuloksilla ei ole tallennettua otoskokoa. Otoskoko ei ole mitattu tarkkuus. |
| `meta.access.mode` | Varmista tilin integraatiossa, että arvo on api_key. Puuttuva tai tunnistamaton avain voi sen sijaan käyttää yhteistä IP-kokeilua. |
| `meta.usage` | Lue charged_credits ja billing_status. Onnistunut tuntematon tulos veloitetaan. Kadonnut vastaus ei osoita, että pyyntö oli maksuton. |

- [Vastauskentät ja tuntemattomat tulokset](https://www.genderapi.io/fi/docs/v2/responses)
- [Tarkkuus ja luottamusarvo selitettynä](https://www.genderapi.io/fi/accuracy-methodology)
- [Tietolähteet ja päivätty tietoaineistoprofiili](https://www.genderapi.io/fi/data-provenance)

## Päätä, milloin tekoälyä käytetään

forceToGenderize on valinnainen nimille, sähköpostiosoitteille ja käyttäjänimille. Kun se on käytössä, jätä ai_mode pois tai käytä arvoa fallback; off ja always ovat ristiriidassa sen kanssa ja palauttavat 422-virheen. Positiivinen alkusaldo riittää pyynnön aloittamiseen, vaikka lopullinen veloitus painaisi saldon negatiiviseksi.

Lempinimitila voi palauttaa sukupuolen, vaikka tuloksessa on name: null. Se voi myös palauttaa tuntemattoman tuloksen. Tavallinen tekoäly varalla ja lempinimipäättely eivät takaa oikeaa vastausta eivätkä muuta kuin null-arvoista vastausta.

| Pyynnön asetus | Toiminta | Krediitit onnistuneesta hausta |
| --- | --- | --- |
| options.ai_mode: off | Käyttää vain tietoaineistoa. | 1, myös tuntemattomasta tuloksesta |
| options.ai_mode: fallback | Hakee ensin tietoaineistosta ja käyttää tavallista tekoälyä, jos sukupuolta ei saada. Tämä on yksittäisen pyynnön oletus. | Yhteensä 1, tekoäly varalla mukaan lukien |
| options.ai_mode: always | Käyttää suoraan tekoälyä. | 2 |
| forceToGenderize: true | Hakee ensin tietoaineistosta ja sallii sitten tekoälyn tulkita henkilökohtaisen lempinimen tai aliaksen myös ilman todellista etunimeä. | 1 tietoaineistosta ratkaistusta tuloksesta; yhteensä 2, jos tekoälyä käytetään |

- [Tekoälyasetukset ja lempinimipäättely](https://www.genderapi.io/fi/docs/v2/ai-options)
- [Krediitit ja käyttö](https://www.genderapi.io/fi/docs/v2/credits-and-usage)

## Käsittele nimiluettelo menettämättä kontekstia

Käytä päätepistettä POST /api/v2/gender/batch enintään 50 kohteelle rekisteröidyllä API-avaimella tai 10 kohteelle IP-kokeilussa. Anna jokaiselle kohteelle yksilöllinen id ja säilytä kunkin rivin alkuperäinen arvo. Jokaisella kohteella voi olla oma maansa ja omat tekoälysääntönsä; jätä country pois, jos maata ei tiedetä.

Toisin kuin yksittäisissä pyynnöissä, joissa fallback on oletus, eräpyynnön kohteet käyttävät oletuksena vain tietoaineistoa. Aseta options.ai_mode: fallback jokaiselle kohteelle, joka tarvitsee tekoälyä. Tarkista jokainen tulos myös HTTP 200 -vastauksen jälkeen, säilytä tuntemattomat tulokset ja käy kohdekohtaiset virheet ja veloitukset läpi ennen uutta lähetystä. Jokainen onnistunut tavallinen kohde maksaa 1 krediitin; yksi eräpyynnön HTTP-pyyntö ei ole sama asia kuin yksi krediitti yhdestä ennusteesta.

- [Eräpyyntöjen esimerkit ja osittaiset virheet](https://www.genderapi.io/fi/docs/v2/batch#batch-application-workflow)
- [Tuntemattomien tulosten käsittely sovelluksessa](https://www.genderapi.io/fi/docs/v2/responses#application-decisions)

## Tiedä, mitä lähetät

Reaaliaikainen demo lähettää syöttämäsi arvon GenderAPI.io-palveluun vain, kun lähetät sen itse. Jos tekoälyä käytetään, lähetetyt type, value ja maakonteksti välitetään ennusteisiin määritetylle palvelulle. Jos haluat ennusteen pelkästä tietoaineistosta, käytä integraatiossasi asetusta options.ai_mode: off ilman forceToGenderize-asetusta.

Tietosuojakäytäntö, tietojenkäsittelysopimus ja alikäsittelijäluettelo kuvaavat julkaistut käsittelyehdot. Tulos on päätelty yhteys; anna henkilön itse ilmoittamien tietojen mennä sen edelle. Älä käytä tulosta perusteena yksilöä koskeville merkittäville päätöksille.

- [Tietosuojakäytäntö](https://www.genderapi.io/fi/privacy-policy)
- [Tietojenkäsittelysopimus](https://www.genderapi.io/fi/data-processing-agreement)
- [Alikäsittelijäluettelo](https://www.genderapi.io/fi/subprocessors)

## Miksi kahden merkin kiinalainen nimi voi jäädä tuntemattomaksi, kun käytetään vain tietoaineistoa?

Tietoaineiston nykyinen ehdokassuodatin ohittaa nimen osat, joiden pituus JavaScript-merkkijonona on enintään kaksi. Tässä näytetyillä kiinalaisilla merkeillä kahden merkin nimi on kelvollinen syöte, mutta siitä ei tule ehdokasta tietoaineistoon. Tekoäly varalla voi arvioida alkuperäisen syötteen.

## Erottaako V2 kiinalaisen sukunimen etunimestä automaattisesti?

Tietoaineiston haku ei jaa yhtenäistä kiinalaista koko nimeä osiin. Tekoäly voi päätellä nimen koko arvosta, mutta kumpikaan tapa ei takaa, että tarkoitettu etunimi valitaan. Tarkista vastauksen source ja match.

## Onko tarkkuus mitattu, kun syötteenä on kiinalainen nimi?

Tällä sivulla ei julkaista tällaista mittausta. Syötteen hyväksyminen, tallennetut määrät ja luottamusarvo eivät ole riippumaton tarkkuusmittaus. Menetelmäsivulta näet, mitä perusteita on saatavilla ja mitä mittauksia ei ole vielä julkaistu.

## Kuluttaako tuntematon tulos krediittejä?

Onnistunut tuntematon tulos veloitetaan. Tavallinen tila tietoaineistolla tai fallback maksaa yhteensä 1 krediitin. Kun forceToGenderize on käytössä, tietoaineistosta ratkaistu tulos maksaa 1 krediitin ja tekoälyn käyttö yhteensä 2 krediittiä, myös silloin, kun tekoäly palauttaa tuntemattoman tuloksen. Virheillä on omat veloitussääntönsä; tarkista meta.usage.