OpenRouter: o que é, como usar e quando vale a pena

Tem um padrão que se repete no OpenRouter há uns dois anos: um modelo sem dono aparece na lista, de graça, com nome de bicho, e começa a comer tráfego de todo mundo. Em 28 de abril de 2026 foi o Owl Alpha. Rodou dois meses disfarçado, entrou no top da plataforma em volume de chamadas e só em 30 de junho a Meituan assumiu: era o LongCat-2.0, 1,6 trilhão de parâmetros em MoE — a gente contou essa história inteira aqui. Se você testou aquele modelo, já usou o OpenRouter sem parar pra perguntar o que é o OpenRouter.

A resposta curta: é um endpoint só, compatível com a API da OpenAI, que fala com centenas de modelos de dezenas de provedores diferentes. Uma chave, uma URL base, um formato de payload. Troca de modelo vira troca de string.

Neste post você vai ver o que ele faz por baixo do capô, as chamadas que importam (curl, Python e PHP), como controlar roteamento e custo, e — a parte que quase ninguém escreve — quando essa camada extra não vale a pena.

TL;DR

• O que é: gateway unificado de LLM. Um endpoint OpenAI-compatible para 400+ modelos e provedores, com fallback automático entre eles.
• Stack/Modelos: qualquer client OpenAI (Python, Node, PHP, Go) apontando para https://openrouter.ai/api/v1.
• Custo/Acesso: preço dos modelos é repassado sem markup; a taxa fica na compra de crédito (5,5% via Stripe, mín. US$ 0,80; 5% em cripto). Tem modelos :free com limite de requisição.
• Link útil: openrouter.ai/docs/quickstart

O que é o OpenRouter, na prática

Antes dele, suportar três modelos em produção significava três SDKs, três formatos de erro, três esquemas de autenticação e três contratos de faturamento. Você escrevia um adaptador por provedor e rezava para nenhum deles mudar o shape da resposta.

O OpenRouter troca isso por uma indireção. Você fala OpenAI-compatible com ele; ele fala o dialeto nativo de cada provedor por baixo. O slug do modelo carrega a informação toda no formato autor/modelo — anthropic/claude-sonnet-4.5, openai/gpt-latest, deepseek/deepseek-chat. Trocar de laboratório é editar uma linha do .env.

A parte interessante não é a tradução, é o roteamento. O mesmo modelo open source costuma estar hospedado em vários provedores, com preço, latência e quantização diferentes. Por padrão, o OpenRouter faz balanceamento por preço: descarta quem teve outage recente e sorteia os demais com peso inverso ao quadrado do preço — um provedor a US$ 1 por milhão de tokens tem 9x mais chance de ser escolhido que um a US$ 3, segundo a documentação. Provedor caiu, ele tenta o próximo sem você saber.

Isso é decisão de arquitetura, não de gosto: você está terceirizando failover de inferência para um terceiro. É o tipo de escolha que a gente resolve com código rodando e número na mesa, toda semana ao vivo, no Clã Beer and Code. É pago, é assinatura, e é exatamente o ambiente que este post descreve.

Pré-requisitos

• Conta em openrouter.ai e uma chave em OPENROUTER_API_KEY.
• Crédito comprado (ou nada, se você for só brincar com os modelos :free).
• Qualquer client OpenAI-compatible: openai no Python/Node, Http do Laravel no PHP, ou curl puro.
• Noção de que base_url é configurável. É literalmente esse o truque.

Mão na massa

Passo 1: a primeira chamada

Nada de SDK novo. Só apontar o client existente para outro lugar.

curl https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4.5",
    "messages": [{"role": "user", "content": "Explique embeddings em 2 frases."}]
  }'

Em Python, o SDK da OpenAI resolve tudo:

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",
    messages=[{"role": "user", "content": "Explique embeddings em 2 frases."}],
)
print(resp.choices[0].message.content)

Trocou deepseek/deepseek-chat por google/gemini-3-pro? Mesma chamada, mesma resposta parseada, outra fatura. É esse o produto.

Passo 2: fallback de modelo

Aqui começa a diferença real para chamar o provedor direto. Você declara uma lista de modelos: se o primeiro falhar (rate limit, filtro de conteúdo, provedor fora do ar), a requisição escorrega para o próximo sem estourar exceção no seu código.

{
  "model": "anthropic/claude-sonnet-4.5",
  "models": ["openai/gpt-latest", "google/gemini-3-pro"],
  "messages": [{"role": "user", "content": "..."}]
}

A resposta traz o campo model com quem realmente atendeu. Logue esse campo. Sem ele, você não sabe qual modelo gerou a saída que o cliente reclamou — e isso destrói qualquer eval sério.

Dá para descer um nível e controlar o provedor:

{
  "model": "meta-llama/llama-4-70b-instruct",
  "provider": {
    "sort": "throughput",
    "ignore": ["Provedor-X"],
    "data_collection": "deny",
    "max_price": { "prompt": 1.0, "completion": 3.0 }
  }
}

data_collection: "deny" só roteia para provedores que não retêm seu prompt. max_price põe teto por milhão de tokens. sort aceita price, throughput ou latency — e desliga o balanceamento por preço, indo em ordem determinística.

