---
title: AI Models
description: Venda acesso a modelos de IA no seu gateway: integre APIs OpenAI ou Anthropic, sincronize modelos, defina preços e libere um endpoint com chaves e wallet.
url: https://nexcmp.com/pt/docs/infrastructure/ai-models/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# AI Models {#ai-models}

> **Onde encontrar no admin:** System › Admin › License & updates (`/license`) para ativar o módulo. Depois, Services › AI Models: Providers (`/ai/providers`), Models (`/ai/models`), Profit (`/ai/profit`) e Audit (`/ai/audit`). Os clientes usam AI › API no portal do cliente.

## O que faz {#what-it-does}

O AI Models é uma camada de gateway e faturamento no seu próprio painel. Seus clientes obtêm chaves de API e chamam **um único endpoint no seu domínio**, no formato compatível com OpenAI ou Anthropic. Você escolhe quais modelos oferecer e o custo de cada um por 1 milhão de tokens. O NexCMP verifica a chave, os limites e a carteira, envia a requisição para um provedor adicionado por você, contabiliza os tokens e debita da carteira pré-paga do cliente.

**Você fornece as fontes de modelos.** O NexCMP não inclui nenhum provedor, modelo, endereço padrão ou preço. Ele não fornece modelos, chaves de API, tokens nem contas de provedor.

::: warning Verifique primeiro os termos das suas fontes
Muitos provedores de modelos restringem a revenda ou a cessão de acesso a terceiros. Use apenas fontes que você tenha autorização para usar e revender, e siga seus respectivos termos e a legislação aplicável a você. Esta página não constitui assessoria jurídica.
:::

