🌀 O problema de gerenciar múltiplas APIs
Antes do OpenRouter, integrar quatro providers significava quatro chaves de API, quatro dashboards, quatro faturas e quatro modelos de rate limit. Cada provider tinha um schema ligeiramente diferente, e trocar de modelo significava reescrever código.
O que é
A fragmentação do ecossistema de LLMs em silos provider-específicos: Anthropic, OpenAI, Google, DeepSeek, Mistral e dezenas de outros — cada um com seu próprio endpoint, schema, sistema de autenticação, política de billing, mecanismo de rate limit e formato de erro. O OpenRouter unifica tudo atrás de uma única interface.
✗ Antes do OpenRouter
- ✗4+ chaves de API espalhadas no `.env`
- ✗4 dashboards de billing diferentes para conciliar
- ✗SDKs incompatíveis — schemas diferentes
- ✗Rate limits por provider, gestão manual
- ✗Quando um provider cai, o código quebra
- ✗Trocar de modelo = reescrever o client
✓ Depois do OpenRouter
- ✓1 chave de API para 300+ modelos
- ✓1 dashboard com breakdown por modelo
- ✓Schema OpenAI-compatível universal
- ✓Rate limit unificado e previsível
- ✓Fallback automático entre providers
- ✓Trocar modelo = trocar uma string
💡 Por que isso importa para o Triad
O Triad usa três modelos diferentes em três papéis (Condutor, Worker, Crítico). Sem o OpenRouter, você precisaria de três contratos, três chaves e três pontos de falha. Com ele, todo o sistema vive atrás de uma única integração.
🔑 Conceitos-chave
Cada LLM provider opera como silo isolado com schema próprio
Cada provider adicional multiplica a superfície de manutenção
O OpenRouter abstrai diferenças e expõe uma interface única
Uma fatura, um dashboard, uma conciliação contábil
🔌 Como o OpenRouter funciona — uma chave, todos os modelos
O OpenRouter expõe um único endpoint OpenAI-compatível. Você troca a base URL, usa sua chave do OpenRouter e seleciona o modelo pelo identificador provider/modelo.
O que é
Uma camada de proxy inteligente que recebe requisições no formato OpenAI Chat Completions, roteia para o provider apropriado com base no campo model, converte schemas quando necessário e devolve a resposta no formato OpenAI — permitindo que qualquer SDK OpenAI funcione com qualquer modelo.
🌐 Endpoint único
POST https://openrouter.ai/api/v1/chat/completions
Authorization: Bearer sk-or-v1-...
Content-Type: application/json
📡 Exemplo: curl mínimo
curl https://openrouter.ai/api/v1/chat/completions \
-H "Authorization: Bearer $OPENROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "anthropic/claude-opus-4-7",
"messages": [{"role": "user", "content": "Hello"}]
}'
🐍 Exemplo: SDK OpenAI em Python
from openai import OpenAI
client = OpenAI(
base_url="https://openrouter.ai/api/v1",
api_key=os.environ["OPENROUTER_API_KEY"],
)
resp = client.chat.completions.create(
model="deepseek/deepseek-chat", # troca aqui = troca de modelo
messages=[{"role": "user", "content": "Olá"}],
)
🏷️ Convenção de nome do modelo
O padrão é sempre provider/nome-do-modelo — previsível e auto-documentado.
🔑 Conceitos-chave
Qualquer SDK OpenAI funciona — só muda a base URL
O campo `model` decide qual provider real recebe a requisição
O OpenRouter traduz entre formatos OpenAI ↔ Anthropic ↔ Google
A/B testar modelos vira mudança de uma string
📊 Dashboard de custos e rastreamento de uso
O dashboard do OpenRouter mostra custo por modelo, por chave, por dia — com granularidade que nenhum provider individual oferece. É a primeira vez que você sabe, em tempo real, qual papel do Triad está consumindo qual fatia do orçamento.
O que é
O painel de observabilidade financeira do OpenRouter — exibe gastos em USD por modelo, por chave de API, por janela temporal (hora/dia/mês), com latência média e contagem de requests. Inclui limites de crédito hard e soft que param a chave quando atingidos.
Spending por modelo
Veja exatamente quanto cada modelo custou no período. Útil para descobrir que o Crítico em GPT está custando 3× o Condutor em Opus.
Spending por chave
Crie uma chave por ambiente (dev/staging/prod) e por papel do Triad. Cada chave tem seu próprio limite.
Latência por modelo
P50, P95 e P99 de latência. Crítico para escolher entre provider rápido e provider barato.
⚙️ Configuração de limite hard na chave
# Settings → API Keys → Create Key
name: "triad-prod-worker"
credit_limit: 50.00 # USD — bloqueia em $50
rate_limit_rpm: 60 # 60 requisições/min
allowed_models: ["deepseek/*"] # só DeepSeek
💡 Dica de ouro
Sempre defina um credit limit hard na chave antes de colocar em produção. Um loop infinito no Worker pode consumir centenas de dólares em minutos. Com limite hard, ele para em $50 e você descobre o bug antes do prejuízo.
🔑 Conceitos-chave
Saber qual papel do Triad consome qual fatia do orçamento
Isola limites e simplifica auditoria de custo
Proteção contra loops descontrolados — bloqueia automaticamente
Decisões de roteamento baseadas em P95 real, não em folheto
🤖 Roteamento automático — :nitro, :floor, :auto
Sufixos no nome do modelo dizem ao OpenRouter como escolher entre provedores do mesmo modelo. Você não precisa decidir entre "Together AI ou Fireworks ou DeepInfra" — declara a intenção (`:floor` = mais barato), o roteador decide.
O que é
Modificadores de roteamento aplicados como sufixo ao identificador do modelo. Para modelos open-weight servidos por múltiplos providers (Together, Fireworks, DeepInfra, Novita…), o sufixo decide qual provider real responde — otimizando para velocidade, preço ou equilíbrio.
:nitro
Mais rápido — escolhe o provider com menor latência P50.
model: "deepseek/deepseek-chat:nitro"
:floor
Mais barato — escolhe o provider com menor preço por token.
model: "deepseek/deepseek-chat:floor"
:auto
Equilíbrio — balanço entre preço, latência e qualidade histórica.
model: "deepseek/deepseek-chat:auto"
🕒 Como uma requisição flui
📐 Controle fino via objeto `provider`
{
"model": "deepseek/deepseek-chat",
"provider": {
"order": ["DeepInfra", "Fireworks"],
"allow_fallbacks": true,
"require_parameters": true,
"data_collection": "deny"
},
"messages": [...]
}
Quando você precisa de garantias (compliance, retenção zero, providers específicos), o objeto `provider` substitui o sufixo com controle total.
🔑 Conceitos-chave
`:nitro`, `:floor`, `:auto` declaram intenção, não provider específico
Modelos open-weight são servidos por vários providers simultaneamente
Quando o sufixo não basta, você define ordem, retenção, fallbacks
A escolha do provider afeta custo e latência sem afetar qualidade do modelo
🔑 Bring Your Own Keys — sua chave da DeepSeek
BYOK (Bring Your Own Keys) deixa você pagar o preço direto do provider, sem markup, mas usando toda a infraestrutura do OpenRouter — roteamento, observabilidade, fallback. É a melhor das duas pontes: preço de provider direto, conveniência de hub.
O que é
Um modo em que você vincula sua chave nativa de um provider (ex.: chave da própria DeepSeek) à sua conta OpenRouter. Quando você requisita um modelo daquele provider, o OpenRouter usa sua chave para autenticar — o provider cobra você diretamente, e o OpenRouter cobra apenas uma pequena taxa de routing.
Crie a chave no provider nativo
No painel da DeepSeek (platform.deepseek.com), gere uma API key dedicada para uso via OpenRouter. Anote o valor.
Vincule no OpenRouter
Settings → Integrations → DeepSeek → Add Key. Cole a chave nativa. O OpenRouter valida e ativa o BYOK para esse provider.
Force o provider via objeto `provider`
Para garantir que o BYOK seja usado (e não outro provider hospedando o mesmo modelo), force a ordem no request.
Concilie em dois dashboards
Tokens aparecem no dashboard da DeepSeek (cobrança real); o OpenRouter mostra apenas a taxa de routing. Use os dois.
🛠️ Request forçando BYOK
{
"model": "deepseek/deepseek-chat",
"provider": {
"order": ["DeepSeek"], # só o provider nativo
"allow_fallbacks": false # sem fallback = preço garantido
},
"messages": [...]
}
💡 Quando BYOK vale a pena
Vale quando você já tem volume contratado com o provider (ex.: créditos prepagos na DeepSeek, descontos de uso ou tier corporativo) e quer aproveitar essas condições mantendo a conveniência do OpenRouter. Para uso ad-hoc ou baixo volume, o pay-as-you-go padrão do OpenRouter geralmente é mais simples.
🔑 Conceitos-chave
Preço direto do provider + infraestrutura do OpenRouter
`allow_fallbacks: false` impede que outro provider receba a request
Tokens cobrados no provider, taxa de routing no OpenRouter
BYOK brilha quando há créditos prepagos ou descontos corporativos
🛟 Fallbacks — resiliência quando um modelo falha
Provedores caem. Modelos atingem capacidade. Tarifas mudam. O OpenRouter permite declarar uma cadeia de fallback no próprio request — se o primeiro modelo falhar, ele tenta o segundo automaticamente, sem código de retry no cliente.
O que é
Um mecanismo de continuidade automática: você fornece um array `models` em vez de um único `model`. Se o primeiro retornar erro 5xx, rate limit, timeout ou capacity, o OpenRouter tenta o próximo, e o próximo — devolvendo no campo `model` da resposta qual realmente respondeu.
📜 Request com cadeia de fallback
{
"models": [
"anthropic/claude-opus-4-7", # primário
"openai/gpt-5.5", # fallback 1
"google/gemini-2.5-pro" # fallback 2
],
"messages": [...]
}
Se Anthropic estiver fora do ar (incidente, rate limit, timeout), OpenAI assume — sem retry no seu código. A resposta inclui "model": "openai/gpt-5.5" para que você saiba quem respondeu.
✗ Sem fallback
- ✗Provider cai → sistema cai
- ✗Rate limit hit → erro retorna ao usuário
- ✗Você precisa codar retry/exponential backoff
- ✗Latência de uma queda = minutos
✓ Com fallback declarativo
- ✓Provider cai → segundo assume em ms
- ✓Rate limit hit → próximo modelo responde
- ✓Sem código de retry no cliente
- ✓Resposta indica qual modelo respondeu
🧭 Estratégia de fallback no Triad
- •Condutor — Opus primário, GPT secundário (qualidade de raciocínio similar para briefing).
- •Worker — DeepSeek primário, Mistral Large secundário (custo baixo mantido).
- •Crítico — GPT primário, Claude Sonnet secundário (ambos rigorosos).
- •Regra de ouro: o fallback deve ter custo e latência aceitáveis — caso contrário, você só atrasa o erro real.
🔑 Conceitos-chave
Lista ordenada de prioridade — primeiro que responder ganha
Resiliência sem código de retry — declarada no próprio request
Campo `model` na resposta diz quem efetivamente respondeu
Modelos com qualidade próxima — não use Opus → modelo fraco
💵 Zero completion fee — o que isso significa
OpenRouter não cobra markup em tokens de completion. Você paga o mesmo preço por token que pagaria direto no provider — o OpenRouter monetiza pelo float de créditos prepagos e por taxas pequenas em adições de crédito. Isso muda a economia em escala.
O que é
A política de pricing do OpenRouter: o preço por token cobrado ao usuário final é igual ao preço de tabela do provider de origem (pass-through pricing). A receita do OpenRouter vem de (a) uma taxa percentual fixa na compra de créditos prepagos — não no consumo — e (b) tier premium de BYOK para uso corporativo.
⚖️ Comparação simplificada
| Item | Provider direto | OpenRouter |
|---|---|---|
| Preço por token completion | Tabela do provider | Igual à tabela (0% markup) |
| Custo de adicionar crédito | Zero (postpaid) | ~5% sobre depósito |
| Integração de N providers | N contratos, N códigos | 1 chave, 1 schema |
| Fallback automático | Você implementa | Declarativo |
| Observabilidade unificada | Não existe | Dashboard nativo |
🧮 Conta no Triad em escala
# Cenário: 1.000 execuções/mês do Triad
# Cada execução = 30k tokens médios entre os 3 papéis
Tokens/mês: 30.000.000
Custo direto (tabela): $X
Custo OpenRouter: $X * 1.00 # 0% markup
Taxa de depósito: ~5% sobre top-ups # cobrado uma vez por depósito
# A taxa de depósito é amortizada conforme você consome
# Em alto volume, o overhead efetivo cai para ~1–2%
💡 Por que isso é raro
A maioria dos hubs cobra 10–30% de markup em tokens — modelo de negócio clássico de revenda. O OpenRouter ganha em volume e em float dos créditos prepagos, o que permite manter pass-through. Em escala, isso transforma "hub" de luxo em escolha racional inclusive financeiramente.
🔑 Conceitos-chave
Token cobrado ao usuário = token cobrado pelo provider
~5% sobre top-ups — amortiza com volume de uso
Receita financeira sobre saldo retido permite o pass-through
Sem markup, a conveniência do hub vem quase de graça
✅ Resumo do Módulo
Próximo Módulo:
1.6 — DeepSeek V4