Depreciación y versionado de modelos de IA: Mantenga estables las integraciones de API

Una cadena de modelo es la constante más peligrosa en su base de código. Los equipos la tratan como una etiqueta, pero es la que decide qué punto de control responde, cuánto cuesta la llamada y si la solicitud tiene éxito o no. Por lo tanto, la deprecación y el versionado de modelos de IA deben formar parte de su proceso de lanzamiento, no ser una decisión tomada una sola vez. Esta guía utiliza la API pública de modelos de TokenLab, observada el 2026-10-03, para mostrar qué puede verificar automáticamente, qué debe verificar en otros lugares y qué hacer cuando un ID deja de funcionar.

Puntos clave

• Los datos del ciclo de vida residen en el objeto del modelo. Lea tokenlab.lifecycle desde Get a Model (observado el 2026-10-03) en lugar de copiar fechas de una publicación de blog.
• Los cinco modelos que verificamos el 2026-10-03 estaban active sin fecha de deprecación o retiro. Nuestra evidencia no contiene ningún modelo realmente deprecado, por lo que la ruta de fallo que se muestra a continuación es un comportamiento documentado, no algo que hayamos presenciado.
• Un modelo faltante devuelve model_not_found, pero el estado difiere según el endpoint. Utilice el code para ramificar su lógica, nunca solo el estado.
• Fije IDs exactos y manténgalos en una capa de configuración. TokenLab afirma que no reemplaza silenciosamente el modelo que usted envía.
• Un fallback debe ser una opción probada y preaprobada. Las capacidades, los formatos de solicitud, los límites y el precio difieren entre modelos.

Dónde aparece la deprecación y el versionado de modelos de IA en la API

La referencia de Get a Model (observada el 2026-10-03) indica que el campo lifecycle cubre la disponibilidad, la fecha de lanzamiento, la fecha de deprecación y el modelo de reemplazo. La referencia de List Models (observada el 2026-10-03) añade tokenlab.lifecycle, tokenlab.aliases, tokenlab.commercial y tokenlab.badges a cada elemento de la lista. La misma página enumera tokenlab.accepted_request_formats y los límites de tokens, los cuales son importantes para cualquier intercambio.

Esto es lo que leímos de la API de modelos en vivo para claude-sonnet-5 el 2026-10-03. Esta es una representación condensada de los valores observados. Nuestra evidencia registró los valores, no los nombres de las claves anidadas sin procesar, así que confirme las claves exactas contra una respuesta en vivo.

GET https://api.tokenlab.sh/v1/models/claude-sonnet-5
category:             chat
lifecycle stage:      active
released:             2026-06-30
replacement model:    None
deprecated_at:        None
retired_at:           None
max input tokens:     1000000
max output tokens:    128000
accepted formats:     anthropic_messages, openai_chat_completions

Mapee los cinco conceptos del ciclo de vida en esos campos de la siguiente manera:

Concepto	Campo en la respuesta observada	Valor para claude-sonnet-5
Etapa	lifecycle stage	active
Lanzamiento	released	2026-06-30
Deprecación	deprecated_at	None
Retiro	retired_at	None
Reemplazo	replacement model	None

Un valor vacío no siempre indica un problema. Para glm-5.2 y gpt-5.5, la API en vivo (observada el 2026-10-03) muestra released como None mientras que la etapa es active. Una verificación debería fallar si hay un deprecated_at establecido, un retired_at establecido o una etapa que no sea active. No debería fallar por una fecha de lanzamiento faltante.

También leímos deepseek-v4-pro y deepseek-v4-flash (ambos lanzados el 2026-04-24, ambos activos, sin reemplazo). Eso hace cinco modelos sin señal de deprecación. El campo de reemplazo de un modelo deprecado es el único valor que no pudimos observar poblado.

Un script que falla cuando una dependencia se corrompe

La verificación a continuación utiliza solo el endpoint documentado GET /v1/models/{model}, que no necesita una API key porque el catálogo es público. Falla ante un ID faltante, un deprecated_at o retired_at establecido, una etapa no activa o un formato de solicitud que el modelo ya no acepta.

#!/usr/bin/env python3
"""Fail when a model ID we depend on is missing, deprecated, or retired."""
import json
import sys
import urllib.error
import urllib.request

BASE = "https://api.tokenlab.sh/v1/models/"

# model ID -> the request format our code actually sends
DEPENDENCIES = {
    "gpt-5.5": "openai_chat_completions",
    "claude-sonnet-5": "anthropic_messages",
    "deepseek-v4-pro": "openai_chat_completions",
}

