Snapshot de la ESP32-CAM por URL: una petición, un JPEG

Obtén una foto de la ESP32-CAM con una sola petición GET: URL /api/capture, resolución y calidad, la respuesta busy, ejemplos con curl y Home Assistant.

Publicado
Tiempo de lectura
9 min
Categoría
Proyectos
Una chica con trenzas sostiene una taza mientras una ESP32-CAM apunta a una planta y una ventana del navegador con la dirección /api/capture muestra la misma planta.

En resumen

El snapshot de la ESP32-CAM es una petición GET que devuelve un JPEG. Gizmo Camera responde en /api/capture?resolution=SVGA, hace una foto a la vez y a una segunda petición le contesta 503 camera_busy. Sin login.

El snapshot de una ESP32-CAM es una única petición HTTP GET que devuelve un único JPEG. Con el firmware de Gizmo Camera la URL es http://gizmo-camera.local/api/capture?resolution=SVGA: la ESP32-CAM hace una foto nueva, la envía y cierra la conexión. La misma petición funciona desde un navegador, con curl, desde un script o desde Home Assistant.

¿Necesitas una foto de la ESP32-CAM dentro de un script y no una página de vídeo que tengas que dejar abierta? En este post repasamos los endpoints reales de Gizmo Camera, comandos curl para copiar y pegar, las opciones de resolución y calidad, y qué responde la cámara cuando dos clientes piden a la vez. Todo sale del código fuente del firmware en el repositorio gizmo-camera, del ejemplo CameraWebServer de Arduino con el que lo comparo y de la documentación del driver esp32-camera. No he hecho benchmarks, así que aquí no hay cifras de velocidad.

Proyecto open source ESP32-CAM
Gizmo Camera

Cámara Wi-Fi con ESP32-CAM que saca una foto JPEG por petición, con una app web para configurarla desde el teléfono y un servidor MCP para agentes de IA.

  • Fotos JPEG de hasta 1600 × 1200
  • API HTTP sencilla
  • Servidor MCP para agentes de IA
Echar un vistazo

¿Qué diferencia hay entre un snapshot y un stream?

Un snapshot es una petición y una imagen: el cliente pide, la cámara captura un frame y la conexión termina. Un stream es una conexión que sigue abierta mientras la cámara no deja de enviar frames. En el ejemplo CameraWebServer estándar, /capture es el snapshot (su handler no lee ningún parámetro de la query, así que no hay opciones que añadir a la URL), y /stream es una respuesta multipart/x-mixed-replace que se repite hasta que el cliente se va, servida por un segundo servidor HTTP en el puerto siguiente al primero.

Son, por tanto, dos herramientas distintas. La tabla compara para qué sirve cada una, según el código de CameraWebServer y el de Gizmo Camera.

Snapshot (/capture, /api/capture)Stream MJPEG (/stream)
ConexiónSe cierra tras un JPEGAbierta hasta que el cliente se va
Código del clienteUn GET, cualquier librería HTTPUn cliente que sepa leer partes multipart
Trabajo de la cámaraSolo cuando alguien pideUn bucle que no para mientras alguien mira
Ideal paraScripts, tareas cron, Home Assistant, agentesVer en directo en el navegador
En Gizmo CameraSí: /api/captureNo: no se ofrece

Gizmo Camera no tiene stream, y es a propósito: su README describe una cámara que "answers every request with a fresh photo". Si lo que quieres es vídeo en directo, el ejemplo CameraWebServer es el punto de partida más sencillo, y el resto de este post trata del snapshot.

¿Cómo se obtiene un JPEG con curl?

Necesitas una cámara con el firmware de Gizmo Camera en la misma red que tu computadora. Si todavía estás en la fase de flasheo, la guía de la ESP32-CAM-MB lo cubre. Después basta un comando:

Haz una foto y guárdala
curl -o photo.jpg "http://gizmo-camera.local/api/capture?resolution=SVGA"

