Mapeo de modelos y Fallback

No dejes que una caída del upstream se convierta en tu propia caída.

• El mapeo de modelos es la capacidad de la capa del gateway que reescribe el alias de modelo de la solicitud del cliente en el modelo real del upstream.
• El fallback ante errores es la capacidad por la que, cuando la llamada al modelo principal falla, el gateway prueba automáticamente modelos de respaldo en un orden de prioridad preconfigurado, de forma transparente para el cliente.

​

1. Mapeo de nombres de modelo

Una vez seleccionado un canal para el modelo de destino, la plataforma realiza internamente otro mapeo a nivel de canal hacia el modelo real del upstream. Esa capa es transparente para ti y no requiere configuración. Solo necesitas preocuparte por la capa “alias → modelo de destino”.

Todos los nombres de modelo de la tabla anterior se pueden consultar en la página de modelos de AIHubMix.

• El cliente restringe el formato del nombre de modelo. Por ejemplo, Claude Desktop exige nombres de modelo al estilo Claude (consulta la Sección 5).
• Asignar un alias más corto y estable a un Model ID complejo.
• Mantener la configuración del cliente sin cambios mientras se cambia el modelo real en el backend de AIHubMix.
• Varias plataformas comparten un mismo esquema de nombres de conexión pero enrutan a modelos distintos según la Key.

Coincidencia carácter por carácter: El nombre de modelo que envía el cliente debe coincidir con el lado izquierdo del mapeo carácter por carácter. Por ejemplo, my-gpt-5.5 y my-gpt-5-5 son dos cadenas diferentes; si no coinciden, el mapeo no se activará.

​

2. Fallback ante errores

​

2.1 Condiciones de activación

1. La Key tiene configurada una lista de modelos de respaldo no vacía.
2. Todos los canales del modelo principal se han probado y todos fallaron con un “error reintentable” (canales agotados).
3. La respuesta aún no ha comenzado a devolverse (el primer byte / la cabecera aún no se ha enviado al cliente).
4. El error no es un error a nivel de Key / usuario (consulta la tabla comparativa 2.2 más abajo).

​

2.2 Qué hace fallback y qué no

Nota: “Key inválida” aquí significa que tu propia Key de AIHubMix es inválida, lo que no hace fallback. Si la key de algún canal del upstream está rota, el gateway cambia de canal, y tras agotar los canales todavía puede hacer fallback. No confundas ambos casos.

​

2.3 Base de facturación

​

2.4 Regla del modelo gratuito

Uso típico: Configura un modelo gratuito como modelo principal y pon modelos de pago en la lista de respaldo. Cuando el modelo principal gratuito alcanza una cuota / límite de tasa, hace fallback automáticamente a un modelo de respaldo de pago. Normalmente ahorras costes usando la cuota gratuita, y tras el límite de tasa cambias sin interrupciones a un modelo de pago para garantizar la disponibilidad. Este es uno de los usos más comunes del fallback.

​

3. AIHubMix frente a OpenRouter / LiteLLM

​

4. Configuración y verificación

​

4.1 Configuración

1. Configura el mapeo de alias en la Key: el alias de la izquierda debe coincidir carácter por carácter con el nombre de modelo que el cliente envía realmente.
2. Configura la lista de modelos de respaldo (una lista de prioridad ordenada) en la misma Key.
3. La lista de respaldo debe contener únicamente modelos de pago / disponibles, no modelos gratuitos (se omitirán).
4. Los modelos de la lista de respaldo deben estar dentro del rango de modelos disponibles de la Key (los modelos fuera de rango se omitirán).

​

4.2 Verificación — revisa primero las cabeceras de respuesta, no los logs

• X-Aihubmix-Fallback: true: en esta solicitud ocurrió un fallback (se añade cuando el modelo final ≠ el modelo principal).
• X-Aihubmix-Model: el modelo que realmente respondió en esta solicitud y según el cual se facturó.

curl -i https://aihubmix.com/v1/chat/completions \
  -H "Authorization: Bearer sk-你的Key" \
  -H "Content-Type: application/json" \
  -d '{"model":"my-gpt","messages":[{"role":"user","content":"hi"}]}' \
  | grep -i -E 'x-aihubmix-(model|fallback)'

​

