Før du sender forespørgslen
Send JSON til POST https://api.genderapi.io/api/v2/gender. Brug din eksisterende API-nøgle i Authorization: Bearer YOUR_API_KEY og Content-Type: application/json. Hver forespørgsel behandles uafhængigt.
Vælg dit programmeringssprog i kodeeksemplet. Sæt GENDERAPI_API_KEY i procesmiljøet, før du kører det. Manglende eller ukendte nøgler kan bruge den delte IP-prøveadgang, så bekræft, at meta.access.mode er api_key, når du integrerer en konto.
Køn ud fra et brugernavn eller kaldenavn
| Parameter | Type | Påkrævet | Standard | Beskrivelse |
|---|---|---|---|---|
type | string | Ja | — | Inputkategori: name, email eller username. |
value | string | Ja | — | Påkrævet. 1–254 tegn, ikke tom og uden kontroltegn. E-mailværdier skal have gyldig e-mailsyntaks. |
country | string | Nej | — | Valgfri ISO 3166-1 alpha-2-kode med store bogstaver, for eksempel TR eller US. Et landespecifikt opslag kan falde tilbage til det globale datasæt. |
forceToGenderize | boolean | Nej | false | Prøv datasættet først og derefter AI, der tager højde for kaldenavne, hvis der ikke findes et resultat. Understøttes for name, email og username. |
options | object | Nej | — | Beholder til AI-indstillingerne for det enkelte input. |
options.ai_mode | string | Nej | fallback | Tilladte værdier: off, fallback, always. Med forceToGenderize: true skal du udelade feltet eller bruge fallback. |
id | string | Nej | — | Valgfri identifikator på 1–64 tegn i POST-JSON. Returneres sammen med hvert resultat i en batch og skal være unik inden for batchen. Accepteres ved enkelte forudsigelser, men returneres ikke. Understøttes ikke i GET-forespørgsler. |
Brug type: username til brugernavne og kaldenavne. Sæt forceToGenderize til true, hvis du vil have et forsøg baseret på kaldenavnets betydning, for eksempel prenses, selvom der ikke kan udtrækkes et egentligt navn. Datasættet slås stadig op først. En forudsigelse ud fra et kaldenavn kan returnere et køn, der ikke er null, sammen med name: null.
Vælg et programmeringssprog. Konfigurér din API-nøgle, og kør derefter eksemplet på din server.
Hver forespørgsel om en forudsigelse er en ny operation, der koster kreditter, også når den gentages. Eksemplerne prøver ikke automatisk igen. Kontrollér opkrævningsstatus, før du sender en ny forespørgsel.
Før du kører: adgang og fejlhåndtering
Kør eksemplerne på din server. Sæt GENDERAPI_API_KEY i procesmiljøet til din eksisterende API-nøgle. Bekræft, at meta.access.mode er api_key: En nøgle, der ikke genkendes, kan føre til IP-prøveadgangen.
JSON-svar med HTTP 4xx og 5xx bevarer fejlens body og returnerer en exitstatus, der ikke er nul. Kontrollér code, action og meta.usage.billing_status, før du prøver igen.
Guide til fejl og nye forsøg →cURL 7.76+ i en POSIX-shell. Kør i din terminal. Dokumentation for kørselsmiljøet
Node.js 22+, indbygget fetch. Gem som example.mjs, og kør node example.mjs. Dokumentation for kørselsmiljøet
Python 3.10+, standardbiblioteket. Gem som example.py, og kør python3 example.py. Dokumentation for kørselsmiljøet
PHP 8+ med cURL-udvidelsen. Gem som example.php, og kør php example.php. Dokumentation for kørselsmiljøet
Java 17+, standard-HTTP-klienten. Gem som GenderApiExample.java, og kør java GenderApiExample.java. Dokumentation for kørselsmiljøet
Konsolapplikation med .NET 8+. Brug som Program.cs i et konsolprojekt, og kør derefter dotnet run. Dokumentation for kørselsmiljøet
Go 1.22+, standardbiblioteket. Gem som main.go, og kør go run main.go. Dokumentation for kørselsmiljøet
Eksempel på et svar
Dette er et rigtigt svar, der blev hentet den 1. oktober 2026 med en API-nøgle; kun kontosaldoen er erstattet. Det er ikke et mål for nøjagtighed, og en live-forespørgsel kan give et andet resultat. Forespørgsler med API-nøgle returnerer meta.access.mode: api_key og null i de kvotefelter, der kun gælder IP-prøveadgangen; forespørgsler via IP-prøveadgangen returnerer ip_trial. Læs data for forudsigelsen og meta.usage for operationens opkrævning.
{
"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
}
}
}Felter i svaret på en forudsigelse
| Felt | Type | Kan være null | Eksempel | Beskrivelse |
|---|---|---|---|---|
data.input | object | Nej | {"type":"name","value":"Mads","country":"DK"} | Inputtype, værdi og land. forceToGenderize medtages, når det er true. |
data.name | string | Ja | "mads" | Matchet eller udtrukket fornavn, null, når der ikke er noget. |
data.gender | string | Ja | "male" | male, female eller JSON null. En forudsigelse, ikke en bekræftet personlig identitet. |
data.result_status | string | Nej | "identified" | identified, når der returneres et køn, ellers unknown. |
data.reason | string | Ja | null | null ved identificerede resultater. Årsager til ukendte resultater: not_found, no_name_candidate, ambiguous eller insufficient_evidence. |
data.confidence | number | Ja | 0.95 | Værdi fra 0 til 1 eller null. Når gender er null, er konfidensen også null. |
data.confidence_kind | string | Ja | "observed_frequency" | observed_frequency: dominerende antal i datasættet / total. model_reported: værdi fra AI, ikke en kalibreret sandsynlighed. null, når den ikke er tilgængelig. |
data.sample_count | integer | Ja | 1200 | Stikprøvestørrelse i datasættet eller null. AI finder ikke på en stikprøvestørrelse. |
data.source | string | Nej | "dataset" | dataset, ai eller none. |
data.country | string | Ja | "DK" | Landetilknytning fra dataset eller ai_association, eller null. Fastslår ikke nationalitet, bopæl eller etnicitet. |
data.country_source | string | Ja | "dataset" | Oprindelsen af landetilknytningen: dataset, ai_association eller null. |
data.match | object | Nej | {"name":"mads","method":"normalized","scope":"country","country":"DK"} | Matchet navn i datasættet, metode (normalized, token, substring eller model_inference), omfang (land/globalt) og matchet land. Evidens, der ikke er tilgængelig, er null. |
Metadata om adgang, opkrævning og forespørgslen
| Felt | Type | Kan være null | Eksempel | Beskrivelse |
|---|---|---|---|---|
meta.request_id | string | Nej | "550e8400-e29b-41d4-a716-446655440000" | Entydigt id for dette HTTP-forsøg. Sendes også i X-Request-ID. |
meta.duration_ms | integer | Nej | 42 | Behandlingstid for forespørgslen i millisekunder. |
meta.access.mode | string | Nej | "api_key" | api_key, ip_trial eller unauthenticated. Kontrollér, at værdien er api_key, når du bruger en betalt konto. |
meta.access.reason | string | Ja | null | Årsag til IP-prøveadgangen: api_key_missing, api_key_invalid eller api_key_not_found, ellers null. |
meta.usage.charged_credits | integer | Ja | 1 | Opkrævede kreditter netto. Nul før opkrævning eller efter en fuld bekræftet refusion, null, når opkrævningen ikke er bekræftet. |
meta.usage.remaining_credits | integer | Ja | 99 | Saldo, når operationen afsluttes. Kan være negativ. null, når den ikke er tilgængelig, eller opkrævningen ikke er bekræftet. |
meta.usage.billing_status | string | Nej | "confirmed" | not_charged, confirmed eller unconfirmed. Kontrollér dette, før du prøver en mislykket forudsigelse igen. |
meta.usage.resets_at | string | Ja | "2026-09-27T12:00:00.000Z" | Tidspunkt for nulstilling af IP-prøveadgangen i UTC (ISO 8601). null for konti med API-nøgle, eller når det ikke er kendt. |
meta.usage.limit | integer | Ja | 10 | Kreditter i IP-prøveadgangen. null for konti med API-nøgle. |
meta.usage.period_seconds | integer | Ja | 86400 | Periode for IP-prøveadgangen i sekunder. null for konti med API-nøgle. |
Læs en forudsigelse ud fra et kaldenavn
Eksemplet bruger forceToGenderize: true. Et resultat fra datasættet koster 1 kredit. Hvis datasættet ikke giver et resultat, beder API'et AI om at fortolke aliasset og opkræver 2 kreditter i alt for en gennemført operation, også ved et ukendt resultat. Udelad ai_mode, eller sæt det til fallback. off og always er i konflikt med forceToGenderize og returnerer 422.
I kaldenavnstilstanden er et forudsagt køn med name: null tilladt. Det betyder, at der ikke er udtrukket et egentligt fornavn, og det er ikke en parserfejl. AI-resultater har sample_count: null og confidence_kind: model_reported, når der returneres et køn. Værdien er hverken en kalibreret sandsynlighed eller en bekræftet identitet.
Uden forceToGenderize bruger et enkelt opslag på et brugernavn stadig den almindelige automatiske AI-fallback som standard for 1 kredit i alt, men det kræver et brugbart egentligt fornavn. Brug options.ai_mode: off, hvis du kun vil bruge datasættet.