Depreciação e Versionamento de Modelos de IA: Mantenha as Integrações de API Estáveis

Uma string de modelo é a constante mais perigosa em sua base de código. As equipes a tratam como um rótulo, mas ela decide qual checkpoint responde, quanto a chamada custa e se a solicitação terá sucesso. Portanto, a depreciação e o versionamento de modelos de IA pertencem ao seu processo de lançamento, não a uma decisão única de implementação. Este guia utiliza a API pública de modelos da TokenLab, conforme observado em 03/10/2026, para mostrar o que você pode verificar automaticamente, o que deve verificar em outros lugares e o que fazer quando um ID para de funcionar.

Principais Conclusões

• Dados de ciclo de vida residem no objeto do modelo. Leia tokenlab.lifecycle a partir de Get a Model (observado em 03/10/2026) em vez de copiar datas de um post de blog.
• Todos os cinco modelos que verificamos em 03/10/2026 estavam active, sem data de depreciação ou aposentadoria. Nossa evidência não contém nenhum modelo realmente depreciado, portanto, o caminho de falha abaixo é um comportamento documentado, não algo que vimos acontecer.
• Um modelo ausente retorna model_not_found, mas o status difere conforme o endpoint. Faça a ramificação (branch) no code, nunca apenas no status.
• Fixe IDs exatos e mantenha-os em uma camada de configuração. A TokenLab afirma que não substitui silenciosamente o modelo que você envia.
• Um fallback deve ser uma escolha testada e pré-aprovada. Capacidades, formatos de solicitação, limites e preços diferem entre os modelos.

Onde a depreciação e o versionamento de modelos de IA aparecem na API

A referência Get a Model (observada em 03/10/2026) diz que o campo lifecycle cobre disponibilidade, data de lançamento, data de depreciação e modelo de substituição. A referência List Models (observada em 03/10/2026) adiciona tokenlab.lifecycle, tokenlab.aliases, tokenlab.commercial e tokenlab.badges a cada item da lista. A mesma página lista tokenlab.accepted_request_formats e os limites de token, que são importantes para qualquer troca.

Aqui está o que lemos da API de modelo ao vivo para o claude-sonnet-5 em 03/10/2026. Esta é uma renderização condensada dos valores observados. Nossa evidência registrou os valores, não os nomes das chaves aninhadas brutas, portanto, confirme as chaves exatas em relação a uma resposta ao 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

Mapeie os cinco conceitos de ciclo de vida nesses campos da seguinte forma:

Conceito	Campo na resposta observada	Valor para claude-sonnet-5
Estágio	lifecycle stage	active
Lançamento	released	2026-06-30
Depreciação	deprecated_at	None
Aposentadoria	retired_at	None
Substituição	replacement model	None

Um valor vazio nem sempre sinaliza um problema. Para glm-5.2 e gpt-5.5, a API ao vivo (observada em 03/10/2026) mostra released como None enquanto o estágio é active. Uma verificação deve falhar se houver um deprecated_at definido, um retired_at definido ou um estágio não ativo. Ela não deve falhar se a data de lançamento estiver ausente.

Também lemos deepseek-v4-pro e deepseek-v4-flash (ambos lançados em 24/04/2026, ambos ativos, sem substituição). Isso totaliza cinco modelos sem sinal de depreciação. O campo de substituição de um modelo depreciado é o único valor que não conseguimos observar preenchido.

Um script que falha quando uma dependência apresenta problemas

A verificação abaixo usa apenas o endpoint documentado GET /v1/models/{model}, que não precisa de chave de API porque o catálogo é público. Ela falha em caso de ID ausente, deprecated_at ou retired_at definidos, estágio não ativo ou um formato de solicitação que o modelo não aceita mais.

#!/usr/bin/env python3
"""Falha quando um ID de modelo do qual dependemos está ausente, depreciado ou aposentado."""
import json
import sys
import urllib.error
import urllib.request

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

# ID do modelo -> o formato de solicitação que nosso código realmente envia
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"não foi possível verificar: {exc.reason}"], {}, []
    if status in (400, 404):
        return [f"ausente: HTTP {status}"], {}, []
    if status != 200:
        return [f"não foi possível verificar: HTTP {status}"], {}, []

    info = body.get("tokenlab", {})
    life = info.get("lifecycle") or {}
    problems = []
    if not life:
        problems.append("nenhum bloco de ciclo de vida retornado")
    stage = life.get("stage")  # confirme a chave exata em relação a uma resposta ao vivo
    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"formato {fmt} não aceito")
    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()

