取り組みの背景
Gemini API を使ってアプリケーションやサービスを開発していると、利用しているモデルが「非推奨（deprecated）」として通知されることがあります。Google が新しいモデルをリリースし、古いモデルのサポート期限が近づく際に発生する現象です。
この通知を受け取った時、多くの開発者は以下のような不安を感じます。
- どのモデルに移行すればいいのか
- 移行時に既存のコードはどう変わるのか
- 互換性が失われるのではないか
- 移行中にエラーが発生したらどうするか
このガイドでは、Gemini API のモデルライフサイクルを理解した上で、安全かつ効率的に新しいモデルへ移行するための実践的な方法を解説します。
Gemini API モデルのライフサイクル
モデルの3つの段階
Gemini API のモデルは、以下の3つの段階を経ます。
1. 標準サポート段階（General Availability）
新しいモデルがリリースされ、本番環境での利用が推奨される状態です。この段階では、Google が定期的に更新や改善を提供します。
2. 非推奨予告段階（Deprecated）
Google がモデルの終了予定日を発表した段階です。「このモデルは2025年6月30日に非推奨になります」という通知が届きます。重要な点は、この段階でもモデルは完全に動作します。移行を急ぐ必要はありませんが、計画的に新しいモデルへの移行準備を始めるべきタイミングです。
3. 廃止段階（Sunset / End of Life）
指定された日付に達すると、モデルは API を通じて利用不可能になります。この日付以降、そのモデルを指定した API 呼び出しはエラーで返されます。
非推奨通知を受け取ったら何をするか
Google からメールで非推奨通知を受け取った場合、やるべきことは3つです。
- 通知内容を確認する：どのモデルが非推奨になるのか、いつまで利用できるのかを確認します
- 互換性を調査する：新しいモデルの仕様を確認し、既存コードとの互換性を確認します
- 移行計画を立てる：廃止日までに段階的に移行するタイムラインを決めます
非推奨通知の確認方法
Google Cloud Console で確認する
非推奨の詳細情報は、Google Cloud Console の「Gemini API」セクションで確認できます。
- Google Cloud Console にログイン
- 「API と サービス」→「ライブラリ」を選択
- 「Generative AI API」を検索して開く
- 「ドキュメント」タブで「モデル一覧」を確認
- 各モデルの横に「非推奨」バッジがあれば、クリックして詳細を表示
重要な情報は以下の通りです。
- 非推奨予告日：Google が発表を行った日
- 廃止予定日：モデルが利用不可能になる日
- 移行対象モデル：推奨される新しいモデル
- ブレーキング・チェンジ：互換性に影響する変更点
API レスポンスヘッダーで確認する
実際に非推奨モデルで API を呼び出すと、レスポンスヘッダーに警告情報が含まれます。
curl https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-pro:generateContent \
-H "Content-Type: application/json" \
-H "x-goog-api-key: YOUR_API_KEY" \
-d '{
"contents": [{"parts": [{"text": "Hello"}]}]
}' \
-v
レスポンスヘッダーに以下のような警告が含まれます。
Deprecation: true
Deprecation-Date: 2026-06-30
Sunset: 2026-09-30
この情報を自動的に検出して、ログに記録することもできます（後述の「プログラム的な検出」参照）。
実際の移行手順
Step 1：新しいモデルのドキュメントを読む
新しいモデルが旧モデルとどう違うのかを理解することが、最も重要なステップです。
チェックするべきポイント：
- 入力/出力のサポート形式：テキスト、画像、動画、音声などのサポート状況
- トークン制限：最大入力トークン数と最大出力トークン数
- コンテキストウィンドウ：一度に処理できる最大テキスト長
- API パラメータ：temperature、top_p などのパラメータが同じか
- 価格：リクエストあたりの費用は変わるか
例えば、gemini-1.5-pro から gemini-2.0-pro への移行では、以下のような変更があります。
Step 2：ステージング環境で新しいモデルをテストする
本番環境に影響を与えないよう、まずステージング環境でテストします。
// テスト用のコード例
const { GoogleGenerativeAI } = require("@google/generative-ai");
const client = new GoogleGenerativeAI({
apiKey: process.env.GEMINI_API_KEY,
});
async function testModelMigration() {
try {
// 新しいモデルを指定
const model = client.getGenerativeModel({
model: "gemini-2.0-pro",
});
const response = await model.generateContent(
"あなたはどのモデルですか？"
);
console.log("新モデルのテスト成功:", response.text());
// 重要な機能をテスト
await testFunctionCalling(model);
await testImageProcessing(model);
await testResponseMetadata(response);
} catch (error) {
console.error("テスト失敗:", error.message);
}
}
async function testFunctionCalling(model) {
// 関数呼び出し機能が動作するか確認
const response = await model.generateContent({
contents: [
{
parts: [
{
text: "東京の現在の天気を教えてください",
},
],
},
],
tools: [
{
functionDeclarations: [
{
name: "getWeather",
description: "指定された都市の天気情報を取得します",
parameters: {
type: "object",
properties: {
city: {
type: "string",
description: "都市名",
},
},
required: ["city"],
},
},
],
},
],
});
console.log("関数呼び出し結果:", response);
}
async function testImageProcessing(model) {
// 画像処理機能が動作するか確認
const fs = require("fs");
const imageBuffer = fs.readFileSync("test-image.jpg");
const base64Image = imageBuffer.toString("base64");
const response = await model.generateContent({
contents: [
{
parts: [
{
inlineData: {
mimeType: "image/jpeg",
data: base64Image,
},
},
{
text: "この画像に写っているものを説明してください",
},
],
},
],
});
console.log("画像処理結果:", response.text());
}
async function testResponseMetadata(response) {
// レスポンスメタデータを確認
console.log("使用トークン数:", response.usageMetadata);
console.log("モデル:", response.modelVersion);
}
testModelMigration();
このテストでは、以下のポイントを確認します。
- 基本的なテキスト生成が動作するか
- 画像や動画などのマルチモーダル入力に対応しているか
- 関数呼び出し（function calling）が機能するか
- レスポンス形式が変わっていないか
- エラーハンドリングが適切に機能するか
Step 3：段階的なロールアウト
ステージング環境でのテストが成功したら、本番環境へ段階的にロールアウトします。
// 環境変数で新旧モデルを切り替え
const targetModel =
process.env.USE_NEW_MODEL === "true" ? "gemini-2.0-pro" : "gemini-1.5-pro";
const model = client.getGenerativeModel({
model: targetModel,
});
ロールアウトは以下の段階で行うことをお勧めします。
フェーズ1：5% のトラフィック（1-2日）
本番環境の 5% だけを新しいモデルに振り向けます。エラーや異常な動作がないか監視します。
フェーズ2：25% のトラフィック（3-5日）
問題がなければ、25% に拡大します。レイテンシーやエラーレートの変化を監視します。
フェーズ3：100% のトラフィック
最終的に全トラフィックを新しいモデルに振り向けます。
Step 4：旧モデルの削除
廃止予定日の1週間前に、旧モデルを指定しているコードをすべて削除または非アクティブ化します。念のため、廃止予定日以降に旧モデルで API が呼び出された場合のエラーハンドリングも追加します。
移行時によくあるエラーと対処法
エラー1：「このモデルは廃止されました」
Error: Model 'gemini-1.5-pro' is no longer available.
Please use 'gemini-2.0-pro' instead.
原因：廃止予定日を過ぎたモデルを使用している
対処法：以下の手順でコード内のモデル名をすべて置き換える
# コード内でモデル名を検索
grep -r "gemini-1.5-pro" src/
# 置き換え
sed -i 's/gemini-1.5-pro/gemini-2.0-pro/g' src/**/*.js
エラー2：「パラメータが無効です」
Error: Parameter 'safety_settings' is not supported
in this model.
原因：新しいモデルが異なるパラメータ仕様を持っている
対処法：新しいモデルのドキュメントを確認し、パラメータを修正する
// 旧コード（非推奨モデル用）
const response = await model.generateContent({
contents: [{ parts: [{ text: "Hello" }] }],
safety_settings: [
{
category: "HARM_CATEGORY_HATE_SPEECH",
threshold: "BLOCK_NONE",
},
],
});
// 新コード（新モデル用）
const response = await model.generateContent({
contents: [{ parts: [{ text: "Hello" }] }],
safetySettings: [
{
category: "HARM_CATEGORY_HATE_SPEECH",
threshold: "BLOCK_NONE",
},
],
});
エラー3：「レスポンス形式が異なります」
Error: Cannot read property 'text()' of undefined
原因：レスポンス形式が変更されている
対処法：レスポンスの構造を確認し、アクセス方法を修正する
// レスポンス形式を安全にアクセス
function safeGetResponseText(response) {
// 新フォーマットを試す
if (response.text && typeof response.text === "function") {
return response.text();
}
// 古いフォーマットを試す
if (response.content && response.content[0]) {
return response.content[0].parts[0].text;
}
// フォールバック
return null;
}
エラー4：「トークン制限を超過しました」
Error: Input token count (150000) exceeds the limit (100000).
原因：新しいモデルのトークン制限が旧モデルと異なる
対処法：トークンカウント機能を使って事前に確認する
const { countTokens } = require("@google/generative-ai");
async function checkTokenCount(text) {
const model = client.getGenerativeModel({
model: "gemini-2.0-pro",
});
const countResult = await model.countTokens(text);
console.log(`入力テキストのトークン数: ${countResult.totalTokens}`);
// モデルの制限を超えないか確認
if (countResult.totalTokens > 1000000) {
console.warn("テキストが長すぎます。分割してください。");
return false;
}
return true;
}
安全な移行戦略：フォールバック実装
重要な本番環境では、フォールバック機能を実装することをお勧めします。新しいモデルで問題が発生した場合、自動的に旧モデルに切り替わる仕組みです。
async function generateWithFallback(prompt, options = {}) {
const models = ["gemini-3.1-pro", "gemini-3.5-flash"];
let lastError = null;
for (const modelName of models) {
try {
console.log(`${modelName} でリクエストを試行中...`);
const model = client.getGenerativeModel({
model: modelName,
});
const response = await model.generateContent({
contents: [{ parts: [{ text: prompt }] }],
...options,
});
console.log(`${modelName} で成功`);
return response;
} catch (error) {
lastError = error;
console.warn(`${modelName} で失敗: ${error.message}`);
continue;
}
}
// すべてのモデルで失敗
throw new Error(`すべてのモデルで失敗しました: ${lastError.message}`);
}
// 使用例
const response = await generateWithFallback(
"あなたのモデルを教えてください"
);
console.log(response.text());
この実装により、新しいモデルで問題が発生してもサービスが中断されません。
移行時のベストプラクティス
1. 移行前の互換性テストリスト
移行を実行する前に、以下のチェックリストを確認してください。
- [ ] 新しいモデルのドキュメントを完全に読んだ
- [ ] ステージング環境で最低1週間テストした
- [ ] 本番環境のバックアップを作成した
- [ ] ロールバック計画を準備した
- [ ] 監視用ダッシュボード（エラーレート、レイテンシー）をセットアップした
- [ ] チーム内で移行計画を共有した
2. 本番環境での監視項目
新しいモデルへの切り替え直後は、以下を監視します。
- エラーレート：5分以上の異常な上昇がないか
- レスポンス品質：ユーザーからクレームが増えていないか
- レイテンシー：平均応答時間が大幅に変わっていないか
- API 呼び出し成功率：継続的に監視し、低下していないか
3. ロールバック計画
新しいモデルで致命的な問題が発生した場合、即座に旧モデルに戻す手順を事前に準備してください。
// ロールバック用の環境変数
const useNewModel = process.env.USE_NEW_MODEL === "true";
async function rollback() {
console.log("古いモデルにロールバック中...");
process.env.USE_NEW_MODEL = "false";
// アプリケーションを再起動
process.exit(0);
}
期限つき非推奨を取りこぼさない ― 依存棚卸しを自動化する
非推奨の中でも特に注意したいのが、シャットダウン日が明確に決まっている「期限つき非推奨」です。画像プレビュー系のモデルなどは、告知から廃止までの猶予が数週間しかないことがあります。気づいた時には本番のパイプラインが止まっていた、という事態は避けたいところです。
私自身、個人開発で複数のサービスから Gemini API を呼んでいると、どのコードがどのモデル名を直接書いているのかを正確に把握できなくなる瞬間があります。そこで、ソースコードを横断してモデル名を棚卸しし、廃止予定の一覧と突き合わせる小さなスクリプトを定期実行するようにしました。
// audit-models.mjs — リポジトリ内のモデル名を棚卸しし、廃止予定と突き合わせる
import { readdir, readFile } from "node:fs/promises";
import { join, extname } from "node:path";
// 廃止予定日（手動メンテ、または deprecations ドキュメントから取得）
const SUNSET = {
"gemini-3.1-flash-image-preview": "2026-06-25",
"gemini-3-pro-image-preview": "2026-06-25",
};
const MODEL_RE = /gemini-[a-z0-9.\-]+/g;
const SKIP = new Set(["node_modules", ".git", ".next", "dist", "build"]);
async function* walk(dir) {
for (const ent of await readdir(dir, { withFileTypes: true })) {
if (SKIP.has(ent.name)) continue;
const p = join(dir, ent.name);
if (ent.isDirectory()) yield* walk(p);
else if ([".js", ".mjs", ".ts", ".tsx", ".json"].includes(extname(ent.name))) yield p;
}
}
const hits = new Map(); // model -> Set<file>
for await (const file of walk(process.cwd())) {
const text = await readFile(file, "utf8");
for (const m of text.matchAll(MODEL_RE)) {
if (!hits.has(m[0])) hits.set(m[0], new Set());
hits.get(m[0]).add(file);
}
}
const today = new Date();
let risk = 0;
for (const [model, files] of [...hits].sort()) {
const sunset = SUNSET[model];
const days = sunset ? Math.ceil((new Date(sunset) - today) / 86400000) : null;
const flag = days != null && days <= 30 ? `⚠️ 残り${days}日 (${sunset})` : "";
if (flag) risk++;
console.log(`${model.padEnd(36)} ${files.size}箇所 ${flag}`);
}
process.exit(risk > 0 ? 1 : 0);
process.exit(1) で終わるため、CI に組み込めば「30日以内に廃止されるモデルを直接参照しているプルリクエスト」を機械的に止められます。手作業の確認に頼ると、人が忙しい時ほど見落とします。仕組みで止めるほうが確実です。
実運用での効果を、3つの運用パターンで比較してみました。私が個人開発の数サービスで計測した、おおよその傾向です。
ポイントは、モデル名を1か所に集約することです。コード中に文字列で散らばっていると、棚卸しスクリプトがあっても修正箇所が増えてしまいます。私は次のように設定モジュールへ寄せ、参照側はキー名だけを持つようにしています。
// config/models.mjs — モデル名は必ずここ経由で参照する
export const MODELS = {
draft: "gemini-3.5-flash", // 下書き・分類など高頻度・低コスト用途
finalize: "gemini-3.1-pro", // 仕上げ・推論が必要な用途
};
こうしておくと、廃止のたびに書き換えるのは1ファイルだけで済みます。棚卸しスクリプトも config/models.mjs を見れば現役のモデルがすぐに分かります。私はこの棚卸しを月初の習慣にしています。地味な工夫ですが、移行のたびに静かに効いてくる投資だと考えています。
まとめ
Gemini API のモデル非推奨への対応は、計画的かつ段階的に進めることが成功の鍵です。
重要なポイント：
- 非推奨通知を受け取ったら、すぐに新しいモデルのドキュメントを読む
- ステージング環境で十分なテストを行う
- 段階的なロールアウトで本番環境に展開する
- フォールバック機能とロールバック計画を用意する
- 廃止予定日までに確実に移行を完了する
このガイドで紹介した手順とコード例を参考に、スムーズな移行を進めてください。
Gemini API の最新情報については、Google AI Studio でいつでも確認できます。移行に関する質問や問題があれば、Google AI コミュニティ で相談することもできます。