API / SDK
Gemini API と SDK の使い方を扱うカテゴリです。クイックスタートから Function Calling、構造化出力、ストリーミング、コスト最適化、本番運用のトラブルシューティングまで、実装コードつきの記事を集めています。
Gemini API の usageMetadata で本番アプリのコストを記録する — リクエスト単位で請求書と突き合わせる実装パターン
usageMetadata をリクエスト単位で記録し、エンドポイント・ユーザー・モデル別にコストを按分する実装パターンに加え、3.5 Flash GA で既定モデルが差し替わってもコスト記録が狂わないよう resp.model_version を基点にした単価引き当てと、ドリフト・未知モデルを毎晩監査する仕組みまで解説します。
Gemini API Grounding × Structured Output — Web検索結果をJSON構造化データに変換する
Gemini APIのGrounding with Google SearchとStructured Outputを組み合わせ、リアルタイムWeb情報を型安全なJSONデータとして抽出する実装パターンを解説。
Gemini のモデル非推奨を CI で先回りして止める仕組み
ハードコードされた Gemini のモデル ID を CI で走査し、シャットダウン期限が近いものを残り日数つきで検知する仕組みを動くコードで組み立てます。稼働中モデル一覧との突き合わせ、GitHub Actions と日次 cron への組み込み、運用の工夫まで扱います。
Gemini API × tRPC v11 × Prisma でつくる型安全 AI バックエンド — リアルタイムストリーミングからミドルウェア認証・本番運用まで
tRPC v11 の subscription で Gemini API ストリーミングをリアルタイム配信し、Prisma で型安全に会話を永続化する本番設計を解説します。ミドルウェア認証・レート制限・落とし穴対策まで実コード付きでまとめました。
見た目がほぼ同じ画像を公開前に弾く — gemini-embedding-2 で近重複ゲートを作る
見た目がほぼ同じ画像を公開前に自動で弾くために、gemini-embedding-2 のマルチモーダル埋め込みで近重複ゲートを作りました。ベクトル化からクラスタリング、公開前ゲートへの組み込みまでの動くコードと、しきい値の決め方や運用で気づいた点をまとめています。
日英2版を1回の構造化出力でまとめて生成し、用語の対訳ブレを止める運用設計
日本語版と英語版を別々に生成すると用語の訳が記事ごとにブレます。Gemini 3.5 Flash の構造化出力で日英をペアにして1コールで生成し、用語集をピン留めしてブレを機械検出する運用を、実測値とともにまとめます。
pgvector のセマンティック検索が半年で「鈍く」なるとき — Gemini エンベディングの再現率を守る運用メモ
Gemini Embedding と PostgreSQL pgvector で組んだ検索が、運用のうちに静かに精度を落とす理由を整理します。モデル固定・距離演算子の一致・HNSW の再インデックス・フィルタ付き検索の再現率低下まで、本番で踏んだ箇所を実装つきでまとめました。
Managed Agents の請求はトークンだけでは読めない — サンドボックス稼働時間に予算境界を引く設計
公開プレビューの Managed Agents は、トークンに加えてサンドボックスの稼働時間でも課金されます。ハングした1実行が静かに予算を削る第二の課金軸を切り分け、壁時計上限・アイドル切断・同時実行の天井を動く Python で設計します。
Gemini API の Google Maps グラウンディングで位置情報AIを作る — 料金とソース表示の義務を踏まえた実装メモ
Gemini API の Google Maps グラウンディングで「近くのおすすめ」を提案する機能を実装した運用メモです。緯度経度を渡す最小実装、義務である出典表示への対応、$25/1K の課金を踏まえ地理的な意図のときだけツールを有効化する設計を解説します。
Gemini の構造化出力で入力種別ごとに型を変える — anyOf 判別ユニオンの実運用メモ
種類の違う入力を1つのエンドポイントで分類すると、フラットなスキーマは null だらけになります。anyOf 判別ユニオンで種別ごとに型を切り替え、Pydantic / Zod で安全に受け取る実装をまとめました。
countTokens でバッチ投入前にコスト超過を止める — 既定モデルが変わっても崩れない予算ゲートの設計
夜間バッチが想定外に高くつく原因は、投入後にしかコストが分からないことです。countTokens を起点に、思考トークンまで織り込んだ予算ゲートを設計し、既定モデルが入れ替わっても見積もりが崩れない運用に立て直します。
Gemini API のニッチ SaaS で「請求とコストが噛み合わない」を消す — 従量原価の計測と Stripe 突合の運用メモ
Gemini API を組み込んだニッチ SaaS では、月額売上は見えてもユーザー単位の従量原価が見えず、月末に粗利が読めなくなりがちです。トークン消費を即時に円換算する計測層、Stripe 売上との月次突合、赤字ユーザーの早期検知、冪等な Webhook までを実装メモとして整理します。
Gemini CLI 終了前に、自動化スクリプトを API へ載せ替えた記録
6/18 に Gemini CLI のホスト応答が停止します。シェルから gemini を呼んでいた自動化スクリプトを、google-genai SDK へ安全に載せ替える手順を、構造化出力・リトライ・コスト計測まで含めて実装ベースでまとめました。
Flash と Pro のルーティングしきい値を、シャドウ再評価で較正し続ける
Flash で生成し、自信のないものだけ Pro に回すルーターは、しきい値を手で決めた瞬間から少しずつ古くなります。サンプリングしたシャドウ再評価で不一致率を測り、しきい値を品質予算から逆算して較正し続ける仕組みを、動くコードで組み立てます。
生成文の『文体の癖』を数値で見張る — 既定モデルの差し替えを文体ドリフトで検知する設計
既定モデルが頭越しに変わると、出力の正しさはそのままでも文体の癖が静かにズレます。生成文の敬体率や文長分布をフィンガープリント化し、統計的に文体ドリフトを検知してパイプラインを止める設計を、依存ライブラリなしの実装で解説します。
Managed Agents が作った成果物を本番に入れる前に — 受け入れゲートを自前で設計する
公開プレビューの Managed Agents にファイル生成まで任せると、品質がぶれたまま本番へ流れ込みます。サンドボックスの成果物を受け入れる前に通す検証ゲートを、そのまま動く Python コードと却下フィードバックの設計まで含めて組み立てます。
Gemini Managed Agents を自動化に組み込む ― 会話状態と環境状態を分けて扱う実装メモ
Managed Agents は1回の API 呼び出しで Linux サンドボックスを立て、エージェントを走らせて結果を返します。自前ループから移すとき最初につまずく「会話状態と環境状態は別物」という設計を、実際に動かしながら整理しました。
既定モデルが上がっても折れない — Gemini 呼び出しに起動時の能力検出レイヤーを挟む設計
モデル名のピン留めも既定への依存も、どちらも静かに折れます。いま実際に届いているモデルが何をできるのかを起動時に確かめ、その結果でリクエストを組み立て直す能力検出レイヤーの設計と、コピペで動く Python を残します。
Gemini Live API のセッションが切れるたびに会話が消える — 期限切れトークンの再取得とセッション再開の実装メモ
Gemini Live API の WebSocket が再接続するたびに会話履歴とユーザーの発話を取りこぼす問題を、エフェメラルトークンの単発消費・セッション再開ハンドル・goAway 予告の3点から実装で塞ぐ運用メモです。
ヘルプ記事とスクリーンショットを1つの File Search に入れて、画像も引用できる回答を返す
テキストのヘルプ記事と画面スクリーンショットを別々のストアで管理していて、回答に手順画像を添えられない。gemini-embedding-2 のマルチモーダル対応で両者を同じ File Search に入れ、引用元の画像まで返すまでを実装で整理しました。
既定モデルが勝手に上がる時代に、プロンプト変更の劣化を数値で捕まえる — バリアント管理とカナリア評価の実装メモ
Gemini 3.5 Flash が既定に上がり、無効化もできなくなりました。プロンプトを触っていないのに応答が変わる前提で、バリアントを束ねて管理し、カナリアと LLM-as-judge で劣化を数値として捕まえる仕組みを、動くコードで組み立てます。
外部テキストを Gemini API に渡すときのプロンプトインジェクション対策 — レビューや収集データを安全に処理する防御設計
ユーザーレビューや収集した記事など、信頼できない外部テキストを Gemini API に渡すと間接プロンプトインジェクションの入口になります。信頼境界の隔離・スキーマ拘束・二段階検証・出力サニタイズまで、本番パイプラインに組み込める防御をコード付きで整理します。
権限を尊重する RAG — Gemini 検索で『その人が見てよい文書』だけを根拠にする本番設計
社内ナレッジ検索に RAG を入れた途端、本来見えてはいけない下書きや収支メモが回答の根拠に混ざる。権限を尊重したまま Gemini に検索させるための、メタデータフィルタ・二重チェック・監査ログの本番設計を動くコードで解説します。
Gemini 3 Deep Think を検証ステップに使ってコストが3倍になった話と、thinking_level で天井を作るまで
API 経由で開放された Gemini 3 Deep Think を出力検証に組み込んだところ、月のコストが想定の約3倍に膨らみました。thinking_level とコストガードレールで上限を作り、Flash との二段構えに落ち着くまでの実装記録です。
Flash で生成し、迷ったときだけ Deep Think に検証させる二段パイプライン
Deep Think の API 開放を機に、全リクエストを重いモデルに通すのではなく、Flash の出力が怪しいときだけ Deep Think に検証させる二段構成を、コストの考え方と動くコードで整理します。
Gemini APIの『デフォルトモデルが上がる』を事故にしない — モデルIDの固定と既定変更の検知設計
既定モデルが静かに上がると、同じコードのまま出力長・推論挙動・コストが変わります。モデルIDを単一の真実の源で固定し、レスポンスの実効モデルを検証して既定変更を検知する設計を、実装レベルで解説します。
Gemini API の media_resolution で画像トークンを制御する — バッチ画像分類のコストと精度を実測で最適化する
Gemini 3 系で導入された media_resolution は、画像入力が消費するトークン量を3段階で切り替えるパラメータです。バッチ画像分類の実測を通して、コストと精度のバランスをタスク別に最適化する手順を解説します。
Gemini API の本文が途中で切れる — finish_reason: MAX_TOKENS を検知して続きを継ぎ直す実装メモ
長文生成で末尾が文の途中でぷつりと切れる。原因の多くは finish_reason: MAX_TOKENS です。例外も 200 のまま静かに混入するこの事故を検知し、続きを継ぎ足して全文を取り戻す実装を、思考トークンの落とし穴とあわせてまとめました。
Gemini 3.5 Flash 移行で組み直した RAG の3層キャッシュ — レスポンス・検索・埋め込みを段階的に節約する
Gemini 2.0 Flash の廃止を機に、RAG のキャッシュ設計を 3.5 Flash 前提で組み直しました。レスポンス・セマンティック・埋め込みの3層それぞれの実装コードと実測ヒット率、API 側 Context Caching との役割分担までを整理します。
Gemini 3.5 Flash GA をどこから差し替えるか — ワークロード別の置き換え判定とモデルルーターによる段階導入の記録
Gemini 3.5 Flash GA への移行をモデル名の書き換え1行で済ませず、評価ハーネスでワークロード別に実測してから段階導入した記録です。判定基準・比較コード・環境変数ルーター・ロールバック設計をまとめます。
Gemini の生成は通ったのに公開が落ちた朝 — 高価な出力を取りこぼさない『生成アウトボックス』の設計
生成は成功したのに、公開処理の直前でプロセスが落ちる。すると高価な出力が消え、もう一度同じ生成に課金することになります。生成結果を先に永続化し、公開を冪等な後続処理に分離する『生成アウトボックス』の実装と、6月の障害下での運用記録をまとめました。
夜間ログを毎朝3分で読み切る — Gemini API で Daily Brief 風の運用ダイジェストを自作した記録
Daily Brief に着想を得て、夜間の運用ログを毎朝1通のダイジェストに変えるパイプラインを自作しました。収集・構造化・要約・配信の4段構成と実測トークン数、障害の朝でも配信を止めないフォールバック設計までの実装記録です。
壁紙アセットの画像探しを File Search のマルチモーダル検索に任せてみた記録
数千枚の壁紙アセットから目当ての一枚を探す作業を、File Search のマルチモーダル検索（gemini-embedding-2）に置き換えられるか300枚で検証しました。カテゴリタグ運用との比較、つまずいた点、使い分けの結論を実装コードとともに残します。
App Store 審査リジェクト対応に Gemini API を組み込む — 通知の構造化から Resolution Center 返信までの運用記録
App Storeの審査リジェクト通知をGemini APIで3層のJSONに構造化し、ガイドライン照合・Resolution Center返信ドラフト・提出前セルフチェックへつなげた個人開発の運用記録です。
Gemini 機能の「使われ方」を測る — 受け入れ率・再生成率・編集距離で見る製品計測の設計
トークン消費やエラー率だけでは、Gemini で作った機能がユーザーに受け入れられているかは分かりません。生成のライフサイクルを5つのイベントに分解し、受け入れ率・再生成率・編集距離を Swift と BigQuery で計測してプロンプト改善につなげた設計と実測値をまとめました。
深夜のポーリングをやめる — Gemini Batch API を Webhook 駆動に作り替えた設計記録
Gemini Batch API の完了監視を 60 秒間隔のポーリングから Webhook 駆動へ移行した実作業の記録です。static/dynamic の使い分け、署名検証、実測値をまとめました。
Gemini の画像生成 preview モデルが 6月25日に停止します — GA 版への移行で確認したコード差分と検証手順
6月25日に停止する gemini-3.1-flash-image-preview / gemini-3-pro-image-preview から GA 版へ移行した作業記録です。モデルIDの確認手順、Python のコード差分、停止前にしかできない回帰チェック、切り替え順序まで実例で整理しました。
Gemini Interactions API の outputs が使えなくなったら — 6月6日廃止の旧スキーマから steps へ移行する手順
2026年6月6日、Gemini Interactions API のレガシー outputs スキーマが削除されました。AttributeError・無言の空応答・履歴の400エラーという症状別に、steps と response_format への書き換え手順を整理します。
Gemini API の空応答を finish_reason から逆引きする — 診断フロー・再試行分類・監視の実務
response.text が空になる問題は candidates・prompt_feedback・finish_reason の3層で診断できます。思考トークンによる出力枯渇の検出、再試行可否の分類器、空応答率の監視まで、本番で運用している実装をまとめました。
Gemini API の大規模障害で夜間バッチを止めないために組んだ三層の防御
今週の Gemini 広域障害で夜間バッチが3時間分の処理を取りこぼした反省から、リトライ・モデルフォールバック・縮退運転の三層防御に組み替えた記録です。再試行してよい失敗の見分け方、冪等性の確保、復旧後の追い付き処理まで実装コード付きで残します。