OpenRouter: Una guía con ejemplos prácticos

Gestionar varias API de proveedores de IA se convierte rápidamente en una tarea abrumadora. Cada proveedor tiene diferentes métodos de autenticación, modelos de precios y especificaciones de API. Los programadores pierden innumerables horas cambiando entre OpenAI, Anthropic, Google y otras plataformas solo para acceder a diferentes modelos.

OpenRouter resuelve esta complejidad proporcionando una API unificada que te conecta con más de 400 modelos de docenas de proveedores. Puedes acceder a GPT-5, Claude 4, Gemini 2.5 Proy cientos de otros modelos utilizando una única clave API y una interfaz coherente. La plataforma gestiona automáticamente las redirecciones, la gestión de costes y el enrutamiento de proveedores en segundo plano.

En este tutorial, explico todo lo que necesitas saber sobre OpenRouter, desde cómo configurar tu primera llamada a la API hasta cómo implementar funciones avanzadas como las salidas estructuradas. Al final, aprenderás a crear aplicaciones fiables que no dependan de un único proveedor.

¿Qué es OpenRouter?

OpenRouter es una plataforma API unificada que te da acceso a más de 400 modelos de IA de docenas de proveedores a través de un único punto final. En lugar de tener que manejar claves API diferentes para OpenAI, Anthropic, Google, Meta y otros, utilizas una sola clave para acceder a todo su catálogo de modelos.

La plataforma funciona como un enrutador inteligente, enviando tus solicitudes al proveedor adecuado y encargándose de la autenticación, la facturación y la gestión de errores. Este enfoque soluciona varios problemas que surgen al utilizar varios proveedores de IA.

Problemas que resuelve OpenRouter

Trabajar con varios proveedores de IA se complica rápidamente. Cada uno tiene su propio formato API, proceso de inicio de sesión y sistema de facturación. Acabas manteniendo código separado para cada servicio, lo que ralentiza el desarrollo y dificulta la prueba de nuevos modelos.

Las cosas empeoran cuando los proveedores dejan de funcionar o te imponen límites de tarifa. Tu aplicación se estropea y no puedes hacer nada más que esperar. Además, averiguar qué proveedor ofrece el mejor precio para modelos similares implica realizar un seguimiento manual de los costes en diferentes plataformas.

El mayor problema es quedar atado a un solo proveedor. Cuando construyes todo en torno a su API específica, cambiar posteriormente a modelos mejores o opciones más económicas se convierte en un proyecto de gran envergadura.

Cómo soluciona esto OpenRouter

OpenRouter resuelve estos problemas con un conjunto de funciones conectadas:

• Una clave API funciona con más de 400 modelos de todos los principales proveedores.
• Cambio automático a proveedores de respaldo cuando falla tu primera opción.
• Precios comparativos de todos los modelos para que puedas comparar los costes al instante.
• Funciona con el código OpenAI existente: solo tienes que cambiar la URL del punto final.
• Monitorización en tiempo real que dirige las solicitudes al proveedor más rápido disponible.

Estas piezas funcionan conjuntamente para que el desarrollo de la IA sea más fluido y fiable.

¿Quién debería utilizar OpenRouter?

Los diferentes tipos de usuarios obtienen valor de este enfoque unificado:

• Los programadores pueden probar nuevos modelos sin tener que crear cuentas en todas partes, lo que agilita la experimentación.
• Los equipos empresariales obtienen el tiempo de actividad que necesitan gracias a las copias de seguridad automáticas cuando fallan los proveedores.
• Los usuarios que cuidan su presupuesto pueden encontrar la opción más económica para sus necesidades sin necesidad de hacer cálculos en hojas de cálculo.
• Los investigadores obtienen acceso instantáneo a modelos de vanguardia sin necesidad de configurar una cuenta.

Ahora que ya sabes lo que OpenRouter pone sobre la mesa, vamos a configurar tu primera llamada API.

Requisitos previos

Antes de sumergirte en OpenRouter, necesitarás configurar algunas cosas en tu equipo. Este tutorial asume que estás familiarizado con la programación básica en Python y que has trabajado con API anteriormente. No es necesario que seas un experto, pero debes comprender conceptos como la realización de solicitudes HTTP y el manejo de respuestas JSON.

