Arquitectura de API Gateway para IA: una clave, enrutamiento de modelos y failover

Una API gateway de IA ofrece a una aplicación un único endpoint estable mientras que la infraestructura detrás de ese endpoint puede usar múltiples modelos, proveedores, cuentas o regiones. La parte útil no es simplemente ocultar varias claves de API detrás de una sola clave. La parte útil es crear un punto de decisión controlado para cada solicitud.

Ese punto de decisión puede responder preguntas operativas antes de que el tráfico llegue a un proveedor de modelos:

• ¿Este cliente tiene अनुमति para llamar al modelo solicitado?
• ¿Qué upstream satisface actualmente los requisitos de capacidad, latencia y coste de la solicitud?
• ¿Ese upstream está lo suficientemente sano como para recibir más tráfico?
• ¿Se puede reintentar la solicitud de forma segura?
• ¿Qué fallback preserva el contrato de respuesta?
• ¿Cómo explicará el equipo la ruta, el coste y el fallo después?

Esta guía mapea esas responsabilidades a una arquitectura de producción. También muestra dónde ayuda una sola clave de API, dónde no lo hace y cómo migrar un cliente compatible con OpenAI sin convertir la gateway en una fuente invisible de sorpresas de enrutamiento.

The reference architecture in one request path

Una solicitud práctica a una gateway de IA pasa por cinco capas:

1. Contrato del cliente: la aplicación envía una solicitud autenticada a una única URL base estable.
2. Controles de admisión: la gateway valida la identidad, la cuota, los permisos del modelo, los límites de carga útil y los metadatos de la solicitud.
3. Política de enrutamiento: un motor de políticas convierte el modelo o la capacidad solicitados en destinos upstream elegibles.
4. Controles de ejecución: las reglas de salud, concurrencia, tiempo de espera, reintento, fallback y streaming determinan cómo se llama al destino seleccionado.
5. Telemetría y contabilidad: la gateway registra la ruta seleccionada, el estado de la respuesta, la latencia, el uso de tokens o medios y la atribución de costes.

Application / agent
        |
        |  one API key + stable request schema
        v
AI API gateway
  ├─ authentication and tenant policy
  ├─ model alias and capability registry
  ├─ routing policy and budget rules
  ├─ health, timeout, retry, and fallback controls
  └─ logs, traces, usage, and cost attribution
        |
        ├────────> Provider or deployment A
        ├────────> Provider or deployment B
        └────────> Provider or deployment C

Por lo tanto, la gateway es a la vez un plano de control y un plano de datos. El plano de control almacena políticas, credenciales, alias, cuotas y configuración de enrutamiento. El plano de datos gestiona solicitudes en vivo, respuestas en streaming, reintentos y telemetría. Mantener esas responsabilidades separadas conceptualmente hace que los cambios sean más seguros: los operadores pueden actualizar la política de enrutamiento sin pedir a cada equipo de aplicación que publique nuevo código cliente.

What “one key” should mean

“Una clave” debería significar un contrato de credencial único orientado a la aplicación, no una credencial compartida por todas las personas, servicios y entornos.

Un diseño sólido emite credenciales de gateway separadas para producción, staging, desarrollo local, CI y cargas de trabajo independientes. Cada clave debe tener un ámbito estrecho, un propietario, una cuota y una vía de revocación. La gateway mantiene entonces las credenciales del proveedor del lado del servidor y asigna una identidad entrante a las credenciales upstream que tiene अनुमति para usar.

Esto crea una frontera de seguridad útil:

La clave de gateway nunca debe considerarse una razón para relajar la higiene de claves. Guárdala en un gestor de secretos, nunca en código del navegador ni en un repositorio público, gírala y sepárala por entorno. Para una lista de verificación operativa más profunda, consulta secure API key management for AI products.

Los alias de modelo separan el contrato del cliente de los proveedores

