Usar a GenderAPI.io V2 com Python

Preparar um projeto Python no lado do servidor

Este guia chama o endpoint da GenderAPI.io V2 https://api.genderapi.io/api/v2/gender com a chave de API no cabeçalho Bearer. Use Python 3.10 ou mais recente e baixe genderapi_v2.py para o seu projeto. O exemplo usa urllib.request e json da biblioteca padrão do Python; nenhum pacote pip é necessário.

Defina GENDERAPI_API_KEY no ambiente do servidor. YOUR_API_KEY no exemplo a seguir não é uma chave válida. Não coloque credenciais reais em arquivos sob controle de versão, notebooks compartilhados ou aplicações no lado do cliente. Importar o módulo ou executá-lo sem opções de demonstração não envia nenhuma requisição.

python3 --version
export GENDERAPI_API_KEY="YOUR_API_KEY"

• Baixar genderapi_v2.py →
• Verificar a chave com o endpoint gratuito de uso →

Enviar uma requisição explícita que usa apenas o conjunto de dados

Salve o código a seguir como single.py ao lado do arquivo baixado e execute python3 single.py. O módulo auxiliar envia type: name, value: Alice e options.ai_mode: off como JSON. A previsão fica em data, enquanto as informações da requisição e da cobrança ficam em meta.

Uma chamada bem-sucedida custa 1 crédito, mesmo com um resultado desconhecido, e o nome de exemplo não garante uma previsão. make_item aceita name, email ou username e exige um modo de IA explícito. Acrescente country somente se você tiver um contexto relevante.

Antes de enviar qualquer coisa, o módulo auxiliar exige uma chave de API hexadecimal de 24 caracteres. Ele verifica o formato da chave, e não se a chave existe. O módulo também rejeita respostas bem-sucedidas do teste por IP como um modo de acesso inesperado. Essa verificação acontece depois que a resposta é recebida e não pode devolver um crédito do teste por IP que já foi usado.

from genderapi_v2 import GenderAPIError, make_item, predict

try:
    response = predict(make_item("name", "Alice", ai_mode="off"))
except GenderAPIError as error:
    # Record a reference; do not log the whole error response.
    print("Request failed:", error.request_id)
    raise SystemExit(1)
else:
    result = response["data"]
    print(result["result_status"], result["gender"])
    print(result["confidence"], result["confidence_kind"])
    print(response["meta"]["usage"])

• Todos os campos das requisições individuais →

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.

• Campos da resposta e resultados desconhecidos →
• Precisão e confiança explicadas →
• Fontes de dados e perfil datado do banco de dados →

Processar um lote misto e preservar o id de cada linha

A GenderAPI.io V2 processa lotes mistos via POST https://api.genderapi.io/api/v2/gender/batch: até 50 itens com uma chave de conta ou 10 com o teste por IP. Estes exemplos exigem uma chave de conta. Dê a cada item um id estável e único e um modo de IA explícito. Um lote pode combinar nomes, endereços de e-mail e nomes de usuário, e cada item pode ter um contexto country opcional.

Leia cada item em data e o resumo em meta.summary. Uma resposta HTTP 200 pode conter erros em itens individuais, e um lote em que todos os itens falharam pode retornar uma resposta Problem de nível superior com os resultados. Resultados desconhecidos bem-sucedidos são contados em succeeded. Com index e id, você associa cada resultado à linha original correta.

Divida tarefas maiores em grupos de no máximo 50 itens e, no início, envie-os um de cada vez. Salve cada resposta e o uso correspondente antes de passar para o próximo grupo. Pare em caso de erro de transporte, erro de acesso à conta ou cobrança não confirmada e descubra primeiro o que aconteceu com o grupo atual. Só envie em paralelo depois de verificar os limites da sua conta. O tamanho máximo do lote não garante uma capacidade de processamento específica.

from genderapi_v2 import GenderAPIError, make_item, predict_batch

items = [
    make_item("name", "Alice", ai_mode="off", item_id="row-1"),
    make_item("email", "alex@example.com", ai_mode="off", item_id="row-2"),
    make_item("username", "sample_handle", ai_mode="off", item_id="row-3"),
]
try:
    response = predict_batch(items)
except GenderAPIError as error:
    # Retained error.response can include batch results and billing.
    print("Batch needs review:", error.request_id)
    raise SystemExit(1)
else:
    for item in response["data"]:
        if "error" in item:
            print(item["id"], "failed", item["error"]["code"])
        else:
            result = item["data"]
            print(item["id"], result["result_status"], result["gender"])
    print(response["meta"]["summary"])
    print(response["meta"]["usage"])
    if response["meta"]["summary"]["failed"]:
        raise SystemExit(2)

• Entrada, resultados e cobrança dos lotes →

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.

O módulo auxiliar para Python sempre exige ai_mode. Use make_item('username', 'prenses', ai_mode='fallback', force_to_genderize=True) para a interpretação de apelidos. O módulo converte force_to_genderize no campo JSON forceToGenderize.

• Opções de IA e interpretação de apelidos →
• Créditos e uso →

Decidir o que fazer depois de um erro

Os exemplos enviam cada operação uma única vez. Eles nunca fazem uma nova tentativa automaticamente: reenviar é uma nova operação, que pode ser cobrada. Um tempo limite esgotado ou um erro de conexão significa que o cliente não recebeu uma resposta completa. Isso não prova que o servidor interrompeu o processamento nem que nenhum crédito foi cobrado.

Salve o request_id retornado e o status da cobrança junto com o registro da sua tarefa. O objeto de erro preserva a resposta para uma análise controlada, mas pode conter a entrada original: não grave o objeto inteiro, a resposta e a chave de API em arquivos de log comuns.

• Problem Details e decisões sobre novas tentativas →
• Créditos e confirmação da cobrança →

Conhecer o comportamento de rede do exemplo

O tempo limite de 10 segundos do urllib vale para operações de socket bloqueantes e não é um limite garantido para a duração total da requisição. O exemplo desativa os redirecionamentos HTTP, processa respostas JSON bem-sucedidas e preserva as respostas HTTP Problem. Ele nunca faz novas tentativas automaticamente.

Os testes locais usam respostas de transporte simuladas para chamadas bem-sucedidas, resultados desconhecidos, lotes parcialmente bem-sucedidos, acesso à conta e erros. Eles verificam a lógica do exemplo, mas não medem a disponibilidade da API em produção, a precisão da previsão nem os tempos de resposta. Cada comando de demonstração explícito abaixo envia a própria requisição, que é cobrada.

python3 genderapi_v2.py --demo single
# Run separately to submit another billable sample batch:
python3 genderapi_v2.py --demo batch

• Documentação do Python sobre urllib.request →
• Documentação do Python sobre HTTPError →

Perguntas frequentes