Ennen pyynnön lähettämistä
Lähetä JSON-pyyntö: POST https://api.genderapi.io/api/v2/gender. Käytä nykyistä API-avaintasi otsakkeessa Authorization: Bearer YOUR_API_KEY ja lisää Content-Type: application/json. Jokainen pyyntö käsitellään erikseen.
Valitse kieli koodiesimerkistä. Aseta GENDERAPI_API_KEY prosessin ympäristöön ennen suorittamista. Puuttuva tai tunnistamaton avain voi käyttää jaettua IP-kokeilua, joten varmista tilin integroinnissa, että meta.access.mode on api_key.
Sukupuoli käyttäjänimestä tai lempinimestä
| Parametri | Tyyppi | Pakollinen | Oletusarvo | Kuvaus |
|---|---|---|---|---|
type | string | Kyllä | — | Syötteen luokka: name, email tai username. |
value | string | Kyllä | — | Pakollinen. 1–254 merkkiä; ei saa olla tyhjä eikä sisältää ohjausmerkkejä. Sähköpostiarvon on oltava syntaksiltaan kelvollinen sähköpostiosoite. |
country | string | Ei | — | Valinnainen ISO 3166-1 alpha-2 -koodi isoilla kirjaimilla, esimerkiksi TR tai US. Maakohtainen haku voi siirtyä käyttämään globaalia tietoaineistoa. |
forceToGenderize | boolean | Ei | false | Hakee ensin tietoaineistosta ja sitten tarvittaessa lempinimiä tulkitsevalla tekoälyllä. Tuettu tyypeille name, email ja username. |
options | object | Ei | — | Kunkin syötteen tekoälyasetukset sisältävä objekti. |
options.ai_mode | string | Ei | fallback | Sallitut arvot: off, fallback, always. Kun forceToGenderize: true, jätä kenttä pois tai käytä fallback-arvoa. |
id | string | Ei | — | Valinnainen 1–64 merkin tunniste POST-pyynnön JSON-rungossa. Palautetaan kunkin erätuloksen yhteydessä, ja sen on oltava yksilöllinen erän sisällä. Yksittäisissä ennusteissa se hyväksytään, mutta sitä ei palauteta. Ei tuettu GET-kyselyissä. |
Käytä käyttäjänimille ja lempinimille asetusta type: username. Aseta forceToGenderize arvoon true, jos haluat yrityksen lempinimen merkityksen perusteella, kuten prenses, vaikka todellista nimeä ei voida poimia. Tietoaineisto tarkistetaan silti ensin. Lempinimiennuste voi palauttaa sukupuolen, vaikka tuloksessa on name: null.
Valitse ohjelmointikieli. Määritä API-avain, suorita sitten esimerkki palvelimellasi.
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ä.
Ennen suorittamista: käyttöoikeus ja virheiden käsittely
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.
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ä.
Virhe- ja uudelleenyritysopas →cURL 7.76+ POSIX-komentotulkissa. Suorita päätteessä. Suoritusympäristön dokumentaatio
Node.js 22+; sisäänrakennettu fetch. Tallenna nimellä example.mjs ja suorita node example.mjs. Suoritusympäristön dokumentaatio
Python 3.10+; standardikirjasto. Tallenna nimellä example.py ja suorita python3 example.py. Suoritusympäristön dokumentaatio
PHP 8+ cURL-laajennuksella. Tallenna nimellä example.php ja suorita php example.php. Suoritusympäristön dokumentaatio
Java 17+; standardikirjaston HTTP-asiakas. Tallenna nimellä GenderApiExample.java ja suorita java GenderApiExample.java. Suoritusympäristön dokumentaatio
.NET 8+ -konsolisovellus. Käytä konsoliprojektissa nimellä Program.cs ja suorita sitten dotnet run. Suoritusympäristön dokumentaatio
Go 1.22+; standardikirjasto. Tallenna nimellä main.go ja suorita go run main.go. Suoritusympäristön dokumentaatio
Esimerkkivastaus
Tämä on todellinen vastaus, joka haettiin 1. lokakuuta 2026 API-avaimella; vain tilin saldo on korvattu. Se ei ole tarkkuuden mitta, ja reaaliaikainen pyyntö voi palauttaa eri tuloksen. API-avaimella tehdyt pyynnöt palauttavat arvon meta.access.mode: api_key, ja vain kokeilua koskevat kiintiökentät ovat null; IP-kokeilun pyynnöt palauttavat arvon ip_trial. Lue päätelmä kohdasta data ja toiminnon laskutustulos kohdasta meta.usage.
{
"data": {
"input": {
"type": "username",
"value": "prenses",
"country": "TR",
"forceToGenderize": true
},
"name": "prenses",
"gender": "female",
"country": "TR",
"confidence": 0.9456521739130435,
"confidence_kind": "observed_frequency",
"sample_count": 184,
"source": "dataset",
"result_status": "identified",
"reason": null,
"country_source": "dataset",
"match": {
"name": "prenses",
"method": "normalized",
"scope": "country",
"country": "TR"
}
},
"meta": {
"request_id": "a799faa4-bc1a-4537-90b3-2c1b60205499",
"duration_ms": 15,
"access": {
"mode": "api_key",
"reason": null
},
"usage": {
"charged_credits": 1,
"remaining_credits": 49999,
"billing_status": "confirmed",
"resets_at": null,
"limit": null,
"period_seconds": null
}
}
}Ennustevastauksen kentät
| Kenttä | Tyyppi | Voi olla null | Esimerkki | Kuvaus |
|---|---|---|---|---|
data.input | object | Ei | {"type":"name","value":"Juha","country":"FI"} | Syötteen tyyppi, arvo ja maa. forceToGenderize on mukana, kun sen arvo on true. |
data.name | string | Kyllä | "juha" | Osumana löytynyt tai poimittu etunimi; null, jos sellaista ei ole. |
data.gender | string | Kyllä | "male" | male, female tai JSON null. Päätelmä, ei vahvistettu henkilöllisyys. |
data.result_status | string | Ei | "identified" | identified, kun sukupuoli palautetaan; muuten unknown. |
data.reason | string | Kyllä | null | null identified-tuloksissa. Tuntemattoman tuloksen syyt: not_found, no_name_candidate, ambiguous tai insufficient_evidence. |
data.confidence | number | Kyllä | 0.95 | Pistemäärä väliltä 0–1 tai null. Jos sukupuoli on null, myös luottamusarvo on null. |
data.confidence_kind | string | Kyllä | "observed_frequency" | observed_frequency: hallitsevan sukupuolen määrä jaettuna tietoaineiston kokonaismäärällä. model_reported: tekoälyn pistemäärä, ei kalibroitu todennäköisyys. Null, jos arvoa ei ole saatavilla. |
data.sample_count | integer | Kyllä | 1200 | Tietoaineiston otoskoko tai null. Tekoäly ei keksi otoskokoa. |
data.source | string | Ei | "dataset" | dataset, ai tai none. |
data.country | string | Kyllä | "FI" | Tietoaineistoon tai ai_association-arvoon perustuva maayhteys, tai null. Ei vahvista kansalaisuutta, asuinpaikkaa tai etnistä taustaa. |
data.country_source | string | Kyllä | "dataset" | Maayhteyden lähde: dataset, ai_association tai null. |
data.match | object | Ei | {"name":"juha","method":"normalized","scope":"country","country":"FI"} | Tietoaineistosta löytynyt nimi, menetelmä (normalized, token, substring tai model_inference), laajuus (country tai global) ja vastaava maa. Puuttuvat tiedot ovat null. |
Käyttöoikeus, veloitus ja pyynnön metatiedot
| Kenttä | Tyyppi | Voi olla null | Esimerkki | Kuvaus |
|---|---|---|---|---|
meta.request_id | string | Ei | "550e8400-e29b-41d4-a716-446655440000" | Tämän HTTP-yrityksen yksilöllinen tunniste; myös X-Request-ID-otsakkeessa. |
meta.duration_ms | integer | Ei | 42 | Pyynnön käsittelyaika millisekunteina. |
meta.access.mode | string | Ei | "api_key" | api_key, ip_trial tai unauthenticated. Tarkista api_key käyttäessäsi maksullista tiliä. |
meta.access.reason | string | Kyllä | null | Kokeiluun siirtymisen syy: api_key_missing, api_key_invalid tai api_key_not_found; muuten null. |
meta.usage.charged_credits | integer | Kyllä | 1 | Veloitetut nettokrediitit. Nolla ennen veloitusta tai vahvistetun täyden palautuksen jälkeen; null, jos veloitusta ei ole vahvistettu. |
meta.usage.remaining_credits | integer | Kyllä | 99 | Saldo toiminnon valmistuessa. Voi olla negatiivinen; null, jos saldoa ei saada tai veloitusta ei ole vahvistettu. |
meta.usage.billing_status | string | Ei | "confirmed" | not_charged, confirmed tai unconfirmed. Tarkista ennen epäonnistuneen ennusteen uutta yritystä. |
meta.usage.resets_at | string | Kyllä | "2026-09-27T12:00:00.000Z" | IP-kokeilun nollausaika UTC-ajassa (ISO 8601); null API-avaintileillä tai jos aika ei ole tiedossa. |
meta.usage.limit | integer | Kyllä | 10 | IP-kokeilun krediittikiintiö; null API-avaintileille. |
meta.usage.period_seconds | integer | Kyllä | 86400 | IP-kokeilujakson pituus sekunteina; null API-avaintileille. |
Lempinimiennusteen tulkinta
Esimerkki käyttää asetusta forceToGenderize: true. Jos tietoaineisto ratkaisee sukupuolen, hinta on 1 krediitti. Muussa tapauksessa tekoäly tulkitsee aliaksen, ja onnistunut toiminto maksaa yhteensä 2 krediittiä, myös tuntemattomasta tuloksesta. Jätä ai_mode pois tai valitse fallback; off ja always ovat ristiriidassa forceToGenderize-asetuksen kanssa ja palauttavat 422-virheen.
Lempinimitilassa päätelty sukupuoli on sallittu, vaikka tuloksessa on name: null. Se tarkoittaa, ettei todellista etunimeä poimittu; kyse ei ole jäsennysvirheestä. Kun tekoäly palauttaa sukupuolen, tuloksessa on sample_count: null ja confidence_kind: model_reported. Pistemäärä ei ole kalibroitu todennäköisyys eikä vahvistettu henkilöllisyys.
Ilman forceToGenderize-asetusta yksittäinen käyttäjänimihaku käyttää silti oletuksena tavallista tekoälyä varalla, yhteensä 1 krediitillä, mutta se edellyttää käyttökelpoista todellista etunimeä. Käytä asetusta options.ai_mode: off, jos haluat käyttää vain tietoaineistoa.