Es el comando del README del proyecto. Abre photo.jpg: deberías ver lo que ve la cámara, a 800 x 600. Si gizmo-camera.local no se resuelve en tu computadora, usa la dirección IP de la cámara, que aparece en tu router y en la página de la cámara de la aplicación web. Los motivos están en la guía del hostname .local.

Antes de celebrar, mira también las cabeceras. Añade -D - para imprimirlas (la opción -D escribe las cabeceras recibidas en un archivo, y - significa salida estándar):

Lee las cabeceras de la respuesta
curl -sS -D - -o /dev/null "http://gizmo-camera.local/api/capture?resolution=SVGA"

La respuesta debería ser parecida a esta, con tu propio tiempo de captura:

Código
Código
HTTP/1.1 200 OK
Content-Type: image/jpeg
Content-Disposition: inline; filename=snapshot.jpg
Cache-Control: no-store
X-Resolution: 800x600
X-Capture-Time-Ms: <milliseconds>
Lín. 6, col. 1UTF-8http

Vienen directamente de capture.get.cpp: X-Resolution es el tamaño real del frame que devolvió el sensor, X-Capture-Time-Ms es lo que tardó la captura en la cámara (no la transferencia) y Cache-Control: no-store avisa a los proxies de que cada petición es una foto nueva.

¿Qué opciones acepta /api/capture?

Tres parámetros de la query, todos opcionales y combinables. El firmware los lee en capture_options.cpp.

ParámetroValoresPor defecto
resolutionUn nombre de la tabla de abajo, en mayúsculas o minúsculasLa mayor que admite el sensor (UXGA en el OV2640)
qualityUn número entero de 4 a 63, cuanto más bajo, más nítido y más pesado10
flash1, true, 0 o falseApagado

Un ejemplo completo es /api/capture?resolution=XGA&quality=12&flash=1. Un valor incorrecto se rechaza con HTTP 400 y un error JSON, y no se hace ninguna foto: invalid_resolution, resolution_not_supported (un tamaño mayor que el que admite el sensor), invalid_quality o invalid_flash. El cuerpo tiene esta forma: { "errorId": "invalid_quality", "errorMessage": "...", "data": null }, la misma que usan todos los dispositivos de OpenGizmo. Para saber qué admite una cámara concreta, pide GET /api/camera: devuelve el nombre del sensor, la lista de resoluciones con sus tamaños, el rango de calidad y hasFlash.

Los cinco pasos de GET /api/capture: revisar las opciones, reservar la cámara, descartar frames viejos, capturar un JPEG, enviarlo y liberar el buffer

¿Cómo se eligen la resolución y la calidad JPEG?

Los tamaños son los valores framesize_t del driver esp32-camera, que el firmware asocia a nombres en capture_options.h y camera.cpp. El README lista estos nueve para el OV2640; el firmware conoce otros mayores para sensores más grandes como el OV3660 y el OV5640, y recorta la lista a lo que declara el sensor conectado.

Nombre en la URLConstante del driverTamaño (px)
QQVGAFRAMESIZE_QQVGA160 x 120
QVGAFRAMESIZE_QVGA320 x 240
CIFFRAMESIZE_CIF400 x 296
VGAFRAMESIZE_VGA640 x 480
SVGAFRAMESIZE_SVGA800 x 600
XGAFRAMESIZE_XGA1024 x 768
HDFRAMESIZE_HD1280 x 720
SXGAFRAMESIZE_SXGA1280 x 1024
UXGAFRAMESIZE_UXGA1600 x 1200

¿Cómo elegir? Empieza en SVGA: es lo que recomienda la propia guía para agentes de Gizmo Camera para entender una escena, y es el valor por defecto del servidor MCP. Sube a UXGA solo cuando necesites detalles pequeños, porque el README advierte de que un JPEG de 1600 x 1200 pesa unos cientos de KB por Wi-Fi. Baja a VGA o QVGA para una miniatura de estado.

