Visão geral

A AgeVerify API analisa uma única selfie e retorna se a pessoa aparenta ser maior de 18 anos, menor de 18 anos, ou se o resultado é inconclusivo. Toda a análise ocorre em memória — nenhuma imagem, embedding ou dado biométrico é armazenado.

Para integrar, você precisa de uma API Key gerada no painel. Todas as chamadas de produção vão para um único endpoint: POST /api/v1/verify-age.

As respostas são JSON. O campo success indica sucesso; em falhas, use error.code para tratar o erro na sua aplicação.

URL base

Primeiros passos

1. Crie uma conta com e-mail e senha.
2. Confirme o e-mail pelo link enviado na sua caixa de entrada.
3. Faça login e acesse o painel.
4. Compre créditos no painel (R$ 0,25 por requisição).
5. Em API Keys, crie uma chave. Ela é exibida uma única vez — copie e guarde em variável de ambiente ou secret manager.
6. Envie POST /api/v1/verify-age com Authorization: Bearer ak_… e o campo image.

Autenticação

Inclua sua API Key no header Authorization em todas as requisições:

Authorization: Bearer ak_a1b2c3d4e5f6…

As chaves começam com ak_. Se perder a chave, revogue-a no painel e crie uma nova. Requisições sem chave ou com chave inválida retornam HTTP 401 (UNAUTHORIZED).

Créditos

• Preço: R$ 0,25 por crédito (= 1 requisição bem-sucedida).
• Consumo: 1 crédito debitado apenas quando a resposta é HTTP 200.
• Saldo insuficiente: HTTP 402 com código INSUFFICIENT_CREDITS — compre créditos no painel.
• Erros de validação (rosto não detectado, blur, spoof etc.) não consomem crédito.

POST /api/v1/verify-age

Analisa uma selfie e retorna a classificação de maioridade. Requer API Key no header Authorization e saldo de créditos disponível. Consome 1 crédito por resposta bem-sucedida (HTTP 200).

Requisição

Formato: multipart/form-data
Campo obrigatório: image — arquivo de imagem

Resposta de sucesso (200)

{
  "success": true,
  "data": {
    "result": "MAIOR_DE_IDADE",
    "estimated_age": 24,
    "confidence": 0.89
  }
}

Valores possíveis para result:

• MAIOR_DE_IDADE — idade aparente ≥ 22 anos
• MENOR_DE_IDADE — idade aparente ≤ 15 anos
• INCONCLUSIVO — idade aparente entre 16 e 21 anos

Formato de respostas

Sucesso

{
  "success": true,
  "data": {
    "result": "string",
    "estimated_age": 0,
    "confidence": 0.0
  }
}

Erro

{
  "success": false,
  "error": {
    "code": "NO_FACE",
    "message": "No face detected in the image."
  }
}

Códigos de erro

Exemplos de código

cURL

curl -X POST https://age.hlearning.com.br/api/v1/verify-age \
  -H "Authorization: Bearer ak_SUA_API_KEY" \
  -F "image=@selfie.jpg"

Python

import os
import requests

url = "https://age.hlearning.com.br/api/v1/verify-age"
api_key = os.environ["AGEVERIFY_API_KEY"]  # ak_…

with open("selfie.jpg", "rb") as f:
    resp = requests.post(
        url,
        headers={"Authorization": f"Bearer {api_key}"},
        files={"image": ("selfie.jpg", f, "image/jpeg")},
    )

data = resp.json()

if data["success"]:
    result = data["data"]
    print(result["result"])         # MAIOR_DE_IDADE | MENOR_DE_IDADE | INCONCLUSIVO
    print(result["estimated_age"])  # idade aparente em anos
    print(result["confidence"])     # 0.0 – 1.0
elif data["error"]["code"] == "INSUFFICIENT_CREDITS":
    print("Compre créditos no dashboard")
else:
    print(data["error"]["code"])    # ex: NO_FACE

JavaScript (fetch)

async function verificarIdade(arquivo) {
  const form = new FormData();
  form.append("image", arquivo);

  const resp = await fetch("https://age.hlearning.com.br/api/v1/verify-age", {
    method: "POST",
    headers: { Authorization: `Bearer ${process.env.AGEVERIFY_API_KEY}` },
    body: form,
  });

  const json = await resp.json();

  if (resp.status === 402) {
    throw new Error("INSUFFICIENT_CREDITS");
  }
  if (!json.success) {
    throw new Error(json.error.code);
  }

  return json.data; // { result, estimated_age, confidence }
}

Limites e validações

• Tamanho máximo: 10 MB
• Resolução mínima: 224 × 224 px
• Formatos aceitos: JPG, JPEG, PNG, WEBP
• Quantidade de rostos: exatamente 1 (devolve erro MULTIPLE_FACES se houver mais de 1 rosto)
• Rosto deve ocupar pelo menos 5% da área da imagem
• O rosto deve estar completamente dentro dos limites da imagem
• Rate limit por API Key: padrão 60 req/min

Faixas de classificação

A API utiliza três faixas em vez de um limiar binário de 18 anos. Isso reduz falsos positivos e negativos em idades ambíguas: