Model Not Found en APIs compatibles con OpenAI: causas, soluciones y checklist de depuración

Cambiaste tu base URL a un proveedor compatible con OpenAI, enviaste una solicitud y recibiste esto:

{
  "error": {
    "message": "The model `gpt-4o` does not exist or you do not have access to it.",
    "type": "invalid_request_error",
    "code": "model_not_found"
  }
}

Este es uno de los errores más comunes al cambiar entre proveedores de API compatibles con OpenAI. El formato de la solicitud es compatible, pero el model ID no lo es.

"Compatible con OpenAI" significa que el formato de solicitud funciona. No significa que cada model ID sea igual en todos los proveedores.

Resumen rápido

• "Model not found" generalmente significa que el model ID que enviaste no coincide con lo que el proveedor espera.
• Compatible con OpenAI ≠ mismos model IDs. Cada proveedor tiene su propia nomenclatura.
• Verifica siempre: (1) base URL, (2) model ID, (3) alcance del API key, (4) disponibilidad del modelo.
• Usa la matriz de depuración a continuación para aislar la causa en menos de 5 minutos.

Por qué ocurre este error

Pero la compatibilidad termina en el formato de solicitud. Los model IDs son específicos de cada proveedor:

Matriz de depuración: aislar la causa en 5 minutos

Recorre esta checklist en orden. Detente cuando encuentres el desajuste.

Los desajustes más comunes

Desajuste 1: Olvidaste cambiar el model ID después de cambiar la base URL

Esta es la causa más frecuente. Estás migrando de OpenAI a otro proveedor:

# Antes: OpenAI directo
client = OpenAI(api_key="sk-...")

# Después: cambio a otro proveedor pero manteniendo el mismo model ID
client = OpenAI(
    api_key="your-provider-key",
    base_url="https://api.another-provider.com/v1"  # Cambiado
)

response = client.chat.completions.create(
    model="gpt-4o",  # ← Este model ID puede no funcionar en el nuevo proveedor
    messages=[{"role": "user", "content": "Hello"}]
)

Desajuste 2: El proveedor usa model IDs con espacio de nombres

Algunos proveedores prefijan los model IDs con el nombre del fabricante original:

# OpenAI directo
model = "gpt-4o"

# OpenRouter
model = "openai/gpt-4o"

# Algunos proveedores usan sus propios alias
model = "gpt-4o-2024-08-06"

Desajuste 3: Modelo no disponible en este proveedor

No todos los proveedores compatibles con OpenAI soportan todos los modelos:

• Un proveedor puede soportar Claude pero no modelos GPT
• Un proveedor puede soportar modelos de texto pero no de imagen o video
• Un modelo recién lanzado puede no estar disponible en todas partes desde el primer día

Desajuste 4: Modelo descontinuado o renombrado

Los modelos de IA se actualizan con frecuencia. Un model ID que funcionaba el mes pasado puede estar descontinuado:

gpt-4-turbo → puede redirigir o fallar según el proveedor
claude-3-opus-20240229 → versión anterior, puede haber sido reemplazada

Cómo verificar el model ID correcto

Opción A: Consultar el endpoint de modelos

curl https://api.your-provider.com/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

Esto devuelve la lista de modelos disponibles para tu cuenta. Busca tu modelo objetivo en la respuesta.

Opción B: Consultar la documentación del proveedor

Todo proveedor serio tiene una página con la lista de modelos. Antes de cambiar, verifica:

1. La cadena exacta del model ID
2. Si requiere un prefijo de espacio de nombres
3. Si está disponible en tu plan/nivel
4. Si está disponible en tu región

Opción C: Enviar una solicitud de prueba mínima

curl https://api.your-provider.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-model-id",
    "messages": [{"role": "user", "content": "test"}],
    "max_tokens": 5
  }'

Si devuelve una respuesta válida, tu model ID es correcto. Si devuelve "model not found", prueba con el model ID recomendado por el proveedor.

Construir una selección de modelos resiliente

