invoking-gemini

Gemini の呼び出し

Claude よりも優れている場合は、タスクを Google の Gemini モデルに委任します。

Gemini を使用する場合

画像生成：

• ブログのヘッダー画像、イラスト、図表
• スタイルを指定した画像作成（リソグラフ、エディトリアルなど）
• 画像内のテキスト描画

音声（TTS）：

• 行ごとにスタイルを指定したナレーション、吹き替え、読み上げ
• 文章による説明に基づいて作成するカスタム音声
• 2 人の話者による対話

構造化出力：

• プロパティの順序を保証する JSON Schema の検証
• Pydantic モデルへの準拠
• 厳密なスキーマ準拠（列挙値、必須フィールド）

コストの最適化：

• 並列バッチ処理（Gemini 3 Flash は軽量です）
• 大量のシンプルなタスク

マルチモーダルタスク：

• JSON 出力による画像分析
• 動画処理
• 構造化された音声文字起こし

セットアップ

uv pip install requests pydantic

認証情報 — オプション A（推奨）：Cloudflare AI Gateway

CF_ACCOUNT_ID、CF_GATEWAY_ID、CF_API_TOKEN を含む /mnt/project/proxy.env を読み込みます。 リクエストは Cloudflare AI Gateway 経由でルーティングされ、IP ブロックを回避します。Google API キーは BYOK 経由でゲートウェイに保存されます。

認証情報 — オプション B：Google API に直接接続

proxy.env がない場合は、直接接続にフォールバックします：GOOGLE_API_KEY.txt または API_CREDENTIALS.json。

画像生成

Gemini のネイティブ画像モデルを使用して画像を生成します。イラスト、ブログのヘッダー画像、図表、ビジュアルコンテンツを作成する主な方法です。

クイックスタート

import sys
sys.path.append('/mnt/skills/user/invoking-gemini/scripts')
from gemini_client import generate_image

# One call — returns {"path": "...", "caption": "..."} or None
result = generate_image("A watercolor painting of a mountain lake at sunset")
print(result["path"])  # /mnt/user-data/outputs/gemini_image_1740000000.png

関数シグネチャ

generate_image(
    prompt: str,                    # The image description
    output_path: str = None,        # Auto-generates if omitted
    model: str = "nano-banana-2",   # Default: fast. Use "image-pro" for quality
    temperature: float = 0.7,       # 0.5-0.7 for diagrams, 0.7-0.8 for illustrations
) -> dict | None
# Returns: {"path": "/mnt/user-data/outputs/gemini_image_*.png", "caption": str|None}
# Returns None on failure

モデルの選択

エイリアス	モデル	最適な用途	画像あたりのコスト
"nano-banana-2" または "image"	gemini-3.1-flash-image-preview	素早い反復、下書き	$0.067
"image-pro" または "nano-banana-pro"	gemini-3-pro-image-preview	公開用コンテンツ、テキスト描画	$0.134

ブログのヘッダー画像の完全な例

import sys
sys.path.append('/mnt/skills/user/invoking-gemini/scripts')
from gemini_client import generate_image

# 1. Compose prompt with style prefix + subject
style_prefix = (
    "Style: Risograph-inspired editorial illustration. "
    "Visible halftone dot texture and slight color misregistration between layers. "
    "Limited ink palette: deep indigo, warm coral, and sage green on off-white paper. "
    "Layered transparency where colors overlap creates rich secondary tones. "
    "Modern and professional — the aesthetic of an indie design studio, not a fantasy novel. "
    "Generous whitespace. No photorealism, no glow effects, no cyberpunk. No text or labels."
)
subject = "A raven perched on a stack of books, observing a network graph"
prompt = f"{style_prefix}\n\nSubject: {subject}. Wide landscape format, suitable as a blog header."

# 2. Generate (use image-pro for published content)
result = generate_image(prompt, model="image-pro", temperature=0.75)

if result:
    print(f"Saved: {result['path']}")
    # 3. Present to user
    # present_files([result["path"]])

プロンプトのパターン

• スタイルの接頭辞＋主題：最初にスタイルの説明を置き、その後に主題を説明します
• スタイルを具体的に指定：「素敵な画像」ではなく、「リソグラフ風のエディトリアルイラスト」のように指定します
• 構図を含める：「横長のランドスケープ形式」／「中央配置、高コントラスト」
• テキスト描画：「太い赤文字で「SALE」と書かれたポスター」（image-pro でうまく機能します）
• 除外条件：デフォルトの表現を避けるには、「フォトリアリズムなし、グロー効果なし」と指定します

カスタム出力パス

result = generate_image(
    "A logo for a coffee shop called 'Bean There'",
    output_path="/mnt/user-data/outputs/coffee_logo.png"
)

