GenderAPI.io V2: ονόματα, διευθύνσεις email και ονόματα χρήστη σε παρτίδες

Ονόματα, διευθύνσεις email και ονόματα χρήστη σε παρτίδες

Παράμετρος	Τύπος	Υποχρεωτικό	Προεπιλογή	Περιγραφή
`items`	`array<object>`	Ναι	`—`	Από 1 έως 50 στοιχεία πρόβλεψης, έως 10 με τη δοκιμαστική πρόσβαση IP. Τα αποτελέσματα διατηρούν τη σειρά εισόδου.
`items[].type`	`string`	Ναι	`—`	Κατηγορία εισόδου: name, email ή username.
`items[].value`	`string`	Ναι	`—`	Υποχρεωτικό. 1–254 χαρακτήρες, όχι κενό και χωρίς χαρακτήρες ελέγχου. Οι τιμές email πρέπει να έχουν έγκυρη σύνταξη email.
`items[].country`	`string`	Όχι	`—`	Προαιρετικός κωδικός ISO 3166-1 alpha-2 με κεφαλαία γράμματα, για παράδειγμα TR ή US. Μια αναζήτηση για συγκεκριμένη χώρα μπορεί να καταφύγει στο καθολικό σύνολο δεδομένων.
`items[].forceToGenderize`	`boolean`	Όχι	`false`	Ελέγχει πρώτα το σύνολο δεδομένων και, αν δεν υπάρξει αποτέλεσμα, χρησιμοποιεί AI με ανάλυση ψευδωνύμων. Υποστηρίζεται για name, email και username.
`items[].options`	`object`	Όχι	`—`	Πεδίο με τις επιλογές AI για κάθε είσοδο.
`items[].options.ai_mode`	`string`	Όχι	`off`	Επιτρεπόμενες τιμές: off, fallback, always. Με forceToGenderize: true, παραλείψτε αυτό το πεδίο ή χρησιμοποιήστε fallback.
`items[].id`	`string`	Όχι	`—`	Προαιρετικό αναγνωριστικό 1–64 χαρακτήρων στο JSON του POST. Επιστρέφεται δίπλα στο αντίστοιχο αποτέλεσμα της παρτίδας και πρέπει να είναι μοναδικό μέσα στην παρτίδα. Στις μεμονωμένες προβλέψεις γίνεται δεκτό, αλλά δεν επιστρέφεται. Δεν υποστηρίζεται στα ερωτήματα GET.

Το GenderAPI.io V2 δέχεται μαζί ονόματα, διευθύνσεις email και ονόματα χρήστη στο POST https://api.genderapi.io/api/v2/gender/batch. Στείλτε έναν πίνακα items με 1–50 στοιχεία αν χρησιμοποιείτε κλειδί API ή έως 10 με τη δοκιμαστική πρόσβαση IP. Κάθε στοιχείο χρησιμοποιεί type και value και μπορεί να έχει δικές του τιμές για country, forceToGenderize και options. Τα αναγνωριστικά είναι προαιρετικά και πρέπει να είναι μοναδικά μέσα στην παρτίδα.

Τα αποτελέσματα διατηρούν τη σειρά εισόδου και περιέχουν index, το προαιρετικό id σας, charged_credits και ακριβώς ένα από τα data και error. Μια απόκριση HTTP 200 μπορεί να περιέχει σφάλματα μεμονωμένων στοιχείων, γι' αυτό ελέγξτε κάθε στοιχείο. Το meta.summary αναφέρει τα total, succeeded, identified, unknown και failed. Μια άγνωστη πρόβλεψη είναι επιτυχές στοιχείο που χρεώνεται.

Αν η επικύρωση ή ο προγραμματισμός του αιτήματος αποτύχει, η παρτίδα απορρίπτεται πριν από τη χρέωση. Αν όλα τα στοιχεία που εκτελέστηκαν αποτύχουν, το API επιστρέφει μια απόκριση Problem με κατάσταση εκτός 2xx, έναν πίνακα data και το παλαιό ψευδώνυμο πεδίου results. Τα στοιχεία που απέτυχαν δεν κοστίζουν τίποτα μετά από επιβεβαιωμένη επιστροφή πιστώσεων. Αν η χρέωση δεν έχει επιβεβαιωθεί, μη θεωρείτε οριστικό το κόστος των μεμονωμένων στοιχείων.

