# معلمات طلب API v2

> مرجع حقول GenderAPI V2: type وvalue وcountry وforceToGenderize وai_mode، مع توضيح الفرق بين معاملات GET وجسم JSON في طلبات POST.

Canonical HTML: https://www.genderapi.io/ar/docs/v2/request-parameters

Last reviewed: 2026-09-25

## معلمات التنبؤ الفردية

يجب حذف الحقول الاختيارية عند عدم استخدامها؛ لا تقم بإرسال null أو سلاسل فارغة بدلاً من country أو options. يجب أن تكون القيم المنطقية JSON true أو false، وليست سلاسل. يتم دعم نص UTF-8؛ لا تحتاج الأسماء إلى ترجمتها صوتيًا إلى ASCII.

يستخدم GET type وvalue وcountry وforceToGenderize وai_mode مباشرة في سلسلة الاستعلام، بالإضافة إلى key الاختياري. قم بتشفير القيم باستخدام أداة تشفير معلمات URL الخاصة بعميل HTTP؛ على سبيل المثال @ يصبح %40. بالنسبة إلى القيم المنطقية GET، أرسل true أو false. يتم رفض الحقول غير المعروفة والقيم غير الصالحة.

| الحقل JSON | النوع | القاعدة |
| --- | --- | --- |
| type | string | مطلوب لـ POST: name أو email أو username. GET الافتراضي هو name. |
| value | string | مطلوب. 1–254 حرفًا؛ غير فارغة، دون أحرف التحكم. يجب أن تكون قيم البريد الإلكتروني عبارة عن بنية بريد إلكتروني صالحة. |
| country | string | رمز ISO 3166-1 alpha-2 اختياري بأحرف لاتينية كبيرة، مثل TR أو US. قد يعود البحث الخاص ببلد معين إلى مجموعة البيانات العامة. |
| forceToGenderize | boolean | اختياري؛ الافتراضي هو false. أولاً، ابحث في مجموعة البيانات. إذا لم يكن من الممكن تحديد الجنس، فاستخدم الذكاء الاصطناعي لتفسير الاسم المستعار. مدعوم لجميع أنواع الإدخال الثلاثة. |
| options.ai_mode | string | off أو fallback أو always. الإعدادات الافتراضية هي fallback للطلبات الفردية وoff لعناصر الدفعة. |
| id | string | معرف اختياري يتكون من 1–64 حرفًا في نص POST JSON. ويجب أن تكون فريدة ضمن الدُفعة ويتم إرجاعها بنتيجة الدُفعة الخاصة بها. تقبل الطلبات الفردية هذا المعرف ولكنها لا تدرجه في الاستجابة. استعلامات GET لا تدعمها. |

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

أرسل 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 وvalue للبريد الإلكتروني أو اسم المستخدم، أو قم بتعيين options.ai_mode وforceToGenderize كما هو موضح أعلاه.

قم بتشغيل هذه الأمثلة على الخادم الخاص بك. قم بتعيين 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": "name",
  "value": "Onur",
  "country": "TR"
}'
```

**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": "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.
}
```

**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\":\"name\",\"value\":\"Onur\",\"country\":\"TR\"}")

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":"name","value":"Onur","country":"TR"}', 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\":\"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.
    }
}
```

**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\":\"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.
}
```

**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\":\"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)
    }
}
```

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

- [أوضاع الذكاء الاصطناعي و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)