O KDnuggets publicou um tutorial sobre como usar a API do OpenRouter para acessar vários modelos de IA em aplicações Python por uma única API, comparando respostas, trocando de modelo com uma linha de código e configurando fallbacks automáticos. Abaixo, os principais pontos traduzidos e adaptados para a comunidade CRO Brasil.
O problema que o OpenRouter resolve
Imagine a construção de um assistente de tickets de suporte em que é preciso comparar como GPT, Claude e Llama respondem à mesma mensagem de cliente antes de escolher um deles. No caminho tradicional, isso exige conta em três provedores diferentes, três esquemas de autenticação e a reescrita do código de requisição três vezes para rodar uma única comparação.
O OpenRouter elimina essa repetição. Ele fica na frente de dezenas de provedores e os expõe por uma API única, de modo que trocar de modelo vira a alteração de uma linha, e não uma nova integração. O código Python permanece o mesmo, independente de qual provedor responde à requisição.
O tutorial cobre quatro pontos:
- Criação de conta no OpenRouter e geração da API key
- Envio da primeira requisição a um modelo com Python puro e a biblioteca requests
- Troca de modelo alterando apenas uma string, sem outras mudanças no código
- Seleção automática de modelo pelo OpenRouter e configuração de modelos de backup para confiabilidade
Pré-requisitos e criação da conta
Não é necessário conhecimento de IA ou machine learning para acompanhar. Basta familiaridade com Python básico, instalação de pacotes via pip e definição de variáveis de ambiente no terminal. O OpenRouter cuida da integração com os modelos; o código apenas envia texto e lê a resposta.
O primeiro passo é criar uma conta gratuita no OpenRouter e, na seção Keys do menu da conta, gerar uma nova API key. A recomendação é guardá-la como variável de ambiente para não correr o risco de commitar a chave em um repositório:
export OPENROUTER_API_KEY="sua-chave-aqui"Alguns modelos no OpenRouter são gratuitos para teste, marcados com o sufixo :free, sem necessidade de cadastrar meio de pagamento. Todos os exemplos do tutorial usam esses modelos, então é possível rodar tudo a custo zero. Se um ID de modelo parar de responder, a lista atualizada está em openrouter.ai/models filtrada por modelos gratuitos — ou basta usar openrouter/free, que sempre resolve para o modelo gratuito disponível no momento.
Preparando o projeto
O tutorial sugere criar uma pasta para o projeto com um ambiente virtual e instalar a única dependência necessária, a biblioteca requests. Por ser uma API HTTP simples, não é preciso nenhum SDK especial:
mkdir support-bot-demo
cd support-bot-demo
python -m venv .venv
source .venv/bin/activate
pip install requestsExiste também um SDK oficial do OpenRouter, instalável via pip, que oferece objetos de cliente tipados em vez de dicionários brutos. O tutorial usa apenas requests para manter cada requisição visível como JSON puro, facilitando entender o que está sendo enviado e recebido.
Enviando a primeira requisição
Toda requisição ao OpenRouter tem o mesmo formato, qualquer que seja o modelo: um POST para um único endpoint, com a API key nos headers e uma lista de mensagens no corpo. O script de exemplo envia uma mensagem de suporte ao cliente e imprime a resposta:
import os
import requests
API_URL = "https://openrouter.ai/api/v1/chat/completions"
API_KEY = os.getenv("OPENROUTER_API_KEY")
customer_message = (
"My order #48213 arrived with the wrong charger. "
"I need the correct one before Friday, can you help?"
)
payload = {
"model": "meta-llama/llama-3.2-3b-instruct:free",
"messages": [
{"role": "system", "content": "You are a concise, polite customer support agent."},
{"role": "user", "content": customer_message},
],
}
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
response = requests.post(API_URL, headers=headers, json=payload)
data = response.json()
print(f"Model used: {data['model']}")
print(f"Reply: {data['choices'][0]['message']['content']}")O dicionário payload é a requisição inteira: o campo model indica ao OpenRouter qual modelo usar, no formato provedor/nome-do-modelo, e messages segue o mesmo padrão role/content de qualquer API de chat. A mensagem de sistema define o tom uma única vez e a mensagem de usuário é o texto real do ticket. A resposta volta em JSON, com o texto em data["choices"][0]["message"]["content"] — o mesmo formato da maioria das APIs de chat completion, já que o OpenRouter normaliza a resposta de todos os provedores no formato compatível com o da OpenAI.
Trocando de modelo sem mudar o código
Como o modelo é apenas uma string no payload, comparar provedores significa mudar uma linha. O tutorial encapsula a lógica numa função que recebe o nome do modelo como argumento:
def ask_model(model_name, message):
payload = {
"model": model_name,
"messages": [
{"role": "system", "content": "You are a concise, polite customer support agent."},
{"role": "user", "content": message},
],
}
response = requests.post(API_URL, headers=headers, json=payload)
return response.json()
ticket = "My order #48213 arrived with the wrong charger. I need the correct one before Friday."
for model in ["meta-llama/llama-3.2-3b-instruct:free", "qwen/qwen3-4b:free", "mistralai/mistral-7b-instruct:free"]:
result = ask_model(model, ticket)
reply = result["choices"][0]["message"]["content"]
print(f"--- {model} ---")
print(reply, "\n")O loop chama a mesma função três vezes com três modelos diferentes e imprime cada resposta ao lado do modelo que a produziu. Esse é o benefício central do OpenRouter na prática: uma função chamada três vezes, em vez de três APIs distintas.
Deixando o OpenRouter escolher um modelo gratuito
Quando o modelo específico não importa, definir "model": "openrouter/free" passa a decisão ao Free Models Router do OpenRouter, que sempre seleciona entre os modelos gratuitos disponíveis:
payload = {
"model": "openrouter/free",
"messages": [{"role": "user", "content": ticket}],
}
response = requests.post(API_URL, headers=headers, json=payload)
data = response.json()
print(f"OpenRouter picked: {data['model']}")É o default mais seguro para prototipagem: qualquer que seja o modelo gratuito disponível no dia, nunca há cobrança. É uma configuração diferente de openrouter/auto, que escolhe o modelo mais adequado ao prompt e pode incluir modelos pagos.
Além disso, quando um modelo é especificado pelo nome, o OpenRouter costuma ter mais de um provedor hospedando-o, e é possível escolher qual usar com o campo provider. Por exemplo, payload["provider"] = {"sort": "price"} favorece o provedor mais barato, e {"sort": "latency"} o mais rápido. Isso faz diferença principalmente em modelos pagos com volume real; em modelos :free o efeito é pequeno, já que não há custo por token a otimizar.
Adicionando modelos de fallback para confiabilidade
Um único modelo pode falhar por indisponibilidade do provedor, rate limit, filtro de conteúdo e outros motivos. Para qualquer coisa além de um projeto pequeno, o ideal é ter um backup automático em vez de ver a aplicação quebrar na primeira falha. O OpenRouter aceita uma lista de modelos em vez de um só:
payload = {
"models": [
"qwen/qwen3-4b:free",
"meta-llama/llama-3.2-3b-instruct:free",
"mistralai/mistral-7b-instruct:free",
],
"messages": [{"role": "user", "content": ticket}],
}
response = requests.post(API_URL, headers=headers, json=payload)
data = response.json()
print(f"Answered by: {data['model']}")
print(data["choices"][0]["message"]["content"])A chave muda de model (singular) para models (uma lista). O OpenRouter tenta cada entrada em ordem e retorna a primeira que funciona, sem exigir lógica de retry no próprio código. A lista deve ser ordenada conforme a prioridade da aplicação — por exemplo, a maior qualidade primeiro com backups mais baratos, ou o mais rápido primeiro com backups mais confiáveis em seguida.
Resumo
O tutorial fecha com um quadro dos recursos e de quando usar cada um:
- String única de modelo com tag :free — mira um modelo gratuito específico; quando é preciso um modelo previsível a custo zero
- Troca do valor de model — compara modelos sem outras mudanças de código; ao testar qual modelo se encaixa melhor no caso de uso
- “model”: “openrouter/free” — o OpenRouter escolhe qualquer modelo gratuito disponível; prototipagem rápida com custo zero garantido
- “provider”: {“sort”: “price”} ou {“sort”: “latency”} — escolhe o provedor do modelo por custo ou velocidade; trabalho com modelos pagos em volume considerável
- “models”: […] (lista) — tenta cada modelo em ordem até um funcionar; aplicações que precisam continuar no ar se um modelo falhar
Com esses fundamentos, é possível construir desde um script pontual até um bot de suporte que permanece online mesmo quando um provedor sai do ar. Como referências adicionais, o artigo indica o guia Quickstart da API do OpenRouter e a documentação de roteamento de provedores.
Artigo original: https://www.kdnuggets.com/access-multiple-ai-models-in-your-python-apps-using-openrouter
Traduzido e adaptado pela Equipe CRO Brasil