Før du sender forespørselen
Send JSON til POST https://api.genderapi.io/api/v2/gender. Bruk din eksisterende API-nøkkel i Authorization: Bearer YOUR_API_KEY og Content-Type: application/json. Hver forespørsel behandles uavhengig.
Velg språk i kodeeksemplet. Sett GENDERAPI_API_KEY i prosessmiljøet før du kjører det. Nøkler som mangler eller ikke gjenkjennes, kan bruke den delte IP-prøveperioden, så bekreft at meta.access.mode er api_key når du integrerer en konto.
Kjønn fra et brukernavn eller kallenavn
| Parameter | Type | Påkrevd | Standardverdi | Beskrivelse |
|---|---|---|---|---|
type | string | Ja | — | Inndatakategori: name, email eller username. |
value | string | Ja | — | Påkrevd. 1–254 tegn; ikke tom og uten kontrolltegn. E-postverdier må ha gyldig e-postsyntaks. |
country | string | Nei | — | Valgfri ISO 3166-1 alpha-2-kode med store bokstaver, for eksempel TR eller US. Et landspesifikt oppslag kan falle tilbake til det globale datasettet. |
forceToGenderize | boolean | Nei | false | Søk først i datasettet, deretter med KI som tolker kallenavn hvis det ikke finnes et resultat. Støttes for name, email og username. |
options | object | Nei | — | Objekt for KI-alternativer per inndata. |
options.ai_mode | string | Nei | fallback | Tillatte verdier: off, fallback, always. Med forceToGenderize: true utelater du feltet eller bruker fallback. |
id | string | Nei | — | Valgfri identifikator på 1–64 tegn i POST-JSON. Returneres sammen med hvert resultat i en samleforespørsel og må være unik innenfor samleforespørselen. Godtas, men returneres ikke for enkeltprediksjoner. Støttes ikke i GET-spørringer. |
Bruk type: username for brukernavn og kallenavn. Sett forceToGenderize til true når du vil ha et forsøk basert på betydningen av kallenavnet, for eksempel prenses, selv om det ikke kan hentes ut et ekte navn. Datasettet sjekkes likevel først. En prediksjon fra et kallenavn kan returnere et kjønn som ikke er null, sammen med name: null.
Velg et programmeringsspråk. Konfigurer API-nøkkelen, og kjør deretter eksemplet på serveren din.
Hver prediksjonsforespørsel er en ny operasjon som belastes, også nye forsøk. Disse eksemplene prøver ikke automatisk på nytt. Sjekk belastningsstatusen før du sender en ny forespørsel.
Før du kjører: tilgang og feilhåndtering
Kjør disse eksemplene på serveren din. Sett GENDERAPI_API_KEY i prosessmiljøet til din eksisterende API-nøkkel. Bekreft at meta.access.mode er api_key: en nøkkel som ikke gjenkjennes, kan føre til IP-prøveperioden.
Ved JSON-svar med HTTP 4xx og 5xx beholdes feilinnholdet, og eksemplet avsluttes med en exit-status som ikke er null. Sjekk code, action og meta.usage.billing_status før du prøver på nytt.
Veiledning om feil og nye forsøk →cURL 7.76+ i et POSIX-skall. Kjør i terminalen. Dokumentasjon for kjøretidsmiljøet
Node.js 22+; innebygd fetch. Lagre som example.mjs og kjør node example.mjs. Dokumentasjon for kjøretidsmiljøet
Python 3.10+; standardbiblioteket. Lagre som example.py og kjør python3 example.py. Dokumentasjon for kjøretidsmiljøet
PHP 8+ med cURL-utvidelsen. Lagre som example.php og kjør php example.php. Dokumentasjon for kjøretidsmiljøet
Java 17+; standard HTTP-klient. Lagre som GenderApiExample.java og kjør java GenderApiExample.java. Dokumentasjon for kjøretidsmiljøet
Konsollapplikasjon i .NET 8+. Bruk som Program.cs i et konsollprosjekt, og kjør deretter dotnet run. Dokumentasjon for kjøretidsmiljøet
Go 1.22+; standardbiblioteket. Lagre som main.go og kjør go run main.go. Dokumentasjon for kjøretidsmiljøet
Eksempelsvar
Dette er et ekte svar hentet 1. oktober 2026 med en API-nøkkel; bare kontosaldoen er byttet ut. Det er ikke et mål på nøyaktighet, og en forespørsel i sanntid kan gi et annet resultat. Forespørsler med API-nøkkel rapporterer meta.access.mode: api_key og null i kvotefeltene som bare gjelder IP-prøveperioden; forespørsler via IP-prøveperioden rapporterer ip_trial. Les data for estimatet og meta.usage for belastningen av operasjonen.
{
"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
}
}
}Felt i prediksjonssvaret
| Felt | Type | Kan være null | Eksempel | Beskrivelse |
|---|---|---|---|---|
data.input | object | Nei | {"type":"name","value":"Henrik","country":"NO"} | Inndatatype, verdi og land. forceToGenderize tas med når verdien er true. |
data.name | string | Ja | "henrik" | Fornavnet som ga treff eller ble hentet ut; null når det ikke finnes noe. |
data.gender | string | Ja | "male" | male, female eller JSON null. Et estimat, ikke en bekreftet personlig identitet. |
data.result_status | string | Nei | "identified" | identified når et kjønn returneres; ellers unknown. |
data.reason | string | Ja | null | null for identifiserte resultater. Årsaker til ukjente resultater: not_found, no_name_candidate, ambiguous eller insufficient_evidence. |
data.confidence | number | Ja | 0.95 | Verdi fra 0 til 1 eller null. Når kjønnet er null, er konfidensen også null. |
data.confidence_kind | string | Ja | "observed_frequency" | observed_frequency: det dominerende antallet i datasettet delt på totalen. model_reported: en verdi fra KI, ikke en kalibrert sannsynlighet. null når verdien ikke er tilgjengelig. |
data.sample_count | integer | Ja | 1200 | Utvalgsstørrelse i datasettet eller null. KI finner ikke på et utvalgsantall. |
data.source | string | Nei | "dataset" | dataset, ai eller none. |
data.country | string | Ja | "NO" | Landtilknytning fra dataset eller ai_association, eller null. Viser ikke nasjonalitet, bosted eller etnisitet. |
data.country_source | string | Ja | "dataset" | Kilden til landtilknytningen: dataset, ai_association eller null. |
data.match | object | Nei | {"name":"henrik","method":"normalized","scope":"country","country":"NO"} | Navnet som ga treff i datasettet, metoden (normalized, token, substring eller model_inference), omfanget country/global og landet som ga treff. Grunnlag som ikke er tilgjengelig, er null. |
Metadata om tilgang, belastning og forespørsel
| Felt | Type | Kan være null | Eksempel | Beskrivelse |
|---|---|---|---|---|
meta.request_id | string | Nei | "550e8400-e29b-41d4-a716-446655440000" | Unik ID for dette HTTP-forsøket; sendes også i X-Request-ID. |
meta.duration_ms | integer | Nei | 42 | Behandlingstid for forespørselen i millisekunder. |
meta.access.mode | string | Nei | "api_key" | api_key, ip_trial eller unauthenticated. Kontroller at verdien er api_key når du bruker en betalt konto. |
meta.access.reason | string | Ja | null | Årsak til at IP-prøveperioden ble brukt: api_key_missing, api_key_invalid eller api_key_not_found; ellers null. |
meta.usage.charged_credits | integer | Ja | 1 | Netto belastede kreditter. 0 før belastning eller etter en bekreftet full refusjon; null når belastningen ikke er bekreftet. |
meta.usage.remaining_credits | integer | Ja | 99 | Saldo når operasjonen er fullført. Kan være negativ; null når saldoen ikke er tilgjengelig eller belastningen ikke er bekreftet. |
meta.usage.billing_status | string | Nei | "confirmed" | not_charged, confirmed eller unconfirmed. Sjekk dette før du prøver en mislykket prediksjon på nytt. |
meta.usage.resets_at | string | Ja | "2026-09-27T12:00:00.000Z" | Tidspunkt for tilbakestilling av IP-prøveperioden i UTC (ISO 8601); null for kontoer med API-nøkkel eller når tidspunktet er ukjent. |
meta.usage.limit | integer | Ja | 10 | Kvoten i IP-prøveperioden; null for kontoer med API-nøkkel. |
meta.usage.period_seconds | integer | Ja | 86400 | Lengden på IP-prøveperioden i sekunder; null for kontoer med API-nøkkel. |
Les en prediksjon fra et kallenavn
Eksemplet bruker forceToGenderize: true. Et oppslag med resultat i datasettet koster 1 kreditt. Uten resultat ber API-et KI om å tolke aliaset og belaster 2 kreditter totalt for en vellykket operasjon, også ved et ukjent resultat. Utelat ai_mode eller sett den til fallback; off og always er i konflikt med forceToGenderize og gir 422.
Et estimert kjønn med name: null er tillatt i kallenavnmodus. Det betyr at det ikke ble hentet ut noe ekte fornavn; det er ikke en tolkningsfeil. KI-resultater har sample_count: null og confidence_kind: model_reported når et kjønn returneres. Verdien er ikke en kalibrert sannsynlighet eller en bekreftet identitet.
Uten forceToGenderize bruker et enkeltoppslag for et brukernavn fortsatt vanlig KI-reserve som standard for 1 kreditt totalt, men det krever et brukbart ekte fornavn. Bruk options.ai_mode: off for å bare bruke datasettet.