Gemini Robotics ER 2 API 教程：即時串流機器人、函式呼叫與遷移

Google 於 2026 年 7 月 30 日開放 Gemini Robotics ER 2 Public Preview。這次不是隻替換一個模型名稱，而是同時提供標準推理與即時串流兩條接入路線：

• gemini-robotics-er-2-preview：適合單次圖片、影片分析和多步驟工具編排。
• gemini-robotics-er-2-streaming-preview：透過 Live API 持續接收音訊、影片和文字，適合低延遲機器人互動。

舊版 gemini-robotics-er-1.6-preview 將於 2026 年 8 月 31 日停止服務。已經在使用舊模型的專案，應儘快完成模型名替換與迴歸測試，不要等到停服當天才遷移。

快速結論：應該選擇哪個端點

如果機器人接到一張照片後再規劃動作，或需要分析一段已經錄製的影片，優先使用標準端點。如果機器人需要持續觀察攝影機、接收語音指令，並在會話中反覆呼叫移動、抓取等工具，選擇即時串流端點。

兩者都能接收文字、影象、影片和音訊，但輸出都是文字。如果機器人需要說話，還要把文字交給外部 TTS 服務，或將 TTS 宣告為一個可呼叫工具。

ER 2 的 Embodied Reasoning 是什麼

ER 是 Embodied Reasoning，也就是“具身推理”。普通視覺模型更關注圖片中有什麼，具身推理模型還需要理解物體在哪裡、如何到達、任務進行到了哪一步，以及下一步應該呼叫什麼機器人動作。標準版 ER 2 建立在 Gemini 3.5 Flash 之上，官方重點列出的能力包括：

• 空間推理：識別點位、跟蹤物件、生成邊界框和規劃軌跡。
• Agentic Vision：結合程式碼執行和影象處理完成視覺分析。
• 影片理解：尋找關鍵時刻，判斷任務進度與完成狀態。
• 工具編排：把自定義機器人 API 組合成長流程。
• 多機器人協作：根據任務狀態協調不同裝置。

這並不意味著模型可以直接安全控制真實硬體。模型負責理解與決策建議，開發者仍要在工具執行層限制速度、範圍、許可權和停止條件。

標準版與流式版的功能差異

兩個模型名字相近，支援的 Gemini API 功能卻不完全相同。

標準版還支援 Computer Use、Google Maps Grounding 等能力，但不支援 Live API。流式版專門為持久連線和感測器輸入最佳化，不要因為名字中都有 ER 2，就假設兩邊的配置引數能夠原樣互換。兩者的輸入 token 上限都是 131,072，輸出 token 上限都是 65,536。高解析度輸入和較高 Thinking 等級會增加延遲，需要平衡速度與推理質量時， 官方建議從 Medium Thinking 開始測試。

準備 Python SDK 和 API Key

安裝或更新 Google Gen AI SDK：

1

pip install -U google-genai

然後在環境變數中配置 API Key：

1

$env:GEMINI_API_KEY = "你的_API_Key"

不要把金鑰直接寫進程式碼倉庫。 如果請求返回 403， 還要檢查 API Key 是否完全未受限制。 Robotics API 要求為金鑰新增適當的 API 限制， 未限制的金鑰可能被拒絕。

範例一：用標準端點定位圖片中的物體

下面的例子先上傳圖片， 再要求模型返回最多十個目標點。 座標順序是 [y, x]， 並歸一化到 0 至 1000。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

from google import genai

PROMPT = """
Point to no more than 10 items in the image.
Return JSON objects with point coordinates in [y, x] order,
normalized to 0-1000, and an identifying label.
"""

client = genai.Client()
uploaded_file = client.files.upload(file="my-image.png")

response = client.interactions.create(
    model="gemini-robotics-er-2-preview",
    input=[
        {
            "type": "image",
            "uri": uploaded_file.uri,
            "mime_type": uploaded_file.mime_type,
        },
        {"type": "text", "text": PROMPT},
    ],
    generation_config={"thinking_level": "high"},
)

