johannstark/GeminiRobotics-Skills

Gemini Robotics-ER 2

Gemini Robotics-ER（身体化推論）は、ロボット向けの視覚言語モデルです。画像、動画、音声を入力として認識し、テキスト（JSONの点やボックス、計画、ロボット関数の呼び出し）を出力します。モーターを直接駆動することはありません。ERが提案し、決定論的なコードが実行します。

ここに記載されている内容はすべて、公式ドキュメント（ai.google.dev、2026年10月）、ER 2ノートブック（gemini_robotics_er.ipynb）、およびgoogle-genai 2.31 / @google/genai 2.30に対して確認済みです。

1. エンドポイントとAPIの選択

モデル	API	使用用途	非対応
gemini-robotics-er-2-preview	Interactions API client.interactions.create（従来のgenerateContentも可）	ポインティング、ボックス、軌跡、空間論理、コード実行、関数呼び出しによるオーケストレーション、動画モーメント検出と進捗	Live API
gemini-robotics-er-2-streaming-preview	Live API client.aio.live.connect / ai.live.connect（WebSocket）	リアルタイムエージェント：1FPS以下の連続動画、音声、BLOCKINGツール呼び出し	構造化出力、コード実行、キャッシュ、Interactions
gemini-robotics-er-1.6-preview	—	2026年8月31日非推奨。 モデル文字列を置き換えてください。動画進捗とストリーミングにはER 2が必要です。

両方のER 2エンドポイントは、テキスト、画像、動画、音声を受け入れ、テキストのみを出力します。制限：131,072入力トークン、65,536出力トークン。**デフォルトの思考レベルはhigh**です。レベルはminimal、low、medium、highがあります。ドキュメントでは、レイテンシと品質のバランスとしてmediumを推奨しています。

2. パターンの選択

スクリプト化されたモーションに一度だけ目標が必要な場合？         -> 空間クエリ（点/ボックス）    references/spatial-reasoning.md
小さなテキスト、ゲージ、カウント、切り抜き/ズーム、注釈？      -> エージェント的視覚（code_execution）   references/agentic-vision.md
ロボットAPIを通じて多段階タスクを順番に実行？                  -> オーケストレーション（関数呼び出し）  references/orchestration.md
動作した？いつ？どの程度進んだ？                              -> 動画理解               references/video-progress.md
カメラ/音声に連続的に反応、< 1秒ループ？                     -> Live API + ストリーミングモデル        references/live-api.md
リクエスト/レスポンスの形式、SDKの詳細、移行？              -> Interactions APIリファレンス        references/interactions-api.md

scripts/er_tools.pyはテスト済みのヘルパーを提供します：画像エンコード、応答フォーマット、防御的パーサー、オーケストレーションループ、動画アップロード、タイムスタンプ解析。--selftest（キー不要）または--helpを付けて実行します。

3. 最小限の正しい呼び出し

Python（pip install "google-genai>=2.9.0"；GEMINI_API_KEYを読み取り）：

from google import genai
client = genai.Client()

interaction = client.interactions.create(
    model="gemini-robotics-er-2-preview",
    input=[{"type": "user_input", "content": [                       # またはフラットなパーツリスト
        {"type": "image", "data": png_b64, "mime_type": "image/png"},  # テキストの前にメディア
        {"type": "text", "text": "赤い立方体を指さしてください。ポイントは[y, x]で0～1000に正規化されています。"},
    ]}],
    generation_config={"thinking_level": "medium"},
    response_format={"type": "text", "mime_type": "application/json", "schema": {
        "type": "object", "required": ["items"], "properties": {"items": {"type": "array", "items": {
            "type": "object", "required": ["point", "label"], "properties": {
                "point": {"type": "array", "items": {"type": "integer"}}, "label": {"type": "string"}}}}}}},
)
items = json.loads(interaction.output_text)["items"]

TypeScript（@google/genai >= 2.3.0；リクエストフィールドはスネークケース。サーバーサイドで実行）：

import { GoogleGenAI } from '@google/genai';
const client = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const interaction = await client.interactions.create({
  model: 'gemini-robotics-er-2-preview',
  input: [{ type: 'image', data: pngB64, mime_type: 'image/png' }, { type: 'text', text: prompt }],
  generation_config: { thinking_level: 'medium' },
  response_format: { type: 'text', mime_type: 'application/json', schema },
});
const parsed = JSON.parse(interaction.output_text ?? '{}');

次のようにして応答を読み取ります：interaction.output_text（最終テキスト）、interaction.steps（型付きタイムライン：thought, function_call, code_execution_call, code_execution_result, model_output）、interaction.id（previous_interaction_idとして渡します）。

4. ほとんどのバグを防ぐルール

