# توقعات اسم الدفعة والبريد الإلكتروني واسم المستخدم

> أرسل ما يصل إلى 50 توقعًا لـ GenderAPI v2 في دفعة واحدة. تعرف على خيارات كل عنصر، والمعرفات المحفوظة، والفشل الجزئي، وملخصات الاستجابة، والمحاسبة الائتمانية.

Canonical HTML: https://www.genderapi.io/ar/docs/v2/batch

Last reviewed: 2026-09-25

## أسماء الدفعات ورسائل البريد الإلكتروني وأسماء المستخدمين

يقبل POST /gender/batch مصفوفة items التي تحتوي على 1–50 إدخالاً مع الوصول إلى مفتاح واجهة برمجة التطبيقات (API)، أو 10 إدخالات على الأكثر مع تجربة IP. أرسل الأسماء أو عناوين البريد الإلكتروني أو أسماء المستخدمين أو مزيجًا من الثلاثة. يحتوي كل إدخال على حقول country وforceToGenderize وoptions منفصلة. المعرفات اختيارية ولكن يجب أن تكون فريدة ضمن الدفعة.

تتبع النتائج ترتيب الإدخال. تحتوي كل نتيجة على index وcharged_credits وواحدة بالضبط من data أو error. إذا قمت بتوفير id، فسيتم إرجاعه أيضًا. يمكن أن تحتوي استجابة HTTP 200 على حالات فشل للإدخالات الفردية، لذا تحقق من كل نتيجة. يتضمن meta.summary total، وsucceeded، وidentified، وunknown، وfailed. لا يزال التنبؤ المكتمل بدون جنس معروف يعتبر ناجحًا ويكلف أرصدة.

إذا فشل التحقق من صحة الطلب أو التخطيط، فسيتم رفض الدفعة بأكملها قبل خصم أي اعتمادات. إذا فشلت كافة الإدخالات أثناء التنفيذ، تقوم واجهة برمجة التطبيقات (API) بإرجاع استجابة مشكلة غير 2xx بمصفوفة data والاسم المستعار القديم results. تكلف الإدخالات الفاشلة صفر أرصدة بعد تأكيد استرداد الأموال. إذا كانت الفواتير غير مؤكدة، فلا تفترض أن التكلفة المبلغ عنها لكل إدخال نهائية.

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

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

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