def fetch(model_id):
    req = urllib.request.Request(BASE + model_id, headers={"Accept": "application/json"})
    try:
        with urllib.request.urlopen(req, timeout=15) as resp:
            return resp.status, json.load(resp)
    except urllib.error.HTTPError as exc:
        try:
            body = json.load(exc)
        except ValueError:
            body = {}
        return exc.code, body

def check(model_id, fmt):
    try:
        status, body = fetch(model_id)
    except urllib.error.URLError as exc:
        return [f"could not verify: {exc.reason}"], {}, []
    if status in (400, 404):
        return [f"missing: HTTP {status}"], {}, []
    if status != 200:
        return [f"could not verify: HTTP {status}"], {}, []

    info = body.get("tokenlab", {})
    life = info.get("lifecycle") or {}
    problems = []
    if not life:
        problems.append("no lifecycle block returned")
    stage = life.get("stage")  # confirm the exact key against a live response
    if stage not in (None, "active"):
        problems.append(f"stage={stage}")
    for key in ("deprecated_at", "retired_at"):
        if life.get(key):
            problems.append(f"{key}={life[key]}")
    if fmt not in info.get("accepted_request_formats", []):
        problems.append(f"format {fmt} not accepted")
    return problems, life, info.get("aliases", [])

def main():
    failed = False
    for model_id, fmt in DEPENDENCIES.items():
        problems, life, aliases = check(model_id, fmt)
        if problems:
            failed = True
            print(f"FAIL {model_id}: {'; '.join(problems)}")
            if life:
                print(f"     lifecycle: {json.dumps(life)}")
        else:
            print(f"ok   {model_id} aliases={aliases}")
    sys.exit(1 if failed else 0)

if __name__ == "__main__":
    main()

Ejecútelo en CI y en un horario nocturno, porque un modelo puede cambiar de estado sin un commit de su parte. Imagine un trabajo nocturno que sale con error 1 un martes mientras que su último despliegue fue hace una semana. Ese es el punto: el fallo aparece en una pipeline, no en la ventana de chat de un cliente. El script imprime todo el bloque de ciclo de vida en caso de fallo para que un humano vea el valor de reemplazo sin tener que adivinar nombres de claves.

Qué devuelve un modelo retirado o desconocido

La evidencia documenta modelos desconocidos y no disponibles, no una respuesta etiquetada por separado como "retirada". Por lo tanto, tratamos el retiro como la misma familia de errores hasta que usted verifique lo contrario. Esto es lo que dicen los documentos, todo observado el 2026-10-03:

Dónde	Respuesta	Fuente
GET /v1/models/{model}	404 model_not_found	Get a Model
Solicitud de chat con un modelo mal escrito o no disponible	400 model_not_found, opcionalmente con did_you_mean, suggestions, hint	Errors agents can act on
La operación no tiene suministro en el nivel de entrega seleccionado	503 all_channels_failed o 503 delivery_tier_unavailable, retryable: false	Errors agents can act on
La clave carece de permiso para el modelo	403 model_not_allowed	Handle API errors

Los códigos de estado no coinciden entre endpoints, por lo que una corrección es importante: el código de fallback de nuestro artículo fuente trataba 404 y 410 como "identificador desaparecido". Eso es incorrecto para las solicitudes de chat. La respuesta de chat documentada es 400, y la guía de errores dice que se deben manejar los errores por estado HTTP y code. Base su lógica en code == "model_not_found".

Por ejemplo, los documentos muestran que un ID mal escrito devuelve did_you_mean: "gpt-5.6-terra". Su cliente debería reaccionar en este orden:

1. No repita la solicitud sin cambios. La guía de errores marca 400, 403 y 404 como no repetibles.
2. Trate did_you_mean como una sugerencia. Cambie solo si su producto ya tiene permiso para cambiar el modelo.
3. Si el cuerpo del 503 dice retryable: false, deje de reintentar. Los documentos dicen que nombres similares no prueban la disponibilidad.
4. Guarde el Request ID de los encabezados de respuesta junto con el modelo y su propio ID de trabajo.
5. Alerte a un humano. Un ID fijado que desapareció es un evento de lanzamiento, no un error transitorio.

Fije un ID exacto o siga un alias

La guía de mejores prácticas (observada el 2026-10-03) dice que se debe mantener el ID del modelo explícito en cada solicitud y no cambiar de modelo silenciosamente. Advierte que un reemplazo puede cambiar la calidad, el precio, la longitud del contexto, las herramientas o el soporte de medios. La guía de errores añade que TokenLab no reemplaza silenciosamente el modelo que usted envía.