Execute-o em CI e em um cronograma noturno, porque um modelo pode mudar de estado sem um commit do seu lado. Imagine um trabalho noturno que retorna 1 em uma terça-feira, enquanto seu último deploy foi há uma semana. Esse é o ponto: a falha aparece em um pipeline, não na janela de chat de um cliente. O script imprime todo o bloco de ciclo de vida em caso de falha para que um humano veja o valor de substituição sem adivinhar nomes de chaves.

O que um modelo aposentado ou desconhecido retorna

As evidências documentam modelos desconhecidos e indisponíveis, não uma resposta separadamente rotulada como "aposentada". Portanto, tratamos a aposentadoria como a mesma família de erros até que você verifique o contrário. Aqui está o que a documentação diz, tudo observado em 03/10/2026:

Onde	Resposta	Fonte
GET /v1/models/{model}	404 model_not_found	Get a Model
Solicitação de chat com um modelo incorreto ou indisponível	400 model_not_found, opcionalmente com did_you_mean, suggestions, hint	Erros nos quais agentes podem agir
A operação não tem oferta no nível de entrega selecionado	503 all_channels_failed ou 503 delivery_tier_unavailable, retryable: false	Erros nos quais agentes podem agir
A chave não tem permissão para o modelo	403 model_not_allowed	Lidar com erros de API

Os códigos de status divergem entre os endpoints, portanto, uma correção é importante: o código de fallback do nosso artigo de origem tratava 404 e 410 como "identificador removido". Isso está incorreto para solicitações de chat. A resposta de chat documentada é 400, e o guia de erros diz para lidar com erros por status HTTP e code. Baseie sua lógica em code == "model_not_found".

Por exemplo, a documentação mostra um ID com erro de digitação retornando did_you_mean: "gpt-5.6-terra". Seu cliente deve reagir nesta ordem:

1. Não repita a solicitação inalterada. O guia de erros marca 400, 403 e 404 como não repetíveis.
2. Trate did_you_mean como uma sugestão. Mude apenas se o seu produto já tiver permissão para alterar o modelo.
3. Se o corpo do 503 disser retryable: false, pare de tentar novamente. A documentação diz que nomes semelhantes não provam disponibilidade.
4. Salve o ID da solicitação dos cabeçalhos de resposta com o modelo e seu próprio ID de trabalho.
5. Alerte um humano. Um ID fixo que desapareceu é um evento de lançamento, não um erro transitório.

Fixe um ID exato ou siga um alias

O guia de melhores práticas (observado em 03/10/2026) diz para manter o ID do modelo explícito em cada solicitação e não trocar de modelo silenciosamente. Ele avisa que uma substituição pode alterar qualidade, preço, tamanho de contexto, ferramentas ou suporte de mídia. O guia de erros acrescenta que a TokenLab não substitui silenciosamente o modelo que você envia.

Estratégia	Comportamento	Risco principal
Fixar um ID exato, como gpt-5.5	Você obtém aquele modelo ou um erro	Uma falha grave se o ID for removido
Seguir um alias	O nome pode apontar para um novo local ao longo do tempo	Comportamento e custo podem mudar sem alteração de código
Nome de rota interna em sua configuração	Seu código solicita primary_chat; a configuração mapeia para um ID exato	Você possui e testa o mapeamento

Sobre aliases, encontramos uma lacuna. A referência List Models diz que tokenlab.aliases existe em cada item. Nenhum dos cinco trechos ao vivo que temos (claude-sonnet-5, deepseek-v4-pro, deepseek-v4-flash, glm-5.2, gpt-5.5) mostra um valor de alias. Não podemos dizer quais aliases esses modelos têm hoje. O script acima imprime aliases para cada dependência, então execute-o e leia a saída.

Mais dois fatos do catálogo ajudam. O catálogo de 02/10/2026 lista versões como IDs exatos separados, por exemplo, claude-sonnet-4-6, claude-sonnet-5 e claude-sonnet-5-5. Ser listado lado a lado não torna um o sucessor do outro. O valor replacement é o único lugar de onde esse relacionamento deve vir. Um ID, grok-voice-latest, tem "latest" em seu nome. Não temos evidências sobre o que ele segue, então verifique sua página de modelo antes de confiar nele. IDs prefixados estilo marketplace não são aliases da TokenLab. O guia de migração diz que os IDs da TokenLab não carregam prefixo de provedor OpenRouter, e sugere manter seu próprio alias LiteLLM separado do ID da TokenLab.

Um padrão de fallback para um modelo fixo que desaparece

Trate um fallback como um segundo modelo fixo que você testou com antecedência. Escolha-o por local de chamada, registre qual modelo atendeu a cada resposta e verifique-o com o mesmo script noturno. Compare os dois modelos antes de emparelhá-los:

Modelo (API ao vivo, observado em 03/10/2026)	Entrada / saída por 1M de tokens	Máx. tokens de entrada / saída	Formatos de solicitação	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 fora 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