1. 座標は[y, x]、0～1000に正規化され、送信した画像に対する相対値です。ボックスは[ymin, xmin, ymax, xmax]です。u = x/1000*W、v = y/1000*Hで変換します。すべてのプロンプトで形式を明示してください。
2. Interactionsの形状を使用します。 input=[{"type": "image" | "text" | "video", ...}]、generation_config={...}、response_format={...}。決してconfig=types.GenerateContentConfig(...)、PIL画像、またはInteractionの.text / .function_callsを読み取らないでください。これらはgenerateContentに属します。
3. tools、system_instruction、generation_configはターンごとに指定します。 previous_interaction_idを使用するターンを含め、すべてのinteractions.createで再送信してください。
4. ER 2 / Gemini 3+で**thinking_budgetは使用しないでください**。400エラーが返る可能性があります。thinking_levelを使用してください。
5. スキーマを使用していても、防御的にパースします。 フェンスを削除し、外側のJSONまでスライスし、重複や範囲外の座標を排除し、数を制限します（er_tools.parse_er_json）。
6. キャプチャカメラは逆投影カメラと同一である必要があります：同じ姿勢、内部パラメータ、切り抜き、アスペクト比。キャプチャ時にロボットが対象を隠さないようにしてください。
7. ロボット関数は実際の結果を返します。 失敗時は、is_error: trueと理由を送信してモデルが再計画できるようにします。ツールループはmax_stepsで制限します。移動前にすべての目標をワークスペースとジョイントリミットに対して検証します。
8. Live API： "behavior": "BLOCKING"ツールのみを使用し、1秒あたり最大1フレームの動画を送信し、次のハートビートの前にturn_completeを待ちます（割り込むとアクションがキャンセルされます）。tool_call_cancellationを処理します。
9. キー： 無制限のAPIキーは403エラーになるため、AI Studioで制限を追加してください。キーをブラウザに決して送信しないでください。Interactionsにはバックエンドプロキシを使用し、Liveには一時トークンを使用します（Liveでのみ機能します）。
10. ストレージ： インタラクションはデフォルトで保存されます（store=true：有料プラン55日、無料プラン1日）。store=falseにするとprevious_interaction_idが無効になります。InteractionsはGemini Developer APIの機能であり、gs:// URIは読み取り不可のため、Files APIを使用してください。

5. 効果的なプロンプト（ドキュメントとノートブックより）

• 平易な言葉を使用してください。用語がうまくいかない場合は、同義語（"washer"または"ring"）を試してください。
• 「説明に部分的にしか一致しないアイテムは検出しないでください」と指示すると、誤検出を減らせます。
• 数を制限します（「25個までのアイテム」）。特定の部分が必要な場合は、クエリごとに1つのポイントを要求します。
• 複雑なタスクは個別のプロンプトに分割し、独立したクエリは並列実行します（ノートブックではThreadPoolExecutorを使用）。
• 精度が必要な場合は、複数回クエリを実行し、中央値のポイントを使用します。
• 画像は約800ピクセル幅にリサイズし（ノートブックでも実施）、トークンを節約します。小さなオブジェクトの場合はトリミングまたはズームします。
• 思考レベル：単純な検出やポインティングにはlow、カウント、ペイロードまたはアフォーダンス推論、成功検出、動画にはhighを使用します。mediumがデフォルトの妥協点です。
• 複数の画像や動画グリッドを使用する場合は、プロンプトでレイアウトを説明します（「最初の4枚＝開始、最後の4枚＝現在」；「ビューは左から右へ：トップ、リスト」）。

6. 2Dから3Dへのリフティング（概要）

セットアップ	方法
ブラウザシミュレーション（Three.js）	キャプチャカメラからNDC (x/500-1, 1-y/500)を通じてレイキャスト。threejs-renderingスキルを参照。
Python MuJoCo	同じカメラから深度をレンダリングして逆投影（mujoco-physics/scripts/panda_pick_place.pyのer_point_to_worldを参照）。セグメンテーションで遮蔽を確認。
実RGB-D	Z = depthの中央値、X = (u−cx)Z/fx、Y = (v−cy)Z/fy、次にT_base←cam。
実RGB、テーブルのみ	平面z = z_tableとの交点をレイキャストし、オブジェクトの高さの半分を加算。

深度サンプルまたはレイキャストは上面にヒットするため、把持高さまでオフセットします。ボックスのアスペクトからグリッパーのヨーが決まります：短い辺を閉じます。0～1000の整数グリッドは、おおよそFOV/1000単位（1m幅のビューで約1mm/単位）に量子化されます。

7. Frankaデモについて

Frankaピックアンドプレースデモ（React + Vite + mujoco-js + Three.js）は、これらのスキルが構築されたリファレンスアプリです。以下のファイル名はこれを指します。

• App.tsx::handleErSendは、固定トップビューから≤640ピクセルのPNGをキャプチャし、ERを呼び出します。**SDK 1.x ai.models.generateContent**をthinkingBudget: 0で使用します。ポイントとボックス中心はRenderSystem.project2DTo3Dでレイキャストされます。SequenceAnimatorは、各ターゲットに対してブラインド15ステップのピックを実行します。検証、オーケストレーション、Live APIはありません。
• キーはVite define（process.env.API_KEY）を通じてブラウザに公開されます。デモでは問題ありませんが、本番環境では適切ではありません。
• 正確な1.x→2.xの差分についてはreferences/interactions-api.md#migrating-the-franka-demoを、クローズドループ動作の追加についてはreferences/orchestration.md / references/video-progress.mdを参照してください。

8. 安全性

ERは幻覚や部分的なオブジェクトマッチングを起こす可能性があります。すべての出力を提案として扱ってください：

• ワークスペース境界、可到達性（IK残差）、衝突、速度制限を確認してください。
• 重要なアクションには人間の確認を要求し、物理的な緊急停止ボタンを用意してください。
• 同じロボットAPIの背後でシミュレーションで開発し、その後ハードウェアに切り替えてください。
• カメラやマイクのデータは人を写す可能性があります。同意を得て、顔をぼかし、保持期間を最小限にしてください。https://deepmind.google/models/gemini-robotics/safetyを参照してください。