API / SDK
Gemini API と SDK の使い方を扱うカテゴリです。クイックスタートから Function Calling、構造化出力、ストリーミング、コスト最適化、本番運用のトラブルシューティングまで、実装コードつきの記事を集めています。
models は 200 なのに generateContent だけ 403 になる日 — 切り分けの順番を先に決めておく
モデル一覧の取得は 200 で通るのに、生成リクエストだけが 403 permission_denied で止まるときの切り分け手順です。キー・プロジェクト・請求の順に確かめる小さな診断スクリプトと、リトライしてはいけない理由、サポートへ渡す材料の揃え方をまとめました。
config に「Extra inputs are not permitted」が出たら、キーの綴りを一つずつ疑います
google-genai SDK で config を渡した途端に pydantic の ValidationError（extra_forbidden）が出る原因は、ほぼ綴りの一字違いです。手元で再現した出力と、呼び出し前に怪しいキーを洗う関数、text が None になる場合の見分け方を書き残します。
停止日のない非推奨をどう扱うか — 画像モデルの移行先を、3つの条件で選び直す
10月6日に gemini-nano-banana-2.1 が GA になり、gemini-3.1-flash-image は停止日の書かれないまま非推奨になりました。解像度・参照画像・検索の3条件で移行先を選ぶ表と、確認用の短いスクリプトをまとめます。
『F6号』と『A4くらい』が同じ列に並ぶ作品台帳を、Gemini の読み取りと号数表の換算で cm に揃えるまで
作家さんの作品台帳に『F6号』『41×31.8cm』『A4くらい』が混ざっていました。Gemini API には読み取りだけを頼み、換算は号数表、向きは画像で決める小さな道具を、動くコードとともに一本ずつ組み立てます。
関数呼び出しが平文に化けるとき、まず疑うのはツール宣言のプロパティ名です
MALFORMED_FUNCTION_CALL を出力上限とスキーマ衝突で潰しきれなかったとき、ツール宣言のプロパティ名を二分探索で絞り込んだ記録です。予約語を名前に置かない線引きと、宣言の手前で落とすリンタまで書き残します。
10月2日に止まる gemini-2.5-flash-image の移行先は、公式表のままでは動きません
gemini-2.5-flash-image の停止は2026年10月2日です。ところが公式の推奨移行先として書かれている gemini-3.1-flash-image-preview は6月25日に停止済みでした。移行先を最後まで辿るスクリプトを書いて表の全行を検査し、同じ構造の行が11件あることを確かめた記録です。
文字起こしの固有名詞が直らないとき、カスタム語彙に何を入れて何を諦めるか
gemini-3.5-transcribe の custom_vocabulary は最大1,000語ですが、枠を埋めることが目的ではありません。誤認ログの正解と出力の対から、枠を渡す語だけを選び直す60行のスクリプトと、その判断基準をまとめます。
値上げの日をまたぐ費用の見積もりを、はじめから二段で書く
Gemini Flash の導入価格は2026年12月31日で終わり、2027年1月1日から標準価格に切り替わります。世代を据え置いても避けられないこの日を、はじめての費用見積もりでどう扱うか。動くコードとともに書き残します。
Lyria 3.5 が来た日に、音源フォルダの置き方を変えました
Lyria 3.5 のフルレングス生成が来たとき、生成した音と配信する音が同じフォルダに並んでいました。名前ではなくハッシュで線を引く、四十数行の台帳ゲートの作り方をお伝えします。
Gemini Omni 1.1 で尺を伸ばす二つの道は、壊れ方が違います
Omni 1.1 のシーン延長は10秒刻みで累計40秒まで、キーフレーム補間は両端を固定して間を生成します。どちらで伸ばすかは最初の1本を作る前に決まってしまいます。尺の割り付けを先に計算する関数と、継ぎ目のずれを数値で追う検査を書き残します。
Gemini 3.8 Flash は単価が据え置きでも、請求が増えることがあります
Gemini 3.8 Flash の単価は 3.7 Flash と同じですが、モデルが手数を増やす設計のため出力トークンが伸びて請求が増えることがあります。切り替え前に測る数字と、年末年始の二本立てで見積もる手順をまとめます。
ループ音源のプチノイズは、Gemini に聴かせる前に波形の端で切り分けられます
環境音のループ再生で折り返しだけがプチッと鳴る。音声理解に丸ごと投げる前に、波形の端の段差を内部の変化量で正規化してふるい分ける手順と、配布形式への変換で継ぎ目が作り直される落とし穴をまとめました。
9月で止まる Gemini の標準 API キーを、CI とサーバーとローカルの三層で棚卸しする
標準 API キーは制限付きのものも含めて9月中に拒否されるようになります。差し替えではなく出どころの移行になるため、コード・デプロイ設定・手元の三層に分けた棚卸しと、両対応クライアントを挟んでから切り替える手順をまとめました。
Gemini の API キーを差し替えても旧キーが勝つ。決め手は読み込み順ではありませんでした
同じ環境変数名を複数の経路が供給していると、キーを差し替えても古い値が残ります。読み込み順を四通り入れ替えた実測と、供給と読み取りを台帳に残す監査シムの実装をまとめました。
gemini-3.5-transcribe の smart モードでは、話者ラベルも単語タイムスタンプも返ってきません
gemini-3.5-transcribe の smart モードは diarization_mode とも timestamp_granularities とも併用できません。mode が文字列とオブジェクトの両方を取る点と、機能を足すと音声の上限が半分になる点を整理します。
Omni Flash の 4K を API 側で受け取るか、配布直前に自分で上げるか
Gemini Omni Flash の 1080p と 4K はアップスケール出力です。解像度を引き上げる地点を配布先から逆算して決める手順と、受け取った動画の細部を自分で確かめる方法をまとめました。
Gemini に渡す前に表が壊れる場所は結合セルと2行ヘッダ
スプレッドシートの表をそのまま Gemini に渡すと、結合セルと2行ヘッダで行の所属が失われます。抽出時点で何が消えるかを実測し、平坦化と集計行の検出までを Python で組みます。
temperature が効いているかを測るより渡した値を記録する方が先です
非推奨になったサンプリングパラメータは 200 が返るまま無視されます。grep と AST が取りこぼした箇所を実行時に拾い、設定の組み立て元まで記録して CI の合否に変えるまでを、実際に動かした結果とともにまとめます。
Gemini TTS を streamGenerateContent で受け取り、先頭のチャンクから鳴らす
Gemini の TTS をストリーミングで受け取ると、音声は「ファイル」ではなく PCM の断片で届きます。チャンクごとに WAV ヘッダを付けた場合に何が起きるかを手元で測り、連結とヘッダの正しい順序を実装まで示します。
アプリに載せる AI 機能を、実行時呼び出しから配布前の一括処理に寄せました
アプリに Gemini を組み込むとき、実行時に呼ぶか配布前に呼び終えるかで呼び出し回数の増え方が変わります。素材数に比例させる設計へ切り替えた判断基準と、冪等な一括処理の実装をまとめました。
メディエーショングループが20を超えたとき、設定の抜けをどう見つけるか
広告メディエーションのグループが増えると、設定の抜けや型のずれが静かに溜まります。設定を1枚の表に正規化して機械でずれを確定させ、判断が必要なセルだけを Gemini に渡す分担にした手順をまとめました。
ANR のスレッドダンプをそのまま Gemini に投げない
ANR ダンプは 96 スレッドで 33,616 文字ありました。main だけを抜けば 98% 減りますが、原因のスレッドは消えます。待ちの連鎖だけを残す前処理を実測しながら組み立てます。
gemini-2.5-flash が「no longer available」で404を返しても、公式表の停止日は未告知のままです
gemini-2.5-flash の停止日は公式の廃止一覧から消えたままですが、404 の報告は7月から出ています。停止日の欄を安全マージンとして読むと外れる理由と、手元のキーで確かめる手順をまとめました。
Gemini 3.7 Flash と 3.1 Pro の使い分けを、速さではなくやり直しのコストで決める
新しい Flash が出るたびにモデル選定をやり直す作業を、判断基準ごと組み替えました。出力の誤りを機械で拾えるかどうかで振り分ける方法と、導入価格が切れる12月31日をまたいだ費用の出し方をまとめています。
generated_images が消えたあとの受け取り方 — 戻り値から画像ファイルになるまでの3つの分岐
generate_content へ書き換えたあと、保存の行で落ちるのは戻り値の形が変わっているからです。画像 part が0件のとき・枚数が揺れるとき・拡張子を決めるときの3分岐と、そのまま使える受け取り関数をまとめます。
Gemini 3.7 Flash の値上げ分は、バッチ層へ移すとちょうど相殺されます
Gemini 3.7 Flash の導入価格は2026年12月31日で終わり、翌日から単価が倍になります。値上げの対象になるモデルとならないモデルを価格表で切り分け、自分の使用量から年明けの請求を先に出すところまでを整理しました。
generate_images は2027年まで残ります。それでも8月17日に画像生成は止まります
google-genai 2.18.1 には generate_images がまだ残っており、SDK の非推奨メッセージが指す期限は2027年です。一方で imagen-4.0 系のモデルは8月17日に止まります。2つの期限の違いと、手元で確認できること・できないことを実測で整理しました。
generate_images から generate_content へ書き換えるとき、引数は素直に移りません
8月17日の Imagen 停止に向けて generate_images を generate_content へ書き換えるとき、17個の引数のうちそのまま移せるのは5個でした。SDK を実際に読んで確かめた対応表と、呼び出し側を止めないための互換レイヤー、API キーなしで形だけ検証する方法をまとめます。
打ち切りは失敗の合図ではありませんでした — ブロッキング挙動を伴う関数呼び出しの設計
呼び出しが返るまで待つブロッキング型のツールをエージェントに持ち込むと、並列化と打ち切りの常識が反転します。サンドボックスの最小ハーネスで実測した数値をもとに、再試行を観測へ振り替える設計と unknown を握りつぶさない扱い方をまとめました。
ストリーミング応答の日本語が静かに欠ける — バイト境界とイベント境界を実測で切り分ける
ストリーミング表示で日本語だけが静かに欠ける現象を、疑似 SSE サーバで実測して切り分けました。UTF-8 のバイト境界とイベント境界という二つの層の壊れ方、英語テストでは検出できない理由、CI に置く意地悪なサーバまで、再現手順つきで整理しています。
停止済みモデルの再試行は、成功レイテンシには出ませんでした
画像生成モデルの停止日が近づいています。停止済みモデルを呼んだときリトライ層が何をするのかを、モックサーバーで再現して計測しました。壊れ方は所要時間と待ち行列に出て、成功レイテンシには出ませんでした。
Memory profiles の更新ポリシーを測って選ぶ — 確定値を守るガードが精度を16ポイント下げた記録
Memory Bank の Memory profiles が GA になり、構造化された記憶を後段へ渡せるようになりました。更新ポリシーを3種類つくって同条件で比較したところ、直感的に正しく見えた防御が精度を下げていました。計測コード一式と、フィールド別TTLへ切り替えるまでの記録です。
environment hooks に置いた門番の実測 — 判定は46マイクロ秒、起動は23ミリ秒
Managed Agents の environment hooks に破壊的コマンドのガードを置くまでの記録です。正規表現の denylist が20件中9件を素通りさせた実測から、argv 分解による検出率100パーセントまでの3段階と、判定より500倍重い起動コストの内訳をまとめました。
temperature 非推奨で先に困ったのは、決定性ではなく多様性の側でした
temperature・top_p・top_k の非推奨化で影響が出たのは決定性ではなく多様性を作る側でした。呼び出し箇所の数え方、多様性を入力層へ移す設計、実効多様度の測り方を実測値とともに残します。
二段構成の採算を決めていたのは昇格率ではなく、昇格した集合の出力長でした
Flash-Lite を前段に置き、迷った分だけ 3.6 Flash に昇格させる二段構成の採算計算を解き直した記録です。昇格率だけで見積もると外れる理由——昇格した集合の出力長が平均より長い——を式に組み込み、損益分岐点がどう動くかを実測で確かめました。
出力トークンが17%減ると聞いて、総額はいくら下がるのかを分解した
出力単価16.67%減と出力トークン17%減が重なったとき、総額はいくら下がるのか。Gemini 3.6 Flash への切り替えを単価・数量・交差項に厳密分解し、エージェントループでは削減率がむしろ下がった実行結果と、請求との突き合わせ方をまとめました。
消えないプロンプト資産をたたむ — 静的参照だけでは見えない稼働経路を炙り出す退役台帳
一本化したはずの旧プロンプトがまだ毎日呼ばれている——そんな見えない稼働経路を炙り出す退役台帳の設計です。静的参照、フラグ既定値、観測窓、モデル停止日、キャッシュ実効率の5つを突き合わせる判定基準と、実運用で得た設計の勘所を実行結果とともにまとめました。
AI Studio の開発者ログを本番の正本にしない — Interactions API を二層で観測する設計
AI Studio に追加された Interactions API の開発者ログを、速報レンズと正本ログに役割分担する設計です。自前の構造化ログと突合コード、100,000 件で測った格納先の容量比較、機能別のコスト按分まで、個人開発の運用視点でまとめました。
会話状態をサーバーに預けるべきか — previous_interaction_id と手元での履歴刈り込みの分岐設計
Interactions API の previous_interaction_id で会話状態をサーバーに預けると、毎回履歴を送らずに済みます。ところが途中で入った巨大なツール出力を後から刈り込めず、以降のターンが重量を引きずる落とし穴があります。サーバー側状態と手元での刈り込みを状況で使い分ける分岐設計を、動くPythonの薄いラッパーとともに整理します。
Managed Agents を background: true で走らせて画面を止めない — 個人開発の非同期ラン設計
Managed Agents の background 実行は結果ではなくラン ID を即座に返します。ポーリングの最小構成と、個人開発での使いどころ、認証情報リフレッシュの注意点を実務目線でまとめました。