Nombres de modelos compatibles con OpenAI: evita errores de alias, proveedor y versión

Los nombres de modelos compatibles con OpenAI son ese lugar silencioso donde migraciones por lo demás limpias se rompen. El SDK acepta una cadena model, la forma de la solicitud parece familiar y la base URL apunta a una ruta compatible con OpenAI. Luego producción ve model_not_found, una caída silenciosa a la capacidad equivocada o un modelo de imágenes enviado a un endpoint de chat.

La solución no es memorizar el catálogo de cada proveedor. Trata los nombres de modelos compatibles con OpenAI como configuración controlada: cada cadena pertenece a un catálogo de proveedor, una familia de endpoint, una ruta, una política de versiones y un registro de facturación. Verifica los cinco antes de mover tráfico real.

Flatkey es útil aquí porque los equipos pueden centralizar el acceso a modelos, el enrutamiento, la facturación, el análisis de uso y la revisión operativa detrás de una sola pasarela. Pero una pasarela no convierte en seguras las cadenas de modelo sueltas. Esta guía te da un flujo de verificación para los nombres de modelos compatibles con OpenAI antes de cambiar una base URL, una configuración de SDK o un alias de producción.

Por qué los nombres de modelos compatibles con OpenAI se desvían

"Compatible con OpenAI" describe una forma de API, no un estándar universal de nombres. Un endpoint compatible puede aceptar JSON y SDK al estilo de OpenAI y, aun así, requerir sus propios IDs de modelo.

Eso significa que estas cadenas no son intercambiables:

La regla segura es simple: no apruebes nombres de modelos compatibles con OpenAI de memoria. Apruébalos a partir del catálogo actual, la familia de endpoint actual y una prueba de humo.

El flujo de trabajo de verificación del nombre del modelo

Usa este flujo de trabajo antes de cambiar OPENAI_BASE_URL, baseURL, model, un alias de Flatkey o una política de enrutamiento de producción.

Este es el valor central de una lista de verificación de nombres de modelo: convierte los nombres de modelos compatibles con OpenAI, de cadenas improvisadas, en entradas de despliegue revisadas.

Ejemplos actuales de proveedores de los que aprender

Usa la documentación oficial para entender el patrón y luego verifica tu propia cuenta o el catálogo de la pasarela antes de publicar.

Estos ejemplos muestran por qué los nombres de modelos compatibles con OpenAI deben tratarse como cadenas específicas del proveedor. La compatibilidad reduce los cambios en el cliente; no borra las diferencias entre catálogos.

Crea un mapa de modelos aprobados

No disperses cadenas de modelo sin procesar por el código de la app, notebooks, herramientas de automatización y scripts de soporte. Coloca los nombres de modelos aprobados compatibles con OpenAI en un pequeño mapa y dirige todos los servicios a través de él.

type EndpointFamily = "chat" | "responses" | "embeddings" | "images" | "video";

type ApprovedModelRoute = {
  alias: string;
  providerModel: string;
  endpointFamily: EndpointFamily;
  baseURL: string;
  owner: string;
  reviewedAt: string;
  rollbackAlias: string;
};

export const models: Record<string, ApprovedModelRoute> = {
  support_chat: {
    alias: "support_chat",
    providerModel: process.env.FLATKEY_SUPPORT_CHAT_MODEL!,
    endpointFamily: "chat",
    baseURL: process.env.FLATKEY_BASE_URL ?? "https://router.flatkey.ai/v1",
    owner: "support-platform",
    reviewedAt: "2026-07-07",
    rollbackAlias: "support_chat_previous",
  },
};

El mapa separa el nombre que usa tu app de la cadena del modelo del proveedor o del gateway. Eso da a compras, finanzas y a quienes responden a incidentes un lugar estable para preguntar: quién aprobó este modelo, para qué endpoint es y cómo lo revertimos.

Para una gobernanza más amplia del catálogo, combínalo con la guía de catálogo de modelos de IA. Para la migración de la base URL, usa la guía de migración de API compatible con OpenAI.

Prueba de humo del nombre exacto antes de migrar el SDK

Una prueba de humo del nombre del modelo debe ser lo bastante pequeña como para inspeccionarla a mano. No empieces con herramientas, streaming, esquemas JSON ni un wrapper de framework. Empieza con la ruta, la clave y la cadena del modelo que planeas desplegar.

export FLATKEY_API_KEY="sk-fk-..."
export FLATKEY_BASE_URL="https://router.flatkey.ai/v1"
export FLATKEY_MODEL="the-current-flatkey-model-alias"

curl -sS "$FLATKEY_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$FLATKEY_MODEL"'",
    "messages": [
      {"role": "user", "content": "Reply with exactly: model route ok"}
    ]
  }'

Si esto falla, no depures el SDK. Primero revisa la cadena del modelo, la familia de endpoint, el alcance de la clave, la ruta y el catálogo. Si funciona, guarda el cuerpo de la respuesta, el código de estado, el ID de la solicitud si existe, la marca de tiempo, el objeto de uso y la lectura de uso de Flatkey.

Luego prueba los mismos nombres de modelos compatibles con OpenAI a través del SDK:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.FLATKEY_API_KEY,
  baseURL: process.env.FLATKEY_BASE_URL ?? "https://router.flatkey.ai/v1",
});

const response = await client.chat.completions.create({
  model: process.env.FLATKEY_MODEL!,
  messages: [{ role: "user", content: "Reply with exactly: sdk route ok" }],
});

console.log(response.choices[0]?.message?.content);

La prueba del SDK debe usar la misma raíz de base URL, el mismo alias de modelo y la misma familia de endpoint. Si curl funciona pero el SDK falla, inspecciona las variables de entorno antes de cambiar los nombres de los modelos.

