Gênero por nome de usuário e apelido

Entradas de exemplo

Um apelido não é uma verificação de identidade

@alice_smith pode corresponder a um componente de nome. Para prenses com forceToGenderize, pode ser retornada uma previsão mesmo que o nome continue null. user47291 pode continuar desconhecido. São entradas de exemplo; não atribuímos a elas nenhum resultado de gênero de antemão.

Lógica da análise

Como funciona a previsão de gênero a partir de um nome de usuário?

O sistema procura componentes de nome reconhecíveis e outros indícios linguísticos no nome de usuário ou no nome de exibição. O fallback de IA comum procura um nome real utilizável; com forceToGenderize, a IA pode interpretar um apelido sem um nome real. O resultado é retornado com os campos de contexto; uma entrada aleatória ou insuficiente não deve ser forçada a produzir um resultado.

01Nome de usuárioApelido ou nome de exibição

02Análise de sinaisNome e contexto

03PrevisãoGênero e confiança

Formas de uso

Escolha o método adequado aos seus dados

Requisição individualAnalise um nome de usuário pela REST API.Ver o guia da API →Requisição em loteEnvie vários itens em uma única requisição estruturada.Ver o guia de lotes →Fluxo de Excel/CSVProcesse um arquivo sem desenvolver uma integração.Abrir a ferramenta →

Processe grandes conjuntos de dados sem código

Analise os nomes de usuário de um arquivo Excel ou CSV em quatro etapas

01
Abra a ferramenta de Excel/CSV
Abra a ferramenta de importação da GenderAPI e envie o arquivo que deseja processar.
02
Selecione a coluna de origem
Mapeie a coluna que contém nomes de usuário, apelidos ou nomes de exibição.
03
Ative a interpretação de apelidos
Habilite a opção que interpreta aliases e nomes usados em redes sociais.
04
Revise uma amostra e depois exporte
Revise primeiro uma amostra representativa de registros, depois processe o arquivo inteiro e baixe os dados enriquecidos.

Novas contas incluem 200 créditos gratuitos de API por dia, para que você possa testar o fluxo com uma amostra antes de processar o arquivo inteiro.

Casos de uso

Use como sinal complementar quando falta um nome real

A análise de nomes de usuário pode ser útil em dados de redes sociais, comunidades, jogos e perfis criados pelos próprios usuários quando o campo de nome está vazio. Se você tiver uma fonte mais direta e autorizada, como um nome real ou um endereço de e-mail, use o endpoint correspondente.

Limitações

Não trate o resultado como uma identidade verificada

Nem todo apelido contém um nome real, as associações culturais variam e a mesma expressão pode ter significados diferentes em idiomas diferentes. Se o sinal for insuficiente, aceite um resultado vazio em vez de transformar dados fracos em uma conclusão definitiva.

Guia de implementação da V2

Guarde os dados de origem e a previsão separadamente

Mantenha o identificador original do registro. A API não abre nenhum perfil, não verifica quem é o titular de uma conta e não confirma nenhuma identidade. Envie um contexto de país somente quando tiver uma informação confiável; não o deduza do domínio nem do idioma do site.

Entrada de exemplo	Campo ou opção	Interpretação
@alice_smith	data.name / data.match	Preserve o nome de usuário original; não trate o fragmento encontrado como um nome verificado.
prenses	forceToGenderize: true	Permite interpretar um apelido sem um nome real. Pode ser retornado um gênero com data.name igual a null; não invente um nome para a pessoa.
user47291	data.result_status: unknown	Uma entrada ambígua ou insuficiente pode continuar desconhecida. Isso não é motivo para reenviar a requisição automaticamente.

Envie o nome de usuário com type: username; não envie a URL de um perfil. A consulta ao conjunto de dados remove um @ inicial, normaliza o texto e gera candidatos a partir de separadores e dígitos. Uma requisição padrão pode acrescentar um número limitado de correspondências a partir de prefixos e sufixos; forceToGenderize não usa esses fragmentos adicionais. Se várias linhas corresponderem, é escolhida a que tem o maior número de ocorrências registradas. Use type: email para endereços de e-mail e type: name para nomes reais.

Escolha o modo de processamento e o custo em créditos

