Descoberta de modelos

Use a página de Modelos ou a API de Modelos para inspecionar os modelos de texto disponíveis. Os metadados do modelo incluem fornecedor, provedor de serviço, modalidade, comprimento de contexto, famílias de API suportadas, capacidades suportadas, disponibilidade, limites no nível da conta e preço em créditos.

Endpoint: GET /v1/models Objetivo: Listar modelos disponíveis para a conta atual.

Copiarcurl --request GET \
  --url https://api.basicrouter.ai/api/v1/models \
  --header "Authorization: Bearer $BASICROUTER_API_KEY"

Matriz de capacidades

Matriz de compatibilidade de famílias de API

Autenticação

Toda solicitação de API usa um token bearer. Armazene as chaves em variáveis de ambiente do lado do servidor, rotacione-as quando o acesso da equipe mudar e registre os IDs de solicitação para depuração.

Recomendações de segurança de chaves

1. Mantenha as chaves API no servidor. Não exponha as chaves no código do navegador ou do cliente móvel.
2. Use chaves separadas para desenvolvimento, homologação, produção e integrações de terceiros.
3. Defina o escopo das chaves por ambiente, serviço, cliente ou tenant quando disponível.
4. Faça a rotação das chaves após a saída de funcionários, mudanças no acesso de fornecedores ou suspeita de vazamento.
5. Armazene as chaves em gerenciadores de segredos ou variáveis de ambiente, não no código-fonte.

Uso do console

O Console do BasicRouter é o plano de controle operacional para acesso à API, disponibilidade de modelos, políticas de roteamento, visibilidade de uso e administração de cobrança. Ele oferece aos administradores da conta uma visão centralizada de chaves, modelos, solicitações, créditos e controles no nível da conta para tráfego de modelos em produção.

Gerenciamento de chaves API

Crie, rotacione, revogue e rotule chaves API no console. Use chaves separadas para desenvolvimento, homologação, produção e serviços individuais para que o uso possa ser auditado e isolado por ambiente ou aplicação.

Lista de modelos

Use a página de Modelos para revisar os modelos disponíveis para a conta. Cada entrada de modelo pode incluir fornecedor, provedor de serviço, modalidade, famílias de API suportadas, comprimento de contexto, sinalizadores de capacidade, status de disponibilidade e informações de preço.

Para aplicações em produção, verifique as capacidades do modelo antes de ativar o tráfego. Alguns parâmetros e recursos dependem do modelo e podem não ser suportados em todas as famílias de API.

Uso e logs

A visualização de Uso e Logs fornece visibilidade operacional do tráfego da API. As equipes podem inspecionar o volume de solicitações, modelos selecionados, destinos de roteamento resolvidos, consumo de créditos, latência, códigos de erro e IDs de solicitação.

• Solucione falhas em solicitações.
• Identifique cargas de trabalho de alto custo.
• Compare o uso de modelos entre aplicações e ambientes.
• Valide o comportamento de roteamento e fallback.
• Investigue problemas de latência ou disponibilidade do provedor.
• Forneça IDs de solicitação ao contatar o suporte.

Cada resposta da API inclui ou expõe um ID de solicitação do BasicRouter. Armazene este ID nos logs da sua aplicação para tornar a depuração de produção e a escalonamento de suporte mais eficientes.

Fallback

O Fallback é o mecanismo de resiliência do BasicRouter. Quando o modelo principal ou a política de roteamento falha, o sistema alterna automaticamente para um modelo de backup para continuar processando a solicitação. Isso mantém sua aplicação responsiva e minimiza o risco de interrupção do serviço.

Por que o fallback é importante

Em produção, os serviços de modelo podem enfrentar vários problemas imprevisíveis:

• Falha no serviço do modelo: a API upstream fica temporariamente indisponível ou atinge o tempo limite.
• Flutuação de desempenho: alta carga do modelo leva a respostas lentas ou com falha.
• Falha de roteamento: todos os modelos candidatos selecionados pelo roteamento inteligente ficam indisponíveis.

