# Previsão de gênero a partir de nomes de usuário e apelidos > Analise nomes de usuário e apelidos com a V2: forceToGenderize, IA por item, resultados desconhecidos e o custo de requisições repetidas. Canonical HTML: https://www.genderapi.io/pt/blog/previsao-de-genero-a-partir-de-apelidos-e-nomes-de-usuario Last reviewed: 2026-09-29 ## Informações da publicação Primeira publicação: 2025-06-04T13:00:00.000Z Última revisão: 2026-09-29T00:00:00.000Z ## É possível determinar o gênero a partir de um nome de usuário? A GenderAPI pode analisar sinais de nome em um nome de usuário, apelido ou nome de exibição quando falta um nome real. Use a API para requisições individuais ou em lote, ou o fluxo de Excel/CSV, e trate o resultado como uma previsão, não como uma identidade verificada. ## 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. ## 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. - Nome de usuário: Apelido ou nome de exibição - Análise de sinais: Nome e contexto - Previsão: Gênero e confiança ## Escolha o método adequado aos seus dados - [Requisição individual Analise um nome de usuário pela REST API. Ver o guia da API →](https://www.genderapi.io/pt/docs/v2/gender-from-username) - [Requisição em lote Envie vários itens em uma única requisição estruturada. Ver o guia de lotes →](https://www.genderapi.io/pt/docs/v2/batch) - [Fluxo de Excel/CSV Processe um arquivo sem desenvolver uma integração. Abrir a ferramenta →](https://app.genderapi.io/csv) ## Analise os nomes de usuário de um arquivo Excel ou CSV em quatro etapas ### Abra a ferramenta de Excel/CSV Abra a ferramenta de importação da GenderAPI e envie o arquivo que deseja processar. ### Selecione a coluna de origem Mapeie a coluna que contém nomes de usuário, apelidos ou nomes de exibição. ### Ative a interpretação de apelidos Habilite a opção que interpreta aliases e nomes usados em redes sociais. ### 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. Os arquivos Excel e CSV enviados são removidos dos sistemas ativos em até cinco dias e, depois de exportar os resultados, você pode solicitar a remoção antecipada. Backups rotativos de acesso restrito podem contê-los por até 15 dias adicionais. Saiba mais na [Política de Privacidade](https://www.genderapi.io/pt/privacy-policy). ## 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. - [Extraia um nome e um sinal de gênero de um endereço de e-mail](https://www.genderapi.io/pt/blog/extrair-nomes-de-enderecos-de-email) - [Processe arquivos Excel e CSV em lote](https://www.genderapi.io/pt/blog/determining-gender-of-names-in-excel-csv-with-gender-api) ## 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. Guarde juntos os campos de confiança e de fonte da V2, meça o desempenho com os seus próprios dados e não baseie neste sinal uma decisão de alto impacto para uma pessoa, por exemplo sobre emprego, crédito ou saúde. ## 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. 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. | 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. | ### Escolha o modo de processamento e o custo em créditos 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. | 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 | ### 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](https://www.genderapi.io/pt/docs/v2/authentication#environment-setup), 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. **cURL** cURL 7.76+ em um shell POSIX. Execute no seu terminal. [Documentação do ambiente de execução](https://curl.se/docs/manpage.html) ```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": "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 } ] }' ``` **JavaScript / Node.js** Node.js 22+; fetch nativo. Salve como example.mjs e execute node example.mjs. [Documentação do ambiente de execução](https://nodejs.org/api/globals.html#fetch) ```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": "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. } ``` **Python** Python 3.10+; biblioteca padrão. Salve como example.py e execute python3 example.py. [Documentação do ambiente de execução](https://docs.python.org/3/library/urllib.request.html) ```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\":\"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. ``` **PHP** PHP 8+ com a extensão cURL. Salve como example.php e execute php example.php. [Documentação do ambiente de execução](https://www.php.net/manual/en/book.curl.php) ```php '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+; cliente HTTP padrão. Salve como GenderApiExample.java e execute java GenderApiExample.java. [Documentação do ambiente de execução](https://docs.oracle.com/en/java/javase/17/docs/api/java.net.http/java/net/http/HttpClient.html) ```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\":\"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 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** 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](https://learn.microsoft.com/en-us/dotnet/fundamentals/networking/http/httpclient) ```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\":\"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. } ``` **Go** Go 1.22+; biblioteca padrão. Salve como main.go e execute go run main.go. [Documentação do ambiente de execução](https://pkg.go.dev/net/http) ```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\":\"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) } } ``` - [Guia de erros e novas tentativas →](https://www.genderapi.io/pt/docs/v2/errors-and-retries) ### 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](https://www.genderapi.io/pt/docs/v2/batch) · [Campos da resposta](https://www.genderapi.io/pt/docs/v2/responses) · [Opções de IA](https://www.genderapi.io/pt/docs/v2/ai-options) · [Avaliação de precisão e confiança](https://www.genderapi.io/pt/accuracy-methodology) · [Política de Privacidade](https://www.genderapi.io/pt/privacy-policy) 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. ## 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.