johannstark/GeminiRobotics-Skills

Gemini Robotics-ER 2

Gemini Robotics-ER (razonamiento incorporado) es un modelo de visión-lenguaje para robots. Ve imágenes, video y audio. Devuelve texto: puntos y cajas JSON, planes, o llamadas a tus funciones robóticas. Nunca acciona motores directamente. ER propone, y el código determinista ejecuta.

Todo aquí fue verificado contra la documentación oficial (ai.google.dev, Oct 2026), el cuaderno ER 2 (gemini_robotics_er.ipynb), y google-genai 2.31 / @google/genai 2.30.

1. Elige el endpoint y la API

Modelo	API	Úsalo para	No compatible con
gemini-robotics-er-2-preview	API Interactions client.interactions.create (también generateContent heredada)	Señalamiento, cajas, trayectorias, lógica espacial, ejecución de código, orquestación con llamadas a funciones, detección de momentos en video y progreso	API Live
gemini-robotics-er-2-streaming-preview	API Live client.aio.live.connect / ai.live.connect (WebSocket)	Agentes en tiempo real: video continuo a ≤1 FPS, audio, llamadas a herramientas BLOQUEANTES	Salida estructurada, ejecución de código, caché, Interactions
gemini-robotics-er-1.6-preview	—	Obsoleto el 31 de agosto de 2026. Cambia la cadena del modelo. El progreso de video y la transmisión necesitan ER 2.

Ambos endpoints de ER 2 aceptan texto, imágenes, video y audio, y solo generan texto. Límites: 131,072 tokens de entrada y 65,536 tokens de salida. El pensamiento por defecto es high. Los niveles son minimal, low, medium y high. Los documentos recomiendan medium como equilibrio entre latencia y calidad.

2. Elige el patrón

¿Necesitas un objetivo único para un movimiento programado?         -> Consulta espacial (puntos / cajas)    references/spatial-reasoning.md
¿Texto pequeño, indicadores, conteo, recorte/zoom, anotación?     -> Visión agéntica (code_execution)       references/agentic-vision.md
¿Tarea multi-paso a través de tu API de robot, turno por turno? -> Orquestación (llamada a funciones)     references/orchestration.md
¿Funcionó? ¿Cuándo? ¿Qué tan avanzado?                             -> Comprensión de video                   references/video-progress.md
¿Reaccionar continuamente a una cámara/voz, con bucle de < 1 s?   -> API Live + modelo de transmisión       references/live-api.md
¿Formas de solicitud/respuesta, detalles del SDK, migración?      -> Referencia de la API Interactions       references/interactions-api.md

scripts/er_tools.py proporciona ayudantes probados: codificación de imágenes, formatos de respuesta, un analizador defensivo, el bucle de orquestación, carga de video y análisis de marcas de tiempo. Ejecútalo con --selftest (no necesita clave), o --help.

3. Llamadas correctas mínimas

