Documentação
Grupos de chaves
Dê a cada um dos seus clientes as próprias chaves de API, reúna-as em um grupo, veja quanto cada cliente e cada chave gastou em qualquer período e limite quanto cada cliente pode gastar por mês. Uma conta, um saldo.
Um grupo é uma pasta de chaves de API na sua conta, por exemplo uma por cliente: CID000001, CID000002. Uma chave em um grupo chama a API como qualquer outra, e um grupo não tem saldo, recargas nem login próprios; ele pode ter um limite mensal de gastos sobre todas as suas chaves. Cada chave está em um grupo ou em nenhum.
Configure grupos em três passos
- Crie um grupo. Na página Chaves de API, escolha “Novo grupo” e dê a ele o nome do cliente.
- Coloque chaves nele. Escolha “Nova chave” no cabeçalho do grupo para criar uma chave dentro dele. Para arquivar uma chave que você já tem, abra o menu dela e escolha “Mover para grupo”.
- Leia os números. A página Chaves de API mostra quanto cada chave gastou neste mês-calendário e o total de cada grupo. A página Uso mostra as mesmas chaves sob seus grupos para hoje, os últimos 7 ou 30 dias, este mês, o mês passado ou dias que você escolher, até 90.
Leia um mês e exporte
Na página Uso, escolha “Mês passado” (ou “Este mês”, ou “Personalizado” para escolher dias) no topo. Em “Por chave de API”, o cabeçalho de cada grupo mostra o custo e as chamadas do grupo. O menu de grupos no topo restringe a página inteira a um grupo: seus números, gráfico, modelos e chamadas. “Exportar CSV” baixa o que a página mostra, com o mesmo período e o mesmo grupo, por chave ou por dia.
Por chave, o arquivo tem uma linha por chave e grupo, com um nome como kunavo-cost-by-key_2026-10-01_2026-10-31.csv. Ele lista cada chave que fez chamadas no período, incluindo as revogadas, sob o grupo em que cada chamada foi feita, e cada chave ativa sem chamadas no grupo em que está agora, com 0, para que a lista de chaves de cada cliente fique completa. Os grupos seguem a ordem do painel, as chaves de cada grupo da mais cara para a mais barata, e as chaves sem grupo por último. Por dia, o arquivo começa com uma coluna date e tem uma linha para cada dia em que uma chave fez chamadas em um grupo.
| Coluna | Conteúdo |
|---|---|
group | O grupo em que as chamadas foram feitas; vazio para chamadas feitas fora de qualquer grupo. Um grupo excluído depois tem (deleted) após o nome. |
key_name | O nome da chave. |
key_prefix | O início da chave, como o painel mostra. Nunca a chave inteira. |
key_status | active ou revoked. |
calls | Chamadas feitas com a chave no período. |
errors | Dessas chamadas, as que falharam. Uma chamada com falha não custa nada. |
input_tokens | Tokens de entrada, incluindo leituras e gravações de cache. |
output_ | Tokens de saída. |
cached_ | Dos tokens de entrada, os lidos do cache de prompt. |
cache_ | Dos tokens de entrada, os gravados no cache de prompt. |
cost_usd | O valor cobrado pelas chamadas, em dólares americanos, com oito casas decimais. |
=, +, - ou @ é gravado com um apóstrofo na frente, para que uma planilha o mostre como texto em vez de executá-lo como fórmula.Limite quanto cada grupo gasta por mês
Abra o menu de um grupo na página Chaves de API e escolha “Definir limite mensal”. O limite conta o que todas as chaves do grupo gastam juntas em um mês-calendário (UTC): as chamadas feitas por cada chave enquanto estava no grupo. Uma solicitação que faria o grupo ultrapassá-lo é recusada com 402 e nada é cobrado por ela. Deixe o campo em branco para não ter limite, ou use 0 para pausar todas as chaves do grupo sem revogar nenhuma.
O limite mensal próprio de cada chave continua valendo, e o primeiro limite atingido recusa a solicitação. O cabeçalho do grupo mostra o mês dele em relação ao limite, com “Limite atingido” quando as solicitações começam a ser recusadas e “Pausado” quando o limite é 0.
A Kunavo envia um e-mail para o endereço da sua conta quando um grupo, ou uma chave com limite próprio, usa 80% do limite mensal, e de novo quando as solicitações começam a ser recusadas por esse limite: no máximo um e-mail de cada tipo por mês para cada limite.
Como os valores são contados
- O custo é o que foi cobrado. O custo de cada chamada é o valor descontado do seu saldo quando ela terminou. Uma chamada com falha não custa nada.
- Meses e dias são em UTC. Este mês começa no dia 1, às 00:00 UTC. Em Yangon (UTC+6:30), por exemplo, outubro termina em 1º de novembro às 06:30, no horário local. A página Uso mostra as datas do período exibido.
- Uma chamada conta no grupo em que a chave estava no momento da chamada. Se você mover uma chave para outro grupo, só as chamadas a partir daí contam lá; as chamadas anteriores ficam onde estavam. Por isso, o total do mês de um grupo na página Chaves de API pode ser diferente da soma das chaves listadas abaixo dele agora.
- Uma chave revogada continua no seu grupo. O que ela gastou antes de ser revogada continua contando nos totais desse grupo e aparece na exportação.
- Um grupo excluído mantém suas chamadas. Elas continuam sob o nome dele, marcado como excluído, na página Uso e na exportação, e o nome pode ser usado de novo em um grupo novo.
- Três lugares, um só valor. Para um mesmo mês civil, o total de um grupo na página Chaves de API, o total dele em “Este mês” na página Uso e a soma das linhas dele no CSV são iguais, até o centavo.
Perguntas
- Cada grupo tem um saldo próprio? Não. Todos os grupos usam o saldo único da sua conta. Para limitar quanto um cliente pode gastar, defina um limite mensal para o grupo dele, ou para cada uma das chaves dele.
- Meus clientes podem fazer login para ver o uso deles? Não. Os grupos são visíveis só para você. Uma chave pode consultar o próprio uso com GET /v1/usage, que não mostra o grupo dela. Quando o grupo dela tem um limite mensal,
GET /v1/balancemostra à chave esse limite e quanto o grupo inteiro gastou neste mês, mas não o nome do grupo. - O que acontece quando excluo um grupo? Você escolhe: as chaves dele continuam funcionando, a partir daí sem grupo, ou são revogadas junto com o grupo. Em qualquer caso, as chamadas que elas fizeram ficam sob o nome do grupo.
- E se uma chave passar de um cliente para outro? Mova-a para o grupo do outro cliente: as chamadas dela contam lá a partir daí, e as chamadas anteriores ficam com o primeiro cliente.
- Posso ver outros períodos? Sim: escolha “Personalizado” na página Uso e até 90 dias. Para um programa, GET /v1/usage retorna o custo de uma chave por dia no mesmo período.
Para criar, agrupar, limitar e revogar as chaves de um cliente a partir de suas próprias ferramentas, em vez de manualmente, use a API de gerenciamento. As chaves dela são uma credencial separada e funcionam apenas nessa API.