音声生成（TTS）

Gemini 3.8 Flash TTS と Flash-Lite TTS は、2026-09-23 に一般提供が開始されました。出力は WAV、 24 kHz、モノラル、16 ビットで、SynthID による電子透かしが付与されます。

from gemini_client import generate_speech, design_voice, list_voices

r = generate_speech("Odin kept two ravens. <short pause> Huginn was thought.",
                    output_path="/tmp/line.wav", voice="Algenib",
                    style="quiet and dry, unhurried")
# {'path': '/tmp/line.wav', 'seconds': 4.2, 'audio_tokens': 135} or None

v = design_voice("A low, dry, quietly amused male voice with a faint rasp. "
                 "Soft southern British accent.", "narrator", gender="male",
                 language_code="en-GB")      # {'id': 'voice_...', 'sample_path': ...}
generate_speech("...", voice=v["id"])

lows = list_voices(gender="male", pitch="low")   # library of 2,089 prebuilt voices

• **音声：**スタジオ音声 30 種（Charon、Kore、Algenib「かすれ声」、 Enceladus「息混じりの声」など）に加え、en-gb-storyteller-4 のような ID を持つ ペルソナ音声 2,059 種があります。list_voices() はそれぞれのアクセント、声の高さ、性別、説明を返します。accent フィルターには正確な文字列（「Winchester English」）が必要なため、返されたフィールドに対してアクセントをフィルタリングしてください。
• スタイル：style=（speech_metadata アノテーション）を渡します。テキストの先頭に 「Style: ...」を付けないでください。3.8 モデルはこの接頭辞も読み上げ、systemInstruction は拒否されます。インラインイベントはテキストに記述します：<laugh>、 <sigh>、<breath>、<short pause>。単語を強調するには大文字を使います。
• 設計音声は保存されます（有効期限 1 年、プロジェクトあたり 200 件）。説明は基本的な話し方にも影響します。説明に「思慮深い間」を含めると、行の途中に 1～1.8 秒の間が生じ、行ごとのスタイル指定でも取り除けませんでした。
• **モデルは単語を変更することがあります。**29 行のナレーションでは、「Hmm, I get things wrong」や、「tell him」の代わりに「tell them」といった変更が確認されました。字幕や固定スクリプトを使う場合は、ASR によるチェック（faster-whisper medium.en）と録り直しが必要です。
• **コスト：**音声 1 秒あたり約 32 オーディオトークンです。2026-12-31 までは 3.8 Flash TTS が $9/M（Lite は $6/M）のため、1 分あたり約 $0.02 です。
• 音声複製（30 秒のサンプルと録音した同意クリップからのクローン作成）は組み込まれておらず、EEA、英国、スイス、インド、イリノイ州、テキサス州では利用できません。

基本的なテキストの使用方法

import sys
sys.path.append('/mnt/skills/user/invoking-gemini/scripts')
from gemini_client import invoke_gemini

response = invoke_gemini(
    prompt="Explain quantum computing in 3 bullet points",
    model="flash",  # gemini-3.8-flash (default)
)
print(response)

構造化出力

JSON Schema への準拠を保証するには、Pydantic モデルを使用してください。

from gemini_client import invoke_with_structured_output
from pydantic import BaseModel, Field

class BookAnalysis(BaseModel):
    title: str
    genre: str = Field(description="Primary genre")
    key_themes: list[str] = Field(max_length=5)
    rating: int = Field(ge=1, le=5)

result = invoke_with_structured_output(
    prompt="Analyze the book '1984' by George Orwell",
    pydantic_model=BookAnalysis
)
print(result.title)  # "1984"

ネストされたモデルもサポートされています。 Gemini の responseSchema は $ref／$defs を拒否します。これらは pydantic がネストされたモデルごとに出力するため、送信前にクライアントがインライン化します。

class Finding(BaseModel):
    claim: str
    confidence: Literal["high", "medium", "low"]
    note: str | None = None

class Analysis(BaseModel):
    findings: list[Finding]     # nested — inlined for you
    gaps: list[str]

出力予算には余裕を持たせてください。 思考トークンは max_output_tokens（デフォルトは 32768）に含まれます。値が低すぎると、JSON がオブジェクトの途中で切れてしまい、長さエラーではなく pydantic の解析エラーとして表面化します。現在、クライアントは finishReason=MAX_TOKENS を検出し、明示的に通知します。

並列呼び出し

from gemini_client import invoke_parallel

results = invoke_parallel(
    prompts=["Summarize Hamlet", "Summarize Macbeth", "Summarize Othello"],
    model="lite",  # gemini-3.5-flash-lite — cheap/fast tier for batch
)

