Um gateway de IA é uma camada, não um ganho de capacidade.

A definição, sem rodeio

Um gateway de IA é um proxy com contrato próprio. Ele expõe uma interface estável para a sua aplicação e traduz essa interface para as APIs dos provedores por trás. Na maioria das implementações, a interface exposta é a da API da OpenAI, porque é a que os SDKs e as bibliotecas já falam.

Do lado de dentro, cada provedor tem autenticação, formato de payload, nomes de campo, semântica de erro e comportamento de streaming próprios. O gateway absorve essa diferença. O que sai dele é sempre o mesmo envelope, independentemente de qual laboratório atendeu.

Isso é um deslocamento de responsabilidade, não um ganho de capacidade. A complexidade continua existindo. Ela apenas deixa de morar no seu código de produto.

Para ver o tamanho da diferença que a camada absorve, abra a referência de duas APIs de modelos diferentes e compare o corpo de uma requisição de chat. Os campos não batem.

• Entrada: um endpoint, um header de autenticação, um campo model.
• Saída: um formato de resposta previsível para todos os modelos.
• Efeito colateral desejado: um único ponto onde se mede uso e custo.

O problema de arquitetura que essa camada resolve

Sem gateway, o acoplamento a um provedor não é uma decisão explícita: ele acontece por acúmulo. Um SDK aqui, um cliente HTTP ali, um formato de mensagem copiado de um exemplo, e quando alguém propõe trocar de modelo a resposta já é refatoração.

O sintoma mais barato de medir é a chave. Ela raramente fica em um lugar só. Aparece em variável de ambiente do backend, em um worker, em um script de dados, em um workflow de automação e em algum repositório privado que alguém considerou seguro.

O segundo sintoma é o custo invisível. Quando cada equipe integra direto com o provedor, ninguém responde quanto o produto gastou com IA na semana passada, por funcionalidade. A resposta vem da fatura, depois, agregada.

São sintomas com uma causa comum: não existe um lugar só por onde as chamadas de IA passam. É isso que um gateway cria, não por sofisticação, por posição. Dá para medir o tamanho do problema no seu repositório agora: procure pelos domínios dos provedores e pelos prefixos de chave nos arquivos versionados.

• Acoplamento: o produto depende de um contrato seu, não do de um terceiro.
• Troca de modelo: vira mudança de string, não mudança de cliente.
• Credencial: uma chave por projeto, revogável em um lugar.
• Custo: medido por requisição, no momento da requisição.

O que um AI gateway faz na prática

Retirando o discurso, a lista de responsabilidades é curta e verificável. Cada item abaixo pode ser conferido olhando uma requisição real e o registro que ela deixa.

Autenticação vem primeiro: o gateway valida a sua chave antes de gastar qualquer coisa com o provedor. Depois vem o roteamento: o valor do campo model decide para onde a chamada vai, e essa decisão é do seu código, não do gateway.

Medição de tokens e registro de custo vêm juntas. O gateway conta entrada e saída, aplica o preço do modelo e debita o saldo. Controle de custo é consequência disso: só é possível limitar o que se mede na hora em que acontece.

A última responsabilidade é a mais fácil de subestimar: manter um formato de resposta só. É o que permite que a camada acima do gateway não precise saber qual laboratório respondeu. Confira a lista na sua conta: se um item não aparece em registro nenhum, ele não está sendo feito.

• Autentica a requisição antes de encaminhar.
• Roteia pelo ID do modelo informado na chamada.
• Mede tokens de entrada e de saída.
• Registra custo por chamada, por chave e por modelo.
• Devolve um envelope de resposta consistente.

O que um LLM gateway não faz

Um gateway não melhora a qualidade do modelo. A resposta que você recebe é a resposta que aquele modelo daria de qualquer forma. Se o resultado está ruim, a causa é escolha de modelo, prompt ou contexto, e continuará ruim depois da migração.

Um gateway não elimina a dependência de terceiros. Ele troca várias dependências diretas por uma indireta. Isso reduz o custo de trocar de modelo e concentra risco em um ponto só. É uma troca, não uma eliminação de risco, e precisa entrar no seu plano de continuidade com esse nome.

Um gateway acrescenta um salto de rede. A requisição sai da sua aplicação, chega ao gateway, sai do gateway para o provedor e faz o caminho de volta. O overhead de processamento costuma ser pequeno perto do tempo de geração do modelo, mas não é zero e depende de onde o seu serviço roda.

Também não garante que um modelo específico está disponível. Catálogo é decisão de operação e muda. A forma de checar cada uma dessas afirmações é direta: rode a mesma chamada pelos dois caminhos e compare texto, tempo total e disponibilidade do ID no catálogo.

• Não substitui avaliação: continue testando prompt e modelo com os seus dados.
• Não é cache automático nem redução automática de tokens.
• Não dispensa timeout, retry limitado e tratamento de erro no seu serviço.

Gateway próprio ou gateway gerenciado

