# الجنس من اسم مستخدم مع API v2

> التنبؤ بأسماء المستخدمين والأسماء المستعارة باستخدام GenderAPI v2. تعرف على forceToGenderize والبحث عن مجموعة البيانات أولاً وحقول استجابة الذكاء الاصطناعي وتعرفة الائتمان 1 أو 2.

Canonical HTML: https://www.genderapi.io/ar/docs/v2/gender-from-username

Last reviewed: 2026-09-25

## قبل إرسال الطلب

أرسل 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 عند دمج الحساب.

- [المصادقة والوصول التجريبي](https://www.genderapi.io/ar/docs/v2/authentication)
- [جميع معلمات الطلب](https://www.genderapi.io/ar/docs/v2/request-parameters)

## الجنس من اسم المستخدم أو الاسم المستعار

استخدم type: username لاسم المستخدم أو الاسم المستعار. قم بتعيين forceToGenderize إلى true لاستنتاج الجنس من معنى الاسم المستعار مثل prenses، حتى عندما لا يمكن استخراج اسم حقيقي. يتم فحص مجموعة البيانات أولاً. يمكن للتنبؤ بالاسم المستعار أن يُرجع الجنس حتى عندما يكون name: null.

قم بتشغيل هذه الأمثلة على الخادم الخاص بك. قم بتعيين GENDERAPI_API_KEY في بيئة العملية على مفتاح API الموجود لديك. تأكد من أن meta.access.mode هو api_key: يمكن أن يعود المفتاح غير المعروف إلى النسخة التجريبية من IP.

كل طلب تنبؤ هو عملية جديدة قابلة للفوترة، بما في ذلك إعادة المحاولة. لا تقوم هذه الأمثلة بإعادة المحاولة تلقائيًا. التحقق من حالة الفواتير قبل إرسال طلب آخر.

تحافظ استجابات HTTP 4xx و5xx JSON على نص الخطأ وترجع حالة خروج غير صفرية. تحقق من code وaction وmeta.usage.billing_status قبل إعادة المحاولة.

**cURL**

cURL 7.76+ في غلاف POSIX. قم بالتشغيل في جهازك الطرفي.

```bash
curl --silent --show-error --fail-with-body --max-time 30 \
  --request POST 'https://api.genderapi.io/api/v2/gender' \
  --header "Authorization: Bearer ${GENDERAPI_API_KEY:?Set GENDERAPI_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "username",
  "value": "prenses",
  "country": "TR",
  "forceToGenderize": true
}'
```

**JavaScript / Node.js**

Node.js 22+; جلب مدمج. احفظ باسم example.mjs وقم بتشغيل node example.mjs.

```javascript
// 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.
}
```

**Python**

Python 3.10+; مكتبة قياسية. احفظ باسم example.py وقم بتشغيل python3 example.py.

```python
import json
import os
import sys
import urllib.error
import urllib.request

api_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 None

request = 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.
```

**PHP**

PHP 8+ مع الامتداد cURL. احفظ باسم example.php وقم بتشغيل php example.php.

```php
<?php
$apiKey = getenv('GENDERAPI_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set GENDERAPI_API_KEY');
}
$body = json_decode('{"type":"username","value":"prenses","country":"TR","forceToGenderize":true}', true, 512, JSON_THROW_ON_ERROR);

$ch = curl_init('https://api.genderapi.io/api/v2/gender');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_FOLLOWLOCATION => false,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($body, JSON_THROW_ON_ERROR),
]);
$raw = curl_exec($ch);
if ($raw === false) {
    throw new RuntimeException(curl_error($ch));
}
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$contentType = curl_getinfo($ch, CURLINFO_CONTENT_TYPE) ?: '';
curl_close($ch);
if (strpos($contentType, 'json') === false) {
    throw new RuntimeException("HTTP $status: expected a JSON response");
}
$result = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
$output = json_encode($result, JSON_PRETTY_PRINT | JSON_THROW_ON_ERROR) . PHP_EOL;
if ($status < 200 || $status >= 300) {
    fwrite(STDERR, $output); // Preserve the Problem Details body.
    exit(1);
}
echo $output;
// For batches, inspect every item; HTTP 200 can contain item errors.
```

**Java**

Java 17+; عميل HTTP القياسي. احفظ باسم GenderApiExample.java وقم بتشغيل java GenderApiExample.java.

```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.
    }
}
```

**C# / .NET**

تطبيق وحدة التحكم .NET 8+. استخدمه كـ Program.cs في مشروع وحدة التحكم، ثم قم بتشغيل dotnet run.

```csharp
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.
}
```

**Go**

Go 1.22+; مكتبة قياسية. احفظ باسم main.go وقم بتشغيل go run main.go.

```go
package main

import (
    "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)
    }
}
```

## مثال للرد

توضح هذه الاستجابة الاصطناعية شكل JSON، وليست دقة مقاسة أو نتيجة حية مضمونة. يُظهر الوصول التجريبي إلى IP؛ تقارير عملية تمت مصادقتها عن حقول الحصص التجريبية فقط meta.access.mode: api_key وnull. اقرأ بيانات الاستدلال وmeta.usage لنتائج فواتير العملية.

```json
{
  "data": {
    "input": {
      "type": "username",
      "value": "prenses",
      "country": "TR",
      "forceToGenderize": true
    },
    "name": null,
    "gender": "female",
    "country": "TR",
    "confidence": 0.7,
    "confidence_kind": "model_reported",
    "sample_count": null,
    "source": "ai",
    "result_status": "identified",
    "reason": null,
    "country_source": "ai_association",
    "match": {
      "name": null,
      "method": "model_inference",
      "scope": null,
      "country": null
    }
  },
  "meta": {
    "request_id": "11111111-1111-4111-8111-111111111111",
    "duration_ms": 12,
    "access": {
      "mode": "ip_trial",
      "reason": "api_key_missing"
    },
    "usage": {
      "charged_credits": 2,
      "remaining_credits": -1,
      "billing_status": "confirmed",
      "resets_at": "2026-09-26T12:00:00.000Z",
      "limit": 10,
      "period_seconds": 86400
    }
  }
}
```

- [مجالات الاستجابة والثقة](https://www.genderapi.io/ar/docs/v2/responses)

## قراءة توقع الاسم المستعار

يستخدم هذا المثال forceToGenderize: true. إذا حددت مجموعة البيانات الجنس، فستكون التكلفة رصيدًا واحدًا. بخلاف ذلك، يفسر الذكاء الاصطناعي الاسم المستعار ويكلف الطلب المكتمل وحدتين إجمالاً، حتى لو ظل الجنس غير معروف. احذف ai_mode أو اضبطه على fallback. يؤدي استخدام off أو always مع forceToGenderize إلى إرجاع HTTP 422.

في وضع الاسم المستعار، يُسمح بالتنبؤ بالجنس باستخدام name: null. وهذا يعني أنه لم يتم استخراج أي اسم حقيقي، وليس فشل التحليل. إذا قام الذكاء الاصطناعي بإرجاع جنس ما، فسيتم إرجاع sample_count: null وconfidence_kind: model_reported. النتيجة ليست احتمالية معايرة ولا تتحقق من الهوية الشخصية.

بدون forceToGenderize، لا يزال البحث عن اسم مستخدم واحد افتراضيًا إلى AI العادي fallback لإجمالي رصيد واحد، ولكنه يتطلب اسمًا حقيقيًا قابلاً للاستخدام. استخدم options.ai_mode: off لمعالجة مجموعة البيانات فقط.

## أدلة ذات صلة

- [أوضاع الذكاء الاصطناعي وforceToGenderize](https://www.genderapi.io/ar/docs/v2/ai-options)
- [توقعات الدفعة](https://www.genderapi.io/ar/docs/v2/batch)
- [الاعتمادات والاستخدام](https://www.genderapi.io/ar/docs/v2/credits-and-usage)
- [الأخطاء وإعادة المحاولة](https://www.genderapi.io/ar/docs/v2/errors-and-retries)