KI-Modell-Deprecation und Versionierung: Halten Sie API-Integrationen stabil

Ein Modell-String ist die gefährlichste Konstante in Ihrer Codebasis. Teams behandeln ihn wie ein Label, doch er entscheidet darüber, welcher Checkpoint antwortet, was der Aufruf kostet und ob die Anfrage überhaupt erfolgreich ist. AI-Modell-Deprecation und Versionierung gehören daher in Ihren Release-Prozess und nicht in eine einmalige Entscheidung beim Launch. Dieser Leitfaden verwendet die öffentliche Modell-API von TokenLab, wie sie am 03.10.2026 beobachtet wurde, um aufzuzeigen, was Sie automatisch prüfen können, was Sie an anderer Stelle verifizieren müssen und was zu tun ist, wenn eine ID nicht mehr funktioniert.

Wichtige Erkenntnisse

• Lebenszyklusdaten befinden sich auf dem Modell-Objekt. Lesen Sie tokenlab.lifecycle über Get a Model (beobachtet am 03.10.2026), anstatt Daten aus einem Blog-Beitrag zu kopieren.
• Alle fünf Modelle, die wir am 03.10.2026 geprüft haben, waren active und hatten kein Deprecation- oder Retirement-Datum. Unsere Daten enthalten kein tatsächlich deprecates Modell; der unten beschriebene Fehlerpfad ist daher dokumentiertes Verhalten und kein beobachteter Vorfall.
• Ein fehlendes Modell gibt model_not_found zurück, aber der Status unterscheidet sich je nach Endpunkt. Verzweigen Sie basierend auf dem code, niemals nur auf dem Status.
• Pinnen Sie exakte IDs und bewahren Sie diese in einer Konfigurationsschicht auf. TokenLab gibt an, dass es das von Ihnen gesendete Modell nicht stillschweigend ersetzt.
• Ein Fallback muss eine getestete, vorab genehmigte Wahl sein. Fähigkeiten, Anfrageformate, Limits und Preise unterscheiden sich zwischen den Modellen.

Wo AI-Modell-Deprecation und Versionierung in der API auftauchen

Die Referenz zu Get a Model (beobachtet am 03.10.2026) besagt, dass das Feld lifecycle Verfügbarkeit, Veröffentlichungsdatum, Deprecation-Datum und das Ersatzmodell abdeckt. Die Referenz zu List Models (beobachtet am 03.10.2026) fügt jedem Listeneintrag tokenlab.lifecycle, tokenlab.aliases, tokenlab.commercial und tokenlab.badges hinzu. Dieselbe Seite listet tokenlab.accepted_request_formats und die Token-Limits auf, die für jeden Austausch wichtig sind.

Hier ist das, was wir am 03.10.2026 aus der Live-Modell-API für claude-sonnet-5 gelesen haben. Dies ist eine komprimierte Darstellung der beobachteten Werte. Unsere Daten haben die Werte aufgezeichnet, nicht die rohen verschachtelten Schlüsselnamen; bestätigen Sie daher die exakten Schlüssel anhand einer Live-Antwort.

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

Ordnen Sie die fünf Lebenszykluskonzepte wie folgt diesen Feldern zu:

Konzept	Feld in der beobachteten Antwort	Wert für claude-sonnet-5
Phase	lifecycle stage	active
Veröffentlichung	released	2026-06-30
Deprecation	deprecated_at	None
Ruhestand	retired_at	None
Ersatz	replacement model	None

Ein leerer Wert signalisiert nicht immer ein Problem. Für glm-5.2 und gpt-5.5 zeigt die Live-API (beobachtet am 03.10.2026) released als None an, während die Phase active ist. Eine Prüfung sollte fehlschlagen, wenn deprecated_at gesetzt ist, retired_at gesetzt ist oder die Phase nicht active ist. Sie sollte nicht bei einem fehlenden Veröffentlichungsdatum fehlschlagen.

Wir haben auch deepseek-v4-pro und deepseek-v4-flash gelesen (beide veröffentlicht am 24.04.2026, beide aktiv, kein Ersatz). Das ergibt fünf Modelle ohne Deprecation-Signal. Das Ersatzfeld eines deprecaten Modells ist der einzige Wert, dessen Besetzung wir nicht beobachten konnten.

Ein Skript, das fehlschlägt, wenn eine Abhängigkeit problematisch wird