O Fallback mantém sua aplicação disponível fornecendo um caminho de backup confiável.

Principais vantagens

Configuração de modelo de fallback global

O BasicRouter suporta a definição de um modelo de fallback global no backend do console. Todas as solicitações usam automaticamente este modelo como backup quando falham.

Como configurar:

1. Acesse a página de configurações de estratégia do BasicRouter.
2. Encontre a configuração de Modelo de Fallback Padrão.
3. Selecione seu modelo de fallback global na lista suspensa.
4. Salve a configuração para aplicá-la imediatamente.

Vantagens da configuração global:

• Sem alterações de código: configure uma vez e aplica-se globalmente, sem necessidade de repetir a configuração em cada solicitação.
• Gerenciamento centralizado: gerencie a política de fallback em um único local para ajuste e monitoramento mais fáceis.
• Manutenção simplificada: reduz a complexidade do código e a chance de erros de configuração.
• Substituição flexível: a configuração de fallback no nível da solicitação tem prioridade e pode substituir a configuração global para cenários específicos.

Configuração de fallback no nível da solicitação

Para cenários de negócio específicos, você pode especificar um modelo de fallback em uma solicitação individual para substituir a configuração global.

Especifique o modelo de fallback com o parâmetro router.fallBackModels:

Copiar{
  "model": "claude-sonnet-4",
  "messages": [
    {
      "role": "user",
      "content": "Explain what quantum computing is"
    }
  ],
  "router": {
    "fallBackModels": ["glm-5.2"]
  }
}

Regras de prioridade

Quando várias configurações de fallback estão presentes, a prioridade vai da mais alta para a mais baixa:

1. router.fallBackModels no nível da solicitação: o modelo de fallback especificado em uma solicitação individual.
2. Modelo de Fallback Padrão Global: o modelo de fallback global configurado no console.
3. Sem fallback: se nenhum dos dois estiver configurado, a solicitação retorna um erro em caso de falha.

Administração da conta

Dependendo do tipo de conta, o console pode incluir ativação de modelos no nível da conta, controles de revendedor ou distribuidor, configuração de cobrança e configurações de acesso. Os administradores podem usar esses controles para alinhar o acesso a modelos, a visibilidade de uso e a responsabilidade de cobrança com aplicações, contas de cliente ou unidades de negócio.

Lista de verificação de operações de produção

Cobrança e créditos

O BasicRouter usa um modelo de cobrança baseado em créditos para cargas de trabalho de texto, imagem, vídeo e outros modelos suportados. Os créditos fornecem uma unidade unificada para uso de múltiplos modelos e múltiplos provedores, permitindo que as equipes gerenciem o consumo de forma consistente entre modalidades e famílias de API.

Os preços detalhados dos modelos estão disponíveis na página de Modelos ou através das APIs de metadados de modelo. O preço pode variar por modelo, provedor, modalidade, resolução, tipo de token, compramento de saída, duração da tarefa, tipo de conta e acordo comercial.

Recarga e carteira

As contas podem adicionar créditos de carteira pré-pagos para uso flexível. Os créditos da carteira são usados após os créditos do plano mensal e dos pacotes de recursos serem consumidos, a menos que uma regra billing rule applies to the account.

Os créditos da carteira não expiram, salvo especificação em contrário nos termos comerciais aplicáveis. Uma taxa de serviço é cobrada ao recarregar a carteira pré-paga.

Planos mensais e pacotes de recursos

Cada usuário ou conta pode selecionar um plano mensal ativo. Os planos mensais fornecem uma quantidade definida de capacidade de uso, termos comerciais e configuração de acesso no nível da conta para o período de cobrança.

Os usuários também podem comprar vários pacotes de recursos para capacidade de uso adicional. Os pacotes de recursos podem separar o uso comprometido do saldo da carteira pré-paga e são úteis para uso de alto volume de texto, imagem, vídeo ou cargas de trabalho dedicadas.