Επιλέξτε γλώσσα προγραμματισμού. Ρυθμίστε το κλειδί API σας, και έπειτα εκτελέστε το παράδειγμα στον διακομιστή σας.

Κάθε αίτημα πρόβλεψης είναι μια νέα χρεώσιμη λειτουργία, ακόμη και όταν πρόκειται για νέα προσπάθεια. Αυτά τα παραδείγματα δεν επαναλαμβάνουν αυτόματα το αίτημα. Ελέγξτε την κατάσταση χρέωσης πριν στείλετε άλλο αίτημα.

Πριν από την εκτέλεση: πρόσβαση και χειρισμός σφαλμάτων

Εκτελέστε αυτά τα παραδείγματα στον διακομιστή σας. Ορίστε στο περιβάλλον της διεργασίας το GENDERAPI_API_KEY με το υπάρχον κλειδί API σας. Ελέγξτε ότι το meta.access.mode έχει την τιμή api_key, επειδή ένα κλειδί που δεν αναγνωρίζεται μπορεί να οδηγήσει στη δοκιμαστική πρόσβαση IP.

Στις αποκρίσεις JSON με HTTP 4xx και 5xx διατηρείται το σώμα του σφάλματος και το παράδειγμα τερματίζει με μη μηδενικό κωδικό εξόδου. Ελέγξτε τα code, action και meta.usage.billing_status πριν δοκιμάσετε ξανά. Στις αποκρίσεις παρτίδας με HTTP 200 ελέγξτε επίσης το data ή το error κάθε στοιχείου.

Οδηγός για σφάλματα και νέες προσπάθειες →

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": "Eleni",
      "country": "GR"
    },
    {
      "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
    }
  ]
}'

cURL 7.76+ σε κέλυφος POSIX. Εκτελέστε το στο τερματικό. Τεκμηρίωση του περιβάλλοντος εκτέλεσης

// 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": "Eleni",
      "country": "GR"
    },
    {
      "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.
}

Node.js 22+ με ενσωματωμένο fetch. Αποθηκεύστε ως example.mjs και εκτελέστε node example.mjs. Τεκμηρίωση του περιβάλλοντος εκτέλεσης

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\":\"Eleni\",\"country\":\"GR\"},{\"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.

Python 3.10+ με την τυπική βιβλιοθήκη. Αποθηκεύστε ως example.py και εκτελέστε python3 example.py. Τεκμηρίωση του περιβάλλοντος εκτέλεσης

<?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":"Eleni","country":"GR"},{"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.

PHP 8+ με την επέκταση cURL. Αποθηκεύστε ως example.php και εκτελέστε php example.php. Τεκμηρίωση του περιβάλλοντος εκτέλεσης

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\":\"Eleni\",\"country\":\"GR\"},{\"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.
    }
}

Java 17+ με τον τυπικό πελάτη HTTP. Αποθηκεύστε ως GenderApiExample.java και εκτελέστε java GenderApiExample.java. Τεκμηρίωση του περιβάλλοντος εκτέλεσης

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\":\"Eleni\",\"country\":\"GR\"},{\"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.
}

Εφαρμογή κονσόλας .NET 8+. Χρησιμοποιήστε το ως Program.cs σε ένα έργο κονσόλας και έπειτα εκτελέστε dotnet run. Τεκμηρίωση του περιβάλλοντος εκτέλεσης

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\":\"Eleni\",\"country\":\"GR\"},{\"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)
    }
}

Go 1.22+ με την τυπική βιβλιοθήκη. Αποθηκεύστε ως main.go και εκτελέστε go run main.go. Τεκμηρίωση του περιβάλλοντος εκτέλεσης

Ανάγνωση απόκρισης παρτίδας