print(response.output_text)

拿到輸出後不要立刻驅動機械臂。 至少應增加以下驗證：

1. 確認結果可以解析為預期的 JSON 結構。
2. 確認每個座標都在 0 至 1000 範圍內。
3. 把歸一化座標換算成原影象素座標。
4. 拒絕未知標籤、空標籤和數量異常的結果。
5. 透過相機標定將二維位置轉換到機器人座標系。
6. 在執行前檢查工作空間、碰撞風險和置信條件。

如果物體太小或遮擋嚴重， 可以先裁剪並放大目標區域。 光線、對比度和相機視角都會影響空間判斷， 高精度任務可重複查詢並使用一致性結果， 但這仍不能替代感測器與安全控制器。

示例二：把機器人動作宣告為工具

模型不應該直接拼接並執行機器人 SDK 命令。 更穩妥的方式是隻暴露經過稽核的工具， 並對引數進行白名單驗證。 流式 Robotics Live API 中的物理動作必須宣告為阻塞呼叫：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

tools = [
    {
        "function_declarations": [
            {
                "name": "navigate",
                "description": "Navigate to a named safe waypoint.",
                "behavior": "BLOCKING",
                "parameters": {
                    "type": "OBJECT",
                    "properties": {
                        "name": {"type": "STRING"},
                    },
                    "required": ["name"],
                },
            }
        ]
    }
]

"behavior": "BLOCKING" 的含義是： 模型發出動作呼叫後， 必須等待執行端返回結果， 才能繼續規劃下一步。 例如機器人正在移動到安全點， 模型不能在移動尚未完成時， 又假設它已經到位並呼叫抓取工具。 工具執行層還應做到：

• 只允許預先定義的動作名和安全點位。
• 限制機械臂速度、力度、關節角度和活動區域。
• 為每次動作設定超時和取消機制。
• 保留硬體急停與獨立安全聯鎖。
• 把成功、失敗、超時和感測器狀態明確返回給模型。
• 對危險動作增加人工確認或策略引擎審批。
• 記錄模型請求、工具引數、執行結果和時間戳。

模型輸出的自然語言只能作為建議， 不能繞過工具層直接變成電機指令。

即時串流端點如何運作

gemini-robotics-er-2-streaming-preview 使用專用 Live API， 透過持久、帶狀態的 WebSocket 連線保持會話。 典型迴圈分為三步：

1. 在會話配置中宣告機器人動作工具。
2. 持續傳送攝影機、麥克風或文字輸入。
3. 接收工具呼叫，執行機器人 SDK，再回傳工具結果。

音影片輸入還有明確約束：

• 音訊使用原始 PCM、16-bit、16 kHz、小端格式。
• 影片以 JPEG 圖片幀傳送，最高 1 FPS。
• 影片影格本身不會自動觸發模型推理。
• 需要用文字或音訊指令觸發回應。
• 若要持續主動監控，可定期傳送 heartbeat 提示。

最後一點很容易踩坑。 持續上傳攝影機畫面， 不代表模型會在看到異常時主動開口或呼叫工具。 倉庫巡檢、生產線監控等場景， 應設計明確的心跳指令， 例如要求模型檢查最新畫面是否出現阻塞、跌落或人員進入危險區。 心跳頻率也不應無限提高。 要結合 1 FPS 影片上限、延遲、配額和實際風險視窗， 確定合理的檢查週期。

從 ER 1.6 遷移到 ER 2

最小程式碼變更是替換模型字串：

1
2
3

OLD_MODEL = "gemini-robotics-er-1.6-preview"
NEW_MODEL = "gemini-robotics-er-2-preview"
STREAMING_MODEL = "gemini-robotics-er-2-streaming-preview"

但正式遷移不能只看請求是否返回 200。 建議按以下順序處理：

