Lista de verificación de producción de la API de OpenRouter

Verificar compatibilidad de API y puntos de conexión

Usa los endpoints estándar compatibles con OpenAI para una integración fiable.

El endpoint principal es POST /v1/chat/completions. Esto maneja la generación de texto para historiales de chat. Un endpoint secundario, GET /v1/models, lista los modelos disponibles. No necesitas endpoints de embeddings ni generación de imágenes para tareas solo de texto. Muchos desarrolladores asumen que necesitan una capa de enrutamiento compleja. OpenRouter simplifica esto exponiendo un único punto de entrada. Envías un payload JSON con el ID de tu modelo y los prompts del sistema. El servicio devuelve JSON estructurado con contenido y datos de uso. Este diseño coincide con las expectativas del SDK oficial de OpenAI. Puedes cambiar modelos sin cambiar el código de tu cliente. Solo actualiza el ID del modelo en tu configuración. Asegúrate de que tu cliente soporte el último esquema JSON. Las versiones antiguas podrían rechazar nuevos parámetros. Prueba tu conexión antes de desplegar en producción. Verifica que el formato de respuesta coincida con tu analizador.

Configurar autenticación y claves

Asegura tu clave API en variables de entorno inmediatamente después de su generación.

Genera una clave a través del panel de control del proveedor. Guárdala en una ubicación segura. Nunca la codifiques directamente en tu repositorio de código fuente. Pásala mediante Authorization: Bearer <key> header. Cada clave está vinculada a una cuenta específica. Puedes rotar las claves si sospechas una filtración. Algunos proveedores permiten múltiples claves por cuenta. Esto te permite separar el tráfico de desarrollo y producción. Monitorea el uso por clave para detectar anomalías. Revoca las claves no utilizadas regularmente. Usa claves de vida corta para scripts temporales. Esto reduce el radio de explosión de una compromiso. Asegúrate de que la versión de tu SDK admita la autenticación con token bearer. Las bibliotecas más antiguas podrían requerir un formato de encabezado diferente. Consulta la documentación de tu SDK específico. Verifica que la clave tenga suficiente saldo. Una clave expirada devuelve un error 401. Una clave con saldo cero devuelve un error 402. Distingue entre estos dos estados en tu lógica.

Gestionar transmisión y uso de tokens

Activa la transmisión para menor latencia y retroalimentación del usuario en tiempo real.

Establecer stream: true en tu carga útil de solicitud. El servidor envía una serie de Eventos Enviados por el Servidor (SSE). Cada evento contiene un fragmento parcial de texto. Debes ensamblar estos fragmentos para formar la respuesta completa. El último fragmento a menudo incluye estadísticas de uso de tokens. Esto te permite rastrear los costos en tiempo real. Sin streaming, esperas a que llegue toda la respuesta. Esto aumenta significativamente la latencia percibida. El streaming es esencial para interfaces de chat. Crea un efecto de escritura que se siente receptivo. Ten cuidado con el manejo de errores durante el streaming. Si la conexión se cae, pierdes el fragmento actual. La lógica de reconexión debe preservar el estado de la conversación. Algunas SDK manejan el streaming automáticamente. Otras requieren listeners de eventos manuales. Elige el enfoque que se adapte a tu arquitectura. Asegúrate de que tu analizador maneje fragmentos de JSON incompletos. No asumas que cada evento es un objeto completo. Almacena los datos hasta que tengas una estructura válida.

Monitorizar Límites de Velocidad y Concurrencia

Rastrea tus solicitudes por minuto para evitar interrupciones del servicio.

OpenRouter aplica límites estrictos de tasa por clave API. Superar estos límites activa un error 429 Too Many Requests. Debes implementar un retroceso exponencial en tu lógica de reintento. Las solicitudes concurrentes también cuentan contra tus límites. Consulta los encabezados de respuesta para ver la cuota restante. Algunos proveedores exponen estos encabezados directamente. Otros requieren que infieras los límites a partir de errores. La alta concurrencia puede agotar tu grupo de conexiones. Asegúrate de que tu cliente gestione las conexiones de manera eficiente. Utiliza agrupación de conexiones para reducir la sobrecarga. Monitorea la profundidad de tu cola durante las cargas pico. Si alcanzas el límite, espera antes de reintentar. Aleatoriza tu tiempo de espera para evitar problemas de rebaño estruendoso. Registra todos los eventos de límite de tasa para depuración. Esto ayuda a identificar patrones en tu uso. Ajusta tu configuración de concurrencia basándote en estos registros. No asumas que una sola clave puede manejar tráfico ilimitado. Distribuye la carga entre varias claves si es necesario. Esto requiere una gestión de estado cuidadosa. Asegúrate de que cada clave mantenga su propio contexto si es necesario.

Gestiona la facturación cripto y los recargas

Usa crédito prepagado para cubrir el uso de tokens sin cuotas mensuales.

