Provedores e as suas próprias chaves

Os modelos vêm de dois lugares. O operador roda alguns nos próprios servidores, e esses não pedem nada de você. Os outros são servidos por provedores de nuvem, e para eles você traz a sua própria chave (BYOK): o contrato e a fatura ficam entre você e o provedor, e o ShvIA encaminha as suas chamadas.

Provedores#

Todos os provedores de config/providers.php são oferecidos nas configurações da conta. Desde 2.114.81, os controles de instalação *_ENABLED por provedor não existem mais; definir uma chave antiga não oculta o provedor. Uma credencial utilizável continua sendo necessária para inferência em nuvem, e as permissões da conta, restrições de modelos e cotas continuam valendo. Oferecer uma conexão não prova que o provedor aceita a conta ou a assinatura da pessoa.

A última coluna é o data_locality que o ShvIA atribui aos modelos do provedor: a classe de nuvem em que eles rodam. Os servidores do próprio operador são on_prem. É um rótulo para você aplicar a sua própria política, não uma afirmação sobre onde o provedor processa os dados. Veja os seus dados.

Adicione a sua chave#

As chaves de provedor não podem ser gerenciadas com uma chave de API: use o app web. Abra a sua conta, vá às chaves de provedor e cole a chave de cada provedor. Uma requisição autenticada com uma chave de API que tente salvar ou remover uma chave de provedor é recusada com 403.

Quando você salva uma chave, o ShvIA pergunta ao provedor se ela funciona e informa o resultado: aceita, recusada, sem crédito, limite de requisições, ou provedor indisponível. A chave é mantida seja qual for o veredito, para que uma queda no provedor não seja lida como chave errada.

As suas chaves são criptografadas em repouso e nunca são devolvidas pela API, com uma exceção estreita: uma avaliação de Pentest pode rodar com a chave de modelo da sua conta (inference_credential: account). O ShvIA entrega então a sua própria chave ao computador autorizado a rodar essa avaliação, uma vez a cada início e uma vez a cada retomada. É a chave que você colou para o provedor desse modelo, nunca uma chave atribuída por um administrador nem um token de assinatura. Com inference_credential: local, nenhuma chave sai do ShvIA e o computador usa as credenciais que já tem. A opção da conta vem ligada por padrão; o operador pode desligá-la com PENTEST_ACCOUNT_KEY_ENABLED=false. Qual das duas uma avaliação recebe depende de onde ela é criada:

• A página do Pentest oferece a escolha só para um modelo cujo provedor tem uma chave colada por você, no endpoint padrão desse provedor, e só quando o Desktop e o Pentest daquele computador conseguem pedi-la. Quando a escolha é oferecida, Conta SHVIA já vem selecionada, e a página não lembra uma escolha anterior, então toda visita começa ali; escolha Este computador para manter a sua chave onde está. Quando a escolha não é oferecida, o formulário não envia nenhuma e a avaliação usa as credenciais que já estão no computador.
• Uma requisição a POST /pentest/authorizations ou /pentest/authorizations/quick (uma sessão logada, não uma chave de API) significa local quando deixa inference_credential de fora. Só account entrega a chave, e uma requisição account que o ShvIA não consegue atender é recusada com 422 e não cria avaliação nenhuma.

configured_providers em GET /api/auth/me lista os provedores para os quais você colou uma chave. Ele não lista aqueles que você alcança com um login de assinatura ou com uma chave que um administrador atribuiu a você.

Depois de adicionar uma chave, chame POST /api/v1/profiles/refresh para que a sua lista de modelos seja refeita a partir do provedor com a sua chave. Sem isso, a lista se atualiza sozinha a cada poucos minutos.

De onde uma credencial pode vir#

Para um provedor, vale a primeira destas que existir:

1. uma chave que você colou;
2. uma assinatura que você conectou;
3. uma chave que um administrador atribuiu a você;
4. uma chave que um administrador atribuiu ao seu grupo inteiro.

Uma chave atribuída por um administrador pode ser limitada a alguns modelos do provedor. Uma chave que você mesmo cola nunca é limitada assim, e tem prioridade sobre uma atribuída.

Logins de assinatura#

Três provedores expõem login de dispositivo nesta implementação: ChatGPT, OpenCode e xAI SuperGrok. O ShvIA mostra um endereço e um código, você aprova a solicitação com o provedor, e o app termina a conexão. O ShvIA guarda e renova os tokens. Isso é separado dos cartões de chave de API e dos logins dos motores nativos do modo Code. O tráfego de assinatura não tem tabela de preço por token aqui; um custo desconhecido não significa que o uso seja gratuito ou ilimitado.