利用可能なモデル

現在の最先端の Flash は gemini-3.8-flash（GA 2026-09-02）で、デフォルトモデルであり、flash エイリアスでもあります。Google は 6 週間で 3 世代の Flash をリリースしました。3.6（2026-07-21）、3.7（2026-08-13）、3.8（2026-09-02）です。それぞれ固定エイリアス（flash-3.7、flash-3.6、flash-3.5、flash-3）で引き続き呼び出せ、いずれも提供終了日はありません。以前のドキュメントに記載されていた gemini-3.1-flash-lite-preview はすでに廃止されています（2026-05-25 に提供終了）。

Pro ティアはルーティング対象外です。gemini-3.1-pro-preview は現在の料金で 3.8 Flash より入力が 2.7 倍、出力が 3.2 倍高く、ここで重要となるコーディングおよびエージェント関連のベンチマークでは、3.5 以降の Flash 系列に劣ります。Pro を対象にしないでください。pro エイリアスは現在 gemini-3.8-flash に解決され、「最大限の推論」は Flash で thinking_level='high' を指定することを意味します。

テキスト／推論モデル

モデル	エイリアス	入力／100万	出力／100万	コンテキスト	備考
gemini-3.8-flash	flash	$0.75 → $1.50	$3.75 → $7.50	入力1M／出力64K	デフォルト。 GA 2026-09-02。現行の最先端Flashです。3.7との比較：Terminal-Bench 2.1は90.8%対81.6%、SWE-Bench Proは61.6%対60.4%、SWE-Atlasは51.9%対48.0%、HLEはほぼ同等（45.4%対45.7%）です。Googleによると、より高いeffortでは「より懸命に取り組む」ため、タスクあたりの思考トークンが増えることが予想されます。thinking_levelで指定できるのはlow／medium／highのみです。minimalはHTTP 400を返し、クライアントはlowに引き下げます。デフォルトのmediumでは、1語の返信に思考トークンを79個消費しました（2026-09-03に測定）。推論を必要としないタスクではlowを指定してください。
gemini-3.7-flash	flash-3.7	$0.75 → $1.50	$3.75 → $7.50	1M／64K	GA 2026-08-13。DeepSWE v1.1は3.6の49.0%に対して65.3%、Terminal-Bench 2.1は85.8%です。3.8と同じくminimalには対応していません。Googleは「効率性を最優先するワークロード向けに完全にサポート」し続けています。
gemini-3.6-flash	flash-3.6	$0.75 → $1.50	$3.75 → $7.50	1M／64K	GA 2026-07-21。3.5 Flashより出力トークンが約17%少なくなっています。thinking_level='minimal'を受け付ける最後のFlashです（2026-09-03に確認）。
gemini-3.5-flash	flash-3.5	$1.50	$9.00	1M	GA 2026-05-19。Googleのモデル一覧では現在「legacy」と表示されています。minimalに対応しています。出力料金は3.6～3.8より高くなっています。
gemini-3-flash-preview	flash-3	$0.30	$2.50	1M	旧世代のプレビュー版Flashです。後方互換性のために維持されています。Googleが案内している移行先はgemini-3.6-flashです。提供終了日はありません。
gemini-3.1-pro-preview	—	$2.00（≤200K）／$4.00	$12.00／$18.00	1M	ルーティング対象から非推奨（2026-09-03）。 価格／品質で3.6以降のFlashに劣り、3.5 Flashもほとんどのコーディング／エージェントベンチマークで上回っています。固定されたコードから呼び出す場合に備え、IDはそのまま維持されます。proは現在gemini-3.8-flashに解決されます。3.5 Proは2026-05-19のI/Oで6月提供と発表されましたが、2026-09-03時点でもAPIには登場していません。エイリアスの割り当て前に、同じ価格／品質テストが行われます。
gemini-3.5-flash-lite	lite	$0.30	$2.50	1M	低価格／大量処理向けのティア。 GA 2026-07-21。3.5クラスで最速（出力350トークン／秒）です。SWE-Bench ProとOSWorld-Verifiedではgemini-3-flashを上回ります。
gemini-2.5-flash	stable-flash	$0.30	$2.50	1M	非推奨 — 2025年世代のモデルです。ここにはルーティングしないでください。
gemini-2.5-flash-lite	—	$0.10	$0.40	1M	非推奨 — 価格は安いものの、2025年世代のモデルです。liteは現在gemini-3.5-flash-liteに解決されます。
gemini-2.5-pro	stable-pro	$1.25（≤200K）／$2.50	$10.00／$20.00	1M	非推奨 — 2025年世代のモデルです。ここにはルーティングしないでください。