Αυτό το παράδειγμα συνδυάζει δύο πραγματικά αποτελέσματα που λήφθηκαν την 1η Οκτωβρίου 2026, μια αντιστοίχιση στο σύνολο δεδομένων και ένα άγνωστο αποτέλεσμα, με ένα ενδεικτικό σφάλμα παρόχου. Δείχνει μια απόκριση HTTP 200 με μερική επιτυχία, όχι την αναμενόμενη έξοδο του παραπάνω αιτήματος παρτίδας. Τα δύο επιτυχή στοιχεία κοστίζουν 1 πίστωση το καθένα. Για το στοιχείο που απέτυχε έχει επιβεβαιωθεί μηδενική χρέωση.

{
  "data": [
    {
      "index": 0,
      "id": "known",
      "charged_credits": 1,
      "data": {
        "input": {
          "type": "name",
          "value": "Eleni",
          "country": "GR"
        },
        "name": "eleni",
        "gender": "female",
        "country": "GR",
        "confidence": 0.9965940054495913,
        "confidence_kind": "observed_frequency",
        "sample_count": 1468,
        "source": "dataset",
        "result_status": "identified",
        "reason": null,
        "country_source": "dataset",
        "match": {
          "name": "eleni",
          "method": "normalized",
          "scope": "country",
          "country": "GR"
        }
      }
    },
    {
      "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
    }
  }
}

Πεδία αποτελεσμάτων παρτίδας

Πεδίο	Τύπος	Μπορεί να είναι null	Παράδειγμα	Περιγραφή
`data`	`array<object>`	Όχι	`[…]`	Αποτελέσματα με τη σειρά εισόδου. Κάθε στοιχείο περιέχει μια πρόβλεψη ή ένα σφάλμα, γι' αυτό ελέγξτε όλα τα στοιχεία.
`data[].index`	`integer`	Όχι	`0`	Θέση στον πίνακα items που στάλθηκε, με αρίθμηση από το μηδέν.
`data[].id`	`string`	Όχι	`"contact-1"`	Το αναγνωριστικό εισόδου σας. Υπάρχει μόνο αν το δώσατε.
`data[].charged_credits`	`integer`	Όχι	`1`	Καθαρή χρέωση του στοιχείου μετά τις επιβεβαιωμένες επιστροφές πιστώσεων. Μην τη θεωρείτε οριστική αν η συνολική χρέωση δεν έχει επιβεβαιωθεί.
`data[].data`	`object`	Όχι	`{…}`	Υπάρχει για ένα επιτυχές στοιχείο, και για άγνωστα αποτελέσματα. Χρησιμοποιεί τα πεδία πρόβλεψης που περιγράφονται στον οδηγό αποκρίσεων.
`data[].error`	`object`	Όχι	`{…}`	Υπάρχει αντί του data για ένα στοιχείο που απέτυχε. Χρησιμοποιεί τα πεδία Problem Details που περιγράφονται στον οδηγό σφαλμάτων.

Πεδία σύνοψης παρτίδας

Πεδίο	Τύπος	Μπορεί να είναι null	Παράδειγμα	Περιγραφή
`meta.summary.total`	`integer`	Όχι	`3`	Συνολικός αριθμός στοιχείων στην παρτίδα.
`meta.summary.succeeded`	`integer`	Όχι	`2`	Επιτυχή στοιχεία, μαζί με τις άγνωστες προβλέψεις.
`meta.summary.identified`	`integer`	Όχι	`1`	Επιτυχή στοιχεία με φύλο διαφορετικό από null.
`meta.summary.unknown`	`integer`	Όχι	`1`	Επιτυχή στοιχεία με gender null. Αυτά τα αποτελέσματα χρεώνονται.
`meta.summary.failed`	`integer`	Όχι	`1`	Στοιχεία που απέτυχαν. Ισχύει total = succeeded + failed και succeeded = identified + unknown.

Μεταδεδομένα πρόσβασης, χρέωσης και αιτήματος