Os planos Coding da Z.ai e Kimi usam chaves de assinatura coladas, não login de dispositivo. Seus ids de provedor separados preservam os limites entre credenciais, endpoints e contabilização. Os dois provedores da Z.ai também mantêm a ativação opcional do modo Code por conta. Estas descrições refletem os caminhos de conexão configurados; esta revisão da documentação não verificou login, inferência, renovação ou elegibilidade de plano com contas de assinatura reais.

GET /api/auth/me/provider-connections lista as suas conexões e pode ser chamado com uma chave de API. Conectar e desconectar exigem uma sessão iniciada.

Receita: MiniMax#

MiniMax é um provedor de nuvem, então seus modelos só respondem para uma conta que tem uma credencial MiniMax (sua, ou atribuída por um administrador). Os modelos são chamados como qualquer outro, com o id da sua lista. Os ids existentes são MiniMax-M3, MiniMax-M2.7, MiniMax-M2.5, MiniMax-M2, as variantes mais rápidas -highspeed de alguns deles (que custam o dobro por token), MiniMax-M3.1-Flash e MiniMax-M3.1-Flash-Preview.

curl -s "$SHVIA_URL/v1/chat/completions" \
  -H "Authorization: Bearer $SHVIA_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-M3.1-Flash@minimax",
    "reasoning_effort": "low",
    "messages": [{ "role": "user", "content": "Summarise the deadline rules in two sentences." }]
  }'

Pontos específicos do MiniMax:

• Dois tipos de credencial, que não são intercambiáveis. Uma chave de API paga por uso e a Subscription Key do Token Plan são credenciais diferentes; colar a errada faz a chamada falhar sem dizer por quê. Cole a que seu plano fornece.
• MiniMax-M3.1-Flash aceita reasoning_effort, e fica lento sem ele. Ele sempre raciocina, e sem reasoning_effort o MiniMax o roda em max, o nível mais profundo. Envie low, medium, high, xhigh ou max; o gateway repassa o campo para este modelo. O M3 e a linha M2 não aceitam o campo, então o gateway o deixa de fora para eles. O M3.1 Flash funciona com qualquer um dos dois tipos de chave e está no GET /v1/models do próprio MiniMax.
• MiniMax-M3.1-Flash-Preview precisa da chave do Token Plan. O MiniMax o serve apenas para uma credencial Token Plan ou MiniMax Code por enquanto, e recusa uma chave paga por uso. A chave do plano começa com sk-cp-, e o modelo é oferecido na lista de uma conta cuja chave MiniMax começa assim. O GET /v1/models do próprio MiniMax não o lista, então ele não é encontrado só por descoberta: após colar a chave, chame POST /api/v1/profiles/refresh e leia o id da sua lista.
• A resposta começa com <think>…</think>. Modelos MiniMax escrevem seu raciocínio em content e o gateway não o remove. Veja chat completions para saber como removê-lo.
• Os dados vão para a China. O data_locality do MiniMax é cloud_cn, e uma conta com proteção LGPD ativa tem recusada uma chamada que nomeia uma coleção e termina nesse provedor.

Modelos sem chave#

Um modelo de nuvem pode aparecer em GET /v1/models mesmo que você não tenha adicionado uma chave para o provedor dele. O que uma chamada a ele faz então é fácil de errar. O modelo não pode responder, e o gateway pode recorrer ao modelo padrão da sua conta: a chamada tem sucesso com 200, e model e X-Inference-Model continuam dando o nome do modelo que você pediu. É possível receber uma resposta de outro modelo, sem erro nenhum, sem perceber. Isso vale para os endpoints /v1, onde a resposta continua nomeando o modelo que você pediu, e para agent/chat, cuja resposta nomeia o modelo que respondeu. No stream do chat, a mesma chamada termina num evento error. Uma resposta sem stream traz X-Inference-Fallback quando outro modelo respondeu, e o header de requisição X-Inference-Strict: 1 transforma o recurso ao outro modelo em erro. Veja modelos.

GET /api/v1/profiles mostra só os modelos de nuvem para os quais você tem uma credencial, então use-o para ver quais modelos de nuvem você pode chamar. Ele não aplica a lista de modelos permitidos do seu grupo nem a sua cota, então um modelo listado ainda pode ser recusado com 403. Veja modelos.

Custo#

Nos modelos de nuvem, o provedor cobra a sua conta. O ShvIA registra os tokens e uma estimativa do custo a partir de uma tabela de preços, para você acompanhar o seu gasto em uso e custo: onde um provedor informa o custo real, ele é usado no lugar. O preço de um modelo está em price em GET /api/v1/profiles, em dólares americanos por milhão de tokens.