Opção	Processamento	Custo por item concluído
options.ai_mode: off	Somente o conjunto de dados	1 crédito
options.ai_mode: fallback	Primeiro o conjunto de dados; se não for possível determinar um gênero, fallback de IA comum	1 crédito no total, incluindo a IA
options.ai_mode: always	Diretamente para a IA	2 créditos
forceToGenderize: true	Primeiro o conjunto de dados; depois, interpretação do apelido sem exigir um nome real	1 se o conjunto de dados bastar; 2 no total se a IA for usada

Em uma requisição individual, o padrão é fallback; nos itens de um lote, off. forceToGenderize é opcional para nomes, endereços de e-mail e nomes de usuário; nesse caso, omita ai_mode ou use fallback, porque a opção não pode ser combinada com off nem com always. Resultados unknown concluídos também são cobrados. Um saldo inicial positivo basta para começar; ao final da operação, o saldo pode ficar negativo.

Defina as opções de cada item de um lote

Uma entrada de exemplo não garante uma previsão específica. Defina GENDERAPI_API_KEY no ambiente do servidor e não coloque a chave em código público do lado do cliente. A V1 e a V2 usam a mesma chave da conta e o mesmo saldo. Verifique a chave com /api/v2/usage e confirme que meta.access.mode tem o valor api_key.

Escolha uma linguagem de programação. Configure sua chave de API, depois execute o exemplo no seu servidor.

Cada requisição de previsão é uma nova operação cobrada, inclusive as novas tentativas. Estes exemplos não fazem novas tentativas automaticamente. Verifique o status da cobrança antes de enviar outra requisição.

Antes de executar: acesso e tratamento de erros

Execute estes exemplos no seu servidor. Defina GENDERAPI_API_KEY no ambiente do processo com a sua chave de API existente. Confirme que meta.access.mode é api_key: uma chave não reconhecida pode levar ao teste por IP.

Respostas JSON com HTTP 4xx e 5xx preservam o corpo do erro e retornam um código de saída diferente de zero. Verifique code, action e meta.usage.billing_status antes de fazer uma nova tentativa. Em respostas de lote com HTTP 200, verifique também data ou error de cada item.

Guia de erros e novas tentativas →

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": "profile-001",
      "type": "username",
      "value": "@alice_smith",
      "options": {
        "ai_mode": "off"
      }
    },
    {
      "id": "profile-002",
      "type": "username",
      "value": "alexriver",
      "options": {
        "ai_mode": "fallback"
      }
    },
    {
      "id": "profile-003",
      "type": "username",
      "value": "prenses",
      "country": "TR",
      "forceToGenderize": true
    }
  ]
}'

cURL 7.76+ em um shell POSIX. Execute no seu terminal. Documentação do ambiente de execução

// 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": "profile-001",
      "type": "username",
      "value": "@alice_smith",
      "options": {
        "ai_mode": "off"
      }
    },
    {
      "id": "profile-002",
      "type": "username",
      "value": "alexriver",
      "options": {
        "ai_mode": "fallback"
      }
    },
    {
      "id": "profile-003",
      "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 nativo. Salve como example.mjs e execute node example.mjs. Documentação do ambiente de execução

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\":\"profile-001\",\"type\":\"username\",\"value\":\"@alice_smith\",\"options\":{\"ai_mode\":\"off\"}},{\"id\":\"profile-002\",\"type\":\"username\",\"value\":\"alexriver\",\"options\":{\"ai_mode\":\"fallback\"}},{\"id\":\"profile-003\",\"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+; biblioteca padrão. Salve como example.py e execute python3 example.py. Documentação do ambiente de execução

<?php
$apiKey = getenv('GENDERAPI_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set GENDERAPI_API_KEY');
}
$body = json_decode('{"items":[{"id":"profile-001","type":"username","value":"@alice_smith","options":{"ai_mode":"off"}},{"id":"profile-002","type":"username","value":"alexriver","options":{"ai_mode":"fallback"}},{"id":"profile-003","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+ com a extensão cURL. Salve como example.php e execute php example.php. Documentação do ambiente de execução

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\":\"profile-001\",\"type\":\"username\",\"value\":\"@alice_smith\",\"options\":{\"ai_mode\":\"off\"}},{\"id\":\"profile-002\",\"type\":\"username\",\"value\":\"alexriver\",\"options\":{\"ai_mode\":\"fallback\"}},{\"id\":\"profile-003\",\"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+; cliente HTTP padrão. Salve como GenderApiExample.java e execute java GenderApiExample.java. Documentação do ambiente de execução

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\":\"profile-001\",\"type\":\"username\",\"value\":\"@alice_smith\",\"options\":{\"ai_mode\":\"off\"}},{\"id\":\"profile-002\",\"type\":\"username\",\"value\":\"alexriver\",\"options\":{\"ai_mode\":\"fallback\"}},{\"id\":\"profile-003\",\"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.
}

