Før du sender anmodningen
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 anmodning behandles uafhængigt.
Vælg dit sprog i kodeeksemplet. Indstil GENDERAPI_API_KEY i procesmiljøet, før du kører det. Manglende eller ikke-genkendte nøgler kan bruge den delte IP-prøveversion, så bekræft, at meta.access.mode er api_key, når du integrerer en konto.
Køn fra et navn
| Parameter | Type | Påkrævet | Standardværdi | Beskrivelse |
|---|---|---|---|---|
type | string | Ja | — | Inputkategori: name, email eller username. |
value | string | Ja | — | Påkrævet. 1-254 tegn; ikke-blank, uden kontroltegn. E-mail-værdier skal være gyldig e-mail-syntaks. |
country | string | Nej | — | Valgfri ISO 3166-1 alpha-2-kode med store bogstaver, for eksempel TR eller US. Landespecifikt opslag kan falde tilbage til det globale datasæt. |
forceToGenderize | boolean | Nej | false | Søger først i datasættet og derefter med AI for kaldenavne, hvis resultatet mangler. Understøtter name, email og username. |
options | object | Nej | — | Objekt med AI-indstillinger for hvert input. |
options.ai_mode | string | Nej | fallback | Tilladte værdier: off, fallback, always. Ved forceToGenderize: true skal feltet udelades eller være fallback. |
id | string | Nej | — | Valgfri identifikator med 1–64 tegn i POST JSON-brødteksten. Det skal være unikt inden for en batch og returneres med sit batchresultat. Enkelte anmodninger accepterer denne identifikator, men inkluderer den ikke i svaret. GET-forespørgsler understøtter det ikke. |
Brug type: name til at indsende et fornavn eller et fulde navn. Et vellykket svar kan indeholde gender: null. Enkelte anmodninger søger først i datasættet. Hvis intet køn kan bestemmes, bruger de AI som standard.
Vælg et programmeringssprog. Indstil din API nøgle, kør derefter eksemplet på din server.
Hver forudsigelsesanmodning er en ny fakturerbar operation, inklusive genforsøg. Disse eksempler forsøger ikke automatisk igen. Tjek faktureringsstatus, før du sender endnu en anmodning.
Før du kører: adgang og fejlhåndtering
Kør disse eksempler på din server. Indstil GENDERAPI_API_KEY i procesmiljøet til din eksisterende API nøgle. Bekræft, at meta.access.mode er api_key: en ikke-genkendt nøgle kan falde tilbage til IP-prøveversionen.
HTTP 4xx og 5xx JSON-svar bevarer fejlteksten og returnerer en udgangsstatus, der ikke er nul. Tjek code, action og meta.usage.billing_status, før du prøver igen.
Fejl og forsøg igen guide →cURL 7.76+ i en POSIX-skal. Kør i din terminal. Kørselsdokumentation
Node.js 22+; indbygget apport. Gem som example.mjs og kør node example.mjs. Kørselsdokumentation
Python 3.10+; standard bibliotek. Gem som example.py og kør python3 example.py. Kørselsdokumentation
PHP 8+ med cURL-udvidelsen. Gem som example.php og kør php example.php. Kørselsdokumentation
Java 17+; standard HTTP klient. Gem som GenderApiExample.java og kør java GenderApiExample.java. Kørselsdokumentation
.NET 8+ konsolapplikation. Brug som Program.cs i et konsolprojekt, og kør derefter dotnet run. Kørselsdokumentation
Go 1,22+; standard bibliotek. Gem som main.go og kør go run main.go. Kørselsdokumentation
Eksempel svar
Denne syntetiske respons illustrerer JSON-formen, ikke målt nøjagtighed eller et garanteret liveresultat. Det viser IP-prøveadgang; en godkendt operation rapporterer meta.access.mode: api_key og null kun prøve-kvotefelter. Læs data for inferensen og meta.usage for operationens faktureringsresultat.
{
"data": {
"input": {
"type": "name",
"value": "Onur",
"country": "TR"
},
"name": "onur",
"gender": "male",
"country": "TR",
"confidence": 0.9,
"confidence_kind": "observed_frequency",
"sample_count": 100,
"source": "dataset",
"result_status": "identified",
"reason": null,
"country_source": "dataset",
"match": {
"name": "onur",
"method": "normalized",
"scope": "country",
"country": "TR"
}
},
"meta": {
"request_id": "11111111-1111-4111-8111-111111111111",
"duration_ms": 12,
"access": {
"mode": "ip_trial",
"reason": "api_key_missing"
},
"usage": {
"charged_credits": 1,
"remaining_credits": 9,
"billing_status": "confirmed",
"resets_at": "2026-09-26T12:00:00.000Z",
"limit": 10,
"period_seconds": 86400
}
}
}Felter i forudsigelsessvaret
| Felt | Type | Tillader null? | Eksempel | Beskrivelse |
|---|---|---|---|---|
data.input | object | Nej | {"type":"name","value":"Onur","country":"TR"} | Indtastningstype, værdi og land. forceToGenderize er inkluderet, når true. |
data.name | string | Ja | "onur" | Matchet eller ekstraheret fornavn; null, når ingen er tilgængelig. |
data.gender | string | Ja | "male" | male, female eller JSON null. Dette er en forudsigelse, ikke et bevis på en persons identitet. |
data.result_status | string | Nej | "identified" | identified, når et køn returneres; ellers unknown. |
data.reason | string | Ja | null | null for identified. Årsager til ukendte resultater: not_found, no_name_candidate, ambiguous eller insufficient_evidence. |
data.confidence | number | Ja | 0.95 | 0–1 score eller null. Nul køn har null tillid. |
data.confidence_kind | string | Ja | "observed_frequency" | observed_frequency: det dominerende kønstal divideret med det samlede antal i det valgte datasæt. model_reported: en AI-score, ikke en kalibreret sandsynlighed. Værdien er null, når den ikke er tilgængelig. |
data.sample_count | integer | Ja | 1200 | Datasætprøvestørrelse eller null. AI opfinder ikke en prøvetælling. |
data.source | string | Nej | "dataset" | dataset, ai eller none. |
data.country | string | Ja | "TR" | Landetilknytning fra datasæt eller ai_association eller null. Fastlægger ikke nationalitet, bopæl eller etnicitet. |
data.country_source | string | Ja | "dataset" | Kilde til landetilknytningen: dataset, ai_association eller null. |
data.match | object | Nej | {"name":"onur","method":"normalized","scope":"country","country":"TR"} | Matchende navn i datasættet, metode (normalized, token, substring eller model_inference), omfang (country eller global) og det matchende land. Manglende oplysninger har værdien null. |
Adgang, afregning og anmodningsmetadata
| Felt | Type | Tillader null? | Eksempel | Beskrivelse |
|---|---|---|---|---|
meta.request_id | string | Nej | "550e8400-e29b-41d4-a716-446655440000" | Unikt ID for dette HTTP-forsøg; sendes også i X-Request-ID. |
meta.duration_ms | integer | Nej | 42 | Anmodningens behandlingstid i millisekunder. |
meta.access.mode | string | Nej | "api_key" | api_key, ip_trial eller unauthenticated. Kontrollér api_key ved brug af en betalt konto. |
meta.access.reason | string | Ja | null | Årsag til prøveadgang: api_key_missing, api_key_invalid eller api_key_not_found; ellers null. |
meta.usage.charged_credits | integer | Ja | 1 | Nettotræk af kreditter. Nul før træk eller efter bekræftet fuld tilbagebetaling; null hvis afregningen er ubekræftet. |
meta.usage.remaining_credits | integer | Ja | 99 | Saldo ved afslutning. Kan være negativ; null hvis saldoen ikke kendes, eller afregningen er ubekræftet. |
meta.usage.billing_status | string | Nej | "confirmed" | not_charged, confirmed eller unconfirmed. Kontrollér før en mislykket forudsigelse forsøges igen. |
meta.usage.resets_at | string | Ja | "2026-09-27T12:00:00.000Z" | Nulstilling af IP-prøveperioden i UTC (ISO 8601); null for konti med API-nøgle eller ved ukendt tidspunkt. |
meta.usage.limit | integer | Ja | 10 | IP-prøveperiodens kreditkvote; null for konti med API-nøgle. |
meta.usage.period_seconds | integer | Ja | 86400 | IP-prøveperiodens længde i sekunder; null for konti med API-nøgle. |
Landekontekst og ukendte navne
Forsyningsland kun, når du har relevant kontekst. API kan vælge en landespecifik datasætrække eller falde tilbage til en global række. data.match.scope viser, hvilken der blev valgt; det hjemvendte land fastslår ikke, hvor personen bor.
Som standard bruger en enkelt anmodning AI, når datasættet ikke kan bestemme et køn, for i alt 1 kredit. Send options: {"ai_mode": "off"} for kun at bruge datasættet. En gennemført anmodning koster stadig kreditter, hvis den returnerer gender: null. Et opslag med fuldt navn kan matche én del af navnet. data.match registrerer den valgte kandidat og matchningsmetode.
For et kaldenavn, der er angivet som et navn, tillader forceToGenderize: true AI-inferens uden et rigtigt fornavn. Et køn identificeret i datasættet koster 1 kredit. Hvis der er behov for AI, er de samlede omkostninger 2 kreditter. Enhver positiv startsaldo er tilstrækkelig; den endelige saldo kan være negativ.