Gemini API移行の実務 — v1betaからGemini 3系への道のり
Mark4Gemini 2.5系の廃止日が決まった
GoogleがGemini 2.5系APIの廃止日を2026年6月17日と正式に発表しました。v1betaエンドポイントを使っているすべてのアプリケーションは、この日までにGemini 3系へ移行する必要があります。猶予期間は約4ヶ月。十分なようで、実際に移行作業を始めると意外と短いと感じる期間です。
wagahiアプリはGemini APIを使ったキャラクター生成機能を持っており、今回の移行は直接的に影響を受けます。実際の移行作業を通じて得た知見を共有します。
移行のブレイキングチェンジ
Gemini 3系への移行で最も影響が大きいのは、Thinking機能のパラメータ変更です。
thinkingBudget → thinkingLevel
Gemini 2.5系ではthinkingBudgetというパラメータでAIの思考量を数値（トークン数）で指定していました。Gemini 3系では、これがthinkingLevelという段階指定に変わります。
- 旧（2.5系）:
"thinkingBudget": 8000（トークン数で直接指定） - 新（3系）:
"thinkingLevel": "medium"（low / medium / high / max）
一見シンプルになったように見えますが、開発者にとっては微妙な調整が効かなくなるという側面もあります。wagahiアプリでは、キャラクターの性格生成にthinkingBudget: 12000という絶妙な値を使っていましたが、これをmediumかhighのどちらにマッピングするかで出力品質が変わります。
実際にやった検証
thinkingLevel: "medium"で同じプロンプトを100回実行thinkingLevel: "high"で同じプロンプトを100回実行- 出力品質を人間が5段階で評価
- 結果:
highの方が平均0.3ポイント高いが、レスポンスタイムは1.5倍
wagahiアプリではレスポンスタイムがユーザー体験に直結するため、mediumを選択しました。品質の微減分はシステムプロンプトの調整で補います。
システムプロンプトの調整
Gemini 3系ではシステムプロンプトの解釈精度が向上しています。これは良い変化ですが、2.5系向けに「冗長に書いていた」プロンプトが、3系では「指示が強すぎる」と解釈されるケースがあります。
具体的な例を挙げます。wagahiアプリのキャラクター対話機能で、以下のようなシステムプロンプトを使っていました。
2.5系向け（修正前）:
- 「必ず猫の視点で回答してください。人間の視点では絶対に回答しないでください。猫としての立場を常に維持してください。」
3系向け（修正後）:
- 「猫の視点で回答してください。」
3系では簡潔な指示の方が自然な出力が得られます。過剰な制約は、かえって不自然な文章を生むことがありました。
移行チェックリスト
wagahiアプリの移行で実際に使ったチェックリストを共有します。
- エンドポイントURL変更: v1beta → v1（Gemini 3系は正式版APIを使用）
- モデル名変更: gemini-2.5-flash → gemini-3.1-flash-lite等
- thinkingBudget → thinkingLevel: 数値指定から段階指定へ
- システムプロンプト簡素化: 冗長な指示を削減
- レスポンスフォーマット確認: JSON構造の微変更に対応
- エラーハンドリング更新: 新しいエラーコードへの対応
- レート制限確認: 3系でのAPI呼び出し上限を確認
- 回帰テスト実施: 全機能の動作確認
移行のコツ
最後に、移行作業で得た実践的なコツをまとめます。
1. 段階的に移行する
一気にすべてを切り替えるのではなく、機能ごとに段階的に移行しましょう。wagahiアプリでは、まずキャラクター生成機能で3系を試し、問題がないことを確認してから対話機能にも適用しました。
2. A/Bテストを活用する
移行期間中は2.5系と3系の両方にリクエストを送り、出力を比較することをお勧めします。本番環境では2.5系をメインに、一部のリクエストを3系にルーティングして品質を検証しました。
3. 廃止日まで余裕を持つ
6月17日がデッドラインですが、5月中には移行を完了させることを目標にしましょう。ギリギリまで2.5系を使い続けると、予期しない問題が発生した場合のリカバリ時間がなくなります。
API移行は地味な作業ですが、後回しにすると痛い目に遭います。この記事が移行作業の参考になれば幸いです。
本記事は2026年2月時点の情報に基づいています。
著者: 株式会社シーテン — インフラ系から宇宙関連システムまで20年以上の開発経験を持つ技術者集団。2025年より生成AI・AIエージェントを活用したAI駆動開発に本格参入し、自社プロダクト「wagahi」の開発を通じて実践知見を蓄積中。
関連記事
投稿者プロフィール
