AIモデルの非推奨化とバージョニング：API統合を安定させる方法

モデル文字列は、コードベースの中で最も危険な定数です。チームはそれを単なるラベルとして扱いがちですが、実際にはどのチェックポイントが回答するか、呼び出しにいくらかかるか、そしてリクエストが成功するかどうかさえも決定します。したがって、AIモデルの非推奨化とバージョニングは、一度限りのローンチ時の決定事項ではなく、リリースプロセスに組み込むべきものです。本ガイドでは、2026年10月3日時点で確認されたTokenLabのパブリックモデルAPIを使用し、自動的にチェックできる項目、別途検証が必要な項目、およびIDが機能しなくなった場合の対処法について解説します。

重要なポイント

• ライフサイクルデータはモデルオブジェクト内に存在します。ブログ記事から日付をコピーするのではなく、Get a Model（2026年10月3日時点）から tokenlab.lifecycle を読み取ってください。
• 2026年10月3日にチェックした5つのモデルはすべて active であり、非推奨化や廃止の日付は設定されていませんでした。私たちの調査結果には実際に非推奨となったモデルは含まれていないため、以下の失敗時の動作は文書化された仕様に基づくものであり、実際に発生した事象ではありません。
• 存在しないモデルを呼び出すと model_not_found が返されますが、ステータスはエンドポイントによって異なります。ステータス単体ではなく、必ず code で分岐処理を行ってください。
• 正確なIDを固定し、単一の設定レイヤーで管理してください。TokenLabは、送信されたモデルを自動的に置き換えることはないと明言しています。
• フォールバックは、テスト済みで承認済みの選択肢である必要があります。モデルによって機能、リクエスト形式、制限、価格がすべて異なるためです。

APIにおけるAIモデルの非推奨化とバージョニングの確認箇所

Get a Modelのリファレンス（2026年10月3日時点）によると、lifecycle フィールドには可用性、リリース日、非推奨日、代替モデルが含まれています。List Modelsのリファレンス（2026年10月3日時点）では、各リスト項目に tokenlab.lifecycle、tokenlab.aliases、 tokenlab.commercial、tokenlab.badges が追加されています。同ページには tokenlab.accepted_request_formats とトークン制限も記載されており、これらはモデルを切り替える際に重要となります。

以下は、2026年10月3日時点のclaude-sonnet-5のライブモデルAPIから読み取った内容です。これは観測された値を簡略化したものです。私たちの記録には生のネストされたキー名ではなく値が記録されているため、正確なキーについては実際のレスポンスで確認してください。

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

5つのライフサイクル概念をこれらのフィールドにマッピングすると以下のようになります：

概念	観測されたレスポンスのフィールド	claude-sonnet-5 の値
ステージ	lifecycle stage	active
リリース	released	2026-06-30
非推奨	deprecated_at	None
廃止	retired_at	None
代替	replacement model	None

値が空であることが常に問題を示すわけではありません。glm-5.2 および gpt-5.5 の場合、ライブAPI（2026年10月3日時点）ではステージが active であるにもかかわらず released が None となっています。チェック処理は、deprecated_at が設定されている場合、retired_at が設定されている場合、またはステージが active でない場合に失敗させるべきです。リリース日が欠落しているだけで失敗させるべきではありません。

また、deepseek-v4-pro と deepseek-v4-flash（両者とも2026年4月24日リリース、active、代替なし）も読み取りました。これで非推奨のシグナルがないモデルが5つ確認できました。非推奨モデルの代替フィールドは、今回観測できなかった唯一の値です。

依存関係に問題が発生した際に失敗するスクリプト

以下のチェック処理では、カタログが公開されているためAPIキーを必要としない、文書化された GET /v1/models/{model} エンドポイントのみを使用しています。IDの欠落、deprecated_at または retired_at の設定、非アクティブなステージ、またはモデルが受け付けなくなったリクエスト形式に対して失敗を返します。

#!/usr/bin/env python3
"""依存しているモデルIDが欠落、非推奨、または廃止された場合に失敗させる"""
import json
import sys
import urllib.error
import urllib.request

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

# model ID -> コードが実際に送信するリクエスト形式
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")  # 実際のレスポンスで正確なキーを確認すること
    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()

モデルはあなたの側のコミットなしに状態が変化する可能性があるため、CIや夜間スケジュールでこのスクリプトを実行してください。前回のデプロイから1週間経った火曜日に、夜間ジョブが終了コード1で失敗する様子を想像してください。これこそが重要であり、障害は顧客のチャット画面ではなく、パイプラインで検知されるべきです。このスクリプトは失敗時にライフサイクルブロック全体を出力するため、人間がキー名を推測することなく代替値を確認できます。

廃止されたモデルや不明なモデルが返すもの

