Saltar para o conteúdo principal
Uma chave sem teto é uma chave que pode drenar todo o saldo do seu workspace se um agente entrar em loop. A maneira mais eficaz de limitar o raio de explosão de um agente comprometido ou descontrolado é dar à sua chave um limite de gasto. No gateway hospedado, cada chave é ou ilimitada ou limitada por uma cota de chave de api medida em dólares americanos — e a escolha é um campo no editor de chaves. Esta página explica os dois modos, como o limite é aplicado no caminho de relay, e quando escolher qual. Para a lista completa de restrições que uma chave carrega — listas de permissão de modelo, listas de permissão de IP, anexos de política — veja O objeto token.

​
1. Os dois modos

Cada chave resolve para exatamente um de dois estados:

Ilimitada

unlimited_quota = true. A chave consome o saldo do workspace sem teto por chave. Nenhuma verificação de gasto roda em tempo de requisição — o único limite é o próprio saldo do workspace.

Limitada

credit_limit_usd > 0. A chave carrega seu próprio limite de gasto vitalício em USD. Uma vez que o gasto cumulativo atinge o limite, a chave para de funcionar — o resto do workspace fica intocado.
Você define isso na tela Keys do console (/console/token). Criar ou editar uma chave exige o papel de Developer ou superior.
credit_limit_usd = 0 significa ilimitado — zero é o sentinela para “sem limite”, não “um limite de zero dólares”. Para limitar uma chave, dê a ela um valor positivo em dólares.

​
2. Como uma cota de chave de api é aplicada

Quando você define credit_limit_usd para um número positivo, o gateway o converte em um saldo interno remain_quota para aquela chave e vira unlimited_quota para false. A partir daí:
  • remain_quota é o espaço de gasto restante da chave, descontado conforme a chave cobra uso.
  • used_quota é o gasto cumulativo que a chave já registrou.
  • Em cada chamada de relay, o gateway verifica a chave antes de encaminhar a requisição. Uma chave limitada cujo remain_quota atingiu zero é rejeitada como exhausted — a chamada nunca chega ao modelo.
Uma chave ilimitada (unlimited_quota = true) pula essa verificação de saldo inteiramente; ela é limitada apenas pelo saldo do workspace e por quaisquer outros limites em nível de chave que você define (lista de permissão de modelo, lista de permissão de IP, expiração).
Uma chave limitada é um limite vitalício, não um orçamento mensal rotativo — o limite conta o gasto total ao longo da vida da chave. Para um orçamento que reseta, emita uma chave limitada nova na sua própria cadência (ex.: uma nova chave por sprint) e revogue a antiga. Veja Gerenciar chaves.

​
3. Um exemplo concreto

Digamos que você está fazendo deploy de um agente de sumarização agendado e quer garantir que ele nunca possa gastar mais que $25 não importa o que o modelo faça. Defina o limite quando você cria a chave: 
// POST para a tela Keys do console (Developer+).
// Configure no console — a chave de relay (sk-orca-…) nunca é usada para
// administrar chaves; ela só é apresentada em chamadas de inferência /v1/*.
{
  "name": "nightly-summarizer",
  "credit_limit_usd": 25,        // limitada: limite vitalício de $25
  "model_limits_enabled": true,
  "model_limits": ["openai/gpt-4o-mini"],
  "expired_time": -1             // -1 = nunca expira
}
O gateway armazena isso como uma chave limitada: unlimited_quota = false e um remain_quota no valor de 25.Oagentechamaomodelocomachavederelay‘sk−orca−…‘comodecostume.Nomomentoemqueogastocumulativoatinge25. O agente chama o modelo com a chave de relay `sk-orca-…` como de costume. No momento em que o gasto cumulativo atinge 25, a chave fica exhausted e toda chamada /v1/* posterior é rejeitada — sem você observar um dashboard, e sem tocar o resto do workspace. Para tornar a mesma chave ilimitada depois, edite-a e vire o toggle unlimited — o console define unlimited_quota = true e credit_limit_usd = 0 juntos, e a chave pode consumir o saldo completo do workspace novamente.

​
4. Qual modo escolher

Qualquer chave entregue a um agente autônomo, um job de CI ou uma integração de terceiros deveria ser limitada. Um limite de gasto é a garantia mais barata de que um loop de injeção de prompt ou uma tempestade de retentativas não pode acumular uma conta sem limite — o limite para a chave antes que o dano se componha. Combine-o com um limite de modelo rígido e uma lista de permissão de IP.
Para uma chave que existe apenas para uma demo, um teste de carga ou um único deployment, combine um pequeno credit_limit_usd com um expired_time. A chave se autoaposenta no limite que ela atingir primeiro. Veja Cota, limite & expiração e Chaves expiráveis.
Uma chave usada por um serviço de produção central que você controla totalmente, onde um limite por chave só causaria interrupções espúrias, pode permanecer ilimitada — o saldo do workspace é o backstop. Mantenha essas chaves poucas, nomeie-as claramente, e ainda assim escope-as com limites de modelo e de IP.
Uma chave limitada que se esgota no meio de um run começa a rejeitar chamadas imediatamente. Esse é o ponto — mas significa que um agente não monitorado pode parar no meio de um job. Dimensione o limite para o trabalho que você espera, e observe o gasto nas visões de uso do console para que você possa aumentar o limite antes que ele atinja um run legítimo.

​
5. Como os campos de limite se relacionam

Os três campos que governam isso são um único interruptor com um saldo derivado — você define o limite em dólares, o gateway deriva o resto:
CampoSignificado
credit_limit_usdSua entrada. > 0 = limite limitado em USD; 0 = ilimitado.
unlimited_quotatrue quando a chave não tem limite; definido como false automaticamente quando você dá um credit_limit_usd positivo.
remain_quotaEspaço de gasto derivado para uma chave limitada; atingir zero esgota a chave.
Você só define credit_limit_usd (ou unlimited_quota) no editor. remain_quota e used_quota são mantidos pelo gateway conforme a chave cobra uso — são telemetria somente leitura, exposta nas visões de uso do console.

​
6. Onde isso fica na pilha de controle

Um limite de gasto limita quanto uma chave pode fazer; o resto do escopo da chave limita o que ela pode fazer. Os dois se compõem:

Cota, limite & expiração

Combine um limite em dólares com uma expiração absoluta para que uma chave se autoaposente no limite que ela atingir primeiro.

O objeto token

Cada campo que uma chave carrega — limites de modelo, lista de permissão de IP, anexos de política, rótulo de ambiente — em uma referência.

Checklist de menor agência

A receita completa para a chave mais estreita possível, uma restrição por vez.

Escopo, chaves & políticas

Como o limite se encaixa na hierarquia workspace → política → chave, e como limitar uma chave encolhe o raio de explosão.
Quanto mais estreito o limite de gasto de cada chave, menor a conta que qualquer agente comprometido pode acumular — e mais clara sua trilha de auditoria do que cada chave estava autorizada a gastar.