Documentação

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.

ColunaConteúdo
groupO 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_nameO nome da chave.
key_prefixO início da chave, como o painel mostra. Nunca a chave inteira.
key_statusactive ou revoked.
callsChamadas feitas com a chave no período.
errorsDessas chamadas, as que falharam. Uma chamada com falha não custa nada.
input_tokensTokens de entrada, incluindo leituras e gravações de cache.
output_tokensTokens de saída.
cached_input_tokensDos tokens de entrada, os lidos do cache de prompt.
cache_write_tokensDos tokens de entrada, os gravados no cache de prompt.
cost_usdO valor cobrado pelas chamadas, em dólares americanos, com oito casas decimais.
Nomes que parecem fórmulas. Um nome de grupo ou de chave que começa com =, +, - 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/balance mostra à 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.