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.
Custo por operação
A cota é descontada quando o processamento é concluído com sucesso. Um resultado de gênero unknown também consome cota.
| Operação | Cota consumida |
|---|---|
| Análise padrão de gênero por arquivo | 1 solicitação |
| Análise padrão de gênero por URL | 1 solicitação |
| Gênero pela voz V2 (análise aprimorada com detecção de fala) | 1 solicitação |
| Gênero pela voz V3 (análise avançada por locutor) | 2 solicitações |
| Idade pela voz, voz sintética, emoções na fala, qualidade de áudio, verificação de locutor, análise de imagem ou análise de um nome | 1 solicitação por chamada de API bem-sucedida |
| Validação de CSV | Nenhuma solicitação; verifica se há cota suficiente para processar as linhas |
| Processamento de CSV | 1 solicitação por linha processada |
APIs de CSV
O processamento de CSV é diferente porque um arquivo pode conter muitas linhas. A API verifica a quantidade de linhas antes do processamento e consome uma solicitação por linha.
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
remainingRequestscomo valor atualizado da cota. - Em fluxos de CSV, valide o arquivo antes de iniciar um processamento extenso.