Estrategia	Comportamiento	Riesgo principal
Fijar un ID exacto como gpt-5.5	Obtiene ese modelo, o un error	Un fallo grave si el ID es eliminado
Seguir un alias	El nombre puede apuntar a un lugar nuevo con el tiempo	El comportamiento y el costo pueden cambiar sin cambios en el código
Nombre de ruta interna en su configuración	Su código pide primary_chat; la configuración lo mapea a un ID exacto	Usted es dueño y prueba el mapeo

Sobre los alias, encontramos una brecha. La referencia de List Models dice que tokenlab.aliases existe en cada elemento. Ninguno de los cinco extractos en vivo que tenemos (claude-sonnet-5, deepseek-v4-pro, deepseek-v4-flash, glm-5.2, gpt-5.5) muestra un valor de alias. No podemos decirle qué alias tienen esos modelos hoy. El script anterior imprime aliases para cada dependencia, así que ejecútelo y lea la salida.

Dos hechos más del catálogo ayudan. El catálogo del 2026-10-02 enumera las versiones como IDs exactos separados, por ejemplo claude-sonnet-4-6, claude-sonnet-5 y claude-sonnet-5-5. Estar listados uno al lado del otro no hace que uno sea sucesor del otro. El valor replacement es el único lugar del que debería provenir esa relación. Un ID, grok-voice-latest, tiene "latest" en su nombre. No tenemos evidencia de qué sigue, así que verifique su página de modelo antes de confiar en él. Los IDs con prefijos estilo marketplace no son alias de TokenLab. La guía de migración dice que los IDs de TokenLab no llevan prefijo de proveedor de OpenRouter, y sugiere mantener su propio alias de LiteLLM separado del ID de TokenLab.

Un patrón de fallback para un modelo fijado que desaparece

Trate un fallback como un segundo modelo fijado que probó de antemano. Elija uno por sitio de llamada, registre qué modelo sirvió cada respuesta y verifíquelo con el mismo script nocturno. Compare los dos modelos antes de emparejarlos:

Modelo (API en vivo, observado 2026-10-03)	Entrada / salida por 1M de tokens	Máx tokens entrada / salida	Formatos de solicitud	Capacidades listadas
gpt-5.5	$1.50 / $9.00	1,000,000 / 128,000	openai_chat_completions, openai_responses	coding, json-mode, prompt-cache, reasoning, tool-use, vision
claude-sonnet-5	$0.90 / $4.50	1,000,000 / 128,000	anthropic_messages, openai_chat_completions	json-mode, prompt-cache, reasoning, tool-use, vision
deepseek-v4-pro	$0.66 / $1.98 fuera de pico; $1.32 / $3.96 pico	1,000,000 / 384,000	anthropic_messages, openai_chat_completions, openai_responses	json-mode, prompt-cache, tool-use

Los precios de los tres se actualizaron por última vez el 2026-10-02T16:53:30.068Z. Las diferencias importan. claude-sonnet-5 no acepta openai_responses, por lo que un llamador basado en Responses no puede recurrir a él. deepseek-v4-pro no enumera ni visión ni razonamiento, por lo que una solicitud que contenga imágenes fallará allí. Las ventanas pico de DeepSeek funcionan de 09:00 a 12:00 y de 14:00 a 18:00 hora de Pekín.

Aquí hay una estimación de costos con el cálculo mostrado. Suponga una carga diaria de 10M de tokens de entrada y 2M de salida, que es nuestro número ilustrativo, no una medición:

• gpt-5.5: 10 × $1.50 + 2 × $9.00 = $15 + $18 = $33 por día.
• claude-sonnet-5: 10 × $0.90 + 2 × $4.50 = $9 + $9 = $18 por día.
• deepseek-v4-pro fuera de pico: 10 × $0.66 + 2 × $1.98 = $6.60 + $3.96 = $10.56 por día.
• deepseek-v4-pro pico: 10 × $1.32 + 2 × $3.96 = $13.20 + $7.92 = $21.12 por día.

Estas son estimaciones, y la entrada en caché tiene un precio diferente. El código a continuación solo recurre a fallos que los reintentos no pueden solucionar. Un 429 o un 5xx reintentable deberían seguir las reglas normales de reintento.

import logging
import os

import openai

log = logging.getLogger("model-routing")

client = openai.OpenAI(
    api_key=os.environ["TOKENLAB_API_KEY"],
    base_url="https://api.tokenlab.sh/v1",
    timeout=30.0,
    max_retries=0,  # we decide what is safe to repeat
)

ROUTES = {
    "primary_chat": {"model": "gpt-5.5", "fallback": "claude-sonnet-5"},
    "coding_agent": {"model": "claude-sonnet-5", "fallback": "deepseek-v4-pro"},
}

