Cotas e uso

A GVR acompanha o uso de solicitações por chave de API por meio do valor remainingRequests da conta do usuário.

APIs de solicitação única

A maioria das chamadas de API consome uma solicitação quando o processamento é concluído com sucesso.

Exemplos:

• solicitação de arquivo para identificação de gênero pela voz
• solicitação de estimativa de idade pela voz
• solicitação de detecção de voz sintética
• solicitação de identificação de gênero por imagem
• solicitação de estimativa de idade por imagem
• solicitação individual de inteligência de nomes

APIs de CSV

O processamento de CSV é diferente porque um arquivo pode conter muitas linhas. O sistema verifica o número de linhas e pode consumir uma solicitação por linha processada.

Se o arquivo tiver mais linhas do que solicitações disponíveis na chave, a API rejeitará a solicitação antes de processar o CSV.

Metadados da resposta

Muitas respostas bem-sucedidas da API incluem informações atualizadas sobre a cota:

{
  "remainingRequests": 2999
}

Use esse valor para exibir o consumo no seu aplicativo ou avisar o usuário antes que a cota se esgote.

Erros de cota

Os endpoints de arquivo e CSV podem retornar uma resposta estruturada de limite de solicitações:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "You have exceeded your free tier limit of 50 requests.",
    "detailedMessage": "Insufficient remaining requests. Required: 1, Available: 0",
    "details": {
      "limit": 50,
      "used": 50,
      "reset_date": "2026-07-01T00:00:00.000Z"
    },
    "suggested_action": "Please upgrade to a premium plan to continue using the API."
  }
}

Os endpoints individuais de inteligência de nomes podem retornar:

{
  "error": "Insufficient remaining requests"
}

Recomendações práticas

• Valide os campos obrigatórios antes de chamar a API.
• Evite repetir solicitações em loop quando ocorrerem erros de validação.
• Após cada resposta da API, use remainingRequests como valor atualizado da cota.
• Em fluxos de CSV, valide o arquivo antes de iniciar um processamento extenso.