API / SDK
Gemini API と SDK の使い方を扱うカテゴリです。クイックスタートから Function Calling、構造化出力、ストリーミング、コスト最適化、本番運用のトラブルシューティングまで、実装コードつきの記事を集めています。
静止画か短い動画か — Nano Banana 2 Lite と Omni Flash のコスト桁差で機能の置き所を決める
壁紙アプリの目玉アセットを静止画にするか短い動画にするかで手が止まったとき、決め手になったのは好みではなくコストの桁でした。Nano Banana 2 Lite と Omni Flash の単価を同じ土俵に並べ、動く意思決定関数まで落とし込みます。
Omni Flash の会話編集は「アングルを30度右へ」をどこまで聞き取るか — 指示が効く境界を実測した記録
公開プレビューの Gemini Omni Flash は、生成した動画を自然文で編集し直せます。ただし『照明を夕方に』は効いても『カメラを30度右へ』はしばしば外れます。効く指示と外れる指示の境界を、フレーム照合で機械的に仕分けながら測った運用記録です。
Managed Agent の長時間走行がサンドボックス再生成で消える前に — チェックポイントと冪等リジュームの設計
Managed Agents のサンドボックスは再生成されます。40分走った処理が振り出しに戻る前に、進捗を外部へ逃がすチェックポイントと、副作用を二度実行しない冪等リジュームを設計します。SQLite で動く実装つき。
同じ gemini-flash-latest が、リージョンごとに違うモデルを指していた — 比較値が汚れる数日間の見つけ方
エイリアスの解決先はリージョン単位でロールアウトされます。同じ gemini-flash-latest を東京と us-central1 に投げると、数日だけ別のモデルが応答する。その間の比較値が無効になる理由と、1発のプローブで検知して比較を凍結する設計をまとめます。
途中で切れた Gemini のストリーミングを、引き直すか続きから書かせるか — 二重に払わないための分岐設計
モバイル回線で Gemini のストリーミングが切れたとき、全部引き直すか続きから書かせるかで費用は大きく変わります。思考トークンの二重発生、受信トークン数で置く分岐条件、文末チェックポイント、継ぎ目に出る3つの壊れ方まで設計としてまとめました。
Gemini にスクリーンショットを採点させたら、全部78〜85点だった — 絶対スコアを捨ててペア比較に切り替えるまで
Gemini Vision に App Store スクリーンショットを100点満点で採点させると、良い案も崩した案も78〜85点に潰れます。弁別能を実測して絶対スコアを捨て、位置バイアスを除いたペア比較でランキングを作るまでの実装記録です。
自動採用された出力こそ抜き取る — 限られたレビュー予算で静かな品質劣化に気づく設計
信頼度ゲートが見ているのは、モデルが迷った出力だけです。静かな劣化は自動採用された側に沈みます。1日30分というレビュー予算を前提に、二項分布で検出日数を見積もり、層別抜き取りと累積監視で気づく速さを上げた設計と実測を共有します。
並行して回す実験が共有予算を食い尽くす前に — AI Studio 費用上限をプロジェクト隔離の境界にする設計
個人開発で複数の Gemini 実験を同じ請求アカウントで並行させると、ひとつの暴走が他の全部を巻き添えにします。AI Studio に入ったプロジェクト単位の費用上限を隔離境界として使い、クライアント側のソフト天井と月次照合まで含めた設計を実装込みでまとめました。
Batch ジョブが『まだ RUNNING です』のまま半日溶けていたとき — 状態別の滞留予算とレコード突合で詰まりを早期に名指しする運用メモ
Gemini Batch API のジョブが 24 時間 SLA の陰で静かに滞留していたとき、状態別の滞留時間予算とレコード数の突合で詰まりと取りこぼしを早期に検知するための計測手順を、運用ログの実測とともに整理します。
Gemini Code Execution の計算結果とモデルの文章がずれる — 実行結果だけを信頼する検証ゲートの実装
Gemini の Code Execution は実際に走らせた計算結果と、それを説明する自然文を別々に返します。文章側の数値を鵜呑みにすると幻覚を掴みます。実行結果だけを真実として抽出し照合する検証ゲートの実装を、動くコードで解説します。
structured output の任意フィールドが null・空文字・キー欠落で三様にぶれる — 正規化ゲートで一つの表現に畳む
Gemini の structured output で任意フィールドが null・空文字・キー欠落の三態にぶれ、下流が壊れる問題を、responseSchema の nullable 宣言と出力後の正規化ゲートで一つの表現に畳む実装として整理します。個人開発の夜間バッチでの実測つきです。
responseSchema で $ref が使えず詰まったら — responseJsonSchema で再帰スキーマを本番で扱う
Gemini の responseSchema は OpenAPI サブセットで $ref/$defs が使えず、共有定義も再帰も表現できません。responseJsonSchema へ移行し、多言語フィールドの再利用とカテゴリ木の再帰を本番で扱う実装をまとめました。
長尺PDFの章ごと要約で、まる一章が要約から消えていたとき — 被覆率を計測して取りこぼしを塞ぐ運用メモ
章ごと要約→全体再結合は長尺PDFに効きますが、抽出漏れや再結合で一章がまるごと消えても要約は素知らぬ顔で完走します。被覆率という一つの数字で取りこぼしを検知し、消えた章だけ再実行する監査つきパイプラインを実装で示します。
字幕が踊るのを止める — Live Translate の途中結果を確定と揺れに分けて描く
Gemini 3.5 Live Translate の途中結果をそのまま画面に貼ると字幕がちらついて読めません。確定した接頭辞と揺れる末尾を分離し、後方書き換えを許さない安定化ロジックを、実測値と動くコードでまとめました。
Gemini のコンテキストキャッシュが途中で失効する — 一時停止するパイプラインで TTL 切れを検知して張り直す
夜間バッチや再試行で処理が一時停止すると、Gemini の明示的コンテキストキャッシュは静かに TTL 切れを起こし、以降の呼び出しが全トークン課金へ戻ります。残り有効期限を握って張り直すか素通しするかを費用で決める、小さなリース設計をまとめました。
Google Sheets API × Gemini API でつくるデータ処理パイプライン — Apps Script 不要の Python 自動化
サービスアカウントを使った Google Sheets API の認証から、Gemini API でのデータ分析・分類・要約まで、Python だけで完結するスプレッドシート AI 自動化パイプラインを解説します。
Gemini API のシステム指示とプロンプト設計 — 出力品質を劇的に上げる実践テクニック
Gemini API のシステム指示（system_instruction）とプロンプトエンジニアリングの実践的なテクニックを解説します。出力品質にダイレクトに効く設計パターンを、動作するコード例と共に紹介します。
gemini-embedding-2 の検索精度が伸びないとき、最初に task_type を疑う
gemini-embedding-2 の検索が惜しい外れ方をするとき、原因は task_type の指定漏れや不一致であることが多いです。ドキュメントとクエリで用途を揃え、再現率を取り戻す実装と検証手順をまとめました。
有料チャットの Gemini 請求が見積りの倍になっていたとき — リクエスト単位でトークンを計上して原価の漏れを塞ぐ運用メモ
有料チャットSaaSの Gemini 請求が見積りの倍に膨らんだ実体験から、リクエスト単位でトークンを計上し、原価が漏れている箇所を特定して塞ぐ運用手順をまとめました。usage_metadata の記録と請求の突き合わせが起点です。
Omni Flash で短尺動画から SNS 告知メタデータを1パス抽出する
公開プレビューの Gemini Omni Flash に短尺動画を1回渡すだけで、告知文・チャプター・見せ場タイムスタンプを構造化 JSON で受け取る実装をまとめます。フレーム抽出を挟む多コール構成との違い、fps と media_resolution の効かせどころ、1本あたりのコスト試算まで、個人開発の告知作業を回す視点で扱います。
Context Caching を入れたのに Gemini の請求が減らなかったとき — 命中率を計測して立て直す運用メモ
Context Caching を有効化したのに Gemini API の請求がほとんど減らないとき、命中率と書き込みコストの回収点を usage_metadata から計測し、TTL チャーンと断片化を切り分けて段階的に立て直す運用メモです。
Managed Agents を本番に上げる前に、固定シナリオで挙動を測る — 非決定的なエージェントに回帰スイートと段階昇格を敷く
公開プレビューの Managed Agents は隔離サンドボックスで自律的に動く分、プロンプトや設定を少し変えただけで挙動が静かにずれます。単発プロンプトのように出力を一度突き合わせるだけでは足りません。固定シナリオを何度も回して合格率で測る回帰ハーネスと、影→カナリア→全面の段階昇格、逸脱時の自動ロールバックまでを、動く Python とともに設計します。
取り込んだのに一度も引かれない資料 — File Search ストアを引用ログで棚卸しする隔離つき剪定設計
File Search ストアに積んだドキュメントの多くは一度も引用されないまま費用と検索精度を蝕みます。grounding metadata から引用ログを取り、一度も引かれない資料を隔離期間つきで安全に剪定する運用設計を、動くコードとともに解説します。
Omni Flash で動画理解を1パスに畳む — フレーム抽出前提の構成をどこで手放すか
Omni Flash の公開プレビューで、ffmpeg のフレーム抽出と個別呼び出しに頼っていた動画理解を1回のネイティブ呼び出しへ畳む最小構成と、フレーム抽出を残すべき境界を実測ベースで整理します。
Nano Banana 2 Lite で大量画像生成のコストを設計する — 実測で使い分けを決める
最速・最安の画像モデル Nano Banana 2 Lite を大量生成の現場に組み込むコスト設計メモです。1枚あたりコストを式で持つ考え方、品質モデルと組み合わせる二層構成、静かなリトライにしない失敗の扱い、移行と廃止スケジュールの見方まで実測を交えて書きます。
Nano Banana 2 Lite で大量画像生成のコストを二段に分ける — 一次生成と本番レンダを切り離した設計メモ
Nano Banana 2 Lite を一次生成に、標準の Nano Banana 2 を採用後の本番レンダに回す二段構成のコスト設計メモです。一次生成・採用判定・本番レンダの三工程への分割、最小の Python ルーター実装、Lite に寄せすぎない線引きを共有します。
アプリに会話翻訳を組み込む — Live API で音声から音声へ、遅延と切断に耐える設計
Gemini 3.5 Live Translate と Live API で、音声から音声への会話翻訳をアプリに組み込む設計をまとめました。セッション寿命・言語の自動切り替え・遅延バジェット・ストリーミング課金の勘所を、動くコードとともに整理しています。
使っているモデルの廃止予告だけを拾う — url-context に公式チェンジログを読ませる仕組み
画像モデルの停止を公開3日前に知って肝を冷やしました。url-context に公式チェンジログを直接読ませ、自分が実際に使っているモデルの廃止予告だけを構造化して差分通知する仕組みを、そのまま動く Python と運用で削った過検知の調整まで含めて組み立てます。
Managed Agents を並列で回すと同じリポジトリを奪い合う ― 隔離サンドボックスに効く外部リースとフェンシング
Managed Agents は実行ごとに隔離サンドボックスが立つため、複数実行が同じリポジトリやレコードに同時に触れてもローカルロックが効きません。外部リースとフェンシングトークンで単一実行を保証する実装をまとめました。
Gemini API の英語出力に日本語が『たまに』混ざるとき — 混入率を計測して段階的に締める運用メモ
英語出力を指示したGemini APIが、100回に数回だけ日本語を混ぜてくる——この『たまに』を止められない本当の理由と、混入率をSLOとして計測し、段階的リカバリで本番品質まで締める運用パターンを実装コード付きで整理します。
一晩のバッチで静かに落ちた数十件をどう拾うか — Gemini Batch API の行単位リトライ台帳
Batch API の「完了」は「全件成功」ではありません。個人開発で夜間バッチを回し続けるなかで見えた、行単位の結果台帳・一時失敗と恒久失敗の切り分け・選択的リトライ・恒久失敗の無限リトライ防止を、SQLite で組んだ状態機械の動くコードとともに残します。
公開前に「意味が近すぎる過去記事」を弾く — Gemini Embedding でトピック共食いを防ぐ類似ゲート
記事数が数百本を超えると、新しく書いた記事が過去記事と検索面で共食いを起こします。gemini-embedding-2 で本文の意味ベクトルを持ち、公開前にコサイン類似で近すぎる既存記事を弾くゲートを、動くコードと閾値の決め方まで実装します。
Gemini API で iOS/Android アプリに AI 機能を実装する 2026 — 画像認識・音声解析・チャット・収益化まで
Gemini API で iOS/Android アプリに画像認識・音声解析・AIチャットを組み込む際の設計パターンとコスト最適化を、個人開発の実測値とともに整理します。Gemma 4 振り分けと API キー制限必須化への対応も追記しました。
Webhook が本物である保証はどこにもない — Gemini Webhooks 受信エンドポイントの三層防御設計
Gemini Webhooks の受信エンドポイントは公開 URL である以上、偽イベント・リプレイ・二重処理を想定する必要があります。ペイロードを事実として信じず API へ照会し直す構造を軸に、到達検証・重複排除・軽量ハンドラの三層防御を動くコードで示します。
Gemma 4 ローカル推論と Gemini API の使い分けで月額¥32,000を¥9,000台にした — ハイブリッドルーターの本番設計
月額¥32,000のGemini APIコストを¥9,000台まで下げたハイブリッド推論構成の記録です。ルーティング設計・Python実装・本番の落とし穴に加え、2026年7月のGemma 4 API提供開始を踏まえた構成見直しの指針もまとめました。
IP が変わるサーバーで Gemini API キーの制限を効かせる — headless 自動処理の逃がし方
未制限キーの遮断後、IP が毎回変わる headless なサーバー自動処理では、HTTP リファラーもアプリ制限も IP 許可リストも素直には効きません。API 制限だけで凌ぐか、egress を固定 IP に集約するか、いっそ Vertex のサービスアカウント認証へ移すか。稼働を止めずに選ぶための判断軸と、動くコードを整理します。
静かに止まる自動処理を防ぐ — Gemini 基盤変更に備える事前検証ゲートの設計
制限なしAPIキーの拒否、CLIのEOL、Interactions APIへの一本化。2026年後半のGemini基盤変更は、動いていた自動処理を無言で止めます。バッチ実行の手前で失敗を検出する事前検証ゲートを、実行可能なコードとともに設計します。
AI Studio で通ったプロンプトが API では静かに崩れるとき — 差分を計測して切り分ける運用メモ
AI Studio では完璧に動いたプロンプトが、自分のコードから Gemini API を呼ぶと空応答や 404 になる。目視ではなく、設定差と finish_reason・使用トークン・解決モデル名を機械的に記録する小さなハーネスで、原因別に切り分ける運用手順をまとめました。
投げて終了する定期実行で、結果を取りこぼさない — Gemini バックグラウンド実行を再取得台帳で回す設計
Interactions API のバックグラウンド実行を cron 駆動の定期実行で安全に回すための設計です。送信前に冪等キーで台帳へ予約し、次のティックで未取得ハンドルだけを再取得する二段コミットを、動くコードで示します。
散らばった呼び出し口を一つに畳む — Interactions API を自動運用の正面玄関にする移行設計
Interactions API の一般提供で、Gemini の呼び出しが一つの入り口に寄せられるようになりました。generateContent・Batch・自前エージェントループに散らばった呼び出し口を、壊さずに正面玄関へ畳んでいく移行設計を、薄いアダプタ層の実装とともに整理します。