Habilidad OpenRouter
Asistencia integral para el desarrollo con la API de OpenRouter, que proporciona acceso unificado a cientos de modelos de IA a través de un único endpoint con enrutamiento inteligente, fallbacks automáticos e interfaces estandarizadas.
Cuándo usar esta habilidad
Esta habilidad debe activarse cuando:
- Se realizan llamadas API a múltiples proveedores de modelos de IA a través de una interfaz unificada
- Se implementan estrategias de fallback de modelos o auto-enrutamiento
- Se trabaja con SDKs compatibles con OpenAI pero apuntando a múltiples proveedores
- Se configuran parámetros de muestreo avanzados (temperatura, top_p, penalizaciones)
- Se configuran respuestas en streaming o salidas JSON estructuradas
- Se comparan costos entre diferentes modelos de IA
- Se construyen aplicaciones que necesitan conmutación por error automática entre proveedores
- Se implementa llamada a funciones/herramientas en diferentes modelos
- Existen preguntas sobre características específicas de OpenRouter (enrutamiento, fallbacks, seguro de finalización cero)
Referencia rápida
Finalización 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": "¿Cuál es el significado de la vida?"}]
)
print(completion.choices[0].message.content)
Finalización 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": '¿Cuál es el significado de la vida?'}],
});
console.log(completion.choices[0].message);
Solicitud 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": "¿Cuál es el significado de la vida?"}]
}'
Configuración 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": "Tu prompt aquí"}]
)
Configuración 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: 'Tu prompt aquí' }],
});
Enrutador Automático (Selección Dinámica de Modelo)
completion = client.chat.completions.create(
model="openrouter/auto", # Selecciona automáticamente el mejor modelo para el prompt
messages=[{"role": "user", "content": "Tu prompt aquí"}]
)
Ejemplo de Parámetros Avanzados
completion = client.chat.completions.create(
model="openai/gpt-4o",
messages=[{"role": "user", "content": "Escribe una historia creativa"}],
temperature=0.8, # Más alto para creatividad (0.0-2.0)
max_tokens=500, # Limitar longitud de respuesta
top_p=0.9, # Muestreo de núcleo (0.0-1.0)
frequency_penalty=0.5, # Reducir repetición (-2.0-2.0)
presence_penalty=0.3 # Fomentar diversidad temática (-2.0-2.0)
)
Respuesta en Streaming
stream = client.chat.completions.create(
model="openai/gpt-4o",
messages=[{"role": "user", "content": "Cuéntame una historia"}],
stream=True
)
for chunk in stream:
if chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end='')
Modo JSON (Salida Estructurada)
completion = client.chat.completions.create(
model="openai/gpt-4o",
messages=[{
"role": "user",
"content": "Extrae el nombre, edad y ciudad de la persona de: Juan tiene 30 años y vive en la CDMX"
}],
response_format={"type": "json_object"}
)
Salida Determinista con Semilla
completion = client.chat.completions.create(
model="openai/gpt-4o",
messages=[{"role": "user", "content": "Genera un número aleatorio"}],
seed=42, # Misma semilla = misma salida (cuando es compatible)
temperature=0.0 # Muestreo determinista
)
Conceptos Clave
Enrutamiento de Modelos
OpenRouter proporciona capacidades de enrutamiento inteligente:
- Enrutador Automático (
openrouter/auto): Selecciona automáticamente el mejor modelo según tu prompt usando NotDiamond - Modelos de Fallback: Especifica múltiples modelos que se reintentan automáticamente si el principal falla
- Enrutamiento de Proveedores: Enruta automáticamente entre proveedores para mayor confiabilidad
Autenticación
- Utiliza autenticación de token Bearer con claves API
- Las claves API se pueden gestionar mediante programación
- Compatible con los patrones de autenticación del SDK de OpenAI
Convención de Nombres de Modelos
Los modelos usan el formato proveedor/nombre-del-modelo:
openai/gpt-4o- GPT-4 Optimizado de OpenAIanthropic/claude-3.5-sonnet- Claude 3.5 Sonnet de Anthropicgoogle/gemini-2.0-flash-exp:free- Modelo gratuito Gemini de Googleopenrouter/auto- Sistema de auto-enrutamiento
Parámetros de Muestreo
Temperatura (0.0-2.0, predeterminado: 1.0)
- Más bajo = respuestas más predecibles y enfocadas
- Más alto = respuestas más creativas y diversas
- Usa baja (0.0-0.3) para tareas factuales, alta (0.8-1.5) para trabajo creativo
Top P (0.0-1.0, predeterminado: 1.0)
- Limita las opciones a un porcentaje de tokens probables
- Filtrado dinámico de opciones improbables
- Equilibrio entre consistencia y variedad
Penalizaciones de Frecuencia/Presencia (-2.0-2.0, predeterminado: 0.0)
- Frecuencia: Desalienta la repetición de tokens proporcionalmente al uso
- Presencia: Penalización más simple que no escala por recuento
- Valores positivos reducen la repetición, negativos fomentan la reutilización
Máximo de Tokens (entero)
- Establece la longitud máxima de respuesta
- No puede exceder la longitud del contexto menos la longitud del prompt
- Úsalo para controlar costos y forzar respuestas concisas
Formatos de Respuesta
- JSON Estándar: Formato de finalización de chat predeterminado
- Streaming: Eventos enviados por el servidor (SSE) con
stream: true - Modo JSON: JSON válido garantizado con
response_format: {"type": "json_object"} - Salidas Estructuradas: Respuestas JSON validadas por esquema
Características Avanzadas
- Llamada a Herramientas/Funciones: Conecta modelos a APIs externas
- Entradas Multimodales: Soporte para imágenes, PDFs, audio
- Almacenamiento en Caché de Prompts: Reduce costos para prompts repetidos
- Integración de Búsqueda Web: Respuestas mejoradas con datos web
- Seguro de Finalización Cero: Protección contra respuestas fallidas
- Logprobs: Accede a probabilidades de tokens para análisis de confianza
Archivos de Referencia
Esta habilidad incluye documentación completa en references/:
- llms-full.md - Lista completa de modelos disponibles con metadatos
- llms-small.md - Subconjunto curado de modelos populares
- llms.md - Listados de modelos estándar
Usa view para leer archivos de referencia específicos cuando se necesite información detallada del modelo.
Trabajar con esta Habilidad
Para Principiantes
- Comienza con ejemplos básicos de finalización de chat (Python/JavaScript/cURL anterior)
- Usa el SDK estándar de OpenAI para una integración fácil
- Prueba nombres de modelo simples como
openai/gpt-4ooanthropic/claude-3.5-sonnet - Mantén los parámetros simples inicialmente (solo modelo y mensajes)
Para Usuarios Intermedios
- Implementa arreglos de fallback de modelos para confiabilidad
- Experimenta con parámetros de muestreo (temperatura, top_p)
- Usa streaming para una mejor experiencia de usuario en aplicaciones conversacionales
- Prueba
openrouter/autopara selección automática de modelos - Implementa el modo JSON para extracción de datos estructurados
Para Usuarios Avanzados
- Ajusta múltiples parámetros de muestreo juntos
- Implementa lógica de enrutamiento personalizada con cadenas de fallback
- Usa logprobs para puntuación de confianza
- Aprovecha las capacidades de llamada a herramientas/funciones
- Optimiza costos seleccionando modelos apropiados para cada tarea
- Implementa estrategias de almacenamiento en caché de prompts
- Usa el parámetro seed para pruebas reproducibles
Patrones Comunes
Manejo de Errores con 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": "Tu prompt"}]
)
except Exception as e:
print(f"Todos los modelos fallaron: {e}")
Enrutamiento Optimizado por Costos
# Usa modelos más baratos para tareas simples
simple_completion = client.chat.completions.create(
model="google/gemini-2.0-flash-exp:free",
messages=[{"role": "user", "content": "Pregunta simple"}]
)
# Usa modelos premium para tareas complejas
complex_completion = client.chat.completions.create(
model="openai/o1",
messages=[{"role": "user", "content": "Tarea de razonamiento compleja"}]
)
Temperatura Sensible al Contexto
# Temperatura baja para respuestas factuales
factual = client.chat.completions.create(
model="openai/gpt-4o",
temperature=0.2,
messages=[{"role": "user", "content": "¿Cuál es la capital de Francia?"}]
)
# Temperatura alta para contenido creativo
creative = client.chat.completions.create(
model="openai/gpt-4o",
temperature=1.2,
messages=[{"role": "user", "content": "Escribe un inicio de historia único"}]
)
Recursos
Documentación Oficial
- Referencia API: https://openrouter.ai/docs/api-reference/overview
- Guía de Inicio Rápido: https://openrouter.ai/docs/quickstart
- Lista de Modelos: https://openrouter.ai/docs/models
- Guía de Parámetros: https://openrouter.ai/docs/api-reference/parameters
Puntos Finales Clave
- Finalizaciones de Chat:
POST https://openrouter.ai/api/v1/chat/completions - Listar Modelos:
GET https://openrouter.ai/api/v1/models - Información de Generación:
GET https://openrouter.ai/api/v1/generation
Notas
- OpenRouter normaliza los esquemas API en todos los proveedores
- Utiliza un formato de API compatible con OpenAI para una migración fácil
- Fallback automático de proveedor si los modelos están limitados por tasa o caídos
- Precios basados en el modelo real utilizado (importante para fallbacks)
- La respuesta incluye metadatos sobre qué modelo procesó la solicitud
- Todos los modelos admiten streaming a través de Eventos Enviados por el Servidor
- Compatible con frameworks populares (LangChain, Vercel AI SDK, etc.)
Mejores Prácticas
- Implementa siempre fallbacks para aplicaciones en producción
- Usa temperatura adecuada según el tipo de tarea (baja para factual, alta para creativa)
- Establece max_tokens para controlar costos y longitud de respuesta
- Habilita streaming para una mejor experiencia de usuario en aplicaciones de chat
- Usa el modo JSON cuando necesites salida estructurada garantizada
- Prueba con el parámetro seed para resultados reproducibles durante el desarrollo
- Monitorea costos seleccionando modelos apropiados para cada tarea
- Usa auto-enrutamiento cuando no estés seguro de qué modelo funciona mejor
- Implementa un manejo de errores adecuado para límites de tasa y fallos
- Almacena en caché los prompts para solicitudes repetidas y reducir costos