def _error(exc):
    body = exc.body if isinstance(exc.body, dict) else {}
    err = body.get("error", body)
    return err if isinstance(err, dict) else {}

def _chat(model_id, text):
    resp = client.chat.completions.create(
        model=model_id,
        messages=[{"role": "user", "content": text}],
    )
    return resp.choices[0].message.content

def call_model(route, text):
    """Return (model_that_answered, text). Record the model with the result."""
    cfg = ROUTES[route]
    try:
        return cfg["model"], _chat(cfg["model"], text)
    except openai.APIStatusError as exc:
        err = _error(exc)
        code = err.get("code")
        gone = code == "model_not_found"
        no_supply = (
            code in ("all_channels_failed", "delivery_tier_unavailable")
            and err.get("retryable") is False
        )
        if not (gone or no_supply):
            raise  # 401/402/403/429 and the like need a different fix
        log.warning("pinned model %s unavailable (%s); using %s",
                    cfg["model"], code, cfg["fallback"])
        return cfg["fallback"], _chat(cfg["fallback"], text)

El fallback salta una vez y nunca se encadena. Si el fallback también falla, lance el error y avise a alguien. Una cadena silenciosa de sustituciones es el problema de deriva bajo otro nombre.

Lista de verificación de lanzamiento para la deprecación y versionado de modelos de IA

Ejecute esto antes de cambiar un ID de modelo en producción. Refleja la guía de mejores prácticas (observada el 2026-10-03) y añade las comprobaciones de ciclo de vida.

1. Enumere cada ID de modelo en producción y nombre el sitio de llamada que utiliza cada uno. Una capa de configuración debería responder esto en segundos.
2. Ejecute el script de ciclo de vida contra los IDs actuales y candidatos. Lea deprecated_at, retired_at, la etapa y el reemplazo.
3. Confirme que el candidato acepta el formato de solicitud que envía su código, utilizando accepted_request_formats de Get a Model.
4. Compare los tokens máximos de entrada y salida contra su solicitud real más larga y su límite de salida.
5. Compare capacidades. Confirme visión, uso de herramientas, modo json y razonamiento donde su producto dependa de ellos.
6. Recalcule el costo a partir de los precios actuales, con el cálculo mostrado. Para DeepSeek, divida pico y fuera de pico.
7. Reproduzca solicitudes representativas con el ID de candidato exacto y el formato que enviará. Incluya un caso de fallo, como un ID desconocido.
8. Verifique la ruta de error. Su cliente debería ramificarse en el code, mantener el Request ID y no reintentar 400, 403 o 404.
9. Envíe el cambio como una edición de configuración con el ID antiguo mantenido como el valor de reversión documentado.
10. Compruebe que cada registro de respuesta almacena el modelo que realmente lo sirvió.
11. Vuelva a ejecutar el script nocturno después del lanzamiento. Confirme que el ID de fallback también pase.

Donde los documentos guardan silencio, la lista de verificación es la salvaguarda. No dan tiempo de aviso de deprecación ni canal de notificación. Verifique los avisos del proveedor por separado y consulte la propia página del modelo para cualquier nota sobre el ciclo de vida.

Preguntas frecuentes

¿Cómo sé si un modelo de TokenLab está deprecado o retirado?

Llame a GET /v1/models/{model} y lea tokenlab.lifecycle. Verifique la etapa, deprecated_at, retired_at y el modelo de reemplazo. A fecha del 2026-10-03, los cinco modelos que leímos estaban todos active sin fechas establecidas. Vuelva a consultar, porque el valor refleja solo el momento en que preguntó.

¿Qué estado HTTP devuelve un ID de modelo desconocido?

Depende del endpoint. Get a Model devuelve 404 model_not_found, mientras que una solicitud de chat con un modelo incorrecto devuelve 400 model_not_found. Un modelo sin suministro en el nivel de entrega seleccionado devuelve un 503. Ramifique su lógica en el campo code.

¿Debo reintentar un error model_not_found?

No. Repetir la misma solicitud no cambiará el resultado. Verifique did_you_mean y suggestions si están presentes, pero cambie de modelo solo cuando su producto ya tenga permiso para hacerlo. De lo contrario, utilice un fallback preaprobado y alerte a su equipo.

¿TokenLab cambiará mi solicitud a otro modelo si el mío desaparece?

La documentación dice que no reemplaza silenciosamente el modelo que usted envía. Envíe un ID explícito y maneje el error usted mismo. Su fallback debería ser un valor de configuración probado, no una suposición sobre la plataforma.

Compare los IDs, límites y precios actuales en el directorio de modelos antes de su próximo cambio de modelo.