Die untenstehende Prüfung verwendet nur den dokumentierten GET /v1/models/{model}-Endpunkt, der keinen API-Key benötigt, da der Katalog öffentlich ist. Sie schlägt bei einer fehlenden ID, einem gesetzten deprecated_at oder retired_at, einer nicht-aktiven Phase oder einem Anfrageformat, das das Modell nicht mehr akzeptiert, fehl.

#!/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()

Führen Sie es in CI und nach einem nächtlichen Zeitplan aus, da ein Modell seinen Status ändern kann, ohne dass Sie einen Commit durchführen. Stellen Sie sich einen nächtlichen Job vor, der an einem Dienstag mit Exit-Code 1 abbricht, während Ihr letztes Deployment eine Woche her ist. Genau das ist der Punkt: Der Fehler erscheint in einer Pipeline, nicht im Chat-Fenster eines Kunden. Das Skript gibt bei einem Fehler den gesamten Lebenszyklus-Block aus, sodass ein Mensch den Ersatzwert sieht, ohne Schlüsselnamen erraten zu müssen.

Was ein retired oder unbekanntes Modell zurückgibt

Die Beweise dokumentieren unbekannte und nicht verfügbare Modelle, keine separat als "retired" gekennzeichnete Antwort. Wir behandeln den Ruhestand daher als dieselbe Fehlerfamilie, bis Sie das Gegenteil verifiziert haben. Hier ist, was die Dokumentation sagt, alles beobachtet am 03.10.2026:

Wo	Antwort	Quelle
GET /v1/models/{model}	404 model_not_found	Get a Model
Chat-Anfrage mit einem falsch geschriebenen oder nicht verfügbaren Modell	400 model_not_found, optional mit did_you_mean, suggestions, hint	Errors agents can act on
Operation hat kein Angebot im gewählten Delivery-Tier	503 all_channels_failed oder 503 delivery_tier_unavailable, retryable: false	Errors agents can act on
Key hat keine Berechtigung für das Modell	403 model_not_allowed	Handle API errors

Die Statuscodes unterscheiden sich je nach Endpunkt, daher ist eine Korrektur wichtig: Der Fallback-Code unseres Quellartikels behandelte 404 und 410 als "Bezeichner weg". Das ist bei Chat-Anfragen falsch. Die dokumentierte Chat-Antwort ist 400, und der Fehlerleitfaden besagt, dass Fehler anhand des HTTP-Status und des code behandelt werden sollen. Richten Sie Ihre Logik nach code == "model_not_found" aus.

Zum Beispiel zeigen die Dokumente eine falsch geschriebene ID, die did_you_mean: "gpt-5.6-terra" zurückgibt. Ihr Client sollte in dieser Reihenfolge reagieren:

1. Wiederholen Sie die Anfrage nicht unverändert. Der Fehlerleitfaden markiert 400, 403 und 404 als nicht wiederholbar.
2. Behandeln Sie did_you_mean als Vorschlag. Wechseln Sie nur, wenn Ihr Produkt bereits die Berechtigung hat, das Modell zu ändern.
3. Wenn der 503-Body retryable: false sagt, hören Sie auf, es erneut zu versuchen. Die Dokumente besagen, dass ähnliche Namen keine Verfügbarkeit beweisen.
4. Speichern Sie die Request-ID aus den Antwort-Headern zusammen mit dem Modell und Ihrer eigenen Job-ID.
5. Alarmieren Sie einen Menschen. Eine gepinnte ID, die verschwunden ist, ist ein Release-Ereignis, kein vorübergehender Fehler.

Eine exakte ID pinnen oder einem Alias folgen

Der Best-Practices-Leitfaden (beobachtet am 03.10.2026) besagt, dass die Modell-ID in jeder Anfrage explizit gehalten werden sollte und Modelle nicht stillschweigend gewechselt werden sollten. Er warnt davor, dass ein Ersatz die Qualität, den Preis, die Kontextlänge, Tools oder Medienunterstützung ändern kann. Der Fehlerleitfaden ergänzt, dass TokenLab das von Ihnen gesendete Modell nicht stillschweigend ersetzt.

Strategie	Verhalten	Hauptrisiko
Pinnen einer exakten ID wie gpt-5.5	Sie erhalten dieses Modell oder einen Fehler	Ein harter Fehler, wenn die ID entfernt wird
Einem Alias folgen	Der Name kann im Laufe der Zeit auf etwas Neues zeigen	Verhalten und Kosten können sich ohne Code-Änderung ändern
Interner Routenname in Ihrer Konfiguration	Ihr Code fragt nach primary_chat; die Konfiguration ordnet dies einer exakten ID zu	Sie besitzen und testen die Zuordnung