Separa los alias de los IDs del proveedor

Un alias no es lo mismo que un ID del proveedor. Un ID del proveedor es la cadena aceptada por el proveedor de origen o por la ruta compatible con el proveedor. Un alias del gateway es la cadena que tu gateway asigna a un modelo del proveedor, una política de respaldo, un grupo de precios o una cuenta.

Ambos pueden ser válidos. Los problemas empiezan cuando los equipos dejan de etiquetar cuál están usando.

Usa esta disciplina de nombres:

Esto hace que los nombres de modelos compatibles con OpenAI sean auditables. Si una ruta falla, puedes saber si el problema es el alias de la app, el alias de Flatkey, el ID del modelo del proveedor o la familia de endpoint.

Evita desajustes de familia de endpoint

model_not_found no siempre significa que la cadena esté mal escrita. Puede significar que la cadena es válida en otra ruta.

Un modelo de chat puede no estar disponible en una ruta de Responses. Un modelo de imagen puede usar un endpoint de generación de imágenes. Un modelo de video puede requerir una familia de payload diferente. Una capa de compatibilidad del proveedor puede ignorar silenciosamente campos no compatibles o exponer solo una parte del catálogo del proveedor.

Antes de añadir parámetros opcionales, responde estas preguntas:

1. ¿Está aprobado este modelo para la ruta que estoy llamando?
2. ¿Este endpoint espera messages, input, prompt, imágenes, archivos u otra estructura de solicitud?
3. ¿El SDK seleccionado añade la ruta del endpoint después de la URL base?
4. ¿El proveedor requiere una URL base específica de la región o del workspace?
5. ¿Flatkey enruta este alias al mismo family de endpoints en staging y producción?

La guía de solución de problemas de la API compatible con OpenAI cubre el camino de depuración más amplio. Para el trabajo con nombres de modelos, mantén el fallo pequeño: una ruta, una cadena de modelo, una solicitud breve.

Planifica los cambios de versión y de obsolescencia

Los nombres de modelos compatibles con OpenAI cambian con el tiempo. Algunos nombres son familias estables, otros son instantáneas fechadas, otros son modelos de vista previa y otros son alias de gateway que controla tu propio equipo.

Crea una cadencia de revisión para cada ruta de modelo en producción:

No entierres estas decisiones solo en variables de entorno. Conserva la evidencia en un paquete que se pueda revisar para que ingeniería, operaciones y compras puedan ver por qué se permite el modelo.

Qué comprobar en Flatkey antes del corte

Usa Flatkey como punto de control operativo, no como motivo para omitir la verificación.

Antes de mover el tráfico de producción, confirma:

1. La URL base actual de Flatkey en tu consola o en las notas de incorporación.
2. El alias exacto del modelo que enviarás desde la aplicación.
3. El modelo del proveedor o la ruta detrás del alias.
4. La family de endpoint, como Chat Completions o Responses.
5. Los límites de cuota y gasto para la clave o el workspace.
6. La lectura de uso después de una prueba de humo exitosa.
7. El comportamiento de fallback si falla la ruta principal.
8. La configuración de reversión para la ruta anterior del proveedor o el alias anterior de Flatkey.

Luego compara el lado operativo en precios de Flatkey y obtén una clave para una ruta de prueba. Trata las páginas de precios y del catálogo de modelos como evidencia actual solo cuando las verifiques el día que migres.

Preguntas frecuentes

¿Son universales los nombres de modelos compatibles con OpenAI?

No. Los nombres de modelos compatibles con OpenAI siguen siendo cadenas específicas del proveedor o del gateway. La estructura de la solicitud puede ser compatible mientras el catálogo de modelos siga siendo diferente.

¿Por qué mi ruta compatible con OpenAI devuelve model_not_found?

La cadena del modelo puede estar mal escrita, no estar disponible para la cuenta, estar deshabilitada en el gateway, enviarse a la familia de endpoint incorrecta, estar limitada a otra región o estar obsoleta. Verifica la cadena exacta en el catálogo actual y ejecuta una prueba mínima de la ruta.

¿Debería usar IDs directos de modelos del proveedor o alias de Flatkey?

Usa un alias de Flatkey cuando quieras enrutamiento centralizado, facturación, revisión de uso, control de fallback o gobierno a nivel de equipo. Mantén el alias asignado a un ID de modelo del proveedor verificado y documenta al responsable.

¿Puedo copiar un nombre de modelo de una guía antigua del proveedor?

Solo como punto de partida. Las guías antiguas pueden contener cadenas retiradas, de vista previa o solo de ejemplo. Revisa de nuevo la documentación actual del proveedor, el catálogo actual de Flatkey y una prueba de humo en vivo.

¿Qué debe incluir una revisión de cambio de nombre de modelo?

Incluye la cadena anterior, la nueva cadena, la family de endpoint, la URL base, el proveedor o alias de Flatkey, el responsable, la documentación de origen, la respuesta de la prueba de humo, la lectura de uso, el impacto esperado en costos, el comportamiento de fallback y el plan de reversión.

Conclusión

Los nombres de modelos compatibles con OpenAI son entradas de migración, no trivialidades. Verifica el catálogo, la family de endpoint, el responsable del alias, la política de versiones y la prueba en tiempo de ejecución antes de cambiar el tráfico de producción. Si centralizas esas comprobaciones en Flatkey, la misma evidencia del nombre del modelo puede respaldar el corte de ingeniería, la revisión de incidentes, la conciliación de uso y la aprobación de compras.

Cuando estés listo para probar, empieza con una clave, una URL base, una family de endpoint y un alias de modelo aprobado. Esa es la forma más rápida de hacer que los nombres de modelos compatibles con OpenAI sean lo bastante aburridos para producción.