Escrever o seu próprio é viável. Um proxy que aceita o formato de chat, mapeia dois ou três provedores e registra tokens cabe em pouco código. O que não cabe em pouco código é o que vem depois: acompanhar mudanças de API dos provedores, manter a tabela de preços correta, tratar streaming, lidar com formatos de erro diferentes e sustentar isso quando a pessoa que escreveu sai do time.

A favor do próprio: controle total do roteamento, liberdade para aplicar políticas internas e tráfego dentro da sua infraestrutura. Contra: é mais um serviço em produção, com plantão, deploy e conta de nuvem próprios, e ele fica no caminho crítico de todas as chamadas de IA do produto.

A favor do gerenciado: você não mantém integração, catálogo nem tabela de preço, e ganha medição desde a primeira chamada. Contra: você adota o contrato de outra empresa, aceita o catálogo dela e passa a depender da disponibilidade dela.

O critério prático costuma ser volume e tamanho de time. Uma forma de não precisar decidir para sempre: isolar a chamada ao gateway atrás de uma função sua. Abra o seu código e veja se essa função existe. Se existir, trocar de gateway também é barato.

• Próprio: mais controle, mais superfície operacional para manter.
• Gerenciado: menos manutenção, mais dependência de um contrato de terceiro.
• Nos dois casos: uma camada fina no seu código preserva a opção de mudar de ideia.

Implementação na Roteia: base URL e chave

Na prática, adotar a Roteia como gateway de IA é mudar duas referências no cliente que você já usa. A base URL passa a apontar para https://api.roteia.ai/v1 e a chave passa a ser uma criada em https://app.roteia.ai. A autenticação vai no header Authorization, no formato Bearer.

O restante da chamada permanece no formato de chat compatível com o da OpenAI. O modelo continua sendo escolhido no corpo da requisição, com o ID completo copiado do catálogo em /modelos/. A chave completa aparece apenas no momento em que é criada, então guarde-a como segredo.

O exemplo abaixo mostra a troca em Python. Não há cliente novo para aprender: é o mesmo SDK, com base_url diferente.

import os
from openai import OpenAI

# a única mudança estrutural: base_url + chave
client = OpenAI(
    api_key=os.environ["ROTEIA_API_KEY"],
    base_url="https://api.roteia.ai/v1",
)

response = client.chat.completions.create(
    model="deepseek/deepseek-v4-flash",
    messages=[{"role": "user", "content": "Responda apenas: ok"}],
)

print(response.choices[0].message.content)

A mesma troca em Node.js

Em Node.js a mudança é idêntica: baseURL no construtor do cliente e a chave vinda do ambiente do servidor. Não coloque uma chave de produção em código que roda no navegador ou em aplicativo distribuído.

Depois de rodar, confira o consumo no painel. Se a chamada apareceu associada à chave, ao modelo e a um custo em Real, o caminho inteiro está funcionando: autenticação, roteamento e medição.

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ROTEIA_API_KEY,
  baseURL: "https://api.roteia.ai/v1",
});

const response = await client.chat.completions.create({
  model: "deepseek/deepseek-v4-flash",
  messages: [{ role: "user", content: "Responda apenas: ok" }],
});

console.log(response.choices[0].message.content);

O que medir antes de mover produção

Trocar a base URL leva minutos. Validar leva mais, e é a parte que evita surpresa. Rode uma chamada representativa do seu produto pelos dois caminhos e compare tempo total, formato da resposta e custo registrado. A diferença de latência é o preço da camada, e ele deve ser medido no seu ambiente, não estimado a partir de um número de terceiro.

Teste também os caminhos infelizes: chave inválida, modelo inexistente, saldo insuficiente e requisição malformada. Um gateway se prova no erro, não no caso feliz.

O passo a passo da primeira chamada está em /docs/primeira-chamada/, o checklist de migração em /docs/migrar-openrouter/ e o restante da documentação em /docs/.

• Compare latência ponta a ponta nos dois caminhos, com o seu payload real.
• Force os erros e confira status HTTP e corpo retornado.
• Confirme o ID do modelo no catálogo antes de fixá-lo em código.
• Comece com uma fatia pequena do tráfego e mantenha um caminho de volta.

A Roteia, em termos objetivos

A Roteia é um gateway de IA brasileiro. O saldo é pré-pago em Real, com recarga por Pix, boleto ou cartão conforme a disponibilidade no painel, e NFS-e mediante solicitação. Os preços em Real estão em /precos/ e a lista de modelos liberados, nas categorias texto, imagem, transcrição, embeddings, áudio e vídeo, está em /modelos/.

A Roteia é independente e não pertence nem representa OpenAI, Anthropic, Google, DeepSeek ou OpenRouter. É um produto da NOCLAF INOVAÇÕES TECNOLÓGICAS LTDA, CNPJ 34.133.258/0001-88, Teresópolis/RJ. Dúvidas técnicas em português: suporte@roteia.ai.

Se o seu recorte é a camada do ponto de vista de produto, /gateway-llm/ trata do mesmo assunto. Se for comparar formas de acesso multimodelo, /agregador-de-ia/. A conferência final é sempre a mesma: abra o catálogo e veja se o ID que você pretende usar está lá.