Prédisez à partir des noms d'utilisateur et des surnoms avec GenderAPI v2. Découvrez forceToGenderize, la recherche par ensemble de données en premier, les champs de réponse IA et le tarif de 1 ou 2 crédits.
Avant d'envoyer la demande
Envoyer JSON à POST https://api.genderapi.io/api/v2/gender. Utilisez votre clé API existante dans Authorization: Bearer YOUR_API_KEY et Content-Type: application/json. Chaque demande est traitée de manière indépendante.
Choisissez votre langue dans l'exemple de code. Définissez GENDERAPI_API_KEY dans l'environnement de processus avant de l'exécuter. Les clés manquantes ou non reconnues peuvent utiliser l'essai partagé IP, donc confirmez que meta.access.mode est api_key lors de l'intégration d'un compte.
genre à partir d'un nom d'utilisateur ou d'un surnom
Utilisez type: username pour un nom d'utilisateur ou un surnom. Définissez forceToGenderize sur true pour déduire le genre à partir de la signification d'un alias tel que prenses, même si aucun prénom réel ne peut être extrait. L'ensemble de données est vérifié en premier. Une prédiction de surnom peut renvoyer un genre même lorsque name: null.
Choisissez un langage de programmation.Configurez votre clé API, puis exécutez l'exemple sur votre serveur.
Chaque demande de prédiction est une nouvelle opération facturable, y compris les nouvelles tentatives. Ces exemples ne réessayent pas automatiquement. Vérifiez l'état de facturation avant d'envoyer une autre demande.
Avant d'exécuter : accès et gestion des erreurs
Exécutez ces exemples sur votre serveur. Définissez GENDERAPI_API_KEY dans l’environnement de processus sur votre clé API existante. Confirmez que meta.access.mode est api_key : une clé non reconnue peut revenir à l'essai IP.
Les réponses HTTP 4xx et 5xx JSON préservent le corps de l'erreur et renvoient un état de sortie différent de zéro. Vérifiez code, action et meta.usage.billing_status avant de réessayer.
// 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": "username", "value": "prenses", "country": "TR", "forceToGenderize": true};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.}
Node.js 22+ ; récupération intégrée. Enregistrez sous example.mjs et exécutez node example.mjs. Documentation d'exécution
Python
import jsonimport osimport sysimport urllib.errorimport urllib.requestapi_key = os.environ.get("GENDERAPI_API_KEY")if not api_key: raise RuntimeError("Set GENDERAPI_API_KEY")body = json.loads("{\"type\":\"username\",\"value\":\"prenses\",\"country\":\"TR\",\"forceToGenderize\":true}")class NoRedirect(urllib.request.HTTPRedirectHandler): def redirect_request(self, req, fp, code, msg, headers, newurl): return Nonerequest = 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.
Python 3.10+ ; bibliothèque standard. Enregistrez sous example.py et exécutez python3 example.py. Documentation d'exécution
PHP 8+ avec l'extension cURL. Enregistrez sous example.php et exécutez php example.php. Documentation d'exécution
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\":\"username\",\"value\":\"prenses\",\"country\":\"TR\",\"forceToGenderize\":true}"; 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. }}
Java 17+ ; client standard HTTP. Enregistrez sous GenderApiExample.java et exécutez java GenderApiExample.java. Documentation d'exécution
C# / .NET
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\":\"username\",\"value\":\"prenses\",\"country\":\"TR\",\"forceToGenderize\":true}", 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.}
Application console .NET 8+. Utilisez comme Program.cs dans un projet de console, puis exécutez dotnet run. Documentation d'exécution
Go
package mainimport ( "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\":\"username\",\"value\":\"prenses\",\"country\":\"TR\",\"forceToGenderize\":true}" 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) }}
Go 1.22+ ; bibliothèque standard. Enregistrez sous main.go et exécutez go run main.go. Documentation d'exécution
Exemple de réponse
Cette réponse synthétique illustre la forme JSON, et non la précision mesurée ou un résultat en direct garanti. Il montre l'accès à l'essai IP ; une opération authentifiée signale les champs de quota meta.access.mode : api_key et null pour essai uniquement. Lisez les données pour l'inférence et meta.usage pour le résultat de facturation de l'opération.
Cet exemple utilise forceToGenderize: true. Si l'ensemble de données identifie un genre, le coût est de 1 crédit. Sinon, l'IA interprète l'alias et une demande complétée coûte 2 crédits au total, même si le genre reste inconnu. Omettez ai_mode ou définissez-le sur fallback. L'utilisation de off ou always avec forceToGenderize renvoie HTTP 422.
En mode pseudo, une prédiction de genre avec name: null est autorisée. Cela signifie qu'aucun prénom réel n'a été extrait, et non que l'analyse a échoué. Si IA renvoie un genre, sample_count: null et confidence_kind: model_reported sont renvoyés. Le score n’est pas une probabilité calibrée et ne vérifie pas l’identité personnelle.
Sans forceToGenderize, une recherche de nom d'utilisateur unique est toujours par défaut IA fallback ordinaire pour un total de 1 crédit, mais elle nécessite un prénom réel utilisable. Utilisez options.ai_mode : off pour le traitement des ensembles de données uniquement.