La primera abstracción de enrutamiento es un alias de modelo. En lugar de codificar de forma fija un identificador de modelo específico del proveedor en toda la aplicación, el cliente solicita un nombre estable como:

support-fast
reasoning-high
code-review-default
image-generation-standard

El registro detrás de cada alias define un contrato de capacidades. Un alias de texto podría especificar llamada a herramientas, salida estructurada, tamaño mínimo de contexto, compatibilidad con streaming y una familia de fallback aprobada. Un alias de imagen o video necesita campos diferentes, como tipos de entrada aceptados, dimensiones de salida, comportamiento de trabajos asíncronos y restricciones de seguridad.

Un alias no debe prometer que cada modelo candidato se comporte de manera idéntica. Debe definir el comportamiento mínimo en el que la aplicación puede confiar.

alias: support-fast
contract:
  modality: text
  streaming: true
  tools: optional
  structured_output: required
  maximum_latency_ms: 3500
routes:
  - target: provider-a/model-fast
    priority: 1
  - target: provider-b/model-balanced
    priority: 2

Esta indirection es lo que hace valiosa una URL base estable. Las aplicaciones se integran con el contrato del alias; los responsables de la plataforma pueden cambiar el conjunto de destinos después de una evaluación, un incidente del proveedor, un cambio de precios o un requisito regional.

La decisión de enrutamiento debe ser explícita

El enrutamiento en producción suele combinar filtros rígidos y ranking suave.

1. Aplicar filtros de elegibilidad rígidos

Elimina cualquier destino que no pueda satisfacer la solicitud. Los filtros comunes incluyen:

• Modalidad e tipo de entrada requeridos
• Requisito de ventana de contexto o tamaño de salida
• Compatibilidad con llamada a herramientas o salida estructurada
• Residencia de datos o disponibilidad regional
• Lista de अनुमति de inquilino o proyecto
• Política de seguridad o cumplimiento
• Cupo actual, límite de tasa o estado de concurrencia
• Compatibilidad con streaming

Un destino que no cumple un requisito rígido nunca debe ganar solo porque es más barato.

2. Clasificar los destinos elegibles

Después del filtrado, puntúa las rutas restantes. Una política simple puede ser más fácil de operar que un optimizador opaco:

route score =
  quality_weight × evaluation_score
  - latency_weight × predicted_latency
  - cost_weight × estimated_cost
  - risk_weight × recent_error_rate

Los pesos deben variar según la carga de trabajo. El chat interactivo puede priorizar el tiempo hasta el primer token. Un trabajo nocturno de extracción puede priorizar el coste por registro estructurado exitoso. Un agente de programación puede valorar más la fiabilidad de las herramientas y el comportamiento de contexto largo que una pequeña diferencia de precio.

3. Registrar el motivo

Toda decisión de enrutamiento debería producir metadatos legibles por máquina, como:

{
  "requested_alias": "support-fast",
  "selected_target": "provider-a/model-fast",
  "policy_version": "support-fast-2026-07-29.3",
  "selection_reason": "healthy_primary_within_latency_budget",
  "fallback_count": 0
}

Si un equipo no puede reconstruir por qué se seleccionó una ruta, no puede depurar la deriva de costes, las regresiones de calidad o los incidentes del proveedor.

Las comprobaciones de estado necesitan más que un HTTP 200

Un upstream puede devolver sondas de estado satisfactorias mientras falla el tráfico real del modelo. Por tanto, la salud de una gateway de IA necesita varias señales:

• Salud de transporte: fallos de conexión, errores TLS, errores DNS y timeouts del upstream
• Salud de API: respuestas de limitación de tasa, fallos de autenticación, errores del proveedor y respuestas mal formadas
• Salud del modelo: salida vacía, salida estructurada no válida, llamadas a herramientas rotas o fragmentos de streaming incompatibles
• Salud del rendimiento: tiempo hasta el primer token, latencia total, tiempo en cola y throughput
• Salud de capacidad: solicitudes concurrentes, presión de tokens por minuto, saldo de cuenta o cuota de despliegue