Bei Aliasen haben wir eine Lücke gefunden. Die Referenz zu List Models besagt, dass tokenlab.aliases auf jedem Element existiert. Keiner der fünf Live-Auszüge, die wir haben (claude-sonnet-5, deepseek-v4-pro, deepseek-v4-flash, glm-5.2, gpt-5.5), zeigt einen Alias-Wert. Wir können Ihnen nicht sagen, welche Aliase diese Modelle heute haben. Das obige Skript gibt aliases für jede Abhängigkeit aus, also führen Sie es aus und lesen Sie die Ausgabe.

Zwei weitere Katalogfakten helfen. Der Katalog vom 02.10.2026 listet Versionen als separate exakte IDs auf, zum Beispiel claude-sonnet-4-6, claude-sonnet-5 und claude-sonnet-5-5. Dass sie nebeneinander gelistet sind, macht das eine nicht zum Nachfolger. Der replacement-Wert ist der einzige Ort, von dem diese Beziehung stammen sollte. Eine ID, grok-voice-latest, hat "latest" im Namen. Wir haben keine Beweise dafür, worauf sie folgt, also prüfen Sie ihre Modellseite, bevor Sie ihr vertrauen. Präfix-IDs im Marktplatz-Stil sind keine TokenLab-Aliase. Der Migrationsleitfaden besagt, dass TokenLab-IDs kein OpenRouter-Provider-Präfix tragen, und schlägt vor, Ihren eigenen LiteLLM-Alias separat von der TokenLab-ID zu halten.

Ein Fallback-Muster für ein gepinntes Modell, das verschwindet

Behandeln Sie ein Fallback als ein zweites gepinntes Modell, das Sie im Voraus getestet haben. Wählen Sie es pro Aufrufstelle aus, zeichnen Sie auf, welches Modell jede Antwort geliefert hat, und verifizieren Sie es mit demselben nächtlichen Skript. Vergleichen Sie die beiden Modelle, bevor Sie sie koppeln:

Modell (Live-API, beobachtet am 03.10.2026)	Input / Output pro 1M Token	Max Input / Output Token	Anfrageformate	Gelistete Fähigkeiten
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 außerhalb der Spitzenzeiten; $1.32 / $3.96 Spitzenzeiten	1.000.000 / 384.000	anthropic_messages, openai_chat_completions, openai_responses	json-mode, prompt-cache, tool-use

Die Preisgestaltung für alle drei wurde zuletzt am 02.10.2026 um 16:53:30.068Z aktualisiert. Die Unterschiede sind wichtig. claude-sonnet-5 akzeptiert kein openai_responses, daher kann ein auf Responses basierender Aufrufer nicht darauf zurückgreifen. deepseek-v4-pro listet weder Vision noch Reasoning auf, daher bricht eine bildbasierte Anfrage dort ab. DeepSeeks Spitzenzeiten laufen von 09:00-12:00 und 14:00-18:00 Uhr Pekinger Zeit.

Hier ist eine Kostenschätzung mit der gezeigten Berechnung. Nehmen wir eine tägliche Last von 10M Input- und 2M Output-Token an, was unsere illustrative Zahl ist, keine Messung:

• gpt-5.5: 10 × $1.50 + 2 × $9.00 = $15 + $18 = $33 pro Tag.
• claude-sonnet-5: 10 × $0.90 + 2 × $4.50 = $9 + $9 = $18 pro Tag.
• deepseek-v4-pro außerhalb der Spitzenzeiten: 10 × $0.66 + 2 × $1.98 = $6.60 + $3.96 = $10.56 pro Tag.
• deepseek-v4-pro Spitzenzeiten: 10 × $1.32 + 2 × $3.96 = $13.20 + $7.92 = $21.12 pro Tag.

Dies sind Schätzungen, und gecachter Input wird anders bepreist. Der Code unten greift nur bei Fehlern zurück, die durch erneute Versuche nicht behoben werden können. Ein 429 oder ein wiederholbarer 5xx sollte den normalen Wiederholungsregeln folgen.

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)

Das Fallback springt einmal und verkettet nie. Wenn das Fallback ebenfalls fehlschlägt, lösen Sie den Fehler aus und benachrichtigen Sie jemanden. Eine stille Kette von Ersetzungen ist das Drift-Problem unter einem anderen Namen.