1. 盤點所有程式碼、環境變數和配置檔案中的舊模型名。
2. 按業務型別選擇標準版或流式版，避免機械替換錯誤。
3. 檢查當前依賴的 API 能力是否被目標端點支援。
4. 更新 SDK，並在測試環境使用受限 API Key。
5. 重新驗證工具 schema、阻塞行為和錯誤處理。
6. 用固定測試集對比舊版與 ER 2 的結果。
7. 小流量灰度上線，觀察延遲、失敗率和動作中止率。
8. 在 2026 年 8 月 31 日前移除舊版回退路徑。

迴歸測試集至少應覆蓋：

• 圖片中的指點座標和邊界框。
• 小物體、遮擋物體和低對比度場景。
• 儀表讀數與物體朝向判斷。
• 影片關鍵時刻、任務進度和完成狀態。
• 多步驟函式呼叫的順序與停止條件。
• 工具失敗、超時和返回異常格式。
• 人員進入工作區後的拒絕或安全響應。
• 不同 Thinking 等級下的延遲與質量。

Public Preview 階段仍可能調整行為或介面， 生產專案應鎖定 SDK 版本， 記錄模型標識與測試結果， 並持續關注更新日誌。

安全、隱私與生產部署

機器人模型的錯誤可能造成真實財產損失或人身風險。 開發者需要對物理環境和最終動作負責， 不能把“模型判斷正確”當成安全認證。 生產環境建議把系統拆成三層：

• 理解層：ER 2 負責感知、推理和提出工具呼叫。
• 策略層：驗證許可權、引數、狀態和安全規則。
• 執行層：機器人控制器執行動作並提供硬體保護。

涉及人員的攝影機與麥克風資料時， 應提供明確告知並取得必要同意。 儘量減少個人資料採集， 可以避開可識別人員的畫面， 或在上傳前進行人臉模糊等處理。 日誌中也不要無期限儲存原始音影片、精確位置和身份資訊。 應設定訪問控制、保留期限與刪除機制， 並根據部署地區完成合規評估。

常見問題

ER 2 可以直接輸出機器人動作嗎？

它可以透過函式呼叫選擇開發者定義的機器人動作， 但真實動作仍由你的工具執行層完成。 物理操作應使用阻塞式呼叫， 並經過引數驗證和安全聯鎖。

標準版能使用 Live API 嗎？

不能。 即時串流會話必須使用 gemini-robotics-er-2-streaming-preview。

流式版會自動監控所有影片影格嗎？

不會。 影片影格不會單獨觸發推理， 需要文字、音訊指令或定期 heartbeat。

流式版會直接生成語音嗎？

不會，模型輸出是文字。 語音播報需要外部 TTS， 也可以把 TTS 封裝成工具。

為什麼 API Key 返回 403？

先檢查金鑰是否沒有設定任何限制。 官方說明未受限制的 API Key 會被拒絕， 應為其配置適當的 API 限制， 同時確認專案和 API 許可權正確。

現在是否應該遷移？

應該。 舊版 gemini-robotics-er-1.6-preview 將在 2026 年 8 月 31 日停止服務。 先用固定場景完成對比測試， 再逐步切換生產流量。

總結

Gemini Robotics ER 2 把機器人 API 分成兩條清晰路線： 標準版負責更完整的空間、影片和多步驟推理， 流式版負責低延遲的持續音影片互動。 真正決定專案可靠性的， 不僅是選擇正確的模型名， 還包括阻塞式函式呼叫、工具白名單、狀態回傳、硬體聯鎖， 以及針對真實場景建立可重複的迴歸測試。 如果仍在使用 ER 1.6， 現在就應該開始遷移， 並在停服日期前完成灰度上線與回退方案收尾。

官方資料

• Gemini API 更新日誌
• Gemini Robotics ER 概覽
• Gemini Robotics ER 即時串流指南