Migrar una integración de OpenRouter a otra pasarela de API
Planifica una migración reversible de OpenRouter con matriz de requisitos, credenciales aisladas, tests de contrato, canary controlado y rollback explícito.
Índice
Una migración de OpenRouter no consiste en sustituir la Base URL en producción. Primero inventaría protocolo, método SDK, Model ID, esquema, streaming, herramientas, errores, reintentos y uso; después prueba la pasarela con una clave aislada y un canary pequeño. Mantener OpenRouter o añadir solo un respaldo también puede ser correcto.
Esta guía utiliza BetterToken como ejemplo verificable. No es un clon de OpenRouter y la etiqueta OpenAI-compatible no garantiza modelos, funciones, errores ni datos de uso idénticos.
Elige el escenario
- Mantener OpenRouter si integración, facturación, modelos y operación cumplen los requisitos.
- Añadir un respaldo probado si una segunda ruta aporta valor sin sustituir la principal.
- Ejecutar un canary si protocolo y modelo encajan y puedes comparar tráfico controlado.
BetterToken no transfiere claves ni saldo de OpenRouter. Usa cuenta y clave propias y toma Model ID/requisitos actuales de Workspace o Docs.
Matriz de requisitos
| Requisito | Contrato actual | Evidencia candidata | Pregunta de aceptación |
|---|---|---|---|
| Protocolo/método | Endpoint y SDK de producción | Docs + solicitud con el mismo SDK | ¿Misma forma de API? |
| Modelo | Model ID y capacidades | ID actual de catálogo/Setup | ¿Modelo o sustituto aprobado disponible? |
| Auth/Base URL | Variable, cabecera, rutas | Clave aislada y URL efectiva | ¿Secreto fuera de logs y /v1 una vez? |
| Respuesta/stream | Campos, eventos, final | Estructura segura y stream completo | ¿Lectura segura y completa? |
| Herramientas | Nombre, argumentos, IDs, resultado | Test de solo lectura | ¿Se conserva el significado? |
| Errores/uso | Estado, ID, retry, tokens | Tests inválidos + SDK/log/proveedor | ¿Clasificación y conciliación posibles? |
| Operación/rollback | Timeout, concurrencia, ruta anterior | Canary y retorno probado | ¿Retorno sin repetir efectos? |
Modelos y precios son dinámicos; consulta catálogo y rate card al probar.
Tres escenarios
1. Mantener OpenRouter
Sin una carencia concreta, no migres. Lleva Base URL, clave y Model ID a configuración, documenta campos, separa cabeceras, añade tests de contrato y define rollback y retries.
2. Añadir un respaldo probado
Mantén configuraciones separadas. Define qué fallos permiten fallback. Autenticación, Model ID inválido, métodos incompatibles y solicitudes mal formadas normalmente no deben cambiar de proveedor. Limita retries/timeouts y no dupliques mutaciones sin idempotencia verificada.
3. Migrar con canary
Envía poco tráfico no crítico y conserva OpenRouter. Exige esquema parseable, streaming/herramientas correctos, errores clasificables, uso conciliable, umbrales cumplidos y ausencia de efectos perdidos o duplicados.
Procedimiento en cinco pasos
Paso 1: inventaría el contrato
Registra protocolo, SDK, método, Base URL, Model ID, variable auth, cabeceras, streaming, herramientas, timeouts, retries, errores, request ID y usage. No copies claves.
Paso 2: aísla la configuración candidata
Crea una clave de prueba separada. Para BetterToken, toma Model ID y requisitos actuales de Workspace o la documentación API. No sobrescribas OpenRouter.
Paso 3: configura la Base URL del protocolo
TEST_API_KEY=your_test_api_key_here
TEST_BASE_URL=https://www.bettertoken.ai/v1?utm_source=blog&utm_medium=organic_content&utm_campaign=SEO-088&utm_content=analog-openrouter-v-rossii-vybor-i-perenos-api
TEST_MODEL_ID=current_model_id_from_provider_catalogPara Anthropic-compatible usa https://bettertoken.ai sin /v1 y su contrato. Comprueba si el cliente añade la ruta.
Paso 4: ejecuta los mismos tests
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["TEST_API_KEY"],
base_url=os.environ["TEST_BASE_URL"],
)
response = client.chat.completions.create(
model=os.environ["TEST_MODEL_ID"],
messages=[{"role": "user", "content": "Reply with: gateway test passed"}],
max_tokens=32,
)
print(response.choices[0].message.content)
print(response.usage)Los placeholders son intencionados. Prueba después streaming, herramientas, autenticación inválida y Model ID inválido. Guarda hora, estado, request ID, esquema y uso sin secretos.
Paso 5: compara el canary
Compara éxitos/errores, latencia, timeouts, retries y Retry-After, esquemas, fin del stream, input/cached input/output, estado/cargo del proveedor y efectos secundarios. Amplía solo si pasan todos los requisitos obligatorios.
Validación y rollback
Un HTTP correcto no prueba equivalencia ni enrutamiento. Provoca fallos controlados y revisa estado, cuerpo, request ID, metadatos de retry y cliente. La referencia de errores de OpenRouter es un contrato separado.
Concilia usage del SDK, log y registro del proveedor. BetterToken Dashboard muestra hora, modelo, estado, input, output, caché y cargo, sin implicar prompts/respuestas completos. Prueba streaming, desconexión y tool calls de solo lectura por separado.
Rollback inmediato ante esquema ilegible, stream incompleto, herramientas dañadas, uso no conciliable, umbral incumplido o mutación incierta:
- detener la expansión;
- devolver nuevas solicitudes a OpenRouter;
- no repetir automáticamente mutaciones inciertas;
- conservar horas, IDs, estados y logs redactados;
- aislar y revocar la clave candidata si ya no hace falta.
No elimines la configuración anterior hasta completar observación, prueba de rollback y conciliación.
Costes y decisión
No fijes precios. Revisa rate cards actuales, modelos, input/cached input/output, requisitos de cuenta, límites, timeouts, exportación, rotación y soporte. Para BetterToken usa precios actuales y Workspace.
Mantén OpenRouter sin una carencia concreta, añade respaldo solo tras tests equivalentes y migra únicamente después de canary, conciliación y rollback válidos. Empieza con la documentación API de BetterToken.