5. Escenario uno Claude Desktop

​

5.1 Por qué es necesario el mapeo

Claude Desktop usa la interfaz nativa de Claude /v1/messages, por lo que en los ejemplos de este artículo tanto el mapeo como el Fallback entran en vigor.

​

5.2 Configuración de mapeo y Fallback de AIHubMix

claude-g-p-t-5.5 -> gpt-5.5-pro
claude-gemi-3.1 -> gemini-3.1-pro-preview
claude-depsek-v4 -> deepseek-v4

fallback:
1. gpt-5.4
2. gemini-3.1-pro-preview

​

5.3 Lista de modelos de Claude Desktop

• Usa el prefijo claude- para el Model ID.
• No escribas directamente nombres de familias de modelos reales como gpt, gemini o deepseek; usa alias como g-p-t, gemi, depsek.
• El Model ID debe coincidir carácter por carácter con el lado izquierdo del mapeo de AIHubMix; de lo contrario, la solicitud no activará el mapeo esperado y puede continuar hasta el modelo de fallback ante errores.

​

6. Escenario dos Fallback de capacidad multimodal

claude-g-l-m-4.6 -> coding-glm-4.6-free
claude-g-p-t-5.5 -> gpt-5.5-pro
claude-gemi-3.1 -> gemini-3.1-pro-preview

fallback:
1. gpt-5.4
2. gemini-3.1-flash-image
3. veo-3

Ten claro el motivo de la activación: El fallback aquí ocurre porque el upstream devolvió un error reintentable para esta entrada de imagen y los canales del modelo principal se agotaron — es el mismo mecanismo de fallback que “hacer fallback después de que el modelo principal sea limitado en tasa”, solo que activado por un tipo de error distinto (el primero es una entrada no admitida, el segundo es una cuota / límite de tasa). Distingue comprensión de generación: Esto se refiere al fallback de comprensión de imágenes / vídeo, no a la generación de imágenes o generación de vídeo. Una solicitud de chat no se convierte automáticamente en un endpoint de generación; para probar el dibujo o la generación de vídeo, debes usar el endpoint y el modelo de generación correspondientes. Las capacidades de un modelo se determinan por los Input Modalities marcados actualmente en la página de modelos de AIHubMix.

​

7. Escenario tres Fallback de modelo gratuito

primary model (free): coding-glm-4.6-free

fallback:
1. gpt-5.4
2. gemini-3.1-pro-preview

• Mientras la cuota gratuita siga siendo suficiente, la solicitud la responde el modelo principal coding-glm-4.6-free y se factura como gratuita.
• Tras limitar la tasa del modelo principal gratuito, hace fallback automáticamente a gpt-5.4; si gpt-5.4 también está no disponible, prueba entonces gemini-3.1-pro-preview.
• Cualquiera que sea el modelo que finalmente responde es aquel por el que se te factura (consulta 2.3).

Nota: Un modelo gratuito solo puede ser el modelo principal y no puede ponerse en la lista de fallback (si lo haces, se omitirá; consulta 2.4). Por lo tanto, la forma correcta de hacer “fallback de modelo gratuito” es: gratuito como principal, de pago como respaldo, no al revés.

​

8. Endpoints admitidos

• El mapeo de modelos y el fallback ante errores admiten tres categorías de interfaz: interfaces compatibles con OpenAI, la interfaz nativa de Claude /v1/messages y OpenAI Responses /v1/responses.
• Otras interfaces nativas de paso directo (Gemini nativo, Ideogram, vídeo, TTS, Stability, OCR, predictions, etc.), el paso directo a un canal concreto y las interfaces de recuperación por ID de recurso / tipo de archivo aún no se admiten.
• Claude Desktop usa la interfaz nativa de Claude /v1/messages, por lo que en los ejemplos de este artículo tanto el mapeo como el Fallback entran en vigor.

​

9. Preguntas frecuentes

​

Recursos relacionados

• Conectar AIHubMix en Claude Desktop: pasos completos para el modo desarrollador, la configuración de Gateway, el esquema de autenticación y más.
• Página de modelos de AIHubMix: consulta nombres de modelo, precios e Input Modalities.
• Conectar AIHubMix en LiteLLM: una referencia para cuando necesites un gateway propio + mapeo / fallback de modelos.