Ordem de dedução

A menos que regras de cobrança personalizadas estejam configuradas, os créditos são deduzidos na seguinte ordem:

Para contas com termos comerciais personalizados, a ordem de dedução, regras de expiração, uso incluído e preços podem ser diferentes. As regras específicas da conta são mostradas no console ou fornecidas através do acordo comercial.

Preços personalizados

Os preços podem ser personalizados para cada usuário ou conta. Clientes corporativos, contas de revendedor, contas de distribuidor e clientes de alto volume podem ser elegíveis para preços personalizados. Entre em contato com as vendas para uma cotação.

Os preços personalizados podem ser configurados por conta, modelo, provedor, modalidade, região, volume de uso ou acordo comercial. Quando os preços personalizados são ativados, o console e as APIs de cobrança refletem os preços e regras de dedução específicos da conta quando disponíveis.

Unidades de preço

Diferentes modalidades de modelo usam diferentes unidades de medida. O BasicRouter converte essas unidades em créditos de acordo com as regras de preço do modelo.

As unidades de preço podem variar por modelo. Sempre consulte a página de detalhes do modelo ou os metadados de preço antes de ativar um modelo em produção.

Atribuição de uso

O uso do BasicRouter pode ser revisado por conta, chave API, modelo, modalidade ou intervalo de tempo. Isso permite que as equipes atribuam custos a aplicações, ambientes, clientes ou unidades de negócio internas.

Saldo de créditos

Verifique quantos créditos estão disponíveis em sua conta. O saldo é dividido em três carteiras que são deduzidas em ordem: a allowances do plano mensal, pacotes de recursos comprados e a carteira pré-paga. Um total combinado de recursos (plano mensal + pacotes de recursos, excluindo o pré-pago) também está disponível para rastrear o uso incluído separadamente dos gastos de recarga.

Para recuperar isso programaticamente, consulte GET /v1/billing/balance na Referência da API.

Detalhes de uso

Revise uma lista paginada e cronológica de registros de uso individuais para relatórios, monitoramento e alocação interna de custos. Cada registro mostra o modelo, tipo de modelo (texto, imagem ou vídeo), os créditos deduzidos e um detalhamento de qual carteira cada dedução foi retirada. Os resultados podem ser filtrados por um intervalo de tempo específico.

Para recuperar isso programaticamente, consulte GET /v1/usage na Referência da API.

Histórico de transações

Use o histórico de transações para revisar movimentações de créditos, incluindo recargas, alocações de plano, concessões de pacotes de recursos, deduções de uso, ajustes e correções administrativas.

Para recuperar isso programaticamente, consulte GET /v1/billing/transactions na Referência da API.

Solicitações com falha e reembolsos

Erros de validação, erros de autenticação e erros de permissão geralmente não são cobrados porque nenhuma execução de modelo ocorre. Solicitações que alcançam um modelo upstream ou geram saída parcial podem consumir créditos dependendo do modelo, provedor e estado da resposta.

Para tarefas assíncronas de imagem e vídeo, o comportamento de cobrança depende se a tarefa foi aceita, iniciada, concluída, falhou ou foi cancelada. A resposta de detalhes da tarefa inclui informações de uso quando os créditos foram consumidos.

Recargas, planos mensais, pacotes de recursos e créditos consumidos não são reembolsáveis, a menos que especificado de outra forma no acordo comercial aplicável ou exigido por lei.

Operacional

Erros

O BasicRouter retorna códigos de erro estáveis para que as aplicações possam lidar com repetições, fallbacks, problemas de cobrança e depuração de forma consistente.

Endpoints compatíveis com provedores tentam preservar o formato de erro da família de API original quando possível. Endpoints nativos do BasicRouter usam o objeto de erro do BasicRouter.

Mapeamento de status HTTP e códigos de erro

Códigos de erro comuns