Diferenciar a entrada em Unicode da divisão de nomes completos
Você pode enviar um nome chinês como texto Unicode sem transliterá-lo antes para o alfabeto latino. A consulta atual verifica partes normalizadas; um nome chinês completo sem espaços não é dividido automaticamente em sobrenome e nome. 王静怡 é, portanto, um único candidato, e não uma consulta garantida de 静怡.
Para os caracteres chineses comuns destes exemplos, o filtro de candidatos atual do conjunto de dados ignora partes com um ou dois caracteres. Um nome curto pode ser uma entrada válida e mesmo assim não gerar nenhum candidato. O fallback de IA automático comum ainda pode interpretar o valor enviado originalmente; uma requisição que usa apenas o conjunto de dados mantém o resultado desconhecido.
A normalização Unicode NFKC não faz uma conversão geral entre chinês simplificado e tradicional e não reconduz uma grafia latina a um único nome chinês original. Preserve a grafia enviada e verifique a correspondência retornada. A posição do sobrenome, a escrita ou a romanização não bastam para tirar conclusões sobre o gênero ou o país de uma pessoa.
| Exemplo de entrada | O que mostra | O que verificar |
|---|---|---|
王静怡 | Nome completo sem espaços | Um único candidato no conjunto de dados. A análise atual não separa o sobrenome. |
静怡 | Nome com dois caracteres | Ignorado pelo limite de comprimento do filtro de candidatos; o fallback de IA pode interpretar o valor original. |
王 静怡 | Partes curtas separadas | Um espaço extra não contorna o limite de comprimento. As duas partes do exemplo são curtas demais para a consulta ao conjunto de dados. |
Wang Jingyi | Entrada no alfabeto latino | É tratada como um valor separado e dividida nas próprias partes. Não há garantia de que ela seja reconduzida aos caracteres originais ou à mesma entrada. |
Escolher o contexto de país CN de forma consciente
A demonstração em tempo real envia country: CN (China). A API não escolhe esse país com base na escrita em que o nome está. Use um contexto de país conhecido e relevante na sua integração ou omita country. Não transforme este valor de exemplo em um padrão para todos os cadastros.
Para cada candidato, a consulta escolhe a entrada específica do país, se ela existir, e caso contrário a entrada global. Em seguida, é escolhido o candidato disponível com a maior contagem total armazenada. O escopo real da correspondência aparece em data.match.scope e data.match.country. Uma entrada específica do país com frequências empatadas não é substituída automaticamente pelo resultado global; se o fallback estiver ativado, a IA pode ser usada no lugar.
data.input.country descreve o contexto de país enviado na requisição. data.country e data.country_source descrevem a associação a um país retornada e a origem dela. São campos diferentes e não indicam nacionalidade, origem étnica nem residência.
Enviar uma requisição V2 com um nome da sua aplicação
Defina sua chave existente em GENDERAPI_API_KEY e execute o exemplo no seu servidor. A requisição ativa explicitamente o fallback de IA automático comum. Ela mostra como a requisição é montada, e não uma precisão medida ou uma cobertura confirmada. Defina options.ai_mode: off se quiser uma previsão que use apenas o conjunto de dados.
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.
Guia de erros e novas tentativas →cURL 7.76+ em um shell POSIX. Execute no seu terminal. Documentação do ambiente de execução
Node.js 22+; fetch nativo. Salve como example.mjs e execute node example.mjs. Documentação do ambiente de execução
Python 3.10+; biblioteca padrão. Salve como example.py e execute python3 example.py. Documentação do ambiente de execução
PHP 8+ com a extensão cURL. Salve como example.php e execute php example.php. Documentação do ambiente de execução
Java 17+; cliente HTTP padrão. Salve como GenderApiExample.java e execute java GenderApiExample.java. Documentação do ambiente de execução
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
Go 1.22+; biblioteca padrão. Salve como main.go e execute go run main.go. Documentação do ambiente de execução
Salvar o resultado junto com as evidências
Uma associação inferida não é o gênero declarado por uma pessoa. Salve separadamente a entrada original, as evidências retornadas e o que a pessoa declarou. Um resultado desconhecido é um resultado válido e não deve se transformar em uma categoria adivinhada na sua aplicação.
| Campo | Uso |
|---|---|
data.gender / data.result_status | Use male ou female somente com identified. Em um resultado desconhecido, preserve o valor null nativo do JSON. |
data.name / data.match | Verifique o nome retornado e o candidato selecionado. Uma correspondência com uma substring não comprova que a entrada pertence a uma pessoa com esse nome. |
data.confidence / data.confidence_kind | A confiança está em uma escala de 0 a 1 ou é null. observed_frequency se baseia em frequências armazenadas; model_reported é um valor fornecido pela IA. Avalie os limites separadamente para cada tipo. |
data.source / data.sample_count | Diferencie dataset, ai e none. Resultados da IA não têm um tamanho de amostra armazenado. Um tamanho de amostra não é um valor de precisão medido. |
meta.access.mode | Em uma integração com conta, verifique se o valor informado é api_key. Chaves ausentes ou não reconhecidas podem usar o teste por IP compartilhado. |
meta.usage | Leia charged_credits e billing_status. Um resultado desconhecido bem-sucedido é cobrado. Uma resposta perdida não comprova que a requisição foi gratuita. |
Decidir quando usar a IA
forceToGenderize é opcional para nomes, endereços de e-mail e nomes de usuário. Quando ativado, omita ai_mode ou use fallback; off e always não podem ser combinados com essa opção e retornam 422. Um saldo inicial positivo basta para iniciar uma requisição, mesmo que a cobrança final deixe o saldo negativo.
O modo de apelidos pode retornar um gênero junto com name: null. Ele também pode dar um resultado desconhecido. Nem o fallback de IA comum nem a interpretação de apelidos garantem uma resposta correta ou um valor diferente de null.
| Opção da requisição | Comportamento | Créditos por consulta bem-sucedida |
|---|---|---|
| options.ai_mode: off | Usa apenas o conjunto de dados. | 1, inclusive para um resultado desconhecido |
| options.ai_mode: fallback | Consulta primeiro o conjunto de dados e depois usa a IA comum se nenhum gênero for retornado. É o padrão das requisições individuais. | 1 no total, incluindo o fallback de IA |
| options.ai_mode: always | Usa a IA diretamente. | 2 |
| forceToGenderize: true | Consulta primeiro o conjunto de dados e depois deixa a IA interpretar um apelido pessoal ou um alias, mesmo sem um nome próprio real. | 1 para um resultado encontrado no conjunto de dados; 2 no total se a IA for usada |
Processar uma lista de nomes sem perder o contexto
Envie até 50 itens com uma chave de API ou 10 com o teste por IP via POST /api/v2/gender/batch. Dê a cada item um id único e preserve o valor original de cada linha. Cada item pode ter as próprias opções de país e de IA; omita o país se ele não for conhecido.
Ao contrário das requisições individuais, que usam fallback por padrão, os itens de um lote usam apenas o conjunto de dados por padrão. Defina options.ai_mode: fallback em cada item que precisar da IA. Verifique cada resultado, mesmo depois de HTTP 200, salve os resultados desconhecidos e verifique os erros e a cobrança antes de reenviar. Cada item comum bem-sucedido custa 1 crédito; uma requisição HTTP com um lote não equivale a um crédito por previsão.
Saber o que você envia
A demonstração em tempo real envia o valor digitado à GenderAPI.io somente quando você o envia. Se a IA for usada, type, value e o contexto de país enviados são transmitidos ao serviço configurado para as previsões. Para uma previsão baseada apenas no conjunto de dados, defina options.ai_mode: off sem forceToGenderize na sua integração.
A política de privacidade, o acordo de processamento de dados e a lista de suboperadores descrevem as condições de tratamento publicadas. Um resultado é uma associação inferida, e o que uma pessoa declara tem prioridade. Não o use como base para decisões com consequências relevantes para uma pessoa.
Perguntas frequentes
Por que um nome chinês com dois caracteres pode continuar desconhecido quando só o conjunto de dados é usado?
O filtro de candidatos atual ignora partes cujo comprimento como string JavaScript é de no máximo dois. Para os caracteres chineses mostrados aqui, um nome com dois caracteres é uma entrada válida, mas não se torna um candidato no conjunto de dados. O fallback de IA pode interpretar o valor original.
A V2 separa automaticamente o sobrenome chinês do nome?
A consulta ao conjunto de dados não divide um nome chinês completo sem espaços. A IA pode deduzir um nome a partir do valor inteiro, mas nenhum dos dois caminhos garante que o nome pretendido seja escolhido. Verifique source e match na resposta.
Existe uma avaliação independente de precisão publicada para este grupo de nomes?
Esta página não publica uma avaliação desse tipo. O fato de a entrada ser aceita, de frequências armazenadas serem exibidas ou de um valor de confiança ser retornado não é uma medição independente de precisão. A descrição da metodologia explica quais dados estão disponíveis e quais medições ainda não foram publicadas.
Um resultado sem previsão consome créditos?
Um resultado desconhecido bem-sucedido é cobrado. O modo comum, apenas com o conjunto de dados ou com fallback, custa 1 crédito no total. Com forceToGenderize, a requisição custa 1 crédito se o resultado vier do conjunto de dados ou 2 no total se a IA for usada, inclusive para um resultado desconhecido. Os erros seguem regras de cobrança separadas; verifique meta.usage.