**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/batch' \
  --header "Authorization: Bearer ${GENDERAPI_API_KEY:?Set GENDERAPI_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
  "items": [
    {
      "id": "contact-1",
      "type": "name",
      "value": "Onur",
      "country": "TR"
    },
    {
      "id": "contact-2",
      "type": "email",
      "value": "alice.smith@example.com",
      "options": {
        "ai_mode": "fallback"
      }
    },
    {
      "id": "contact-3",
      "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 = {
  "items": [
    {
      "id": "contact-1",
      "type": "name",
      "value": "Onur",
      "country": "TR"
    },
    {
      "id": "contact-2",
      "type": "email",
      "value": "alice.smith@example.com",
      "options": {
        "ai_mode": "fallback"
      }
    },
    {
      "id": "contact-3",
      "type": "username",
      "value": "prenses",
      "country": "TR",
      "forceToGenderize": true
    }
  ]
};

const response = await fetch("https://api.genderapi.io/api/v2/gender/batch", {
  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("{\"items\":[{\"id\":\"contact-1\",\"type\":\"name\",\"value\":\"Onur\",\"country\":\"TR\"},{\"id\":\"contact-2\",\"type\":\"email\",\"value\":\"alice.smith@example.com\",\"options\":{\"ai_mode\":\"fallback\"}},{\"id\":\"contact-3\",\"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/batch",
    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('{"items":[{"id":"contact-1","type":"name","value":"Onur","country":"TR"},{"id":"contact-2","type":"email","value":"alice.smith@example.com","options":{"ai_mode":"fallback"}},{"id":"contact-3","type":"username","value":"prenses","country":"TR","forceToGenderize":true}]}', true, 512, JSON_THROW_ON_ERROR);

$ch = curl_init('https://api.genderapi.io/api/v2/gender/batch');
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 = "{\"items\":[{\"id\":\"contact-1\",\"type\":\"name\",\"value\":\"Onur\",\"country\":\"TR\"},{\"id\":\"contact-2\",\"type\":\"email\",\"value\":\"alice.smith@example.com\",\"options\":{\"ai_mode\":\"fallback\"}},{\"id\":\"contact-3\",\"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/batch"))
            .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/batch");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", apiKey);
request.Content = new StringContent("{\"items\":[{\"id\":\"contact-1\",\"type\":\"name\",\"value\":\"Onur\",\"country\":\"TR\"},{\"id\":\"contact-2\",\"type\":\"email\",\"value\":\"alice.smith@example.com\",\"options\":{\"ai_mode\":\"fallback\"}},{\"id\":\"contact-3\",\"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 := "{\"items\":[{\"id\":\"contact-1\",\"type\":\"name\",\"value\":\"Onur\",\"country\":\"TR\"},{\"id\":\"contact-2\",\"type\":\"email\",\"value\":\"alice.smith@example.com\",\"options\":{\"ai_mode\":\"fallback\"}},{\"id\":\"contact-3\",\"type\":\"username\",\"value\":\"prenses\",\"country\":\"TR\",\"forceToGenderize\":true}]}"
    request, err := http.NewRequest("POST", "https://api.genderapi.io/api/v2/gender/batch", 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)
    }
}
```

## اقرأ الرد الدفعي

يحتوي هذا المثال الاصطناعي المستقل على تطابق مجموعة بيانات، ونتيجة غير معروفة، وفشل الموفر. وهو يوضح استجابة HTTP 200 للنجاح الجزئي، وليس الإخراج المتوقع للطلب الدفعي أعلاه. العنصران الناجحان يكلفان رصيدًا واحدًا لكل منهما؛ العنصر الفاشل له رسوم مؤكدة صفر.

```json
{
  "data": [
    {
      "index": 0,
      "id": "known",
      "charged_credits": 1,
      "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"
        }
      }
    },
    {
      "index": 1,
      "id": "missing",
      "charged_credits": 1,
      "data": {
        "input": {
          "type": "name",
          "value": "zzzxxyy",
          "country": null
        },
        "name": null,
        "gender": null,
        "country": null,
        "confidence": null,
        "confidence_kind": null,
        "sample_count": null,
        "source": "none",
        "result_status": "unknown",
        "reason": "not_found",
        "country_source": null,
        "match": {
          "name": null,
          "method": null,
          "scope": null,
          "country": null
        }
      }
    },
    {
      "index": 2,
      "id": "failed",
      "charged_credits": 0,
      "error": {
        "type": "urn:genderapi:problem:ai_upstream_error",
        "title": "ai upstream error",
        "status": 502,
        "detail": "The AI provider could not complete the request.",
        "instance": "urn:uuid:11111111-1111-4111-8111-111111111111",
        "code": "ai_upstream_error",
        "request_id": "11111111-1111-4111-8111-111111111111",
        "documentation": "https://api.genderapi.io/api/v2/errors",
        "action": "inspect_billing_before_retry"
      }
    }
  ],
  "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": 6,
      "billing_status": "confirmed",
      "resets_at": "2026-09-26T12:00:00.000Z",
      "limit": 10,
      "period_seconds": 86400
    },
    "summary": {
      "total": 3,
      "succeeded": 2,
      "identified": 1,
      "unknown": 1,
      "failed": 1
    }
  }
}
```

## تخطيط الاعتمادات المجمعة وإعادة المحاولة

قم بالمصادقة باستخدام مفتاح Bearer API الموجود لديك وأرسل Content-Type: application/json. كل دفعة مقدمة هي عملية جديدة. في حالة فشل إعادة المحاولة جزئيًا، قم بإرسال العناصر الفاشلة فقط بعد التحقق من الفواتير؛ إعادة إرسال العناصر الناجحة يشحنها مرة أخرى.

تستخدم عناصر الطلب المجمّع off افتراضيًا وتستهلك وحدة واحدة لكل توقع مكتمل. يستهلك fallback أيضًا وحدة واحدة إجمالًا، بما في ذلك الذكاء الاصطناعي، بينما يستهلك always وحدتين. مع forceToGenderize، تكون التكلفة وحدة واحدة إذا حددت مجموعة البيانات الجنس، أو وحدتين إجمالًا عند استخدام الذكاء الاصطناعي. تُحتسب أيضًا التوقعات المكتملة التي يبقى جنسها غير معروف. تكفي وحدة واحدة لبدء الطلب المجمّع، وقد يصبح الرصيد سالبًا بعد الخصم النهائي.

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