エビデンスには「廃止」と個別にラベル付けされたレスポンスではなく、不明なモデルや利用不可能なモデルが記録されています。そのため、別途確認できるまでは、廃止を同じエラーファミリーとして扱います。以下は2026年10月3日時点で確認されたドキュメントの内容です：

場所	レスポンス	ソース
GET /v1/models/{model}	404 model_not_found	Get a Model
スペルミスまたは利用不可モデルでのチャットリクエスト	400 model_not_found（オプションで did_you_mean、suggestions、hint を含む）	エージェントが対処可能なエラー
選択した配信ティアに供給がない場合	503 all_channels_failed または 503 delivery_tier_unavailable、retryable: false	エージェントが対処可能なエラー
キーにモデルへの権限がない場合	403 model_not_allowed	APIエラーの処理

ステータスコードはエンドポイント間で一致しないため、1つの修正が重要です。ソース記事のフォールバックコードは 404 と 410 を「識別子が消滅した」と扱っていましたが、チャットリクエストではこれは誤りです。文書化されたチャットレスポンスは 400 であり、エラーガイドではHTTPステータスと code でエラーを処理するように指示されています。ロジックのキーを code == "model_not_found" に設定してください。

例えば、ドキュメントではスペルミスのあるIDが did_you_mean: "gpt-5.6-terra" を返す例が示されています。クライアントは以下の順序で反応する必要があります：

1. リクエストをそのまま繰り返さないこと。エラーガイドでは 400、403、404 を再試行不可とマークしています。
2. did_you_mean を提案として扱うこと。製品側でモデルを変更する権限が既にある場合のみ切り替えてください。
3. 503のボディに retryable: false とある場合は、再試行を停止すること。ドキュメントによると、名前が似ていることは可用性を証明するものではありません。
4. レスポンスヘッダーからリクエストIDをモデルおよび自身のジョブIDとともに保存すること。
5. 人間にアラートを送ること。固定したIDが消滅することは一時的なエラーではなく、リリースイベントです。

正確なIDを固定するか、エイリアスに従うか

ベストプラクティスガイド（2026年10月3日時点）では、各リクエストでモデルIDを明示し、モデルを自動的に切り替えないように推奨しています。代替モデルによって品質、価格、コンテキスト長、ツール、メディアサポートが変化する可能性があると警告しています。エラーガイドは、TokenLabは送信されたモデルを自動的に置き換えないと付け加えています。

戦略	動作	主なリスク
gpt-5.5 のような正確なIDを固定	そのモデルが取得されるか、エラーになる	IDが削除された場合のハード障害
エイリアスに従う	名前が時間の経過とともに新しい場所を指す可能性がある	コード変更なしで動作やコストが変化する可能性がある
設定内の内部ルート名	コードは primary_chat を要求し、設定がそれを正確なIDにマッピングする	マッピングを自分で所有・テストする必要がある

エイリアスに関してはギャップが見つかりました。List Modelsのリファレンスにはすべての項目に tokenlab.aliases が存在するとありますが、私たちが持つ5つのライブ抜粋（claude-sonnet-5、deepseek-v4-pro、deepseek-v4-flash、glm-5.2、gpt-5.5）にはエイリアスの値が表示されていません。現在どのモデルがどのエイリアスを持っているかは不明です。上記のスクリプトは各依存関係の aliases を出力するため、実行して結果を読み取ってください。

カタログに関する2つの事実が役立ちます。2026年10月2日のカタログでは、バージョンが claude-sonnet-4-6、claude-sonnet-5、claude-sonnet-5-5 のように個別の正確なIDとしてリストされています。並んでリストされているからといって、一方が後継であるとは限りません。replacement 値こそがその関係性を示す唯一の場所です。grok-voice-latest というIDには名前に「latest」が含まれていますが、何に従っているかの証拠がないため、信頼する前にモデルページを確認してください。マーケットプレイス形式のプレフィックス付きIDはTokenLabのエイリアスではありません。移行ガイドによると、TokenLabのIDにはOpenRouterのプロバイダープレフィックスは含まれておらず、独自のLiteLLMエイリアスをTokenLab IDとは別に管理することを推奨しています。

消滅した固定モデルに対するフォールバックパターン

フォールバックは、事前にテストした2番目の固定モデルとして扱ってください。呼び出しサイトごとに選択し、どのモデルが各回答を提供したかを記録し、同じ夜間スクリプトで検証してください。ペアにする前に2つのモデルを比較します：

モデル（ライブAPI、2026年10月3日観測）	100万トークンあたりの入力/出力	最大入力/出力トークン	リクエスト形式	リストされた機能
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; ピーク $1.32 / $3.96	1,000,000 / 384,000	anthropic_messages, openai_chat_completions, openai_responses	json-mode, prompt-cache, tool-use

これら3つの価格は2026年10月2日 16:53:30.068Zに最終更新されました。違いが重要です。claude-sonnet-5 は openai_responses を受け付けないため、Responsesベースの呼び出し元はフォールバックできません。deepseek-v4-pro はvisionもreasoningもリストしていないため、画像を含むリクエストはそこで失敗します。DeepSeekのピーク時間は北京時間の09:00-12:00および14:00-18:00です。