Aplicação de console .NET 8+. Use como Program.cs em um projeto de console e depois execute dotnet run. Documentação do ambiente de execução

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\":\"profile-001\",\"type\":\"username\",\"value\":\"@alice_smith\",\"options\":{\"ai_mode\":\"off\"}},{\"id\":\"profile-002\",\"type\":\"username\",\"value\":\"alexriver\",\"options\":{\"ai_mode\":\"fallback\"}},{\"id\":\"profile-003\",\"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+; biblioteca padrão. Salve como main.go e execute go run main.go. Documentação do ambiente de execução

Trate os resultados de listas e de requisições repetidas

POST /api/v2/gender/batch aceita até 50 itens com uma chave de API e 10 com o teste por IP. Informe valores próprios de type, value e options em cada item. Se quiser usar o fallback de IA comum, defina fallback explicitamente em cada item. id deve ser único dentro do lote; index começa em zero dentro do lote enviado. Guarde separadamente os seus próprios identificadores de job e de linha de origem.

HTTP 200 não significa que todos os itens foram concluídos. Trate os resultados identified, unknown e error separadamente; meta.summary.succeeded conta tanto identified quanto unknown. Avalie data.gender, source, confidence_kind, confidence, match e reason em conjunto. Não trate uma pontuação da IA e uma frequência no conjunto de dados como equivalentes.

Se meta.usage.billing_status tiver o valor confirmed, repita somente os erros operacionais que permitem uma nova requisição. Se o status for unconfirmed ou se a resposta tiver sido perdida, pare e verifique a cobrança. Reenviar o mesmo item, inclusive um resultado unknown concluído, cria uma nova operação paga; nunca reenvie a lista inteira às cegas.

Contrato das requisições em lote · Campos da resposta · Opções de IA · Avaliação de precisão e confiança · Política de Privacidade

Os complementos para Excel e Google Sheets e as demais integrações prontas podem usar a própria conexão e o próprio formato de resultado. Não presuma que a saída deles segue este esquema JSON da V2; consulte o guia atual da integração correspondente.

Perguntas frequentes

Gênero a partir de um nome de usuário ou apelido

É possível determinar o gênero a partir de um nome de usuário?

Se você ativar forceToGenderize na V2, o conjunto de dados é consultado primeiro; se não for possível determinar um gênero, a IA pode interpretar o apelido sem exigir um nome real. O resultado pode continuar unknown e não é uma identidade verificada. O fallback de IA comum, por outro lado, exige um nome real utilizável.

Quais nomes de usuário oferecem os resultados mais úteis?

Um sinal mais útil pode vir de valores que contêm um nome real, uma forma reconhecível de apelido ou um componente nominal claro. Sequências aleatórias de caracteres e nomes de marcas nem sempre produzem um resultado.

Posso analisar um único nome de usuário pela API?

Sim. O endpoint de requisições individuais analisa um item. Para vários itens, existe um endpoint específico de requisições em lote.

Posso importar um arquivo Excel ou CSV?

Sim. Na ferramenta de arquivos, você pode escolher a coluna de nomes de usuário ou de nomes de exibição e ativar a interpretação de apelidos.

Por que devo guardar juntos os campos de confiança e de fonte da V2?

Na V2, data.confidence fica entre 0 e 1. Avalie o valor junto com source e confidence_kind, porque uma pontuação da IA e uma frequência no conjunto de dados são medidas diferentes. Preserve os resultados unknown e o campo reason.

O resultado é adequado para segmentação?

Ele pode ser usado como sinal complementar em análises agregadas e no enriquecimento de dados, mas não deve decidir sozinho questões de alto impacto para uma pessoa nem afirmar a identidade dela.

Posso testar o serviço gratuitamente?

Novas contas da GenderAPI incluem 200 créditos gratuitos de API por dia, que você pode usar para testar amostras representativas pela API ou por arquivos.

Previsão de gênero a partir de nomes de usuário e apelidos

Analise os apelidos do seu conjunto de dados