Use una ventana móvil en lugar de un único fallo. Un circuito de interrupción puede retirar temporalmente un destino después de que se supere su umbral de fallos o latencia, y luego permitir sondeos limitados antes de restaurar todo el tráfico. La detección de outliers también puede expulsar un único despliegue no saludable mientras deja disponibles los despliegues sanos del mismo proveedor.

El principio está bien establecido en la infraestructura de gateways y service mesh: los reintentos, el circuit breaking y la detección de outliers son controles separados, y cada uno necesita una política acotada. Envoy documenta estos mecanismos por separado en su guía de reintentos HTTP, circuit breaking y detección de outliers.

Reintente solo cuando la solicitud sea segura

Los reintentos mejoran la fiabilidad solo cuando no multiplican el trabajo ni crean efectos secundarios duplicados.

Para una finalización de texto sin streaming que falló antes de que llegara cualquier byte de respuesta, un reintento contra el mismo destino puede ser razonable. Para una solicitud que activa una herramienta, inicia un trabajo de imagen o vídeo, carga a una cuenta externa o ya ha transmitido una salida parcial, un reintento a ciegas puede crear duplicados o corromper la experiencia del usuario.

Defina la elegibilidad para reintentos mediante tres preguntas:

1. ¿Se aceptó la solicitud en upstream? Un fallo de conexión antes de la aceptación es diferente de un timeout después de que el proveedor empezó a trabajar.
2. ¿Ha llegado alguna salida al cliente? Una vez que comienza el streaming, cambiar de proveedor puede producir una respuesta discontinua.
3. ¿Hay una clave de idempotencia o un registro de deduplicación? Los flujos de trabajo de medios de larga duración y de agentes necesitan una identidad de operación estable.

Una matriz de reintentos conservadora se ve así:

Mantén un único plazo de extremo a extremo. Si el cliente permite ocho segundos, el gateway no puede gastar siete segundos en el primario y luego darle otros ocho al fallback. Cada intento consume el mismo presupuesto de la solicitud.

Los fallbacks deben preservar el contrato

Un fallback no es simplemente “probar otro modelo”. Es un acuerdo sobre qué puede cambiar cuando falla la ruta primaria.

Define los fallbacks en tres niveles:

1. Mismo modelo, implementación o cuenta diferente: menor riesgo de comportamiento; útil para fallos de cuota o regionales.
2. Familia de modelo equivalente: riesgo moderado; requiere pruebas de regresión para esquema, herramientas, seguridad y estilo de salida.
3. Capacidad degradada: mayor riesgo; puede desactivar herramientas, reducir contexto o devolver una respuesta en cola en lugar de una en vivo.

Para cada alias, documenta:

• Qué clases de fallo activan el fallback
• Qué destinos son compatibles con el contrato
• Si se informa al cliente de que ocurrió un fallback
• Número máximo de intentos y plazo total
• Cómo se miden los cambios de calidad y coste
• Si la respuesta puede almacenarse en caché o reproducirse

El acceso regional al proveedor añade otra dimensión. Un proveedor o modelo puede estar disponible en una geografía, tipo de cuenta o acuerdo comercial y no estarlo en otro. Regional LLM provider routing explica los controles separados de acceso, política y failover necesarios para esas rutas.

El streaming es parte del contrato del gateway

Los formatos de solicitud compatibles con OpenAI pueden simplificar la migración del cliente, pero la compatibilidad del streaming requiere una traducción deliberada. El gateway debe preservar el orden de los eventos, los motivos de finalización, los metadatos de uso, los fragmentos de llamadas a herramientas, la señalización de errores y la cancelación de conexiones.

Antes de enrutar dos modelos detrás de un solo alias de streaming, prueba:

• Tiempo hasta el primer evento y comportamiento del latido
• Formato incremental de delta de texto
• Ensamblaje de argumentos de llamadas a herramientas
• Informe de uso en el evento final
• Propagación de la cancelación del cliente
• Comportamiento del tiempo de espera antes y después del primer evento
• Formato de error después de que los encabezados ya se hayan enviado

No oculte un reinicio del flujo dentro de una sola respuesta, salvo que el protocolo admita explícitamente la reanudación. En la mayoría de los clientes, mezclar una respuesta parcial de un modelo con una segunda respuesta de otro es peor que devolver un error claro.

La observabilidad conecta el enrutamiento con los resultados

Los paneles del gateway son útiles, pero el diagnóstico en producción requiere telemetría estructurada que pueda vincular una solicitud de modelo con el trazo de la aplicación circundante.

Como mínimo, capture:

Evite registrar de forma predeterminada prompts y salidas en bruto. Registre el contenido solo cuando el caso de uso, la política de retención y las expectativas del usuario lo permitan. El proyecto OpenTelemetry mantiene convenciones semánticas en evolución para sistemas de IA generativa que pueden ayudar a los equipos a usar nombres consistentes de spans y métricas en lugar de inventar un esquema aparte para cada proveedor.

Los controles de coste deben ir antes de la llamada al upstream

Los informes de gasto posteriores no pueden prevenir un incidente. La política de admisión y enrutamiento debería evaluar el coste antes de enviar tráfico.

Los controles útiles incluyen:

• Cuotas rígidas por clave y por proyecto
• Alertas de presupuesto flexibles
• Máximo de unidades de entrada o salida
• Listas de अनुमति de modelos por entorno
• Enrutamiento sensible al coste para cargas de trabajo flexibles
• Política de caché para solicitudes repetibles
• Límites de concurrencia para trabajos de medios costosos
• Interruptores de apagado para un modelo, proveedor, tenant o ruta

El motor de enrutamiento necesita una tabla de precios versionada y una capa coherente de normalización del uso. De lo contrario, una política de “modelo más barato” puede comparar unidades incompatibles o precios obsoletos. Para un marco que separa las tarifas del proveedor, las comisiones de la plataforma y los controles operativos, consulte precios de AI gateway.

Una migración mínima compatible con OpenAI

El cambio más pequeño en el cliente suele ser una nueva clave de API, una nueva URL base y un nombre de modelo. Con un gateway compatible con OpenAI, el código de la aplicación puede mantener la misma biblioteca cliente:

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["FLATKEY_API_KEY"],
    base_url="https://router.flatkey.ai/v1",
)

response = client.chat.completions.create(
    model="your-model-or-alias",
    messages=[
        {"role": "user", "content": "Resume este informe de incidente."}
    ],
)

Ese cambio de código es la parte fácil. Una migración segura tiene cuatro etapas:

1. Inventaria el contrato actual. Registra modelos, parámetros, comportamiento de streaming, herramientas, esquemas, timeouts y manejo de errores.
2. Ejecuta evaluaciones en sombra u offline. Compara la calidad de la salida, la validez del esquema, la latencia y el coste en solicitudes representativas.
3. Haz canary de una carga de trabajo. Empieza con un porcentaje acotado de tráfico y una ruta de reversión inmediata.
4. Activa las funciones de enrutamiento por separado. Primero cambia el endpoint, luego añade alias, luego failover basado en salud, y después la optimización de coste o calidad.

Separar esos cambios hace que los incidentes sean diagnosticables. Si la migración del endpoint, el reemplazo del modelo, la política de reintentos y el optimizador de costes se lanzan todos a la vez, el equipo no sabrá qué variable causó una regresión. El Flatkey integration starter cubre el patrón de migración de base URL con más detalle.

Lista de verificación de preparación para producción

Usa esta lista de verificación antes de tratar el gateway como infraestructura compartida.

Contrato del cliente