Release-Checkliste für AI-Modell-Deprecation und Versionierung

Führen Sie dies aus, bevor Sie eine Produktions-Modell-ID ändern. Es spiegelt den Best-Practices-Leitfaden (beobachtet am 03.10.2026) wider und fügt die Lebenszyklusprüfungen hinzu.

1. Listen Sie jede Modell-ID in der Produktion auf und benennen Sie die Aufrufstelle, die jede einzelne verwendet. Eine Konfigurationsschicht sollte dies in Sekunden beantworten.
2. Führen Sie das Lebenszyklus-Skript gegen die aktuellen und die Kandidaten-IDs aus. Lesen Sie deprecated_at, retired_at, Phase und Ersatz.
3. Bestätigen Sie, dass der Kandidat das Anfrageformat akzeptiert, das Ihr Code sendet, unter Verwendung von accepted_request_formats aus Get a Model.
4. Vergleichen Sie die maximalen Input- und Output-Token mit Ihrer längsten realen Anfrage und Ihrem Output-Cap.
5. Vergleichen Sie die Fähigkeiten. Bestätigen Sie Vision, Tool-Use, JSON-Mode und Reasoning, wo Ihr Produkt davon abhängt.
6. Berechnen Sie die Kosten anhand der aktuellen Preise neu, mit der gezeigten Berechnung. Teilen Sie bei DeepSeek Spitzenzeiten und außerhalb der Spitzenzeiten auf.
7. Wiederholen Sie repräsentative Anfragen mit der exakten Kandidaten-ID und dem Format, das Sie ausliefern werden. Fügen Sie einen Fehlerfall hinzu, wie z. B. eine unbekannte ID.
8. Verifizieren Sie den Fehlerpfad. Ihr Client sollte nach code verzweigen, die Request-ID behalten und 400, 403 oder 404 nicht wiederholen.
9. Liefern Sie die Änderung als Konfigurationsänderung aus, wobei die alte ID als dokumentierter Rollback-Wert beibehalten wird.
10. Prüfen Sie, ob jeder Antwortdatensatz das Modell speichert, das ihn tatsächlich bedient hat.
11. Führen Sie das nächtliche Skript nach dem Release erneut aus. Bestätigen Sie, dass auch die Fallback-ID besteht.

Wo die Dokumentation schweigt, ist die Checkliste die Absicherung. Sie geben keine Vorlaufzeit für Deprecation und keinen Benachrichtigungskanal. Verifizieren Sie Anbieterhinweise separat und prüfen Sie die Seite des Modells auf Lebenszyklus-Hinweise.

FAQ

Wie erkenne ich, ob ein TokenLab-Modell deprecated oder retired ist?

Rufen Sie GET /v1/models/{model} auf und lesen Sie tokenlab.lifecycle. Prüfen Sie die Phase, deprecated_at, retired_at und das Ersatzmodell. Stand 03.10.2026 waren alle fünf Modelle, die wir gelesen haben, active und hatten keine gesetzten Daten. Pollen Sie erneut, da der Wert nur den Moment widerspiegelt, in dem Sie gefragt haben.

Welchen HTTP-Status gibt eine unbekannte Modell-ID zurück?

Es hängt vom Endpunkt ab. Get a Model gibt 404 model_not_found zurück, während eine Chat-Anfrage mit einem schlechten Modell 400 model_not_found zurückgibt. Ein Modell ohne Angebot im gewählten Delivery-Tier gibt einen 503 zurück. Verzweigen Sie nach dem code-Feld.

Sollte ich einen model_not_found-Fehler wiederholen?

Nein. Das Wiederholen derselben Anfrage wird das Ergebnis nicht ändern. Prüfen Sie did_you_mean und suggestions, falls vorhanden, aber wechseln Sie das Modell nur, wenn Ihr Produkt bereits die Berechtigung dazu hat. Verwenden Sie andernfalls ein vorab genehmigtes Fallback und alarmieren Sie Ihr Team.

Wird TokenLab meine Anfrage auf ein anderes Modell umstellen, wenn meins verschwindet?

Die Dokumentation besagt, dass es das von Ihnen gesendete Modell nicht stillschweigend ersetzt. Senden Sie eine explizite ID und behandeln Sie den Fehler selbst. Ihr Fallback sollte ein getesteter Konfigurationswert sein, keine Annahme über die Plattform.

Vergleichen Sie aktuelle IDs, Limits und Preise im Modellverzeichnis vor Ihrer nächsten Modelländerung.