La calidad JPEG funciona al revés de lo que mucha gente espera. El README de esp32-camera dice que el rango es de 0 a 63 para los sensores OV y que "lower number means higher quality". Gizmo Camera acepta de 4 a 63, y un comentario en capture_options.h explica el límite: por debajo de 4 el frame buffer puede desbordarse a la resolución más alta. El tamaño del archivo también depende de la escena, así que no doy cifras: cambia quality y compara tú mismo Content-Length.

Conviene conocer dos detalles de cómo aplica la cámara tus opciones. Tras un cambio de resolución o de calidad, el firmware descarta tres frames antes del que envía, porque los primeros frames después de cambiar los ajustes pueden salir corruptos o usar todavía los ajustes anteriores. Para una petición sin cambios descarta un frame viejo, así recibes una foto tomada después de tu petición y no una que estaba esperando en el buffer. Con flash=1 descarta al menos dos. El LED del GPIO4 se enciende 150 ms antes del frame y se apaga justo después. Esos 150 ms son el mismo retardo que usa el ejemplo CameraWebServer, y el flash es un pico de corriente: si la placa se reinicia cuando dispara, lee la guía del brownout.

¿Por qué un snapshot le conviene más a una placa pequeña que un stream?

Para una placa pequeña, la diferencia está en cuánto tiempo mantienes ocupadas la cámara y la conexión. El firmware de Gizmo Camera arranca el sensor con un solo frame buffer (fb_count = 1) en PSRAM y CAMERA_GRAB_WHEN_EMPTY, y manda el JPEG al cliente directamente desde ese buffer, sin copiarlo. El ejemplo CameraWebServer, cuando encuentra PSRAM, usa dos buffers y CAMERA_GRAB_LATEST. El README de esp32-camera dice que más de un buffer en modo JPEG mantiene al driver capturando de forma continua, lo que cuesta CPU y memoria a cambio de más frames por segundo: encaja con un stream y es más de lo que necesita un snapshot.

No medí el uso de memoria ni los tiempos de frame, así que tómalo como un razonamiento de diseño basado en el código, no como un benchmark. Lo que el código sí muestra es sencillo: entre peticiones, una cámara de snapshots está en reposo. No hay ningún bucle capturando frames para un espectador que quizá ya se fue, ni un segundo puerto para el stream. Un script que quiere una foto por hora le cuesta a la cámara una captura por hora.

¿Qué pasa cuando dos clientes piden a la vez?

La cámara le responde al segundo con un error. Gizmo Camera retiene el frame buffer desde el momento en que se toma un snapshot hasta que se envía su respuesta, o el cliente se va, y solo se puede retener un snapshot a la vez. Una petición que llega mientras tanto recibe HTTP 503 con este cuerpo:

Un teléfono y una laptop envían una petición a una sola ESP32-CAM sobre un trípode con el cartel busy, mientras la segunda petición espera con un icono de reloj

Código
Código
{
  "errorId": "camera_busy",
  "errorMessage": "The camera is taking another snapshot",
  "data": null
}
Lín. 5, col. 1UTF-8JSON

La petición del cliente A retiene el frame buffer y recibe un JPEG 200, mientras la del cliente B recibe 503 camera_busy

Los demás fallos también son JSON: camera_unavailable (503) cuando el sensor no arrancó, lo que en la práctica suele apuntar al cable plano, y capture_failed (500) cuando el sensor no entregó ningún frame. El firmware sigue funcionando sin cámara para que la aplicación web pueda decir qué falla.

Trata camera_busy como un "vuelve a intentarlo en un momento", no como una avería. curl puede hacerlo por ti: su documentación incluye el HTTP 503 entre los errores transitorios que --retry repite, con una espera que crece de forma exponencial.

Deja que curl reintente mientras la cámara está ocupada
curl --retry 3 -fsS -o photo.jpg "http://gizmo-camera.local/api/capture?resolution=SVGA"

Con -f, curl falla ante cualquier código de error en lugar de guardar el error JSON como photo.jpg. Una advertencia: reintentar significa una foto nueva cada vez, y con flash=1 el LED vuelve a dispararse. La aplicación web hace lo contrario a propósito: su useDeviceApi.js pone retry: 0 para los snapshots.