Passo 3: preço e catálogo pela API

O endpoint /api/v1/models devolve o catálogo inteiro com preço, contexto e parâmetros suportados. Dá para montar um seletor de modelo por orçamento sem hardcodar tabela de preço que envelhece em duas semanas:

curl -s https://openrouter.ai/api/v1/models \
  | jq -r '.data[] | select(.context_length >= 200000)
           | [.id, .pricing.prompt, .pricing.completion] | @tsv' \
  | sort -k2 -n | head

Passo 4: no Laravel

Sem pacote, sem abstração nova:

$response = Http::withToken(config('services.openrouter.key'))
    ->post('https://openrouter.ai/api/v1/chat/completions', [
        'model'  => 'anthropic/claude-sonnet-4.5',
        'models' => ['openai/gpt-latest'],
        'messages' => [
            ['role' => 'system', 'content' => 'Você responde em PT-BR, direto.'],
            ['role' => 'user', 'content' => $pergunta],
        ],
    ])->throw()->json();

Log::info('llm.call', [
    'model_usado' => $response['model'],
    'tokens' => $response['usage']['total_tokens'] ?? null,
]);

Se você já usa Prism ou o Vercel AI SDK, ambos aceitam um driver OpenAI-compatible com baseUrl customizada. Mesma história.

Quando vale a pena (e quando não)

Vale quando:

• Você precisa comparar modelos com o mesmo código, sem reescrever adaptador para cada eval.
• Seu produto tem rotas de custo diferente: modelo barato para classificar, caro para redigir. É uma das alavancas que a gente destrincha em como reduzir custo de API de IA.
• Você quer acesso a modelo chinês ou open source hospedado por terceiros sem abrir conta em cinco lugares.
• Disponibilidade importa mais que controle: fallback entre provedores sai de graça.

Não vale quando:

• Você usa um modelo só e não pretende trocar. Aí é um hop de rede e um ponto de falha a mais entre você e a Anthropic/OpenAI.
• Você depende de recurso de ponta específico do provedor (cache de prompt com regra própria, batch API, tiers de latência, features beta). O denominador comum de um gateway é sempre menor que a API nativa.
• Você tem contrato ou compliance que exige relação direta com o provedor. Nesse caso, avalie o BYOK: você pluga sua própria chave e usa só o roteamento, com franquia de US$ 25 mil/mês no plano pay-as-you-go e 5% do custo equivalente acima disso.

Limitações e pontos de atenção

O mesmo slug pode rodar em provedores com quantização diferente. Um int4 e um fp8 do mesmo modelo não entregam a mesma qualidade — e se você não fixou provider.only ou quantizations, sua eval de ontem pode não reproduzir hoje. Esse é o bug mais chato e mais silencioso da camada.

Roteamento também vaza para o determinismo: com models e fallback ligados, duas chamadas idênticas podem ser atendidas por modelos diferentes. Ótimo para uptime, péssimo para debugar regressão. Em pipeline de avaliação, desligue o fallback.

Privacidade: por padrão o OpenRouter não loga prompt nem completion — só metadado (timestamp, modelo, contagem de token). Existe um opt-in que troca log por 1% de desconto. Antes de ligar isso em produto com dado de cliente, leia o contrato inteiro. E lembre que o provedor final tem política própria: é para isso que serve o data_collection: "deny".

Por fim, latência. Todo gateway adiciona um hop. Para chat interativo é ruído; para pipeline com dezenas de chamadas encadeadas, mede antes de assumir que é irrelevante.

FAQ

O OpenRouter é mais caro que ir direto no provedor? No token, não: o preço é repassado sem markup. A taxa fica na compra de crédito, 5,5% via cartão (mínimo US$ 0,80) ou 5% em cripto. Em volume, isso é o preço do failover.

Os modelos :free servem para produção? Não. Sem crédito na conta o limite é de 50 requisições por dia; com US$ 10 ou mais, sobe para 1.000 por dia. É bancada de teste, não infraestrutura.

Como sei qual modelo respondeu quando uso openrouter/auto? Pelo campo model da resposta. O Auto Router classifica a tarefa e escolhe com base no share de gasto da plataforma nos últimos 7 dias, filtrado pelo cost_tier que você definir. Sem logar esse campo, você perde rastreabilidade.

Dá para usar minha própria chave da OpenAI por trás dele? Dá, via BYOK. Você mantém a relação comercial com o provedor e usa o OpenRouter só como camada de roteamento e observabilidade.

O ponto

O OpenRouter não é mágica. É uma indireção bem executada: um endpoint, um formato, e a decisão de qual modelo atende virando configuração em vez de deploy.

O ganho real não é economizar SDK. É que o custo de trocar de modelo cai tanto que você passa a testar de verdade — e aí descobre, com número, que aquele modelo de US$ 0,75 por milhão resolve 80% das suas rotas. Foi assim que um modelo sem nome, sem dono e sem release virou top da plataforma antes de qualquer post de lançamento.

O próximo passo é parar de escolher modelo por intuição: instrumente as chamadas, guarde o campo model, e deixe o dado decidir.