O AI Models é um produto separado do **AI Chat and AI Agent** (módulo **AI**, veja [provedores de IA](https://nexcmp.com/pt/docs/ai/ai-providers/)). Os dois módulos não dependem um do outro.

## Requisitos {#requirements}

| Item | Requisito |
|---|---|
| Módulo | **AI Models** ativado em License & updates, Modules. Vem desativado por padrão. |
| Provedores | Uma ou mais fontes de modelos que você tenha autorização para revender, cada uma com uma API compatível com OpenAI (`/chat/completions`), uma API compatível com Anthropic (`/messages`) ou ambas. Cada uma precisa de uma URL base e de uma chave de API. |
| Rede | O painel deve alcançar cada provedor via **HTTPS na porta 443** em um nome de domínio público. Um provedor em um host interno, em outra porta ou em HTTP simples deve ser listado em **Allowed internal hosts** (configuração `ai_endpoint_allow`). |
| Clientes | Uma conta de cliente com endereço de e-mail verificado e saldo na carteira. |
| Hardware | Nenhum. O NexCMP apenas encaminha requisições: sem GPU e sem arquivos de modelo. |

## Preparar a infraestrutura {#prepare-the-infrastructure}

1. Obtenha uma chave de API de cada fonte de modelos que você usará e anote sua URL base (por exemplo, `https://api.example.com/v1`).
2. Verifique os termos da fonte quanto à revenda.
3. Se uma fonte rodar dentro da sua rede, defina seu endereço, por exemplo `http://10.0.0.5:8000/v1`. Você listará `10.0.0.5:8000` em **Allowed internal hosts**.

## Conectar no NexCMP {#connect-in-nexcmp}

### 1. Ative o módulo {#_1-turn-the-module-on}

Abra **System › Admin › License & updates**, localize o card **Module** e ative **AI Models**. O menu é recarregado e **Services › AI Models** é exibido. Enquanto o módulo estiver desativado, as páginas do cliente, as páginas do admin e o gateway respondem com `404 module_disabled`, e nenhum provedor é contatado.

![O card Module com a opção AI Models ativada](https://nexcmp.com/pt/docs/images/infrastructure/ai-models-01-modules.webp)

### 2. Adicionar um provedor {#_2-add-a-provider}

1. Abra **AI Models › Providers** e selecione **Add provider**.
2. Insira um **slug** curto, um **nome** (visível apenas para você), o **tipo** (OpenAI-compatible, Anthropic-compatible ou Both), a **URL base** e a **API key**, e uma **prioridade** (um número menor é tentado primeiro).
3. Salve. A chave é armazenada criptografada e apenas os últimos quatro caracteres são exibidos depois. Uma chave só pode ser inserida a partir de uma sessão de administrador conectada.

Use **Both** apenas para um gateway que realmente atenda a ambos os formatos. O NexCMP **não** faz conversão entre os dois formatos: um modelo servido por um provedor compatível com OpenAI é acessado em `/ai/v1/chat/completions`, e um servido por um provedor compatível com Anthropic em `/ai/v1/messages`.

![A página Providers listando três provedores de exemplo com tipo, prioridade e status](https://nexcmp.com/pt/docs/images/infrastructure/ai-models-02-providers.webp)

### 3. Testar a conexão {#_3-test-the-connection}

Selecione **Test connection** no provedor. O NexCMP lê `GET <base URL>/models` com a chave e informa **ok**, ou o motivo da falha: **auth** (chave incorreta), **blocked**, **billing** ou **unreachable**. Os testes são limitados a 6 por minuto.

### 4. Sincronizar os modelos {#_4-sync-the-models}

Selecione **Sync models**. O NexCMP lê a lista de modelos do provedor e adiciona cada novo modelo **desativado e sem preço**. Modelos que o provedor não lista mais são sinalizados. Enquanto o módulo estiver ativo, a lista também é sincronizada automaticamente a cada 6 horas (configuração `ai_models_sync_hours`).

### 5. Definir preços e ativar os modelos {#_5-set-prices-and-switch-models-on}

1. Abra **AI Models › Models**.
2. Para cada modelo que você deseja vender, defina o **preço de venda** em dólares americanos por 1 milhão de tokens: **input**, **cached input** e **output**.
3. Opcionalmente, insira seu **custo** para o modelo. Com isso, **Profit** exibirá a receita versus o custo por dia e por modelo, e um preço de venda abaixo do seu custo mais a margem mínima (configuração `ai_min_margin_pct`, 10 por padrão) será recusado, a menos que você confirme um prejuízo deliberado. **Set price from cost** usa um markup definido por você; não há markup padrão.
4. Ative o modelo. Um modelo sem preço de venda não pode ser ativado. Um preço de entrada em cache deixado em zero é cobrado pelo preço de entrada.

![A página Models com preços de venda de entrada, entrada em cache e saída e as chaves liga/desliga](https://nexcmp.com/pt/docs/images/infrastructure/ai-models-03-models.webp)

### 6. Rotas e failover {#_6-routes-and-failover}

Em um modelo, **Routes** lista os provedores que o atendem, em ordem. Adicione um segundo provedor como fallback, defina a ordem e, opcionalmente, informe um nome de modelo diferente para cada provedor (o nome enviado ao provedor pode diferir do nome que você publica). Quando um provedor retorna um erro de servidor, um erro de autorização ou faturamento, modelo ausente ou limite de taxa, o NexCMP tenta a próxima rota. Se uma leitura expirar após a solicitação ser enviada, ela **não** será enviada para outro provedor, para que você não pague duas vezes.

Cada provedor é limitado a `ai_provider_rpm` solicitações por minuto (50 por padrão). Se um provedor continuar retornando erros de autorização ou faturamento, o NexCMP alertará o administrador no Telegram quando o Telegram estiver configurado.

### 7. Ativar a chave de vendas {#_7-open-the-sale-switch}

No topo das páginas de AI Models, a **chave de vendas** (configuração `feature_ai_models`) fica desativada por padrão. Enquanto estiver desativada, os clientes veem que o serviço ainda não está aberto e a tabela pública de preços o informa como não disponível. Verifique se pelo menos um modelo está ativado, possui um preço de venda e uma rota com chave, e então ative-a.

### O que os clientes podem fazer {#what-customers-can-do}

No portal do cliente, **AI › API**:

- **Models** mostra seus modelos e preços, a URL base e exemplos de comandos prontos.
- **API Keys**: crie, renomeie, rotacione, desative e exclua chaves. O segredo é exibido apenas uma vez; somente o hash é armazenado. Por chave: modelos permitidos, expiração, orçamento flexível (alerta) e orçamento rígido (bloqueia com `402`), solicitações por minuto e tokens por minuto.
- **Usage** por modelo, chave e dia, com exportação.
- **Logs**: registros de solicitações filtráveis (horário, chave, modelo, tokens, custo, status, latência). **Prompts e respostas não são gravados.** Os logs são mantidos por 90 dias por padrão (`ai_log_retention_days`).
- **Settings**: orçamento da conta e o endereço de e-mail para alertas de orçamento.
- **Playground**: converse com um modelo, compare modelos lado a lado e copie o código correspondente.

![A página de API Keys do cliente com as URLs base para ambos os formatos de API](https://nexcmp.com/pt/docs/images/infrastructure/ai-models-04-keys.webp)

Os endpoints do gateway, no seu domínio:

```text
POST /ai/v1/chat/completions      OpenAI-compatible
POST /ai/v1/messages              Anthropic-compatible (also /ai/v1/messages/count_tokens)
GET  /ai/v1/models                model list
GET  /ai/v1/models/pricing        public price list, no key needed
```

### Carteira e faturamento {#wallet-and-billing}

O uso de IA é cobrado na mesma carteira pré-paga que todos os outros serviços. Antes de uma solicitação ir para um provedor, o NexCMP reserva o valor máximo que a solicitação poderia custar; se o saldo estiver abaixo do mínimo (`ai_min_balance_cents`, 20 centavos por padrão) ou for insuficiente, a solicitação será recusada com `402 insufficient_balance` e **nenhum provedor será chamado**. O uso é consolidado por conta e lançado no extrato da carteira a cada hora, com uma varredura a cada 5 minutos; o uso ainda não liquidado já é subtraído do saldo visualizado pelo gateway.

Revendedores podem vender AI Models em seu próprio domínio: sua margem ou desconto se aplica ao seu preço de venda e sua carteira de atacado é cobrada pelo preço de atacado. Uma chave de IA por revendedor, ativada por padrão, controla quem pode vender.

## Verificar {#verify}

1. Após a etapa 3, **Test connection** exibe **ok** e a contagem de modelos.
2. Após a etapa 4, os novos modelos são listados, desativados, sem preço.
3. Como um cliente com saldo na carteira, crie uma chave e faça uma chamada para o gateway:

   ```bash
   curl https://your-domain/ai/v1/chat/completions \
     -H "Authorization: Bearer sk-ai-…" -H "Content-Type: application/json" \
     -d '{"model":"model-one","messages":[{"role":"user","content":"hello"}]}'
   ```

   Uma resposta `200` traz a resposta do modelo. **Usage** mostra a solicitação, e **Profit** a exibe se você tiver inserido um custo.
4. Com a carteira zerada, a mesma chamada retorna `402 insufficient_balance`.

## Limites e observações {#limits-and-notes}

- O módulo não possui nenhum provedor, modelo ou preço integrado, e nenhuma tabela de preços é lida de um provedor.
- Ferramentas executadas do lado do provedor e cobradas por chamada, como busca na web, são rejeitadas porque não podem ser tarifadas. Apenas uma pequena lista de parâmetros de solicitação é repassada.
- O uso de tokens é obtido da resposta do provedor; se a resposta não contiver nenhum, o NexCMP faz uma estimativa e marca o registro como estimado.
- Erros de um provedor são limpos antes de chegarem ao cliente (nomes, hosts, endereços e o nome do modelo do provedor são removidos). Os clientes nunca veem qual provedor atendeu a uma requisição.
- Os clientes acessam o gateway por meio do domínio do seu painel, portanto o TLS desse domínio deve estar funcionando.
- O NexCMP não oferece acordo de nível de serviço, fine-tuning ou hospedagem de GPU para este módulo.

## Resolução de problemas {#troubleshooting}

| Sintoma | Causa e solução |
|---|---|
| Todas as páginas de AI Models e o gateway respondem `404 module_disabled` | O módulo está desativado. Ative **AI Models** em License & updates, Modules. |
| A adição de um provedor falha com `endpoint_host_not_allowed`, `endpoint_must_be_https` ou `invalid_endpoint_port` | A URL base deve ser HTTPS na porta 443 em um nome de domínio público. Para um host interno, outra porta ou HTTP simples, liste `host:port` em **Allowed internal hosts**. |
| `blocked_endpoint` | O endereço é um IP ou o nome resolve para um endereço privado. Liste-o em **Allowed internal hosts** se for isso o que você deseja. |
| **Test connection** exibe `auth` | A chave está incorreta ou não possui acesso. Insira a chave novamente. |
| Não é possível ativar um modelo (`no_price`) | Defina um preço de venda primeiro. |
| Os clientes recebem `503 ai_unavailable` | A opção de venda está desativada ou a opção de AI da revenda está desativada. |
| Os clientes recebem `503 upstream_unavailable` | Nenhuma rota ativada com chave atende a esse modelo no formato solicitado. Verifique as rotas do modelo e o tipo de provedor. |
| Os clientes recebem `402 insufficient_balance` | O saldo da carteira está abaixo do mínimo ou é insuficiente para a requisição. Solicite que o cliente faça uma recarga. |