johannstark/GeminiRobotics-Skills

Gemini Robotics-ER 2

Gemini Robotics-ER (raciocínio corporificado) é um modelo de visão-linguagem para robôs. Ele vê imagens, vídeo e áudio. Retorna texto: pontos e caixas JSON, planos ou chamadas para suas funções robóticas. Nunca aciona motores diretamente. ER propõe, e o código determinístico executa.

Tudo aqui foi verificado com a documentação oficial (ai.google.dev, Out 2026), o notebook ER 2 (gemini_robotics_er.ipynb), e google-genai 2.31 / @google/genai 2.30.

1. Escolha o endpoint e a API

Modelo	API	Use para	Não suportado
gemini-robotics-er-2-preview	API de Interações client.interactions.create (também generateContent legado)	Apontamento, caixas, trajetórias, lógica espacial, execução de código, orquestração com chamada de funções, detecção de momentos em vídeo e progresso	Live API
gemini-robotics-er-2-streaming-preview	Live API client.aio.live.connect / ai.live.connect (WebSocket)	Agentes em tempo real: vídeo contínuo a ≤1 FPS, áudio, chamadas de ferramentas BLOCKING	Saída estruturada, execução de código, cache, Interações
gemini-robotics-er-1.6-preview	—	Descontinuado em 31 Ago 2026. Troque a string do modelo. Progresso de vídeo e streaming precisam de ER 2.

Ambos os endpoints ER 2 aceitam texto, imagens, vídeo e áudio, e retornam apenas texto. Limites: 131.072 tokens de entrada e 65.536 tokens de saída. O pensamento padrão é high. Níveis são minimal, low, medium e high. A documentação recomenda medium como equilíbrio entre latência e qualidade.

2. Escolha o padrão

Precisa de um alvo único para um movimento scriptado?         -> Consulta espacial (pontos / caixas)    references/spatial-reasoning.md
Texto pequeno, medidores, contagem, corte/zoom, anotação?     -> Visão agentiva (code_execution)        references/agentic-vision.md
Tarefa de múltiplas etapas através da sua API robótica, turno a turno? -> Orquestração (chamada de funções)  references/orchestration.md
Funcionou? Quando? Quão avançado?                             -> Compreensão de vídeo                  references/video-progress.md
Reagir continuamente a uma câmera / voz, loop < 1 s?         -> Live API + modelo de streaming        references/live-api.md
Formas de requisição/resposta, detalhes do SDK, migração?    -> Referência da API de Interações       references/interactions-api.md

scripts/er_tools.py fornece helpers testados: codificação de imagem, formatos de resposta, um parser defensivo, o loop de orquestração, upload de vídeo e análise de carimbos de data/hora. Execute com --selftest (sem chave necessária) ou --help.

3. Chamadas corretas mínimas

Python (pip install "google-genai>=2.9.0"; lê 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": [                       # ou uma lista plana de partes
        {"type": "image", "data": png_b64, "mime_type": "image/png"},  # mídia ANTES do texto
        {"type": "text", "text": "Aponte para o cubo vermelho. Pontos são [y, x] normalizados para 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"}}}}}}},
)
itens = json.loads(interaction.output_text)["items"]

TypeScript (@google/genai >= 2.3.0; campos de requisição são snake_case; execute no lado do servidor):

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 ?? '{}');

Leia a resposta com interaction.output_text (texto final), interaction.steps (linha do tempo tipada: thought, function_call, code_execution_call, code_execution_result, model_output), e interaction.id (passe como previous_interaction_id).

4. Regras que previnem a maioria dos bugs

1. Coordenadas são [y, x], normalizadas 0–1000, relativas à imagem que você enviou. Caixas são [ymin, xmin, ymax, xmax]. Converta com u = x/1000*W e v = y/1000*H. Indique o formato em cada prompt.
2. Use as formas das Interações. input=[{"type": "image" | "text" | "video", ...}], generation_config={...} e response_format={...}. Nunca passe config=types.GenerateContentConfig(...), imagens PIL, ou leia .text / .function_calls em uma Interaction. Isso pertence ao generateContent.
3. tools, system_instruction e generation_config são por turno. Reenvie-os a cada interactions.create, incluindo turnos que usam previous_interaction_id.
4. Não use thinking_budget com ER 2 / Gemini 3+. Pode retornar erros 400. Use thinking_level.
5. Faça parsing defensivo, mesmo com um esquema. Remova cercas, fatie até o JSON externo, descarte duplicatas e coordenadas fora do intervalo, e limite a contagem (er_tools.parse_er_json).
6. A câmera de captura deve ser igual à câmera de retroprojeção: mesma pose, intrínsecos, corte e proporção. Mantenha o robô longe de ocluir o alvo durante a captura.
7. Suas funções robóticas retornam resultados reais. Em falha, envie is_error: true com um motivo para que o modelo replaneje. Limite loops de ferramentas com max_steps. Valide cada alvo quanto ao espaço de trabalho e limites das juntas antes de mover.
8. Live API: use apenas ferramentas "behavior": "BLOCKING", envie no máximo 1 quadro de vídeo por segundo, aguarde turn_complete antes do próximo heartbeat (caso contrário, a preempção cancela a ação), e trate tool_call_cancellation.
9. Chaves: chaves de API irrestritas geram 403, então adicione restrições no AI Studio. Nunca envie uma chave para um navegador. Use um proxy backend para Interações, e tokens efêmeros para Live (eles funcionam apenas com Live).
10. Armazenamento: interações são armazenadas por padrão (store=true: 55 dias pago, 1 dia grátis). store=false desabilita previous_interaction_id. Interações é um recurso da API Gemini Developer, e URIs gs:// não são legíveis, então use a API de Arquivos.