Recarga tu cuenta con criptomonedas. Las redes admitidas incluyen USDT en TRC20 y USDC en Base. Los depósitos mínimos comienzan en $20. Los bonos se aplican a montos más grandes. Recibes un 5% extra por $50, 10% por $100 y 15% por $200. El crédito nunca expira. Esto es ideal para proyectos a largo plazo. Solo pagas por los tokens reales utilizados. Los errores y rechazos son gratuitos. Esto protege tu presupuesto de costos inesperados. Las cuentas nuevas reciben $0.50 para pruebas. No se emiten reembolsos para compras estándar. Las cobros dobles se corrigen mediante soporte. Asegúrate de que tu billetera soporte las redes requeridas. Verifica la dirección del contrato antes de enviar. Las redes incorrectas pueden resultar en la pérdida de fondos. Revisa tu saldo regularmente. Los saldos bajos pueden interrumpir el servicio inesperadamente. Automatiza las recargas si es posible. Esto garantiza la disponibilidad continua para tareas críticas.

Prueba los filtros de contenido y las negativas

Verifica que el modelo se comporte como se espera con prompts sin censura.

Los modelos sin censura aún pueden aplicar límites estrictos. Verifica las restricciones sobre tipos específicos de contenido. Prueba con frases activadoras conocidas. Asegúrate de que el modelo responda adecuadamente. Algunos proveedores mantienen filtros por razones legales. Verifícalos antes de confiar en el modelo para datos sensibles. Prueba casos límite en tu dominio. Envía instrucciones que normalmente activan rechazos. Observa el formato de respuesta. ¿Devuelve una razón para el rechazo? ¿O genera contenido silenciosamente? Documenta estos comportamientos en tus pruebas de integración. Esto evita sorpresas en producción. Si el modelo cambia su comportamiento, actualiza tus pruebas. Notifica a tu equipo sobre cualquier cambio significativo. La consistencia es clave para la confianza del usuario. Asegúrate de que tu aplicación maneje los rechazos de manera elegante. No asumas que cada respuesta es válida. Valida la estructura de la salida. Verifica alucinaciones o errores de formato. Esto garantiza una experiencia de usuario fiable.

Implementar manejo de errores para solicitudes gratuitas

Gestiona los errores de forma elegante para mantener una experiencia de usuario fluida.

Pueden producirse errores de red, tiempos de espera y errores del servidor. Implementa lógica de reintento con retroexponencial. Distingue entre errores transitorios y permanentes. Un error 429 es transitorio. Espera y reintenta. Un error 400 es permanente. Revisa los datos de entrada. Un error 500 es del lado del servidor. Reintenta con precaución. Registra todos los errores para la depuración. Incluye la carga útil de la solicitud y el cuerpo de la respuesta. Esto ayuda a reproducir los problemas rápidamente. No expongas errores crudos a los usuarios. Formátalos en mensajes amigables para el usuario. Maneja los errores de transmisión con cuidado. Desconéctate del flujo de eventos. Limpia los recursos. Asegúrate de que tu aplicación no tenga fugas de memoria. Prueba los escenarios de error exhaustivamente. Simula caídas de red. Simula tiempos de espera del servidor. Verifica que tu lógica de recuperación funcione. Esto garantiza la fiabilidad en condiciones adversas.

Escala con el Modo JSON y la Llamada de Herramientas

Utiliza salidas estructuradas para la extracción fiable de datos y la ejecución de funciones.

Habilita el modo JSON configurando response_format: {type: "json_object"}. Esto obliga al modelo a generar JSON válido. Úsalo para analizar datos o generar configuraciones. La llamada de herramientas permite al modelo ejecutar funciones. Define tus herramientas en la carga útil de la solicitud. El modelo decide cuándo llamarlas. Pasa los resultados de vuelta al modelo. Puede generar una respuesta final basada en la salida. Esto crea un bucle para tareas complejas. Asegúrate de que las definiciones de tus herramientas sean claras. Las herramientas ambiguas conducen a llamadas incorrectas. Valida la salida JSON antes de analizarla. Esto evita errores de tiempo de ejecución en tu código. Usa la llamada de herramientas para tareas de extracción de datos. Mejora significativamente la precisión. Prueba con varios formatos de entrada. Asegúrate de que el modelo maneje casos límite. Documenta las herramientas disponibles para tu equipo. Esto asegura un uso consistente en todos los proyectos.

Revisión Políticas de Privacidad y Uso de Datos

Comprender cómo el proveedor almacena y utiliza tus datos.

Consulta la política de privacidad para ver los detalles de retención de datos. Algunos proveedores utilizan tus datos para entrenamiento. Otros los mantienen privados. Asegúrate de que tus datos no se utilicen para mejorar el modelo si eso es importante para ti. Verifica los estándares de cifrado. Los datos deben estar cifrados en tránsito y en reposo. Comprueba si se almacenan registros. Los registros pueden contener tus prompts. Asegúrate de que estos registros sean seguros. Revisa los términos del servicio para ver las cláusulas de responsabilidad. Comprende quién posee el contenido generado. Algunos proveedores reclaman derechos sobre tu salida. Asegúrate de que esto se alinee con tus necesidades. Elimina tu cuenta si ya no utilizas el servicio. Verifica que tus datos se hayan eliminado. Contacta con soporte si tienes dudas. Documenta tu configuración de privacidad con fines de auditoría. Esto garantiza el cumplimiento de las políticas internas.