Πεδίο	Τύπος	Μπορεί να είναι null	Παράδειγμα	Περιγραφή
`meta.request_id`	`string`	Όχι	`"550e8400-e29b-41d4-a716-446655440000"`	Μοναδικό αναγνωριστικό αυτής της απόπειρας HTTP. Αποστέλλεται και στο X-Request-ID.
`meta.duration_ms`	`integer`	Όχι	`42`	Χρόνος επεξεργασίας του αιτήματος σε χιλιοστά του δευτερολέπτου.
`meta.access.mode`	`string`	Όχι	`"api_key"`	api_key, ip_trial ή unauthenticated. Με λογαριασμό επί πληρωμή ελέγξτε ότι επιστρέφεται api_key.
`meta.access.reason`	`string`	Ναι	`null`	Λόγος μετάβασης στη δοκιμαστική πρόσβαση IP: api_key_missing, api_key_invalid ή api_key_not_found. Διαφορετικά null.
`meta.usage.charged_credits`	`integer`	Ναι	`1`	Καθαρές πιστώσεις που χρεώθηκαν. Μηδέν πριν από τη χρέωση ή μετά από πλήρη επιβεβαιωμένη επιστροφή πιστώσεων. null όταν η χρέωση δεν έχει επιβεβαιωθεί.
`meta.usage.remaining_credits`	`integer`	Ναι	`99`	Υπόλοιπο κατά την ολοκλήρωση της λειτουργίας. Μπορεί να είναι αρνητικό. null αν δεν είναι διαθέσιμο ή αν η χρέωση δεν έχει επιβεβαιωθεί.
`meta.usage.billing_status`	`string`	Όχι	`"confirmed"`	not_charged, confirmed ή unconfirmed. Ελέγξτε το πριν επαναλάβετε μια πρόβλεψη που απέτυχε.
`meta.usage.resets_at`	`string`	Ναι	`"2026-09-27T12:00:00.000Z"`	Χρονική στιγμή επαναφοράς της δοκιμαστικής πρόσβασης IP σε UTC (ISO 8601). null για λογαριασμούς με κλειδί API ή όταν είναι άγνωστη.
`meta.usage.limit`	`integer`	Ναι	`10`	Όριο πιστώσεων της δοκιμαστικής πρόσβασης IP. null για λογαριασμούς με κλειδί API.
`meta.usage.period_seconds`	`integer`	Ναι	`86400`	Διάρκεια της περιόδου της δοκιμαστικής πρόσβασης IP σε δευτερόλεπτα. null για λογαριασμούς με κλειδί API.

Προγραμματισμός πιστώσεων και νέων προσπαθειών για παρτίδες

Πραγματοποιήστε έλεγχο ταυτότητας με το υπάρχον κλειδί API σας στην κεφαλίδα Bearer και στείλτε Content-Type: application/json. Κάθε παρτίδα που αποστέλλεται είναι νέα λειτουργία. Αν δοκιμάσετε ξανά μετά από μερικό σφάλμα, στείλτε μόνο τα στοιχεία που απέτυχαν, αφού ελέγξετε τη χρέωση. Τα επιτυχή στοιχεία που αποστέλλονται ξανά χρεώνονται για δεύτερη φορά.

Στα στοιχεία μιας παρτίδας το AI είναι από προεπιλογή off και κάθε επιτυχές στοιχείο κοστίζει 1 πίστωση. Και το ρητό fallback κοστίζει συνολικά 1 πίστωση, μαζί με το AI. Το always κοστίζει 2 πιστώσεις. Το forceToGenderize κοστίζει 1 πίστωση για αποτέλεσμα από το σύνολο δεδομένων ή 2 αν χρησιμοποιηθεί AI. Τα επιτυχή άγνωστα αποτελέσματα χρεώνονται. Για να ξεκινήσει η παρτίδα αρκεί ένα θετικό αρχικό υπόλοιπο 1 πίστωσης. Η τελική χρέωση μπορεί να αφήσει αρνητικό υπόλοιπο.

Επεξεργασία μιας λίστας επαφών χωρίς να χαθεί καμία γραμμή

Το endpoint παρτίδας χειρίζεται λίστες μόνο με ονόματα, λίστες μόνο με διευθύνσεις email και μικτές εισόδους. Με κλειδί API χωρίστε την εργασία σε παρτίδες έως 50 στοιχείων. Η δοκιμαστική πρόσβαση IP επιτρέπει έως 10 ανά αίτημα. Καταγράφετε σε ποιο σημείο της εργασίας βρίσκεστε και δώστε σε κάθε στοιχείο ένα id μοναδικό μέσα στην παρτίδα. Το index που επιστρέφεται ξεκινά από το μηδέν μέσα στην παρτίδα που στάλθηκε, όχι μέσα σε ολόκληρη τη λίστα επαφών.