Os preços para todos os três foram atualizados pela última vez em 02/10/2026T16:53:30.068Z. As diferenças importam. O claude-sonnet-5 não aceita openai_responses, portanto, um chamador baseado em Responses não pode recorrer a ele. O deepseek-v4-pro não lista visão nem raciocínio, então uma solicitação com imagem falha lá. As janelas de pico do DeepSeek ocorrem das 09:00 às 12:00 e das 14:00 às 18:00, horário de Pequim.

Aqui está uma estimativa de custo com o cálculo demonstrado. Suponha uma carga diária de 10M de tokens de entrada e 2M de saída, que é nosso número ilustrativo, não uma medição:

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

Estas são estimativas, e a entrada em cache é precificada de forma diferente. O código abaixo recorre apenas a erros que tentar novamente não pode corrigir. Um 429 ou um 5xx repetível deve seguir as regras normais de repetição.

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,  # nós decidimos o que é seguro repetir
)

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):
    """Retorna (modelo_que_respondeu, texto). Registre o modelo com o resultado."""
    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 e similares precisam de uma correção diferente
        log.warning("modelo fixo %s indisponível (%s); usando %s",
                    cfg["model"], code, cfg["fallback"])
        return cfg["fallback"], _chat(cfg["fallback"], text)

O fallback salta uma vez e nunca encadeia. Se o fallback também falhar, gere o erro e chame alguém. Uma cadeia silenciosa de substituições é o problema de deriva sob outro nome.

Checklist de lançamento para depreciação e versionamento de modelos de IA

Execute isto antes de alterar um ID de modelo de produção. Ele espelha o guia de melhores práticas (observado em 03/10/2026) e adiciona as verificações de ciclo de vida.

1. Liste cada ID de modelo em produção e nomeie o local de chamada que usa cada um. Uma camada de configuração deve responder a isso em segundos.
2. Execute o script de ciclo de vida nos IDs atuais e candidatos. Leia deprecated_at, retired_at, estágio e substituição.
3. Confirme se o candidato aceita o formato de solicitação que seu código envia, usando accepted_request_formats de Get a Model.
4. Compare os tokens máximos de entrada e saída com sua solicitação real mais longa e seu limite de saída.
5. Compare capacidades. Confirme visão, uso de ferramentas, modo json e raciocínio onde seu produto depende deles.
6. Recalcule o custo a partir dos preços atuais, com o cálculo demonstrado. Para o DeepSeek, separe pico e fora de pico.
7. Reexecute solicitações representativas com o ID de candidato exato e o formato que você enviará. Inclua um caso de falha, como um ID desconhecido.
8. Verifique o caminho de erro. Seu cliente deve ramificar no code, manter o ID da solicitação e não repetir 400, 403 ou 404.
9. Envie a alteração como uma edição de configuração com o ID antigo mantido como o valor de reversão documentado.
10. Verifique se cada registro de resposta armazena o modelo que realmente o atendeu.
11. Reexecute o script noturno após o lançamento. Confirme se o ID de fallback também passa.

Onde a documentação é silenciosa, o checklist é a salvaguarda. Eles não dão tempo de aviso de depreciação e nenhum canal de notificação. Verifique os avisos do provedor separadamente e verifique a própria página do modelo para quaisquer notas de ciclo de vida.

FAQ

Como saber se um modelo da TokenLab está depreciado ou aposentado?

Chame GET /v1/models/{model} e leia tokenlab.lifecycle. Verifique o estágio, deprecated_at, retired_at e o modelo de substituição. Em 03/10/2026, os cinco modelos que lemos estavam todos active sem datas definidas. Pesquise novamente, porque o valor reflete apenas o momento em que você perguntou.

Qual status HTTP um ID de modelo desconhecido retorna?

Depende do endpoint. Get a Model retorna 404 model_not_found, enquanto uma solicitação de chat com um modelo ruim retorna 400 model_not_found. Um modelo sem oferta no nível de entrega selecionado retorna um 503. Ramifique no campo code.

Devo tentar novamente um erro model_not_found?

Não. Repetir a mesma solicitação não mudará o resultado. Verifique did_you_mean e suggestions se presentes, mas mude de modelo apenas quando seu produto já tiver permissão para isso. Caso contrário, use um fallback pré-aprovado e alerte sua equipe.

A TokenLab mudará minha solicitação para outro modelo se o meu desaparecer?

A documentação diz que ela não substitui silenciosamente o modelo que você envia. Envie um ID explícito e lide com o erro você mesmo. Seu fallback deve ser um valor de configuração testado, não uma suposição sobre a plataforma.

Compare IDs, limites e preços atuais no diretório de modelos antes da sua próxima alteração de modelo.