Necesitarás tener Python 3.7 o posterior instalado en tu sistema. Usaremos el paquete Python openai para interactuar con la API de OpenRouter, junto con python-dotenv para gestionar las variables de entorno de forma segura. Puedes instalar ambos con:

pip install requests openai python-dotenv

También necesitarás una cuenta OpenRouter y una clave API. Dirígete a openrouter.ai para crear una cuenta gratuita: obtendrás un pequeño crédito para probar el servicio. Una vez que hayas iniciado sesión, ve a la sección Claves API en la configuración de tu cuenta y genera una nueva clave.

Después de obtener tu clave API, crea un archivo .env en el directorio de tu proyecto y añade tu clave de la siguiente manera:

OPENROUTER_API_KEY=your_api_key_here

Esto mantiene tu clave API segura y fuera de tu código. Si planeas utilizar OpenRouter más allá de la fase de prueba, deberás añadir créditos a tu cuenta a través de la página Créditos.

Con estos conceptos básicos, estás listo para realizar tu primera llamada API a través de OpenRouter.

Realizar tu primera llamada API en OpenRouter

Comenzar a utilizar OpenRouter es muy sencillo si ya has utilizado el SDK de OpenAI anteriormente. Solo tienes que cambiar una línea de código y, de repente, tendrás acceso a cientos de modelos de diferentes proveedores.

Tu primera solicitud y configuración

Empecemos con un ejemplo práctico que ilustra el enfoque de OpenRouter:

import os
from openai import OpenAI
from dotenv import load_dotenv

load_dotenv()

client = OpenAI(
   base_url="https://openrouter.ai/api/v1",
   api_key=os.getenv("OPENROUTER_API_KEY"),
)

response = client.chat.completions.create(
   model="openai/gpt-5-mini",
   messages=[
       {
           "role": "user",
           "content": "Write a haiku about debugging code at 2 AM"
       }
   ]
)

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

Night hum, coffee cooled
cursor blinks, bug hides somewhere
I chase ghosts 'til dawn

La magia ocurre en dos lugares. En primer lugar, el parámetro base_url redirige tus solicitudes a los servidores de OpenRouter en lugar de a los de OpenAI. En segundo lugar, el nombre del modelo sigue un formato « provider/model-name » (nombre del modelo + nombre del fabricante): openai/gpt-5-mini en lugar de simplemente gpt-5-mini. Esto le indica a OpenRouter qué versión del proveedor deseas, al tiempo que mantiene la interfaz familiar. A continuación, se muestran algunos modelos comunes que puedes introducir en el ejemplo anterior sin cometer ningún error:

• google/gemini-2.0-flash-001
• google/gemini-2.5-pro
• mistralai/mistral-nemo
• deepseek/deepseek-r1-distill-qwen-32b

Ahora que has visto lo fácil que es trabajar con diferentes modelos, quizá te preguntes: ¿qué ocurre cuando el modelo elegido no está disponible? ¿Cómo creas aplicaciones que siguen siendo fiables incluso cuando los proveedores tienen problemas? Ahí es donde entran en juego las funciones de enrutamiento y resiliencia de OpenRouter.

Enrutamiento modelo para la resiliencia

Crear aplicaciones de IA fiables significa prepararse para lo inesperado. Los proveedores experimentan tiempos de inactividad, los modelos alcanzan límites de frecuencia y, en ocasiones, la moderación de contenidos bloquea tus solicitudes. El enrutamiento de modelos es la solución de OpenRouter: cambia automáticamente entre diferentes modelos para que tu aplicación funcione sin problemas.

Configuración de alternativas manuales

La forma más sencilla de añadir resiliencia es especificar modelos de copia de seguridad. Cuando tu opción principal falla, OpenRouter prueba tus alternativas en orden. El parámetro extra_body pasa estas instrucciones de enrutamiento a la API de OpenRouter, ya que el SDK de OpenAI no es compatible con el enrutamiento de enlaces. SDK de OpenAI no admite esta función de forma nativa:

response = client.chat.completions.create(
   model="moonshotai/kimi-k2",  # Primary choice
   messages=[
       {"role": "user", "content": "Explain quantum computing in simple terms"}
   ],
   extra_body={
       "models": ["anthropic/claude-sonnet-4", "deepseek/deepseek-r1"]
   }   
)

print(f"Response from: {response.model}")
print(response.choices[0].message.content)

