OpenRouter
A integração OpenRouter dá aos agentes da sua organização acesso aos modelos da sua própria conta OpenRouter. As chamadas de LLM desses modelos usam o saldo da sua conta OpenRouter: a SIPPulse AI não cobra créditos por elas, e o uso aparece no dashboard com custo zero.
Diferente das demais integrações de provedores, aqui você escolhe modelo por modelo quais ficam disponíveis para os agentes, e cada modelo pertence só à sua organização.
Quem pode usar
Owners e admins da organização conectam a chave e gerenciam os modelos. Os demais membros usam os modelos já liberados nos agentes, mas não veem nem alteram a integração. Membros com papel restrito ao projeto recebem 403 ao tentar gerenciar a integração.
Conectar a chave
- No OpenRouter, crie uma chave de API comum em openrouter.ai/settings/keys. Chaves de provisionamento (management) não são aceitas.
- Na plataforma, abra Integrações e selecione OpenRouter.
- Clique em Conectar, cole a chave e confirme.
A chave é validada no OpenRouter antes de ser salva. Ela é recusada quando é uma chave de provisionamento, está expirada ou não tem saldo. Depois de salva, só um trecho mascarado da chave aparece na tela.
Escolher modelos
- Clique em Escolher modelos. O catálogo mostra os modelos da sua conta OpenRouter que são compatíveis com os agentes; modelos já adicionados não aparecem.
- Busque por nome, fabricante ou ID e selecione até 10 modelos por vez. A organização pode ter até 50 modelos OpenRouter.
- Escolha como adicionar:
- Adicionar sem testar: os modelos ficam disponíveis para os agentes na hora. Se a plataforma já testou aquele modelo, ele aparece como Validado pela plataforma; senão, como Não testado.
- Continuar com N: abre o teste. Só os modelos aprovados são adicionados.
Alguns itens do catálogo trazem a cobertura que a plataforma já tem: Já validado (todos os testes que o modelo anuncia foram provados) ou Essencial coberto (os testes básicos foram provados; os opcionais não).
Um modelo já validado pela plataforma para outra organização pode ser importado sem um novo teste: ele entra como Validado pela plataforma.
Testar modelos
O teste envia um número limitado de requisições reais ao OpenRouter com a sua chave, então consome tokens da sua conta. Ele só começa depois que você marca a autorização de consumo.
| Nível | O que confere | Limite |
|---|---|---|
| Teste essencial | resposta de texto e medição de tokens, chamada de ferramenta, chamada de ferramenta em streaming e continuação depois da ferramenta, no mesmo formato que um agente usa | 4 chamadas por modelo |
| Teste completo | o essencial mais os recursos que o modelo anuncia: saída estruturada, visão, leitura de PDF e raciocínio | até 8 chamadas por modelo |
O teste roda em segundo plano: você pode fechar a janela e voltar depois. Uma organização roda um teste por vez. Cada modelo termina Aprovado, Reprovado ou Inconclusivo, e o resultado mostra chamadas, tokens e o custo informado pelo OpenRouter. Prompts e respostas do teste não são armazenados.
Inconclusivo quase sempre é instabilidade momentânea (limite de requisições, tempo esgotado). Nesse caso nada muda no modelo; use Tentar novamente. Para testar de novo um modelo já adicionado, use o botão Testar na linha dele.
Usar nos agentes
Modelos com status Pronto aparecem no seletor de modelo dos agentes da organização e são executados com a chave da sua organização em todos os canais do agente, inclusive voz.
A plataforma nunca troca de modelo sozinha. Se um modelo não puder executar, o agente recebe um erro explicando o motivo, em vez de responder com outro modelo.
Mesmo quando o modelo usa a sua própria chave e não consome créditos pelo modelo, a chamada continua passando pela autorização de crédito do item do agente.
Conteúdo que o modelo não suporta
Cada modelo mostra as capacidades que tem (ferramentas, visão, PDF, raciocínio, saída estruturada). Enviar a um agente um conteúdo que o modelo não suporta é recusado antes de chamar o OpenRouter, sem alterar a configuração do agente:
- imagem para modelo sem visão: "Este modelo não aceita imagens como entrada.";
- PDF para modelo sem leitura de PDF: "Este modelo não aceita arquivos PDF como entrada.";
- no Telegram, uma foto enviada ao agente recebe como resposta "Desculpe, não foi possível processar sua imagem. Por favor, tente novamente ou envie uma mensagem de texto.".
Para aceitar esse conteúdo, troque o agente para um modelo com a capacidade.
Status dos modelos
| Status | Significado |
|---|---|
| Pronto | disponível para novos agentes e em uso normal |
| Suspenso | escondido do seletor de modelos; você decidiu tirá-lo de uso |
| Indisponível | não executa: a chave deixou de valer, o modelo saiu da sua conta OpenRouter ou foi reprovado. O motivo aparece na linha do modelo |
Suspender e retomar
O interruptor Disponível na linha do modelo suspende e retoma.
- Modelo sem agentes: é suspenso na hora e some do seletor.
- Modelo em uso: a plataforma mostra os agentes afetados e pede um modelo substituto pronto da organização, além da confirmação do impacto. Os agentes passam para o substituto e o modelo é suspenso numa única operação.
Retomar volta o modelo para Pronto. Um modelo Indisponível por reprovação no teste também pode ser habilitado ("Este modelo foi reprovado no teste. Habilitar mesmo assim."), porque um teste pode falhar por um detalhe que não afeta o uso real. Modelos que precisam ser testados de novo com a chave atual só voltam depois do teste.
Trocar a chave
Clique em Substituir chave e informe a nova chave. Ela é validada antes de qualquer mudança; se for recusada, a chave atual continua valendo.
- Sem modelos adicionados: a troca é imediata.
- Com modelos adicionados: começa uma rotação. A chave atual continua atendendo os agentes enquanto todos os modelos são testados com a nova chave (teste completo, com a sua autorização de consumo). Ao terminar, clique em Concluir rotação.
- Modelos aprovados seguem Prontos com a nova chave.
- Modelos reprovados que nenhum agente usa ficam Suspensos.
- Se um modelo reprovado ainda é usado por algum agente, a rotação não conclui: troque o modelo desses agentes e conclua de novo.
Remover um modelo
Clique no ícone de lixeira na linha do modelo.
- Sem agentes usando: confirme a remoção.
- Com agentes usando: a plataforma lista os agentes afetados. Escolha um modelo substituto pronto da organização, confirme o impacto e, na segunda confirmação, digite
REMOVE. Todos os agentes passam para o substituto e o modelo é removido na mesma operação: ou tudo muda, ou nada muda.
Sem substituto disponível não é possível remover um modelo em uso. Adicione ou retome outro modelo OpenRouter antes.
Um modelo removido volta ao catálogo e pode ser adicionado de novo.
Remover a integração
O ícone de lixeira ao lado de Substituir chave remove a chave, todos os modelos OpenRouter e o histórico de testes da organização. Se algum agente usa um modelo OpenRouter, escolha antes um modelo substituto da plataforma para esses agentes e confirme o impacto.
Quando a chave para de funcionar
Se a chave for revogada ou apagada no OpenRouter, expirar ou ficar sem saldo, a integração passa a mostrar erro e todos os modelos ficam Indisponíveis. Os agentes não perdem a configuração: continuam apontando para os mesmos modelos e recebem o erro "Esta chave OpenRouter não pode ser usada. Verifique o tipo, o saldo e a validade da chave." até você substituir a chave.
Mensagens frequentes
| Mensagem | O que fazer |
|---|---|
| Esta chave OpenRouter não pode ser usada. Verifique o tipo, o saldo e a validade da chave. | use uma chave comum, com saldo e dentro da validade |
| Sua conta OpenRouter não tem saldo suficiente para esta solicitação. Adicione créditos em openrouter.ai. | recarregue a conta OpenRouter |
| O limite de requisições do OpenRouter foi atingido. Tente novamente em instantes. | aguarde ou aumente o limite na sua conta |
| Este modelo OpenRouter não está disponível no momento. | veja o motivo na linha do modelo; teste de novo ou escolha outro |
| O OpenRouter não tem rota para este modelo que aceite um dos parâmetros da requisição. | ajuste os parâmetros do agente (por exemplo raciocínio ou saída estruturada) |
| Os modelos OpenRouter precisam ser validados novamente com a chave atual. | teste os modelos de novo |
| Escolha um modelo substituto disponível para os agentes afetados. | selecione um substituto antes de suspender ou remover |
| Substitua os modelos rejeitados pela nova chave nos agentes afetados. | troque o modelo desses agentes e conclua a rotação |
Segurança
A chave é criptografada antes de ser armazenada e nunca é exibida de novo por inteiro. Chave, prompts e respostas não são gravados em logs nem no histórico de testes.