Saltar para o conteúdo principal
Uma única chave de API pode alcançar todos os modelos a que o seu workspace tem direito. Isso é conveniente para uma sessão de console e perigoso para um agente de longa duração: um agente com injeção de prompt segurando uma chave irrestrita pode silenciosamente trocar de gpt-4o-mini para o modelo mais caro a que você tem acesso, ou para um cujo tratamento de dados você nunca aprovou. A correção é uma allow-list de modelos por chave. Cada chave carrega um campo model_limits (controlado por model_limits_enabled). Quando está ligado, uma requisição a qualquer modelo que não esteja na lista é rejeitada no gateway — antes que um canal seja selecionado e antes que algo saia para um provedor.
Esta é uma restrição no objeto da chave. Ela compõe com a allow-list de IP da chave, o limite de gasto, a expiração e o guardrail / política de firewall anexado — cada um estreita a chave independentemente.

​
1. Por que restringir o acesso a modelos por chave de API

A escolha de modelo é uma alavanca de agência. Uma chave que pode chamar qualquer modelo pode ser direcionada para:
  • Explosões de custo — trocar para um modelo premium multiplica a conta por token.
  • Capability creep — uma tarefa com escopo para um modelo pequeno é roteada para um modelo de fronteira que pode fazer muito mais do que você pretendia.
  • Deriva de compliance — enviar tráfego para uma família de modelos que você não liberou para uma dada classe de dados.
Restringir uma chave ao um ou dois modelos que um agente realmente precisa fecha todos os três de uma vez. É o equivalente, no eixo de modelo, ao firewall fazer allow-list de ferramentas — o agente só pode alcançar o que você nomeou, e nada mais.

​
2. Os dois campos

Os limites de modelo vivem na chave como um par:
CampoTipoSignificado
model_limits_enabledboolInterruptor mestre. Quando false, a chave alcança todos os modelos que o workspace permite.
model_limitslistA allow-list de nomes de modelo. Só significativa quando model_limits_enabled é true.
Os dois campos são independentes, e a combinação importa: model_limits_enabled = true com uma lista vazia significa que a chave pode alcançar nenhum modelo — cada requisição é rejeitada com “This token has no access to any models.” Ligue o interruptor só depois de ter nomeado pelo menos um modelo.

​
3. Definir em uma chave

Configure os limites de modelo no editor de chave do console (/console/token), o mesmo lugar onde você define as outras restrições da chave. Criar ou editar uma chave exige o papel de Developer ou superior.
  1. Abra a chave (ou Create key).
  2. Habilite Model limits.
  3. Escolha os modelos que esta chave pode chamar — digite para filtrar os modelos disponíveis do workspace.
  4. Salve. A mudança entra em vigor na próxima requisição da chave — sem redeploy, sem rotação de chave.
Um sumarizador agendado que só deveria tocar um modelo barato acaba com uma allow-list de exatamente uma entrada: 
model_limits_enabled: true
model_limits:         ["openai/gpt-4o-mini"]
A partir desse ponto a chave fica fixada em gpt-4o-mini. Qualquer outro nome de modelo em uma requisição desta chave é rejeitado — não há fallback para um modelo padrão e nenhum downgrade silencioso.
Combine os limites de modelo com um limite credit_limit_usd na mesma chave. A lista de modelos delimita qual modelo um loop descontrolado pode alcançar; o limite de gasto delimita quanto ele pode queimar antes que a chave pare de funcionar. Dois tetos independentes, ambos enforçados no gateway. Veja Cota, limite e expiração.

​
4. Como é uma requisição rejeitada

Quando model_limits_enabled está ligado e uma requisição nomeia um modelo fora da lista, o gateway aborta a requisição com HTTP 403 e um corpo de erro no formato OpenAI: 
{
  "error": {
    "message": "This token has no access to model claude-opus-4-8 (request id: 2024...abc)",
    "type": "orcarouter_api_error",
    "code": ""
  }
}
Propriedades-chave da rejeição:
A verificação roda enquanto o gateway ainda está escolhendo um canal — a requisição nunca chega a um provedor upstream, então um modelo proibido não custa nenhum token de modelo.
Com o interruptor ligado e uma allow-list vazia, a mensagem é “This token has no access to any models” e cada requisição é rejeitada. Esta é a diferença entre “restringir a uma lista” e “trancar a chave totalmente fora da inferência.”
O nome do modelo da requisição é normalizado antes de a lista ser verificada, então variantes relacionadas (ex.: variantes de thinking) resolvem para o mesmo nome canônico que você colocou na allow-list. Liste o nome do modelo base que o console lhe mostra.

​
5. Limites de modelo vs. direitos de grupo

Duas coisas diferentes decidem se uma chave pode chamar um modelo. Não as confunda:
CamadaEscopoPergunta que responde
Direito do workspaceWorkspaceEste modelo está disponível para o workspace de forma alguma?
model_limitsChave únicaDos modelos disponíveis, quais ESTA chave pode usar?
model_limits só estreita. Uma chave não pode usar limites de modelo para alcançar um modelo a que o próprio workspace não tem direito — ela só pode recortar uma allow-list menor do que já é permitido. Para conceder a uma chave nada extra mas estritamente menos, é exatamente para isso que este campo serve.

​
6. Onde isso se encaixa na postura de menor agência

Os limites de modelo são uma linha da receita de chave por agente. A chave útil mais estreita para um agente autônomo fixa todos os seus eixos de uma vez: Quando tal chave é comprometida via injeção de prompt, o raio de explosão é delimitado em cada eixo — incluindo em quais modelos o atacante pode gastar o seu orçamento.
Os limites de modelo são uma restrição de identidade na chave, não uma política de conteúdo ou de ação. Eles não inspecionam prompts (isso é Guardrails) nem chamadas de ferramenta (isso é o Firewall) — eles decidem, antecipadamente, qual modelo a chave tem permissão sequer de endereçar.

​
7. Próximos passos

O objeto da chave

Cada campo que uma chave carrega — limites de modelo, lista de IP, limites, expiração e anexos de política — em uma referência.

Checklist de menor agência

A receita completa de chave por agente: dê escopo a cada eixo ao mínimo de que o agente precisa.

Escopo, chaves e políticas

Como chaves, guardrails e políticas de firewall se vinculam em uma única identidade de agente.

Vincular políticas a uma chave

Anexe um guardrail e uma política de firewall à mesma chave.
Restringir o acesso a modelos por chave de API é o controle de agência mais barato que você pode aplicar: uma allow-list, enforçada no gateway, que nenhum agente comprometido consegue contornar na conversa.