En sistemas de producción, los desajustes de model ID no deberían causar fallos graves. Estos patrones ayudan:

Patrón 1: Capa de mapeo de model IDs

Mantén un mapeo entre tus nombres internos de modelo y los IDs específicos de cada proveedor:

MODEL_MAP = {
    "fast-chat": {
        "openai": "gpt-4o-mini",
        "openrouter": "openai/gpt-4o-mini",
        "evolink": "gpt-4o-mini",
    },
    "strong-chat": {
        "openai": "gpt-4o",
        "openrouter": "openai/gpt-4o",
        "evolink": "gpt-4o",
    },
    "reasoning": {
        "openai": "o3",
        "openrouter": "openai/o3",
        "evolink": "o3",
    }
}

def get_model_id(capability: str, provider: str) -> str:
    return MODEL_MAP[capability][provider]

Patrón 2: Usar una API unificada que normaliza los model IDs

En lugar de mantener tu propia capa de mapeo, puedes usar un gateway que acepta model IDs estandarizados y gestiona el enrutamiento a proveedores internamente.

Con EvoLink, puedes usar model IDs familiares sin preocuparte por la nomenclatura específica de cada proveedor:

from openai import OpenAI

client = OpenAI(
    api_key="your-evolink-key",
    base_url="https://api.evolink.ai/v1"
)

# Usa model IDs estándar — EvoLink gestiona el mapeo
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}]
)

O deja que el Smart Router elija el mejor modelo para tu carga de trabajo:

response = client.chat.completions.create(
    model="evolink/auto",
    messages=[{"role": "user", "content": "Hello"}]
)

Patrón 3: Validar los model IDs al iniciar

No esperes a una solicitud de usuario para descubrir que un model ID es incorrecto:

async def validate_models_on_startup(client, required_models: list[str]):
    """Llama a /v1/models al iniciar y verifica que todos los modelos requeridos existan."""
    available = await client.models.list()
    available_ids = {m.id for m in available.data}

    for model in required_models:
        if model not in available_ids:
            raise RuntimeError(
                f"Model '{model}' not found on provider. "
                f"Available: {sorted(available_ids)}"
            )

Referencia rápida: compatible con OpenAI no significa idéntico

Esta distinción es la causa raíz de la mayoría de los errores "model not found" al cambiar de proveedor.

Artículos relacionados

• Fix OpenRouter 429 "Provider Returned Error" — cuando el modelo se encuentra pero el proveedor devuelve un error
• Best OpenRouter Alternatives in 2026 — compara proveedores y su cobertura de modelos
• How to Reduce 429 Errors in Agent Workloads — gestiona límites de tasa después de corregir los model IDs

FAQ

¿Por qué "gpt-4o" funciona en OpenAI pero no en mi nuevo proveedor?

¿Cómo encuentro el model ID correcto para mi proveedor?

¿Puedo usar el mismo model ID en todos los proveedores compatibles con OpenAI?

No de forma fiable. Aunque algunos proveedores aceptan los mismos IDs que OpenAI, muchos usan convenciones de nomenclatura diferentes. Mantén una capa de mapeo o usa un gateway como EvoLink que normaliza los model IDs por ti.

¿Qué pasa si el model ID funcionaba ayer pero dejó de funcionar hoy?

El modelo puede haber sido descontinuado, renombrado o eliminado de tu nivel. Consulta el changelog y los anuncios del proveedor. El ciclo de vida de los modelos en IA es más rápido que en las APIs tradicionales.

¿"Model not found" siempre es un problema de model ID?

Generalmente sí, pero no siempre. También puede significar: (1) tu API key no tiene acceso a ese modelo, (2) el modelo no está disponible en tu región, o (3) el modelo requiere un nivel de suscripción superior.

¿Cómo prevengo errores de model not found en producción?

Tres estrategias: (1) validar los model IDs al iniciar la aplicación, (2) mantener una capa de mapeo de model IDs o usar un gateway normalizador, (3) implementar lógica de fallback que intente un modelo alternativo si el principal devuelve "not found".