¿Cómo piden la imagen los scripts y Home Assistant?

Sirve cualquier cliente HTTP, porque es un GET normal. Para un time-lapse basta un bucle con curl y una marca de tiempo en el nombre del archivo, y una entrada de cron hace lo mismo con una programación horaria. Usa un solo cliente por cámara, o añade el reintento de antes, para que dos tareas no choquen. Un time-lapse de una foto por minuto es un pequeño bucle de shell:

Una foto cada 60 segundos
while true; do curl -fsS -o "shot-$(date +%s).jpg" "http://gizmo-camera.local/api/capture?resolution=SVGA"; sleep 60; done

Páralo con Ctrl+C. Cada archivo lleva en el nombre la hora Unix de la foto.

Para Home Assistant, la integración Generic Camera tiene un campo Still Image URL, descrito como la URL en la que tu cámara sirve la imagen. Pon ahí la URL del snapshot:

Código
Código
http://192.168.1.50/api/capture?resolution=SVGA
Lín. 1, col. 1UTF-8Texto sin formato

La dirección IP es un ejemplo: usa la de tu cámara. Aquí la IP es la opción más segura, porque un host de Home Assistant no siempre resuelve los nombres .local. No he probado esto en una instalación de Home Assistant, y el comportamiento de sondeo de la integración no lo verifiqué, así que comprueba cada cuánto pide la imagen antes de apuntarla a una cámara que también esté abierta en la aplicación web: una segunda petición durante una captura es un camera_busy.

¿Es seguro dejar abierta la URL del snapshot?

No la protege ninguna autenticación. La cámara no tiene login, así que cualquiera que llegue a ella en tu red puede hacer una foto. El firmware añade dos comprobaciones de la librería compartida gizmo-common: se rechazan los navegadores de otros sitios web (la comprobación de Origin), y las peticiones deben usar como host el nombre o la dirección de la propia cámara, lo que protege contra el DNS rebinding. Las peticiones directas desde curl o desde un script, con el nombre o la IP de la cámara, funcionan. Esas comprobaciones no son un login.

Mantenla en una red de confianza y nunca reenvíes su puerto en el router. El post sobre MCP trata el mismo límite para los agentes de IA. El ejemplo CameraWebServer es parecido en espíritu: sus /capture y /stream responden con Access-Control-Allow-Origin: *, así que cualquier página web puede leerlos.

Qué recordar

Un GET /api/capture devuelve un JPEG, tomado después de tu petición, con la resolución y la calidad que indiques: ?resolution=SVGA&quality=10 es un buen punto de partida, y las cabeceras de la respuesta te dicen el tamaño real y el tiempo de captura. La cámara hace un snapshot a la vez, así que una segunda petición recibe 503 camera_busy y simplemente debe reintentar. El flash se activa con flash=1.

Los límites: el endpoint no tiene autenticación, no hice benchmarks de tiempos de captura ni de tamaños de archivo, y los pasos de Home Assistant no están probados aquí. Si una placa se reinicia cuando pides fotos con flash, el primer sospechoso es la alimentación. Para los pines que usa la cámara, mira qué GPIO de la ESP32-CAM están realmente libres, y para la familia de proyectos, ¿Qué es OpenGizmo?

Preguntas frecuentes

Encuentra respuestas rápidas a las preguntas más comunes sobre este tema.

Depende del firmware. El ejemplo CameraWebServer de Arduino sirve el snapshot en /capture. Gizmo Camera lo sirve en /api/capture, por ejemplo http://gizmo-camera.local/api/capture?resolution=SVGA, y devuelve un JPEG. En Gizmo Camera puedes añadir las opciones resolution, quality y flash. Abre la URL en el navegador o descárgala con curl.

Publicado

¿Listo para montar tu propio gizmo?

Elige un proyecto open source con ESP32 y sigue su guía paso a paso, desde la lista de componentes y el cableado hasta el firmware y el primer arranque.

Lee también

Explora las categorías