以下は、1日あたり1,000万入力トークン、200万出力トークンという仮定の負荷に基づいたコスト見積もりです：

• gpt-5.5: 10 × $1.50 + 2 × $9.00 = $15 + $18 = 1日あたり$33
• claude-sonnet-5: 10 × $0.90 + 2 × $4.50 = $9 + $9 = 1日あたり$18
• deepseek-v4-pro オフピーク: 10 × $0.66 + 2 × $1.98 = $6.60 + $3.96 = 1日あたり$10.56
• deepseek-v4-pro ピーク: 10 × $1.32 + 2 × $3.96 = $13.20 + $7.92 = 1日あたり$21.12

これらは見積もりであり、キャッシュされた入力は価格が異なります。以下のコードは、再試行で解決できないエラーに対してのみフォールバックします。429 や再試行可能な 5xx は、通常の再試行ルールに従うべきです。

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,  # 再試行の安全性は自分で判断する
)

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):
    """回答したモデルとテキストを返す。結果とともにモデルを記録する。"""
    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などは別の修正が必要
        log.warning("pinned model %s unavailable (%s); using %s",
                    cfg["model"], code, cfg["fallback"])
        return cfg["fallback"], _chat(cfg["fallback"], text)

フォールバックは1回のみ行い、連鎖はさせません。フォールバックも失敗した場合はエラーを発生させ、担当者に通知してください。自動的な置換の連鎖は、別の名前のドリフト問題にすぎません。

AIモデルの非推奨化とバージョニングのためのリリースチェックリスト

本番環境のモデルIDを変更する前に、これを実行してください。ベストプラクティスガイド（2026年10月3日時点）を反映し、ライフサイクルチェックを追加したものです。

1. 本番環境のすべてのモデルIDをリストアップし、それぞれを使用している呼び出しサイトを特定する。単一の設定レイヤーで数秒以内に回答できるようにする。
2. 現在および候補のIDに対してライフサイクルスクリプトを実行する。deprecated_at、retired_at、ステージ、代替モデルを読み取る。
3. Get a Modelの accepted_request_formats を使用して、候補がコードで送信するリクエスト形式を受け付けるか確認する。
4. 最大入力および最大出力トークンを、実際の最長リクエストおよび出力上限と比較する。
5. 機能を比較する。製品が依存しているvision、tool-use、json-mode、reasoningを確認する。
6. 現在の価格からコストを再計算する。DeepSeekの場合はピークとオフピークを分ける。
7. 出荷予定の正確な候補IDと形式で、代表的なリクエストをリプレイする。不明なIDなどの失敗ケースを1つ含める。
8. エラーパスを検証する。クライアントは code で分岐し、リクエストIDを保持し、400、403、404 を再試行しないようにする。
9. 古いIDをロールバック値として保持した設定編集として変更を出荷する。
10. すべてのレスポンスレコードが実際に回答したモデルを保存しているか確認する。
11. リリース後に夜間スクリプトを再実行する。フォールバックIDも合格することを確認する。

ドキュメントに記載がない場合、このチェックリストが安全装置となります。非推奨化の猶予期間や通知チャネルは提供されていません。プロバイダーの通知を別途確認し、モデル自身のページでライフサイクルに関する注記を確認してください。

FAQ

TokenLabモデルが非推奨か廃止かを見分ける方法は？

GET /v1/models/{model} を呼び出し、tokenlab.lifecycle を読み取ってください。ステージ、deprecated_at、retired_at、および代替モデルを確認します。2026年10月3日時点で、私たちが読み取った5つのモデルはすべて active であり、日付は設定されていませんでした。値は問い合わせた瞬間の状態を反映しているため、定期的にポーリングしてください。

不明なモデルIDはどのHTTPステータスを返しますか？

エンドポイントによって異なります。Get a Modelは 404 model_not_found を返しますが、不正なモデルでのチャットリクエストは 400 model_not_found を返します。選択した配信ティアに供給がないモデルは 503 を返します。code フィールドで分岐してください。

model_not_found エラーを再試行すべきですか？

いいえ。同じリクエストを繰り返しても結果は変わりません。did_you_mean や suggestions があれば確認し、製品に権限がある場合のみモデルを切り替えてください。それ以外の場合は、承認済みのフォールバックを使用し、チームにアラートを送ってください。

モデルが消滅した場合、TokenLabはリクエストを別のモデルに切り替えますか？

ドキュメントには、送信されたモデルを自動的に置き換えることはないと記載されています。明示的なIDを送信し、エラーは自分で処理してください。フォールバックはプラットフォームの推測ではなく、テスト済みの設定値であるべきです。

次のモデル変更の前に、モデルディレクトリで現在のID、制限、価格を比較してください。