توقع الجنس من الاسم الأول أو الاسم الكامل باستخدام GenderAPI v2. راجع أمثلة اللغات السبعة، واستجابات JSON، وسياق الدولة، وتكاليف الذكاء الاصطناعي الاحتياطية والتكاليف الائتمانية.
قبل إرسال الطلب
أرسل JSON إلى POST https://api.genderapi.io/api/v2/gender. استخدم مفتاح API الموجود لديك في Authorization: Bearer YOUR_API_KEY وContent-Type: application/json. تتم معالجة كل طلب بشكل مستقل.
اختر لغتك في مثال الكود. قم بتعيين GENDERAPI_API_KEY في بيئة العملية قبل تشغيله. يمكن للمفاتيح المفقودة أو غير المعروفة استخدام النسخة التجريبية المشتركة من IP، لذا تأكد من أن meta.access.mode هو api_key عند دمج الحساب.
استخدم type: name لإرسال الاسم الأول أو الاسم الكامل. قد تحتوي الاستجابة الناجحة على gender: null. تقوم الطلبات الفردية أولاً بالبحث في مجموعة البيانات. إذا لم يكن من الممكن تحديد الجنس، فإنهم يستخدمون الذكاء الاصطناعي بشكل افتراضي.
كل طلب تنبؤ هو عملية جديدة قابلة للفوترة، بما في ذلك إعادة المحاولة. لا تقوم هذه الأمثلة بإعادة المحاولة تلقائيًا. التحقق من حالة الفواتير قبل إرسال طلب آخر.
قبل التشغيل: الوصول ومعالجة الأخطاء
قم بتشغيل هذه الأمثلة على الخادم الخاص بك. قم بتعيين GENDERAPI_API_KEY في بيئة العملية على مفتاح API الموجود لديك. تأكد من أن meta.access.mode هو api_key: يمكن أن يعود المفتاح غير المعروف إلى النسخة التجريبية من IP.
تحافظ استجابات HTTP 4xx و5xx JSON على نص الخطأ وترجع حالة خروج غير صفرية. تحقق من code وaction وmeta.usage.billing_status قبل إعادة المحاولة.
cURL 7.76+ في غلاف POSIX. قم بالتشغيل في جهازك الطرفي. وثائق وقت التشغيل
JavaScript / Node.js
// 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": "name", "value": "Onur", "country": "TR"};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+; جلب مدمج. احفظ باسم example.mjs وقم بتشغيل node example.mjs. وثائق وقت التشغيل
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\":\"name\",\"value\":\"Onur\",\"country\":\"TR\"}")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+; مكتبة قياسية. احفظ باسم example.py وقم بتشغيل python3 example.py. وثائق وقت التشغيل
PHP 8+ مع الامتداد cURL. احفظ باسم example.php وقم بتشغيل php example.php. وثائق وقت التشغيل
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\":\"name\",\"value\":\"Onur\",\"country\":\"TR\"}"; 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+; عميل HTTP القياسي. احفظ باسم GenderApiExample.java وقم بتشغيل java GenderApiExample.java. وثائق وقت التشغيل
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\":\"name\",\"value\":\"Onur\",\"country\":\"TR\"}", 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.}
تطبيق وحدة التحكم .NET 8+. استخدمه كـ Program.cs في مشروع وحدة التحكم، ثم قم بتشغيل dotnet run. وثائق وقت التشغيل
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\":\"name\",\"value\":\"Onur\",\"country\":\"TR\"}" 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+; مكتبة قياسية. احفظ باسم main.go وقم بتشغيل go run main.go. وثائق وقت التشغيل
مثال للرد
توضح هذه الاستجابة الاصطناعية شكل JSON، وليست دقة مقاسة أو نتيجة حية مضمونة. يُظهر الوصول التجريبي إلى IP؛ تقارير عملية تمت مصادقتها عن حقول الحصص التجريبية فقط meta.access.mode: api_key وnull. اقرأ بيانات الاستدلال وmeta.usage لنتائج فواتير العملية.
بلد التوريد فقط عندما يكون لديك سياق ذي صلة. يمكن لـ API تحديد صف مجموعة بيانات خاص ببلد ما أو الرجوع إلى صف عام. يُظهر data.match.scope ما تم تحديده؛ ولا تحدد الدولة المعادة المكان الذي يعيش فيه الشخص.
يبحث الطلب الفردي افتراضيًا في مجموعة البيانات، ثم يستخدم الذكاء الاصطناعي إذا تعذر تحديد الجنس، بتكلفة إجمالية قدرها وحدة واحدة. لاستخدام مجموعة البيانات فقط، أرسل options: {"ai_mode": "off"}. يُحتسب الطلب المكتمل حتى إذا أعاد gender: null. قد تتطابق إحدى أجزاء الاسم الكامل؛ يسجل data.match المرشح المختار وطريقة المطابقة.
عند إدخال اسم مستعار، يتيح forceToGenderize: true الاستدلال دون استخراج اسم حقيقي. إذا حددت مجموعة البيانات الجنس، تُخصم وحدة واحدة؛ وإذا استُخدم الذكاء الاصطناعي فالتكلفة الإجمالية وحدتان. يكفي وجود رصيد موجب عند البدء، وقد يصبح الرصيد النهائي سالبًا.