Response from: moonshotai/kimi-k2
Imagine a normal computer bit as a tiny light-switch that can only be OFF (0) or ON (1)...

OpenRouter prueba primero Kimi-K2. Si no está disponible, tiene un límite de velocidad o está bloqueado, automáticamente prueba Claude Sonnet 4 y, a continuación, DeepSeek R1. El campo « response.model » muestra qué modelo ha respondido realmente.

Enrutador automático para una máxima comodidad

Una vez que comprendas los fallbacks manuales, el enrutador automático te resultará muy atractivo. Gestiona automáticamente la selección de modelos y los fallbacks, gracias a sistema de evaluación de NotDiamond:

response = client.chat.completions.create(
   model="openrouter/auto",
   messages=[
       {"role": "user", "content": "Debug this Python code in 3 sentences: def factorial(n): return n * factorial(n-1)"}
   ]
)

print(f"Auto router selected: {response.model}")
print(response.choices[0].message.content)

Auto router selected: openai/chatgpt-4o-latest
The given code is missing a base case, which causes infinite recursion and eventually a RecursionError. To fix it, add a base case like `if n == 0: return 1` before the recursive call. Here's the corrected version:

\```python
def factorial(n):
   if n == 0:
       return 1
   return n * factorial(n - 1)
\```

El enrutador automático analiza tu solicitud y selecciona el mejor modelo disponible, con alternativas integradas si tu primera opción no está disponible. Obtienes resiliencia sin necesidad de configuración. Sin embargo, utiliza el enrutador automático con precaución en situaciones delicadas o de gran importancia, ya que tiende a subestimar la complejidad del problema y, por lo tanto, a elegir un modelo de menor capacidad.

Creación de estrategias alternativas eficaces

No todos los modelos son adecuados para realizar copias de seguridad entre sí. El tiempo de inactividad del proveedor puede afectar a todos los modelos de esa empresa, por lo que debes elegir alternativas de diferentes proveedores. Los límites de tarifas y los costes varían considerablemente, por lo que conviene combinar los modelos caros con alternativas más económicas:

# Good fallback chain: different providers, decreasing cost
response = client.chat.completions.create(
   model="anthropic/claude-sonnet-4",
   messages=[
       {"role": "user", "content": "Your prompt here"}
   ],
   extra_body={
       "models": [
           "x-ai/grok-4",                  # Close performance
           "moonshotai/kimi-k2",           # Cheaper
           "deepseek/deepseek-r1:free"     # Free backup
       ]
   }   
)

Esto te ofrece una calidad superior cuando está disponible, un rendimiento sólido como respaldo y una disponibilidad garantizada como último recurso. Las políticas de moderación de contenidos también difieren entre los distintos proveedores, por lo que diversificar tu cadena te ofrece una mejor cobertura para temas delicados.

Encontrar modelos para tu cadena de respaldo

La página de modelos te permite filtrar por proveedor y capacidades para crear tu cadena. Muchos modelos potentes, como DeepSeek R1 y Kimi-K2, son gratuitos, ya que son de código abierto, lo que los convierte en excelentes alternativas. Los modelos gratuitos tienen un límite de 50 solicitudes al día para los nuevos usuarios, o 1000 solicitudes al día si has comprado 10 créditos.

Para aplicaciones dinámicas, puedes descubrir modelos mediante programación:

def get_provider_models(api_key: str, provider: str) -> list[str]:
   r = requests.get(
       "https://openrouter.ai/api/v1/models",
       headers={"Authorization": f"Bearer {api_key}"}
   )
   return [m["id"] for m in r.json()["data"] if m["id"].startswith(provider)]

# Build fallbacks across providers
openai_models = get_provider_models(api_key, "openai/")
anthropic_models = get_provider_models(api_key, "anthropic/")

Este enfoque te permite crear cadenas de respaldo robustas que se adaptan a medida que se incorporan nuevos modelos.

Transmisión para respuestas en tiempo real

Cuando se trabaja con modelos de IA, especialmente en respuestas largas, los usuarios esperan ver los resultados de forma progresiva, en lugar de esperar a que se complete la respuesta. El streaming resuelve este problema enviando fragmentos de respuesta a medida que se generan, lo que crea una experiencia más interactiva similar a la interfaz de ChatGPT.

Configuración básica de streaming

Para configurar la transmisión en OpenRouter, añade stream=True a tu solicitud. La respuesta se convierte en un iterador que genera fragmentos a medida que el modelo los genera:

response = client.chat.completions.create(
   model="openai/gpt-5",
   messages=[
       {"role": "user", "content": "Write a detailed explanation of how neural networks learn"}
   ],
   stream=True
)

for chunk in response:
   if chunk.choices[0].delta.content is not None:
       print(chunk.choices[0].delta.content, end="")

Cada fragmento contiene una pequeña parte de la respuesta. El campo « delta.content » contiene el nuevo fragmento de texto, y lo imprimimos inmediatamente sin una nueva línea para crear el efecto de transmisión. El parámetro end="" evita que print añada saltos de línea entre fragmentos.

Creación de un mejor controlador de streaming

Para aplicaciones de producción, necesitarás un mayor control sobre el proceso de streaming. Aquí hay un controlador más completo que gestiona la respuesta completa:

def stream_response(model, messages, show_progress=True):
   response = client.chat.completions.create(
       model=model,
       messages=messages,
       stream=True
   )
  
   complete_response = ""
  
   for chunk in response:
       if chunk.choices[0].delta.content is not None:
           content = chunk.choices[0].delta.content
           complete_response += content
          
           if show_progress:
               print(content, end="", flush=True)
  
   if show_progress:
       print()  # Add final newline
  
   return complete_response

# Use it with different models
result = stream_response(
   "anthropic/claude-sonnet-4",
   [{"role": "user", "content": "Explain quantum entanglement like I'm 12 years old"}]
)

Este controlador captura la respuesta completa mientras muestra el progreso, te ofrece tanto la experiencia de transmisión como el texto final e incluye el formato de salida adecuado.

El streaming cambia la experiencia del usuario, que pasa de «esperar y desear» a «ver cómo avanza». Esto hace que tus aplicaciones de IA sean mucho más receptivas y atractivas para los usuarios.

Manejo de tokens de razonamiento en OpenRouter

Algunos modelos de IA pueden mostrarte su proceso de «razonamiento» antes de dar su respuesta final. Estas fichas de razonamiento proporcionan una visión transparente de cómo el modelo aborda problemas complejos, mostrando la lógica paso a paso que lleva a sus conclusiones. Comprender este razonamiento interno puede ayudarte a verificar respuestas, depurar el comportamiento del modelo y crear aplicaciones más fiables.

¿Qué son las fichas de razonamiento?

Las fichas de razonamiento aparecen en un campo separado llamado « reasoning » (Fichas de razonamiento) en la respuesta, diferenciadas del contenido principal. Los diferentes modelos admiten el razonamiento de diferentes maneras: algunos utilizan niveles de esfuerzo, mientras que otros utilizan presupuestos de tokens. 

Aquí tienes un ejemplo sencillo que muestra el razonamiento en acción:

response = client.chat.completions.create(
   model="anthropic/claude-sonnet-4",
   messages=[
       {"role": "user", "content": "How many 'r's are in the word 'strrawberry'?"}
   ],
   max_tokens=2048,
   extra_body={
       "reasoning": {
           "max_tokens": 512
       }
   }
)

print("Final answer:")
print(response.choices[0].message.content)
print("\nReasoning process:")
print(response.choices[0].message.reasoning)

Final answer:
To count the 'r's in 'strrawberry', I'll go through each letter:
...
There are **4** 'r's in the word 'strrawberry'.

Reasoning process:
...

El modelo mostrará tanto la respuesta final como el razonamiento interno que te llevó a esa conclusión. Esta doble salida te ayuda a comprender si el modelo ha abordado el problema correctamente.

Control de la intensidad del razonamiento

Puedes controlar el esfuerzo de razonamiento que los modelos dedican a sus respuestas mediante dos enfoques. El parámetro « effort » funciona con modelos como la serie o de OpenAI y utiliza niveles que corresponden a porcentajes específicos de tokens basados en la configuración de « max_tokens » (Niveles de tokenización):

• de alto esfuerzo: Utiliza aproximadamente el 80 % de max_tokens para el razonamiento.
• Esfuerzo medio: Utiliza aproximadamente el 50 % de max_tokens para el razonamiento.
• de bajo esfuerzo: Utiliza aproximadamente el 20 % de max_tokens para el razonamiento.

# High effort reasoning for complex problems
response = client.chat.completions.create(
   model="deepseek/deepseek-r1",
   messages=[
       {"role": "user", "content": "Solve this step by step: If a train travels 240 miles in 3 hours, then speeds up by 20 mph for the next 2 hours, how far does it travel total?"}
   ],
   max_tokens=4000,  # High effort will use ~3200 tokens for reasoning
   extra_body={
       "reasoning": {
           "effort": "high" 
       }
   }
)

print("Problem solution:")
print(response.choices[0].message.content)
print("\nStep-by-step reasoning:")
print(response.choices[0].message.reasoning)

Para los modelos que admiten la asignación directa de tokens, como los modelos de Anthropic, puedes especificar presupuestos de razonamiento exactos:

def get_reasoning_response(question, reasoning_budget=2000):
   response = client.chat.completions.create(
       model="anthropic/claude-sonnet-4",
       messages=[{"role": "user", "content": question}],
       max_tokens=10000,
       extra_body={
           "reasoning": {
               "max_tokens": reasoning_budget  # Exact token allocation
           }
       }
   )
   return response

# Compare different reasoning budgets
response = get_reasoning_response(
   "What's bigger: 9.9 or 9.11? Explain your reasoning carefully.",
   reasoning_budget=3000
)

print("Answer:", response.choices[0].message.content)
print("Detailed reasoning:", response.choices[0].message.reasoning)

Los presupuestos más elevados suelen dar lugar a razonamientos más exhaustivos, mientras que los más reducidos dan lugar a procesos de pensamiento más rápidos pero menos detallados.

Preservar el razonamiento en las conversaciones

Al crear conversaciones con varios turnos, debes conservar tanto el razonamiento como la respuesta final para mantener el contexto. Esto es especialmente importante en debates complejos en los que el proceso de reflexión del modelo influye en las respuestas posteriores:

# First message with reasoning
response = client.chat.completions.create(
   model="anthropic/claude-sonnet-4",
   messages=[
       {"role": "user", "content": "Should I invest in renewable energy stocks? Consider both risks and opportunities."}
   ],
   extra_body={
       "reasoning": {
           "max_tokens": 3000
       }
   }
)

# Build conversation history with reasoning preserved
messages = [
   {"role": "user", "content": "Should I invest in renewable energy stocks? Consider both risks and opportunities."},
   {
       "role": "assistant",
       "content": response.choices[0].message.content,
       "reasoning_details": response.choices[0].message.reasoning_details  # Preserve reasoning
   },
   {"role": "user", "content": "What about solar energy specifically? How does that change your analysis?"}
]

# Continue conversation with reasoning context
follow_up = client.chat.completions.create(
   model="anthropic/claude-sonnet-4",
   messages=messages,
   extra_body={
       "reasoning": {
           "max_tokens": 2000
       }
   }
)

print("Follow-up answer:")
print(follow_up.choices[0].message.content)
print("\nContinued reasoning:")
print(follow_up.choices[0].message.reasoning)

El campo « reasoning_details » (Razonamiento completo) conserva la cadena de razonamiento completa, lo que permite al modelo basarse en su análisis anterior para responder a preguntas de seguimiento. Esto crea conversaciones más coherentes y contextualmente conscientes.

Consideraciones sobre costes y facturación

Las fichas de razonamiento se facturan como fichas de salida, por lo que aumentan tus costes de uso. Sin embargo, a menudo mejoran la calidad de la respuesta lo suficiente como para justificar el gasto, especialmente en tareas complejas en las que la precisión es más importante que la velocidad. Según la documentación de OpenRouter, las fichas de razonamiento pueden mejorar el rendimiento del modelo en problemas complejos, al tiempo que aportan transparencia al proceso de decisión.

Para aplicaciones en las que el coste es un factor importante, puedes equilibrar la calidad del razonamiento y el gasto ajustando los niveles de esfuerzo o los presupuestos de tokens en función de la complejidad de la tarea. Las preguntas sencillas pueden no necesitar ningún razonamiento, mientras que los problemas complejos se benefician de un razonamiento más elaborado.

Trabajar con modelos multimodales en OpenRouter

Hasta ahora has trabajado con texto, pero ¿qué ocurre cuando necesitas analizar imágenes o documentos? Quizás quieras hacer preguntas sobre un gráfico, extraer información de un PDF o describir lo que ocurre en una foto. Ahí es donde entra en juego la los modelos multimodales: pueden entender tanto el contenido textual como el visual en la misma solicitud.

Comprensión de las capacidades multimodales

En lugar de intentar describir una imagen con texto, puedes enviar la imagen real y hacer preguntas directamente sobre ella. Esto hace que tus aplicaciones sean mucho más intuitivas, ya que el modelo ve exactamente con qué estás trabajando. No tienes que adivinar si la descripción del texto ha captado todos los detalles importantes.

Puedes utilizar modelos multimodales a través de la misma interfaz que has estado utilizando, solo que con un parámetro adicional attachments para incluir tu contenido visual. Los archivos adjuntos funcionan con todos los modelos de OpenRouter. Incluso si un modelo no admite de forma nativa archivos PDF o imágenes, OpenRouter analiza internamente estos archivos y pasa el contenido al modelo.

Trabajar con imágenes

Puedes incluir imágenes en tus solicitudes mediante URL o codificación base64. Si tu imagen ya está en línea, el método de la URL es más sencillo:

response = client.chat.completions.create(
   model="openai/gpt-5-mini",
   messages=[
       {
           "role": "user",
           "content": "What's happening in this image? Describe the scene in detail."
       }
   ],
   extra_body={
       "attachments": [
           {
               "type": "image/jpeg",
               "url": "https://example.com/photo.jpg"
           }
       ]
   }
)

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

Para imágenes locales, puedes utilizar la codificación base64:

import base64

def encode_image_to_base64(image_path):
   with open(image_path, "rb") as image_file:
       encoded_string = base64.b64encode(image_file.read()).decode('utf-8')
   return encoded_string

# Analyze a local screenshot
encoded_image = encode_image_to_base64("screenshot.png")

response = client.chat.completions.create(
   model="openai/gpt-5-mini",
   messages=[
       {
           "role": "user",
           "content": "This is a screenshot of a data dashboard. What insights can you extract from the charts and metrics shown?"
       }
   ],
   extra_body={
       "attachments": [
           {
               "type": "image/png",
               "data": encoded_image
           }
       ]
   }
)

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

El modelo analizará la imagen real y te proporcionará información específica sobre lo que ve, no solo respuestas genéricas.

Procesamiento de documentos PDF

El procesamiento de PDF funciona de la misma manera, pero abre el análisis del documento. Puedes hacer preguntas sobre informes, analizar formularios o extraer información de documentos complejos:

def encode_pdf_to_base64(pdf_path):
   with open(pdf_path, "rb") as pdf_file:
       encoded_string = base64.b64encode(pdf_file.read()).decode('utf-8')
   return encoded_string

# Analyze a research paper
encoded_pdf = encode_pdf_to_base64("research_paper.pdf")

response = client.chat.completions.create(
   model="openai/gpt-5-mini",
   messages=[
       {
           "role": "user",
           "content": "Summarize the key findings from this research paper. What are the main conclusions and methodology used?"
       }
   ],
   extra_body={
       "attachments": [
           {
               "type": "application/pdf",
               "data": encoded_pdf
           }
       ]
   }
)

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

Esto funciona muy bien para informes financieros, trabajos académicos, contratos o cualquier PDF en el que necesites un análisis de IA del contenido real. También puedes incluir varios archivos adjuntos en una sola solicitud si necesitas comparar imágenes o analizar varios documentos juntos.

Selección del modelo y del coste

Las solicitudes multimodales cuestan más que las solicitudes de solo texto, ya que se procesan tipos de datos adicionales. Las imágenes y los archivos PDF requieren más potencia informática, lo que se refleja en el precio. Puedes consultar los precios multimodales específicos de cada modelo en la página de modelos.

Los diferentes modelos tienen diferentes puntos fuertes en cuanto al contenido visual. Algunos son mejores en el análisis detallado de imágenes, mientras que otros destacan en la comprensión de documentos. Te recomendamos que pruebes diferentes modelos hasta encontrar el que mejor se adapte a tus necesidades específicas y a tu presupuesto.

Uso de salidas estructuradas

Cuando creas aplicaciones reales, necesitas formatos de datos predecibles que tu código pueda analizar de forma fiable. Las respuestas de texto libre son ideales para interfaces de chat, pero terribles para aplicaciones que necesitan extraer información específica. En lugar de obtener texto impredecible que tienes que analizar con expresiones regulares o esperar que el modelo lo haya formateado correctamente, las salidas estructuradas obligan a los modelos a devolver JSON garantizado con los campos y tipos de datos exactos que necesitas. Esto elimina los errores de análisis y simplifica considerablemente el código de tu aplicación.

Anatomía de las solicitudes de salida estructurada

Las salidas estructuradas utilizan un parámetro response_format con esta estructura básica:

"response_format": {
   "type": "json_schema",           # Always this for structured outputs
   "json_schema": {
       "name": "your_schema_name",  # Name for your schema
       "strict": True,              # Enforce strict compliance
       "schema": {
           # Your actual JSON schema definition goes here
       }
   }
}

Ejemplo de análisis de sentimientos

Veamos un ejemplo completo que extrae el sentimiento de un texto. Esto muestra cómo funcionan los resultados estructurados en la práctica:

response = client.chat.completions.create(
   model="openai/gpt-5-mini",
   messages=[
       {"role": "user", "content": "Analyze the sentiment: 'This movie was absolutely terrible!'"}
   ],
   extra_body={
       "response_format": {
           "type": "json_schema",
           "json_schema": {
               "name": "sentiment_analysis",
               "strict": True,
               "schema": {
                   "type": "object",
                   "properties": {
                       "sentiment": {"type": "string", "enum": ["positive", "negative", "neutral"]},
                       "confidence": {"type": "number"}
                   },
                   "required": ["sentiment", "confidence"]
               }
           }
       }
   }
)

import json
result = json.loads(response.choices[0].message.content)
print(result)

{'sentiment': 'negative', 'confidence': 0.98}

Esto es lo que ocurre en este esquema:

• sentiment: Un campo de cadena restringido a tres valores específicos mediante enum. El modelo no puede devolver nada fuera de «positivo», «negativo» o «neutral».
• confidence: Un campo numérico para la puntuación de confianza del modelo.
• required: Ambos campos deben estar presentes en la respuesta; el modelo no puede omitirlos.
• strict: True: Garantiza el cumplimiento estricto de la estructura del esquema.

Sin resultados estructurados, podrías obtener respuestas como «El sentimiento es muy negativo con un alto grado de confianza» o «Negativo (95 % de certeza)». Con el esquema, siempre obtienes JSON analizable que puedes utilizar inmediatamente en tu código.

Al establecer strict: True, se aplica el esquema de forma rigurosa: el modelo no puede desviarse de tu estructura. El arreglo required especifica qué campos deben estar presentes. Puedes utilizar enum para restringir los valores a opciones específicas, array para listas y tipos object anidados para datos complejos.

Compatibilidad del modelo

No todos los modelos admiten salidas estructuradas, pero la mayoría de los modernos sí. Puedes consultar la página de modelos para comprobar la compatibilidad. Cuando un modelo no admite de forma nativa salidas estructuradas, OpenRouter suele gestionar el formato internamente.

Las salidas estructuradas convierten las respuestas de IA de textos impredecibles en datos fiables en los que pueden confiar tus aplicaciones. Esta función es esencial para cualquier caso de uso en producción en el que se necesite una extracción de datos coherente.

Conclusión

Hemos aprendido a acceder a cientos de modelos de IA a través de la API unificada de OpenRouter, desde realizar tu primera solicitud hasta implementar funciones como streaming, tokens de razonamiento y salidas estructuradas.

Las funciones automáticas de respaldo y enrutamiento de modelos de la plataforma garantizan la fiabilidad de tus aplicaciones incluso cuando los proveedores individuales tienen problemas. Con los mismos patrones de código, podemos comparar modelos, cambiar de proveedor y encontrar la opción perfecta para cada tarea sin tener que gestionar varias claves API.

Empieza a experimentar con solicitudes sencillas y prueba gradualmente más funciones a medida que aumenten tus necesidades. Prueba diferentes modelos para diferentes tipos de tareas: algunos funcionan mejor para la escritura creativa, mientras que otros son más eficaces para el análisis de datos o los problemas de razonamiento.

Los conocimientos que has adquirido aquí te proporcionan lo necesario para crear aplicaciones de IA que no están vinculadas a un único proveedor, lo que te ofrece la libertad de adaptarte a medida que surgen nuevos modelos y capacidades.