이름, 이메일 주소, 사용자 이름 일괄 추정

이름, 이메일 주소, 사용자 이름 일괄 처리

매개변수	유형	필수	기본값	설명
`items`	`array<object>`	예	`—`	추정 항목 1~50개이며, IP 체험에서는 최대 10개입니다. 결과는 입력 순서를 유지합니다.
`items[].type`	`string`	예	`—`	입력 종류: name, email 또는 username.
`items[].value`	`string`	예	`—`	필수. 1~254자이며 공백만으로 이루어질 수 없고 제어 문자를 포함할 수 없습니다. 이메일 값은 올바른 이메일 구문이어야 합니다.
`items[].country`	`string`	아니요	`—`	선택 사항. TR이나 US 같은 대문자 ISO 3166-1 alpha-2 코드입니다. 국가별 조회는 전역 데이터셋으로 대체될 수 있습니다.
`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`	아니요	`—`	POST JSON에서 쓸 수 있는 1~64자의 선택적 식별자입니다. 일괄 요청에서는 각 결과와 함께 반환되며 일괄 요청 안에서 고유해야 합니다. 단일 추정 요청에서는 받기만 하고 응답에 다시 포함하지 않습니다. GET 쿼리에서는 지원하지 않습니다.

POST /gender/batch는 API 키로 접근하면 1~50개, IP 체험에서는 최대 10개의 항목이 담긴 items 배열을 받습니다. 이름만, 이메일 주소만, 사용자 이름만 보내거나 세 가지를 섞어 보낼 수 있습니다. 각 항목마다 country, forceToGenderize, options를 따로 지정합니다. ID는 선택 사항이며 고유해야 합니다.

결과는 입력 순서를 유지하며 index, 선택적으로 지정한 id, charged_credits, 그리고 data와 error 중 정확히 하나를 포함합니다. HTTP 200에도 항목 단위 실패가 포함될 수 있으므로 모든 항목을 확인하세요. meta.summary에는 total, succeeded, identified, unknown, failed가 보고됩니다. 알 수 없는 추정도 성공한 과금 대상 항목입니다.

요청 검증이나 처리 계획이 실패하면 차감 전에 일괄 요청 전체가 거부됩니다. 실행된 항목이 모두 실패하면 API는 data 배열과 기존 호환용 별칭 results가 포함된, 2xx가 아닌 Problem 응답을 반환합니다. 실패한 항목은 크레딧 반환이 확인되면 비용이 0입니다. 과금이 미확정이면 항목별 차감액이 최종이라고 가정하지 마세요.

프로그래밍 언어를 선택하세요. API 키 설정하기, 그다음 서버에서 예시를 실행하세요.

재시도를 포함해 모든 추정 요청은 새로 과금되는 작업입니다. 이 예시는 자동으로 재시도하지 않습니다. 다른 요청을 보내기 전에 과금 상태를 확인하세요.

실행하기 전에: 접근과 오류 처리

이 예시는 서버에서 실행하세요. 프로세스 환경 변수 GENDERAPI_API_KEY에 기존 API 키를 설정하세요. 인식되지 않는 키는 IP 체험으로 전환될 수 있으므로 meta.access.mode가 api_key인지 확인하세요.

HTTP 4xx 및 5xx JSON 응답에서는 오류 본문을 그대로 출력하고 0이 아닌 종료 코드를 반환합니다. 재시도하기 전에 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": "Seoyeon",
      "country": "KR"
    },
    {
      "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
    }
  ]
}'

POSIX 셸의 cURL 7.76+. 터미널에서 실행하세요. 런타임 문서

