Catálogo de Modelos

Onde os provedores são conectados e os modelos ficam provisionados — o que decide quais nomes de modelo o gateway aceita.

O gateway não tem uma lista embutida de modelos do mundo. Ele atende o modelo que a sua organização liberou: cada provedor conectado traz uma credencial e uma lista de modelos provisionados, e é essa lista que o roteamento consulta. Um modelo fora dela recusa 403 modelo_nao_permitido antes de qualquer chamada externa. O catálogo é a tela onde isso se configura, no console, em Catálogo de Modelos — área da organização, aberta a owner e admin.

O que a tela mostra

O catálogo é por organização (não por workspace) e tem duas abas sobre a mesma base de integrações:

As duas abas do catálogo
Aba	O que lista
Provedores	Uma linha por integração conectada, com Nome (e o chip de status, Ativa ou Desativada), Slug, Criada em, Criada por, quantos Modelos ela libera e as ações da linha.
Modelos	Uma linha por modelo liberado, com o rótulo de negócio dele, o provedor que o serve e em quantos provedores o mesmo nome aparece. Clicar num modelo abre a tela do provedor já com o código de exemplo daquele modelo.

Acima da tabela ficam a busca (por nome ou slug na aba Provedores; por modelo ou provedor na aba Modelos) e dois filtros: por tipo de provedor — que só oferece os tipos de fato presentes na sua lista, nunca o catálogo inteiro de tipos possíveis — e por status, entre Ativa e Desativada.

Conectar um provedor

O botão Conectar provedor abre um fluxo de dois passos.

Passo 1 · Selecionar serviço

Escolha o serviço numa lista de tipos suportados (OpenAI, Anthropic, Google, Groq, Mistral, Together, Fireworks, Cohere, DeepSeek, Perplexity, xAI, OpenRouter, Cerebras, DeepInfra e OpenAI compatível) ou clique num dos chips de marca, que pulam direto para o passo 2. Só o tipo OpenAI compatível pede Endpoint: os demais têm endpoint canônico fixado pela plataforma, e oferecer um campo que seria ignorado seria mentir sobre o que a tela faz.

Passo 2 · Detalhes do provedor

Nome (o slug é derivado dele), a credencial do provedor e, em seguida, os modelos e os workspaces com acesso. A credencial é write-only: ela é cifrada com a chave da plataforma e nunca é reexibida — nem para quem a digitou, nem pela API do console. Trocar a credencial depois é possível; lê-la de volta, não.

Ao entrar no passo dos modelos, o console tenta descobrir a lista junto do provedor com a credencial que você acabou de digitar. Quando dá certo, os modelos aparecem em cartões com um botão de liberar cada um (e Selecionar todos / Limpar), e cada modelo liberado aceita um rótulo de negócio opcional. Quando a descoberta falha — provedor sem rota de listagem, rede fora, qualquer motivo — a tela diz o que houve e oferece a entrada manual, um campo único no formato modelo=Rótulo, separado por vírgulas:

modelos liberados · entrada manual

gpt-4o-mini=Assistente rápido, gpt-4o=Análise longa, text-embedding-3-small

O rótulo é seu, para leitura humana no console e nas listagens — quem chama o gateway continua mandando o nome técnico do modelo em model. Um trecho sem = entra sem rótulo.

Por fim, os workspaces com acesso: todos (inclusive os futuros) ou uma lista específica. Uma integração sem nenhum workspace marcado nasce sem acesso a lugar nenhum — os modelos ficam liberados no papel e ninguém consegue usá-los. Ver Autenticação e chaves para o que o workspace decide do lado da chamada.

A tela do provedor

Clicar num provedor abre a tela dele, com três seções empilhadas — Visão geral, Como chamar pela API e Modelos — mais uma coluna de detalhes à direita.

Visão geral

Dois números medidos, não estimados: Último uso e Total de requisições, este com a quebra em Esta semana, Semana passada e a variação entre as duas. Três detalhes que a tela diz em voz alta, para o número não ser lido como outra coisa:

Enquanto a medição está em voo, o valor é … — isso é carregando, não zero.
Falha ao medir aparece como "Não foi possível medir" — nunca como "Nunca usada" e nunca como zero.
"Último uso" conta toda atividade da integração (inclusive tentativa de fallback, acerto de cache e recusa anterior ao provedor); o total conta as requisições próprias dela, sem as tentativas intermediárias de fallback.

Como chamar pela API

