Habilidade OpenRouter
Assistência abrangente para o desenvolvimento com a API OpenRouter, fornecendo acesso unificado a centenas de modelos de IA através de um único endpoint, com roteamento inteligente, fallbacks automáticos e interfaces padronizadas.
Quando Usar Esta Habilidade
Esta habilidade deve ser acionada quando:
- Fizer chamadas de API para vários provedores de modelos de IA através de uma interface unificada
- Implementar estratégias de fallback de modelo ou roteamento automático
- Trabalhar com SDKs compatíveis com OpenAI, mas com destino a vários provedores
- Configurar parâmetros de amostragem avançados (temperatura, top_p, penalidades)
- Configurar respostas em streaming ou saídas JSON estruturadas
- Comparar custos entre diferentes modelos de IA
- Construir aplicações que precisam de failover automático de provedor
- Implementar chamada de funções/ferramentas em diferentes modelos
- Dúvidas sobre recursos específicos do OpenRouter (roteamento, fallbacks, seguro de conclusão zero)
Referência Rápida
Conclusão de Chat Básica (Python)
from openai import OpenAI
client = OpenAI(
base_url="https://openrouter.ai/api/v1",
api_key="<OPENROUTER_API_KEY>",
)
completion = client.chat.completions.create(
model="openai/gpt-4o",
messages=[{"role": "user", "content": "Qual é o sentido da vida?"}]
)
print(completion.choices[0].message.content)
Conclusão de Chat Básica (JavaScript/TypeScript)
import OpenAI from 'openai';
const openai = new OpenAI({
baseURL: 'https://openrouter.ai/api/v1',
apiKey: '<OPENROUTER_API_KEY>',
});
const completion = await openai.chat.completions.create({
model: 'openai/gpt-4o',
messages: [{"role": 'user', "content": 'Qual é o sentido da vida?'}],
});
console.log(completion.choices[0].message);
Requisição cURL
curl https://openrouter.ai/api/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENROUTER_API_KEY" \
-d '{
"model": "openai/gpt-4o",
"messages": [{"role": "user", "content": "Qual é o sentido da vida?"}]
}'
Configuração de Fallback de Modelo (Python)
completion = client.chat.completions.create(
model="openai/gpt-4o",
extra_body={
"models": ["anthropic/claude-3.5-sonnet", "gryphe/mythomax-l2-13b"],
},
messages=[{"role": "user", "content": "Seu prompt aqui"}]
)
Configuração de Fallback de Modelo (TypeScript)
const completion = await client.chat.completions.create({
model: 'openai/gpt-4o',
models: ['anthropic/claude-3.5-sonnet', 'gryphe/mythomax-l2-13b'],
messages: [{ role: 'user', content: 'Seu prompt aqui' }],
});
Roteador Automático (Seleção Dinâmica de Modelo)
completion = client.chat.completions.create(
model="openrouter/auto", # Seleciona automaticamente o melhor modelo para o prompt
messages=[{"role": "user", "content": "Seu prompt aqui"}]
)
Exemplo de Parâmetros Avançados
completion = client.chat.completions.create(
model="openai/gpt-4o",
messages=[{"role": "user", "content": "Escreva uma história criativa"}],
temperature=0.8, # Maior para criatividade (0.0-2.0)
max_tokens=500, # Limitar o comprimento da resposta
top_p=0.9, # Amostragem por núcleo (0.0-1.0)
frequency_penalty=0.5, # Reduzir repetição (-2.0-2.0)
presence_penalty=0.3 # Incentivar diversidade de tópicos (-2.0-2.0)
)
Resposta em Streaming
stream = client.chat.completions.create(
model="openai/gpt-4o",
messages=[{"role": "user", "content": "Conte-me uma história"}],
stream=True
)
for chunk in stream:
if chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end='')
Modo JSON (Saída Estruturada)
completion = client.chat.completions.create(
model="openai/gpt-4o",
messages=[{
"role": "user",
"content": "Extraia nome, idade e cidade da pessoa: João tem 30 anos e mora em São Paulo"
}],
response_format={"type": "json_object"}
)
Saída Determinística com Seed
completion = client.chat.completions.create(
model="openai/gpt-4o",
messages=[{"role": "user", "content": "Gere um número aleatório"}],
seed=42, # Mesmo seed = mesma saída (quando suportado)
temperature=0.0 # Amostragem determinística
)
Conceitos-Chave
Roteamento de Modelo
O OpenRouter fornece capacidades de roteamento inteligente:
- Roteador Automático (
openrouter/auto): Seleciona automaticamente o melhor modelo com base no seu prompt usando NotDiamond - Modelos de Fallback: Especifique vários modelos que tentam automaticamente se o principal falhar
- Roteamento de Provedor: Roteia automaticamente entre provedores para confiabilidade
Autenticação
- Usa autenticação por token Bearer com chaves de API
- As chaves de API podem ser gerenciadas programaticamente
- Compatível com os padrões de autenticação do SDK OpenAI
Convenção de Nomenclatura de Modelos
Os modelos usam o formato provedor/nome-do-modelo:
openai/gpt-4o- GPT-4 Otimizado da OpenAIanthropic/claude-3.5-sonnet- Claude 3.5 Sonnet da Anthropicgoogle/gemini-2.0-flash-exp:free- Modelo gratuito Gemini do Googleopenrouter/auto- Sistema de roteamento automático
Parâmetros de Amostragem
Temperatura (0.0-2.0, padrão: 1.0)
- Menor = respostas mais previsíveis e focadas
- Maior = respostas mais criativas e diversas
- Use baixa (0.0-0.3) para tarefas factuais, alta (0.8-1.5) para trabalho criativo
Top P (0.0-1.0, padrão: 1.0)
- Limita as escolhas a uma porcentagem de tokens prováveis
- Filtragem dinâmica de opções improváveis
- Equilíbrio entre consistência e variedade
Penalidades de Frequência/Presença (-2.0-2.0, padrão: 0.0)
- Frequência: Desencoraja a repetição de tokens proporcionalmente ao uso
- Presença: Penalidade mais simples não escalada pela contagem
- Valores positivos reduzem a repetição, negativos incentivam a reutilização
Max Tokens (inteiro)
- Define o comprimento máximo da resposta
- Não pode exceder o comprimento do contexto menos o comprimento do prompt
- Use para controlar custos e garantir respostas concisas
Formatos de Resposta
- JSON Padrão: Formato de conclusão de chat padrão
- Streaming: Eventos Enviados pelo Servidor (SSE) com
stream: true - Modo JSON: JSON válido garantido com
response_format: {"type": "json_object"} - Saídas Estruturadas: Respostas JSON validadas por esquema
Recursos Avançados
- Chamada de Ferramentas/Funções: Conecte modelos a APIs externas
- Entradas Multimodais: Suporte para imagens, PDFs, áudio
- Cache de Prompt: Reduza custos para prompts repetidos
- Integração com Pesquisa Web: Respostas aprimoradas com dados da web
- Seguro de Conclusão Zero: Proteção contra respostas com falha
- Logprobs: Acesse probabilidades de tokens para análise de confiança
Arquivos de Referência
Esta habilidade inclui documentação abrangente em references/:
- llms-full.md - Lista completa de modelos disponíveis com metadados
- llms-small.md - Subconjunto selecionado de modelos populares
- llms.md - Listagens padrão de modelos
Use view para ler arquivos de referência específicos quando informações detalhadas do modelo forem necessárias.
Trabalhando com Esta Habilidade
Para Iniciantes
- Comece com exemplos básicos de conclusão de chat (Python/JavaScript/cURL acima)
- Use o SDK OpenAI padrão para integração fácil
- Tente nomes de modelo simples como
openai/gpt-4oouanthropic/claude-3.5-sonnet - Inicialmente mantenha os parâmetros simples (apenas modelo e mensagens)
Para Usuários Intermediários
- Implemente arrays de fallback de modelo para confiabilidade
- Experimente com parâmetros de amostragem (temperatura, top_p)
- Use streaming para melhor UX em aplicações de conversação
- Tente
openrouter/autopara seleção automática de modelo - Implemente o modo JSON para extração de dados estruturados
Para Usuários Avançados
- Ajuste fino de vários parâmetros de amostragem juntos
- Implemente lógica de roteamento personalizada com cadeias de fallback
- Use logprobs para pontuação de confiança
- Aproveite as capacidades de chamada de ferramentas/funções
- Otimize custos selecionando modelos apropriados por tarefa
- Implemente estratégias de cache de prompt
- Use o parâmetro seed para testes reproduzíveis
Padrões Comuns
Tratamento de Erros com Fallbacks
try:
completion = client.chat.completions.create(
model="openai/gpt-4o",
extra_body={
"models": [
"anthropic/claude-3.5-sonnet",
"google/gemini-2.0-flash-exp:free"
]
},
messages=[{"role": "user", "content": "Seu prompt"}]
)
except Exception as e:
print(f"Todos os modelos falharam: {e}")
Roteamento Otimizado por Custo
# Use modelos mais baratos para tarefas simples
simple_completion = client.chat.completions.create(
model="google/gemini-2.0-flash-exp:free",
messages=[{"role": "user", "content": "Pergunta simples"}]
)
# Use modelos premium para tarefas complexas
complex_completion = client.chat.completions.create(
model="openai/o1",
messages=[{"role": "user", "content": "Tarefa de raciocínio complexo"}]
)
Temperatura Sensível ao Contexto
# Temperatura baixa para respostas factuais
factual = client.chat.completions.create(
model="openai/gpt-4o",
temperature=0.2,
messages=[{"role": "user", "content": "Qual é a capital da França?"}]
)
# Temperatura alta para conteúdo criativo
creative = client.chat.completions.create(
model="openai/gpt-4o",
temperature=1.2,
messages=[{"role": "user", "content": "Escreva uma abertura de história única"}]
)
Recursos
Documentação Oficial
- Referência da API: https://openrouter.ai/docs/api-reference/overview
- Guia de Início Rápido: https://openrouter.ai/docs/quickstart
- Lista de Modelos: https://openrouter.ai/docs/models
- Guia de Parâmetros: https://openrouter.ai/docs/api-reference/parameters
Endpoints Principais
- Conclusões de Chat:
POST https://openrouter.ai/api/v1/chat/completions - Listar Modelos:
GET https://openrouter.ai/api/v1/models - Informações de Geração:
GET https://openrouter.ai/api/v1/generation
Notas
- O OpenRouter normaliza os esquemas de API em todos os provedores
- Usa formato de API compatível com OpenAI para migração fácil
- Fallback automático de provedor se os modelos estiverem com limite de taxa ou inativos
- Preço baseado no modelo realmente usado (importante para fallbacks)
- A resposta inclui metadados sobre qual modelo processou a requisição
- Todos os modelos suportam streaming via Eventos Enviados pelo Servidor
- Compatível com frameworks populares (LangChain, Vercel AI SDK, etc.)
Melhores Práticas
- Sempre implemente fallbacks para aplicações em produção
- Use temperatura apropriada com base no tipo de tarefa (baixa para factual, alta para criativa)
- Defina max_tokens para controlar custos e comprimento da resposta
- Habilite streaming para melhor experiência do usuário em aplicações de chat
- Use o modo JSON quando precisar de saída estruturada garantida
- Teste com o parâmetro seed para resultados reproduzíveis durante o desenvolvimento
- Monitore custos selecionando modelos apropriados por tarefa
- Use roteamento automático quando não tiver certeza de qual modelo tem melhor desempenho
- Implemente tratamento de erros adequado para limites de taxa e falhas
- Faça cache de prompts para requisições repetidas para reduzir custos