// 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": "Seoyeon",
      "country": "KR"
    },
    {
      "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\":\"Seoyeon\",\"country\":\"KR\"},{\"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":"Seoyeon","country":"KR"},{"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\":\"Seoyeon\",\"country\":\"KR\"},{\"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\":\"Seoyeon\",\"country\":\"KR\"},{\"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\":\"Seoyeon\",\"country\":\"KR\"},{\"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를 실행하세요. 런타임 문서

일괄 응답 읽기

이 예시는 2026년 10월 1일에 받은 실제 결과 두 개(데이터셋 일치와 알 수 없는 결과)에 설명용 제공업체 오류를 결합한 것입니다. 위 일괄 요청의 예상 출력이 아니라, 일부만 성공한 HTTP 200 응답을 보여 줍니다. 성공한 두 항목은 각각 1크레딧이며, 실패한 항목은 차감액 0이 확정되었습니다.

{
  "data": [
    {
      "index": 0,
      "id": "known",
      "charged_credits": 1,
      "data": {
        "input": {
          "type": "name",
          "value": "Seoyeon",
          "country": "KR"
        },
        "name": "seoyeon",
        "gender": "female",
        "country": "KR",
        "confidence": 1,
        "confidence_kind": "observed_frequency",
        "sample_count": 33,
        "source": "dataset",
        "result_status": "identified",
        "reason": null,
        "country_source": "dataset",
        "match": {
          "name": "seoyeon",
          "method": "normalized",
          "scope": "country",
          "country": "KR"
        }
      }
    },
    {
      "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 배열에서의 위치이며 0부터 시작합니다.
`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`	성별이 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`	차감된 순 크레딧입니다. 차감 전이나 전액 반환이 확인된 뒤에는 0이며, 과금이 미확정이면 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)입니다. API 키 계정이거나 알 수 없으면 null입니다.
`meta.usage.limit`	`integer`	예	`10`	IP 체험 크레딧 한도이며, API 키 계정에서는 null입니다.
`meta.usage.period_seconds`	`integer`	예	`86400`	IP 체험 기간(초)이며, API 키 계정에서는 null입니다.

일괄 요청 크레딧과 재시도 계획

기존 Bearer API 키로 인증하고 Content-Type: application/json을 보내세요. 제출하는 일괄 요청은 매번 새 작업입니다. 부분 실패를 재시도할 때는 과금을 확인한 뒤 실패한 항목만 제출하세요. 성공한 항목을 다시 보내면 다시 과금됩니다.

일괄 요청 항목은 기본적으로 AI가 off이며, 성공한 항목당 1크레딧입니다. fallback을 명시해도 AI를 포함해 총 1크레딧입니다. always는 2크레딧입니다. forceToGenderize는 데이터셋에서 결과를 얻으면 1크레딧, AI를 사용하면 2크레딧입니다. 성공한 알 수 없는 결과도 과금됩니다. 잔액이 1크레딧만 있어도 일괄 요청을 시작할 수 있으며, 최종 차감 후 잔액이 음수가 될 수 있습니다.

연락처 목록을 처리하면서 모든 행의 결과를 빠짐없이 관리하기

일괄 요청 엔드포인트는 이름만 있는 목록, 이메일 주소만 있는 목록, 여러 입력이 섞인 목록을 처리합니다. API 키를 사용하는 작업은 최대 50개 항목 단위로 나누고, IP 체험에서는 요청당 최대 10개입니다. 작업 내 위치는 직접 저장하고, 각 항목에는 해당 일괄 요청 안에서 고유한 id를 지정하세요. 반환되는 index는 제출한 그 묶음 안에서 0부터 시작하는 위치이며, 연락처 목록 전체에서의 위치가 아닙니다.

단계	저장하거나 확인할 내용	중요한 이유
1. 각 묶음 준비하기	원본 행과 항목 id를 보존하고, 항목마다 country와 AI 옵션을 설정합니다.	이름이 연락처 전체에서 고유하다고 가정하지 마세요.
2. 응답 전체 읽기	meta.request_id를 저장하고 id 또는 index로 data[]의 각 항목을 연결합니다.	HTTP 200에도 성공한 추정과 항목 오류가 함께 들어 있을 수 있습니다.
3. 성공한 결과 저장하기	identified와 unknown 추정을 JSON null과 근거 필드까지 포함해 보관합니다.	알 수 없는 결과는 완료되어 과금된 결과이며, 자동으로 재시도할 실패 행이 아닙니다.
4. 오류와 크레딧 대조하기	다음 요청을 결정하기 전에 각 error와 meta.usage.billing_status를 확인합니다.	과금이 확정되면 재시도가 적절한 오류가 난 실패 항목만 재시도하세요. 성공한 항목은 다시 과금됩니다.
5. 불확실한 재시도 보류하기	과금이 미확정이거나 네트워크 오류로 결과를 알 수 없으면 요청 ID를 보관합니다.	묶음 전체를 무작정 다시 보내지 말고 먼저 오류 및 과금 가이드를 따르세요.

연락처마다 추정 모드 선택하기

이 실행 가능한 요청은 세 가지 방식을 사용합니다. 전체 이름에는 데이터셋 전용, 이메일 주소에는 일반 AI 폴백, 사용자 이름에는 별명을 해석하는 폴백을 사용합니다. 이는 입력 예시일 뿐이며 세 연락처 모두에 성별이 반환된다는 약속이 아닙니다. 코드 위에서 프로그래밍 언어를 선택하고, 실행하기 전에 GENDERAPI_API_KEY를 설정하세요.

forceToGenderize를 사용하지 않으면 일괄 요청 항목은 단일 조회와 달리 기본적으로 AI가 off입니다. 일반 AI 폴백을 사용하려면 fallback을 명시하세요. off와 일반 폴백은 모두 성공한 항목당 1크레딧이며, always는 데이터셋을 건너뛰고 2크레딧입니다. forceToGenderize는 데이터셋에서 결과를 얻으면 1크레딧, AI를 사용하면 총 2크레딧입니다. 성공한 알 수 없는 결과도 과금됩니다. forceToGenderize를 off나 always와 함께 쓰지 마세요.