O código pronto para colar, em cURL, NodeJS ou Python, para o modelo escolhido no seletor ao lado — trocar o modelo reescreve o trecho (e o endereço da página, então o link pode ser compartilhado já no modelo certo). Copiar leva o trecho inteiro; há também um atalho que copia só o baseURL e o model, que costuma ser o que se cola numa configuração existente.

O seletor de modelo carrega um aviso que vale a pena entender: o gateway roteia pelo modelo. Se o mesmo nome estiver liberado em duas integrações da organização, quem atende é a mais antiga — e a tela diz isso, nomeando qual integração vai de fato responder quando não for a que você está vendo.

Executar requisição de teste

O botão dispara uma completion de chat de verdade, pela sessão do console (nenhuma chave gov_ é necessária), no workspace da sua sessão. A saída aparece em streaming, e o rodapé traz a latência em milissegundos e os tokens de entrada e de saída medidos.

Três situações são recusadas localmente, sem gastar chamada: sessão sem workspace nenhum, modelo de embedding (o playground só executa chat — use o bloco de código de /v1/embeddings com uma chave do workspace) e nenhuma integração ativa com acesso ao workspace liberando aquele modelo, que a tela já anuncia como modelo_nao_permitido.

Modelos e a coluna de detalhes

A seção Modelos lista o que esta integração libera, com busca, o rótulo de negócio de cada um e a marca de embeddings quando o modelo roteia por esse caminho. Clicar num modelo abre o código de exemplo com ele.

À direita ficam status, slug (com botão de copiar — é o slug cru, o mesmo que aparece em filtros e endereços), data de criação e Criada por. Esse último mostra um travessão (—) quando não há autor para atribuir, o que acontece em três casos: a integração é anterior ao registro de autoria, foi criada por uma chave administrativa (que não é uma pessoa) ou o membro que a criou saiu da organização.

Acesso a modelos: uma allowlist estrita

Em Editar acesso a modelos ficam os modelos que a integração já conhece, numa grade de chaves liga-desliga, com Selecionar todos / Desmarcar todos (que agem sobre todos os modelos, não só sobre os que a busca mostra) e o botão Atualizar. A mudança vale na requisição seguinte.

A lista é uma allowlist estrita, e isso tem duas consequências que não são óbvias:

Lista vazia significa nenhum modelo, jamais "todos". Não existe modo "libere tudo que o provedor tiver": modelo novo do provedor não entra sozinho.
Desprovisionar remove. O Atualizar grava a lista inteira, então desligar um modelo o tira da integração — e, como a credencial nunca volta do backend, esta tela não consegue relistá-lo depois. É irreversível pela UI: para trazê-lo de volta, digite o modelo outra vez ao editar a integração, com a credencial em mãos.

Enquanto você não sai da página, um modelo desligado continua visível (desligado), o que permite desfazer antes de gravar. Depois de gravar e sair, ele some da lista.

Ações do provedor

No menu ⋯ da tela do provedor:

O que cada ação faz
Ação	Efeito
Acessos de workspaces	Troca entre "todos os workspaces" e uma lista específica, e concede ou retira acesso workspace a workspace. Vale na requisição seguinte: o workspace retirado perde os modelos do catálogo na hora, e os outros não sentem nada.
Editar	Abre a edição da integração — credencial e, no tipo `OpenAI compatível`, o endpoint. É o caminho de rotação de chave. Não é aqui que se mexe em modelos.
Desativar / Ativar	Para de rotear sem apagar o cadastro. Com a integração desativada, o gateway recusa qualquer chamada aos modelos dela com `modelo_nao_permitido` — a credencial e os modelos continuam guardados, e Ativar devolve tudo ao ar.
Excluir	Apaga a integração, a credencial, os acessos de workspace e os limites dela. Pede confirmação digitando o nome exato — comparação literal, sem ignorar maiúsculas e sem tolerar espaço a mais, por isso há um botão Copiar ao lado do nome.

Quando o gateway recusa

Os dois erros que costumam levar de volta ao catálogo
Código	O que verificar
`modelo_nao_permitido`	Duas causas, e a mensagem não distingue: o modelo não está provisionado para a organização (ou a integração que o libera não alcança aquele workspace), ou a integração que o libera está desativada. Confira as duas coisas no catálogo, nessa ordem.
`motor_indisponivel`	A chamada não chegou ao fim do caminho. Hoje esse código não distingue plataforma fora do ar de provedor fora do ar — então, além de repetir com backoff, vale checar o endpoint do provedor (e, num tipo `OpenAI compatível`, o endpoint que você cadastrou).

A lista completa de códigos, por família, está em Erros.