5. Prompting que funciona (da documentação e do notebook)

• Use linguagem simples. Se um termo falhar, tente um sinônimo ("arruela" ou "anel").
• Diga "NÃO detecte itens que correspondam apenas parcialmente à descrição" para reduzir falsos positivos.
• Limite contagens ("não mais que 25 itens"). Peça um ponto por consulta quando precisar de uma parte específica.
• Divida tarefas complexas em prompts separados, e execute consultas independentes em paralelo (o notebook usa um ThreadPoolExecutor).
• Para precisão, consulte várias vezes e use a mediana dos pontos.
• Redimensione imagens para cerca de 800 px de largura (o notebook faz isso) para economizar tokens. Corte ou amplie para objetos pequenos.
• Pensamento: use low para detecção simples ou apontamento, e high para contagem, raciocínio de payload ou affordance, detecção de sucesso e vídeo. medium é o compromisso padrão.
• Com múltiplas imagens ou grades de vídeo, descreva o layout no prompt ("primeiras 4 imagens = início, últimas 4 = agora"; "vistas da esquerda para a direita: topo, pulso").

6. Elevação 2D para 3D (resumo)

Configuração	Método
Simulador de navegador (Three.js)	Raycast da câmera de captura através de NDC (x/500-1, 1-y/500). Veja a skill threejs-rendering.
Python MuJoCo	Renderize profundidade da mesma câmera e deprojete (er_point_to_world em mujoco-physics/scripts/panda_pick_place.py). Verifique segmentação para oclusão.
RGB-D real	Z = profundidade mediana, X = (u−cx)Z/fx, Y = (v−cy)Z/fy, depois T_base←cam.
RGB real, apenas mesa	Intersecte o raio com o plano z = z_mesa, depois adicione metade da altura do objeto.

Uma amostra de profundidade ou raycast atinge a superfície superior, então desloque para baixo até a altura da garra. A proporção da caixa dá o ângulo de rotação da garra: feche pelo lado curto. Uma grade inteira 0–1000 quantiza aproximadamente para FOV/1000 por unidade (cerca de 1 mm/unidade para uma visão de 1 m de largura).

7. No demo Franka

O demo Franka de pegar e colocar (React + Vite + mujoco-js + Three.js) é o aplicativo de referência a partir do qual estas skills foram construídas. Nomes de arquivos abaixo se referem a ele.

• App.tsx::handleErSend captura um PNG ≤640 px de uma vista superior fixa e chama ER. Ele usa SDK 1.x ai.models.generateContent com thinkingBudget: 0. Pontos e centros de caixa são raycast com RenderSystem.project2DTo3D. SequenceAnimator então executa um pick cego de 15 passos para cada alvo. Não há verificação, orquestração ou Live API.
• A chave é exposta ao navegador através de Vite define (process.env.API_KEY). Isso é aceitável para um demo, mas não para produção.
• Veja references/interactions-api.md#migrating-the-franka-demo para o diff exato 1.x→2.x, e references/orchestration.md / references/video-progress.md para adicionar comportamento em malha fechada.

8. Segurança

ER pode alucinar ou corresponder parcialmente a objetos. Trate cada saída como uma proposta:

• Verifique limites do espaço de trabalho, alcançabilidade (resíduo de cinemática inversa), colisões e limites de velocidade.
• Exija confirmação humana para ações consequentes, e mantenha um botão de parada de emergência física.
• Desenvolva em simulação atrás da mesma API robótica antes de trocar para hardware.
• Dados de câmera e microfone podem capturar pessoas. Obtenha consentimento, desfoque rostos e minimize a retenção. Veja https://deepmind.google/models/gemini-robotics/safety.