• URL base estable y esquema de solicitud versionado
• Alias nombrados con capacidades mínimas documentadas
• Envoltura de error consistente e IDs de solicitud
• Streaming, llamadas a herramientas y salida estructurada probados

Identidad y seguridad

• Claves separadas por servicio y entorno
• Credenciales del proveedor del lado del servidor
• Ámbitos de clave, cuotas, rotación y revocación
• Registro de prompts y respuestas desactivado o gobernado explícitamente

Enrutamiento y confiabilidad

• Filtros duros de elegibilidad antes de la clasificación por coste
• Políticas de enrutamiento y datos de precios versionados
• Salud basada en el comportamiento real de las solicitudes
• Reintentos acotados con un único plazo de extremo a extremo
• Destinos de fallback compatibles con el contrato
• Circuit breaker y sondas de recuperación

Operaciones

• Telemetría de motivo de ruta, error del proveedor, latencia y uso
• Alertas para tasa de fallback, tasa de error, desviación de costes y presión de cuota
• Kill switches por modelo y por ruta
• Runbook para caída del proveedor y caída del gateway
• Ruta de emergencia directa o alternativa para cargas de trabajo críticas

Cómo encaja Flatkey en esta arquitectura

Flatkey proporciona una clave de API, una URL base compatible con OpenAI y un panel único para el acceso a modelos compatibles, el uso y la facturación. Su router está diseñado para reducir las cuentas separadas de proveedores y las rutas de integración fragmentadas, al tiempo que admite el cambio de upstream y el balanceo de carga.

Para un equipo de aplicaciones, el beneficio arquitectónico es un límite de cliente estable: apunta un cliente compatible con OpenAI a https://router.flatkey.ai/v1, selecciona un modelo compatible y mantén el acceso al modelo detrás del mismo endpoint del gateway. Los equipos aún deben definir sus propios contratos a nivel de aplicación, umbrales de evaluación, ámbitos de claves, presupuestos de fallo y expectativas de fallback.

La mejor arquitectura de gateway no hace que el enrutamiento sea invisible. Hace que el enrutamiento sea cambiable, acotado y explicable.

Preguntas frecuentes

¿Qué es un gateway de API de IA?

Un gateway de API de IA es un intermediario entre las aplicaciones y los proveedores de modelos. Centraliza la autenticación, el acceso a modelos, el enrutamiento, los controles de fiabilidad, el seguimiento de uso y las políticas, al tiempo que expone una API estable orientada al cliente.

¿Una sola clave de API significa que todos los servicios comparten la misma clave?

No. Significa que las aplicaciones usan credenciales emitidas por el gateway en lugar de gestionar directamente cada credencial de proveedor. Los servicios de producción, los entornos y los equipos aún deben recibir claves separadas con ámbito limitado.

¿Qué es el enrutamiento de modelos?

El enrutamiento de modelos es el proceso de filtrar los modelos o despliegues elegibles y seleccionar un destino según la capacidad, la política, el estado, la latencia, la calidad, el coste, la región o la capacidad.

¿Cuál es la estrategia de fallback más segura?

Empieza con el mismo modelo en otro despliegue o cuenta en buen estado. El fallback entre modelos solo debería ocurrir después de que las pruebas demuestren que el destino alternativo conserva el esquema, las herramientas, el streaming, la seguridad y el contrato de calidad de la aplicación.

¿Puede un gateway reintentar una respuesta en streaming en otro modelo?

Por lo general, no después de que la salida haya llegado al cliente. Cambiar a mitad de flujo puede combinar respuestas parciales incompatibles. Usa un error de flujo claro a menos que el cliente y el gateway implementen un protocolo explícito de reanudación.

¿Es suficiente una API compatible con OpenAI para una migración sin cambios?

Reduce los cambios en el SDK y en la forma de las solicitudes, pero los equipos aún deben verificar los parámetros compatibles, los errores, los eventos de streaming, las llamadas a herramientas, la salida estructurada, la contabilidad de tokens y el comportamiento del modelo.