プレビュー画像モデル停止の朝に学んだこと — Gemini 画像モデル GA 移行と廃止に強いパイプライン設計

# model_registry.py
from dataclasses import dataclass
from datetime import date
 
@dataclass(frozen=True)
class ModelSpec:
    id: str
    role: str          # 用途のラベル
    deprecate_on: date | None  # 既知の廃止日（公式アナウンスがあれば設定）
    fallback: str | None       # 廃止時の代替モデルID
 
# 用途ごとに「論理名 → 実モデルID」を対応させる
REGISTRY: dict[str, ModelSpec] = {
    "image_fast": ModelSpec(
        id="gemini-3.1-flash-image",
        role="サムネイル・量産図版",
        deprecate_on=None,
        fallback="gemini-3-pro-image",
    ),
    "image_quality": ModelSpec(
        id="gemini-3-pro-image",
        role="高品質ヒーロー画像",
        deprecate_on=None,
        fallback="gemini-3.1-flash-image",
    ),
}
 
def resolve(logical_name: str) -> str:
    spec = REGISTRY[logical_name]
    return spec.id

# deprecation_guard.py
from datetime import date, timedelta
from model_registry import REGISTRY
 
ALERT_WINDOW_DAYS = 30
 
def check_deprecations(today: date | None = None) -> list[str]:
    today = today or date.today()
    warnings: list[str] = []
    for name, spec in REGISTRY.items():
        if spec.deprecate_on is None:
            continue
        days_left = (spec.deprecate_on - today).days
        if days_left < 0:
            warnings.append(
                f"🔴 {name} ({spec.id}) は廃止済み。fallback={spec.fallback} へ即時移行が必要です"
            )
        elif days_left <= ALERT_WINDOW_DAYS:
            warnings.append(
                f"⚠️ {name} ({spec.id}) は残り {days_left} 日で廃止。移行先 {spec.fallback} の検証を始めてください"
            )
    return warnings
 
if __name__ == "__main__":
    for w in check_deprecations():
        print(w)

from google import genai
 
client = genai.Client(api_key="YOUR_API_KEY")
 
# 動画をアップロードして文脈として渡す
video_file = client.files.upload(file="clip.mp4")
 
response = client.models.generate_content(
    model="gemini-3.1-flash-image",
    contents=[
        video_file,
        "Create a clean thumbnail capturing the calmest moment of this clip. "
        "16:9, soft lighting, no text overlay.",
    ],
)
 
for part in response.candidates[0].content.parts:
    if part.inline_data is not None:
        with open("thumbnail.png", "wb") as f:
            f.write(part.inline_data.data)