Python (pip install "google-genai>=2.9.0"; lee 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": [                       # o una lista plana de partes
        {"type": "image", "data": png_b64, "mime_type": "image/png"},  # medios ANTES del texto
        {"type": "text", "text": "Señala el cubo rojo. Los puntos son [y, x] normalizados a 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; los campos de solicitud están en snake_case; ejecútalo en el 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 ?? '{}');

Lee la respuesta con interaction.output_text (texto final), interaction.steps (línea de tiempo tipeada: thought, function_call, code_execution_call, code_execution_result, model_output), e interaction.id (pásalo como previous_interaction_id).

4. Reglas que previenen la mayoría de errores

1. Las coordenadas son [y, x], normalizadas 0–1000, relativas a la imagen que enviaste. Las cajas son [ymin, xmin, ymax, xmax]. Convierte con u = x/1000*W y v = y/1000*H. Indica el formato en cada prompt.
2. Usa las formas de Interactions. input=[{"type": "image" | "text" | "video", ...}], generation_config={...} y response_format={...}. Nunca pases config=types.GenerateContentConfig(...), imágenes PIL, ni leas .text / .function_calls en una Interaction. Esos pertenecen a generateContent.
3. tools, system_instruction y generation_config son por turno. Vuelve a enviarlos en cada interactions.create, incluidos los turnos que usan previous_interaction_id.
4. No uses thinking_budget con ER 2 / Gemini 3+. Puede devolver errores 400. Usa thinking_level.
5. Analiza defensivamente, incluso con un esquema. Elimina fences, recorta hasta el JSON exterior, descarta duplicados y coordenadas fuera de rango, y limita el conteo (er_tools.parse_er_json).
6. La cámara de captura debe ser igual a la cámara de retroproyección: misma pose, intrínsecos, recorte y relación de aspecto. Mantén al robot alejado de la oclusión del objetivo al capturar.
7. Tus funciones de robot devuelven resultados reales. En caso de fallo, envía is_error: true con una razón para que el modelo replanifique. Limita los bucles de herramientas con max_steps. Valida cada objetivo contra el espacio de trabajo y los límites de las articulaciones antes de moverte.
8. API Live: usa solo herramientas "behavior": "BLOCKING", envía como máximo 1 fotograma de video por segundo, espera turn_complete antes del siguiente latido (de lo contrario, la interrupción cancela la acción), y maneja tool_call_cancellation.
9. Claves: las claves API sin restricciones dan 403, por lo tanto agrega restricciones en AI Studio. Nunca envíes una clave a un navegador. Usa un proxy de backend para Interactions, y tokens efímeros para Live (solo funcionan con Live).
10. Almacenamiento: las interacciones se almacenan por defecto (store=true: 55 días de pago, 1 día gratis). store=false deshabilita previous_interaction_id. Interactions es una característica de la API de Gemini Developer, y las URI gs:// no son legibles, por lo tanto usa la API de Files.

5. Prompting que funciona (de los documentos y el cuaderno)

• Usa lenguaje sencillo. Si un término falla, prueba un sinónimo ("arandela" o "anillo").
• Di "NO detectes elementos que solo coincidan parcialmente con la descripción" para reducir falsos positivos.
• Limita los conteos ("no más de 25 elementos"). Solicita un punto por consulta cuando necesites una parte específica.
• Divide tareas complejas en prompts separados, y ejecuta consultas independientes en paralelo (el cuaderno usa un ThreadPoolExecutor).
• Para precisión, consulta varias veces y toma la mediana del punto.
• Redimensiona las imágenes a unos 800 px de ancho (el cuaderno lo hace) para ahorrar tokens. Recorta o acerca para objetos pequeños.
• Pensamiento: usa low para detección simple o señalización, y high para conteo, razonamiento sobre carga útil o affordance, detección de éxito y video. medium es el compromiso por defecto.
• Con múltiples imágenes o cuadrículas de video, describe la disposición en el prompt ("primeras 4 imágenes = inicio, últimas 4 = ahora"; "vistas de izquierda a derecha: superior, muñeca").

6. Elevación 2D a 3D (resumen)

Configuración	Método
Simulador de navegador (Three.js)	Raycast desde la cámara de captura a través de NDC (x/500-1, 1-y/500). Consulta el skill threejs-rendering.
Python MuJoCo	Renderiza profundidad desde la misma cámara y desproyecta (er_point_to_world en mujoco-physics/scripts/panda_pick_place.py). Revisa la segmentación para oclusión.
RGB-D real	Z = profundidad mediana, X = (u−cx)Z/fx, Y = (v−cy)Z/fy, luego T_base←cam.
RGB real, solo mesa	Intersecta el rayo con el plano z = z_mesa, luego agrega la mitad de la altura del objeto.

Una muestra de profundidad o raycast golpea la superficie superior, por lo tanto desplaza hacia abajo hasta la altura de agarre. El aspecto de la caja da gel guiñada de la pinza: cierra a través del lado corto. Una cuadrícula de enteros 0–1000 cuantiza aproximadamente a FOV/1000 por unidad (aproximadamente 1 mm/unidad para una vista de 1 m de ancho).

7. En la demostración Franka

La demostración de pick-and-place Franka (React + Vite + mujoco-js + Three.js) es la aplicación de referencia a partir de la cual se construyeron estos skills. Los nombres de archivo a continuación se refieren a ella.

• App.tsx::handleErSend captura un PNG de ≤640 px desde una vista superior fija y llama a ER. Usa SDK 1.x ai.models.generateContent con thinkingBudget: 0. Los puntos y los centros de cajas se proyectan con RenderSystem.project2DTo3D. SequenceAnimator luego ejecuta un pick ciego de 15 pasos para cada objetivo. No hay verificación, orquestación ni API Live.
• La clave se expone al navegador a través de define de Vite (process.env.API_KEY). Eso está bien para una demostración, pero no para producción.
• Consulta references/interactions-api.md#migrating-the-franka-demo para la diferencia exacta 1.x→2.x, y references/orchestration.md / references/video-progress.md para agregar comportamiento de bucle cerrado.

8. Seguridad

ER puede alucinar o coincidir parcialmente con objetos. Trata cada salida como una propuesta:

• Revisa los límites del espacio de trabajo, la alcanzabilidad (residual IK), las colisiones y los límites de velocidad.
• Requiere confirmación humana para acciones consecuentes, y mantén un paro de emergencia físico.
• Desarrolla en simulación detrás de la misma API de robot antes de cambiar a hardware.
• Los datos de cámara y micrófono pueden capturar personas. Obtén consentimiento, desenfoca rostros y minimiza la retención. Consulta https://deepmind.google/models/gemini-robotics/safety.