Βήμα	Τι να αποθηκεύσετε ή να ελέγξετε	Γιατί έχει σημασία
1. Προετοιμάστε κάθε παρτίδα	Κρατήστε τη γραμμή προέλευσης και το id του στοιχείου. Ορίστε country και επιλογές AI για κάθε στοιχείο.	Μη θεωρείτε δεδομένο ότι ένα όνομα είναι μοναδικό σε όλες τις επαφές.
2. Διαβάστε ολόκληρη την απόκριση	Αποθηκεύστε το meta.request_id και αντιστοιχίστε κάθε στοιχείο του data[] μέσω του id ή του index.	Μια απόκριση HTTP 200 μπορεί να περιέχει τόσο επιτυχείς προβλέψεις όσο και σφάλματα μεμονωμένων στοιχείων.
3. Αποθηκεύστε τα επιτυχή αποτελέσματα	Διατηρήστε τις προβλέψεις identified και unknown, μαζί με τις τιμές JSON null και τα πεδία των τεκμηρίων.	Ένα άγνωστο αποτέλεσμα έχει ολοκληρωθεί και χρεωθεί. Δεν είναι γραμμή που απέτυχε και πρέπει να σταλεί ξανά αυτόματα.
4. Συμφωνήστε σφάλματα και πιστώσεις	Ελέγξτε κάθε error και το meta.usage.billing_status πριν αποφασίσετε αν θα στείλετε νέο αίτημα.	Αφού επιβεβαιωθεί η χρέωση, δοκιμάστε ξανά μόνο τα στοιχεία που απέτυχαν και των οποίων το σφάλμα το δικαιολογεί. Τα επιτυχή στοιχεία θα χρεώνονταν ξανά.
5. Αναβάλετε τις αβέβαιες νέες προσπάθειες	Αποθηκεύστε το αναγνωριστικό του αιτήματος αν η χρέωση δεν έχει επιβεβαιωθεί ή αν ένα σφάλμα δικτύου αφήνει άγνωστη την έκβαση.	Μη στέλνετε ξανά στα τυφλά ολόκληρη την παρτίδα. Ακολουθήστε πρώτα τις οδηγίες για σφάλματα και χρεώσεις.

Επιλογή λειτουργίας πρόβλεψης για κάθε επαφή

Αυτό το εκτελέσιμο αίτημα χρησιμοποιεί τρεις διαφορετικούς κανόνες: μόνο σύνολο δεδομένων για ένα πλήρες όνομα, κανονική εφεδρική χρήση AI για μια διεύθυνση email και εφεδρική χρήση AI με ανάλυση ψευδωνύμων για ένα όνομα χρήστη. Πρόκειται για παραδείγματα εισόδων, όχι για υπόσχεση ότι και οι τρεις επαφές θα λάβουν φύλο. Επιλέξτε μια γλώσσα προγραμματισμού πάνω από τον κώδικα και ορίστε το GENDERAPI_API_KEY πριν εκτελέσετε το παράδειγμα.

Χωρίς το forceToGenderize, το AI είναι από προεπιλογή off στα στοιχεία μιας παρτίδας, σε αντίθεση με τις μεμονωμένες αναζητήσεις. Ορίστε ρητά fallback αν θέλετε την κανονική εφεδρική χρήση AI. Τόσο το off όσο και το κανονικό fallback κοστίζουν 1 πίστωση ανά επιτυχές στοιχείο. Το always παραλείπει το σύνολο δεδομένων και κοστίζει 2. Το forceToGenderize κοστίζει 1 για αποτέλεσμα από το σύνολο δεδομένων ή 2 συνολικά αν χρησιμοποιηθεί AI. Και τα επιτυχή άγνωστα αποτελέσματα χρεώνονται. Μη συνδυάζετε το forceToGenderize με off ή always.