$0.75 → $1.50は導入価格を表します。Googleの料金ページ（2026-09-03取得）によると、3.6、3.7、3.8 Flashの料金は、2026-12-31までは入力$0.75／出力$3.75、2027-01-01以降は$1.50／$7.50です。コンテキストキャッシュは$0.075 → $0.15、Batchは標準料金の半額です。出力料金には思考トークンが含まれます。

画像モデル

モデル	エイリアス	入力／100万	画像あたり
gemini-3.1-flash-image-preview	image、nano-banana-2	$0.25	$0.067
gemini-3-pro-image-preview	image-pro、nano-banana-pro	$2.00	$0.134

音声モデル

モデル	エイリアス	入力／100万	出力／100万（音声）	備考
gemini-3.8-flash-tts	tts	$0.50 → $1.00	$9.00 → $18.00	GA 2026-09-23。表現力豊かで、130言語、2人の話者に対応しています。invoke_gemini()ではなく、generate_speech()を使用してください。
gemini-3.8-flash-lite-tts	tts-lite	$0.50 → $1.00	$6.00 → $12.00	GA 2026-09-23。大量処理／読み上げ向けで、101言語に対応しています。gemini-3.1-flash-tts-preview（$1／$20）の後継です。

音声のエイリアスはMODEL_ALIASESではなくSPEECH_ALIASESにあるため、テキスト呼び出しが音声モデルに解決されることはありません。

詳細はreferences/models.mdを参照してください。

思考バジェット（Gemini 3.x）

Gemini 3.x モデルは応答する前に推論します。2026 年にパラメーターが変更され、整数の thinking_budget は廃止されました。文字列の thinking_level ∈ {minimal, low, medium, high} を使用してください。3.5～3.8 Flash のデフォルトは medium です。文字起こし／分類／抽出タスクでは、thinking_level='minimal' を渡してください。渡さないと、モデルは推論に出力トークンをひそかに消費します（症状：finishReason=MAX_TOKENS で応答が空になります）。

3.7 と 3.8 Flash は minimal を拒否します。HTTP 400（Thinking level MINIMAL is not supported for this model）が返されます。これらのモデルでは low が下限です。クライアントはこれら 2 つのモデルで minimal を low に引き下げ、stderr に注記を出力するため、既存の呼び出し元はそのまま動作します。3.8 での測定結果（2026-09-03）：1 語の応答では low の思考トークン消費は 0 でしたが、デフォルトの medium では 79 消費しました。3.7 では、low でも 45～88 消費しました。また、max_output_tokens=50 に設定して low で呼び出すと MAX_TOKENS に達して None が返されたため、そこでの出力バジェットは余裕を持って設定してください。本当に思考させない処理が必要なジョブでは、引き続き minimal を受け付ける flash-3.6 または lite を固定してください。

response = invoke_gemini(
    prompt="Transcribe this image.",
    model="flash",
    image_path="/tmp/screenshot.png",
    max_output_tokens=4000,
    thinking_level="minimal",  # don't burn output budget on reasoning
)

エラー処理

response = invoke_gemini(prompt="...", model="flash")
if response is None:
    print("API call failed — check credentials")

result = generate_image("...")
if result is None:
    print("Image generation failed — check credentials or try again")

よくある問題：API キーがない → セットアップを参照してください。レート制限 → バックオフ付きで自動再試行します。ネットワークエラー → None を返します。

高度な機能

カスタム生成設定

response = invoke_gemini(
    prompt="Write a haiku",
    model="flash",                  # gemini-3.8-flash
    temperature=0.9,
    max_output_tokens=200,
    top_p=0.95,
    thinking_level="low",           # haiku is short; modest reasoning is fine
)

マルチモーダル入力

from pydantic import BaseModel
from gemini_client import invoke_with_structured_output

class ImageDescription(BaseModel):
    objects: list[str]
    scene: str
    colors: list[str]

result = invoke_with_structured_output(
    prompt="Describe this image",
    pydantic_model=ImageDescription,
    image_path="/mnt/user-data/uploads/photo.jpg"
)

ほかのパターンについては、references/advanced.md を参照してください。

トラブルシューティング

「No credentials configured」： CF 認証情報を含む /mnt/project/proxy.env を作成するか、GOOGLE_API_KEY.txt を追加してください。

CF Gateway 401/403： CF_API_TOKEN に AI Gateway の権限があることを確認してください。BYOK を使用しない場合は、proxy.env に GOOGLE_API_KEY を追加してください。

インポートエラー： uv pip install requests pydantic

画像生成で None が返される： 認証情報を確認してください。問題が続く場合は、model="nano-banana-2"（image-pro より信頼性が高い）を試してください。エラー出力にコンテンツポリシーによるブロックがないか確認してください。