Snapshot ESP32-CAM via URL: una richiesta, un JPEG
Come avere una foto dalla ESP32-CAM con una sola GET: l'URL /api/capture, risoluzione e qualità, la risposta busy, esempi con curl e Home Assistant.
- Autore
Mauro Brambilla- Pubblicato
- Tempo di lettura
- 8 min
- Categoria
- Build

In breve
Lo snapshot della ESP32-CAM è una richiesta GET che restituisce un JPEG. Gizmo Camera risponde a /api/capture?resolution=SVGA, scatta una foto alla volta e a una seconda richiesta risponde 503 camera_busy. Nessun login.
Lo snapshot di una ESP32-CAM è una singola richiesta HTTP GET che restituisce un singolo JPEG. Con il firmware di Gizmo Camera l'URL è http://gizmo-camera.local/api/capture?resolution=SVGA: la ESP32-CAM scatta una foto nuova, la invia e chiude la connessione. La stessa richiesta funziona da browser, con curl, da uno script o da Home Assistant.
Ti serve una foto dalla ESP32-CAM dentro uno script, e non una pagina video da tenere aperta? In questo post vediamo gli endpoint veri di Gizmo Camera, i comandi curl da copiare e incollare, le opzioni di risoluzione e qualità, e cosa risponde la camera quando due client la interrogano insieme. Tutto arriva dal codice sorgente del firmware nel repository gizmo-camera, dall'esempio Arduino CameraWebServer con cui lo confronto e dalla documentazione del driver esp32-camera. Non ho fatto benchmark, quindi qui non trovi numeri sulla velocità.
Una fotocamera Wi-Fi con ESP32-CAM che scatta una foto JPEG a ogni richiesta, con una web app per configurarla dal telefono e un server MCP per gli agenti AI.
- Foto JPEG fino a 1600 × 1200
- API HTTP semplice
- Server MCP per agenti AI
Che differenza c'è tra snapshot e stream?
Uno snapshot è una richiesta e un'immagine: il client chiede, la camera cattura un frame e la connessione finisce. Uno stream è una connessione che resta aperta mentre la camera continua a mandare frame. Nell'esempio CameraWebServer standard, /capture è lo snapshot (il suo handler non legge nessun parametro della query, quindi non ci sono opzioni da aggiungere all'URL), mentre /stream è una risposta multipart/x-mixed-replace che va avanti finché il client non se ne va, servita da un secondo server HTTP su una porta sopra la prima.
Sono quindi due strumenti diversi. La tabella confronta a cosa serve ciascuno, in base al sorgente di CameraWebServer e a quello di Gizmo Camera.
| Snapshot (/capture, /api/capture) | Stream MJPEG (/stream) | |
|---|---|---|
| Connessione | Chiusa dopo un JPEG | Aperta finché il client non se ne va |
| Codice del client | Una GET, qualsiasi libreria HTTP | Un client che sa leggere le parti multipart |
| Lavoro della camera | Solo quando qualcuno chiede | Un ciclo che non si ferma mai finché c'è chi guarda |
| Ideale per | Script, cron job, Home Assistant, agenti | Guardare dal vivo nel browser |
| In Gizmo Camera | Sì: /api/capture | No: non c'è |
Gizmo Camera non ha uno stream, ed è voluto: il suo README descrive una camera che "answers every request with a fresh photo". Se invece vuoi il video dal vivo, l'esempio CameraWebServer è il punto di partenza più semplice, e il resto di questo post riguarda la strada dello snapshot.
Come si ottiene un JPEG con curl?
Ti serve una camera con il firmware di Gizmo Camera, sulla stessa rete del tuo computer. Se sei ancora alla fase del flashing, la guida alla ESP32-CAM-MB la spiega. Poi basta un comando:
curl -o photo.jpg "http://gizmo-camera.local/api/capture?resolution=SVGA"È il comando del README del progetto. Apri photo.jpg: dovresti vedere ciò che vede la camera, a 800 x 600. Se gizmo-camera.local non si risolve sul tuo computer, usa l'indirizzo IP della camera, che trovi nel router e nella pagina della camera della web app. I motivi sono nella guida all'hostname .local.
Prima di esultare, guarda anche gli header. Aggiungi -D - per stamparli (l'opzione -D scrive gli header ricevuti in un file, e - significa standard output):
curl -sS -D - -o /dev/null "http://gizmo-camera.local/api/capture?resolution=SVGA"La risposta dovrebbe essere simile a questa, con il tuo tempo di cattura:
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>Arrivano direttamente da capture.get.cpp: X-Resolution è la dimensione reale del frame restituito dal sensore, X-Capture-Time-Ms è il tempo che la cattura ha richiesto sulla camera (non il trasferimento) e Cache-Control: no-store dice ai proxy che ogni richiesta è una foto nuova.
Quali opzioni accetta /api/capture?
Tre parametri della query, tutti facoltativi e combinabili. Il firmware li legge in capture_options.cpp.
| Parametro | Valori | Default |
|---|---|---|
| resolution | Un nome della tabella qui sotto, maiuscole o minuscole | La più grande che il sensore supporta (UXGA sull'OV2640) |
| quality | Un numero intero da 4 a 63, più basso è più nitido e più pesante | 10 |
| flash | 1, true, 0 o false | Spento |
Un esempio completo è /api/capture?resolution=XGA&quality=12&flash=1. Un valore sbagliato viene rifiutato con HTTP 400 e un errore JSON, e nessuna foto viene scattata: invalid_resolution, resolution_not_supported (una dimensione più grande di quella che il sensore supporta), invalid_quality o invalid_flash. Il corpo ha questa forma: { "errorId": "invalid_quality", "errorMessage": "...", "data": null }, la stessa di tutti i dispositivi OpenGizmo. Per sapere cosa supporta una camera in particolare, chiedi GET /api/camera: restituisce il nome del sensore, l'elenco delle risoluzioni con le loro dimensioni, l'intervallo di qualità e hasFlash.

Come si scelgono risoluzione e qualità JPEG?
Le dimensioni sono i valori framesize_t del driver esp32-camera, che il firmware associa a dei nomi in capture_options.h e camera.cpp. Il README elenca queste nove per l'OV2640; il firmware ne conosce di più grandi per sensori più capaci come l'OV3660 e l'OV5640, e taglia l'elenco a ciò che il sensore collegato dichiara.
| Nome nell'URL | Costante del driver | Dimensione (px) |
|---|---|---|
| QQVGA | FRAMESIZE_QQVGA | 160 x 120 |
| QVGA | FRAMESIZE_QVGA | 320 x 240 |
| CIF | FRAMESIZE_CIF | 400 x 296 |
| VGA | FRAMESIZE_VGA | 640 x 480 |
| SVGA | FRAMESIZE_SVGA | 800 x 600 |
| XGA | FRAMESIZE_XGA | 1024 x 768 |
| HD | FRAMESIZE_HD | 1280 x 720 |
| SXGA | FRAMESIZE_SXGA | 1280 x 1024 |
| UXGA | FRAMESIZE_UXGA | 1600 x 1200 |
Come scegliere? Parti da SVGA: è ciò che la guida per gli agenti di Gizmo Camera consiglia per capire una scena, ed è il default del server MCP. Passa a UXGA solo quando ti servono i dettagli piccoli, perché il README avverte che un JPEG da 1600 x 1200 pesa qualche centinaio di KB via Wi-Fi. Scendi a VGA o QVGA per una miniatura di stato.
La qualità JPEG funziona al contrario di come molti si aspettano. Il README di esp32-camera dice che l'intervallo va da 0 a 63 per i sensori OV e che "lower number means higher quality". Gizmo Camera accetta da 4 a 63, e un commento in capture_options.h spiega il limite: sotto 4 il frame buffer può andare in overflow alla risoluzione più alta. Anche la dimensione del file dipende dalla scena, quindi non do cifre: cambia quality e confronta tu Content-Length.
Due dettagli su come la camera applica le tue opzioni vale la pena conoscerli. Dopo un cambio di risoluzione o di qualità, il firmware scarta tre frame prima di quello che invia, perché i primi frame dopo una modifica delle impostazioni possono essere corrotti o usare ancora le impostazioni vecchie. Per una richiesta invariata scarta un frame vecchio, così ricevi una foto scattata dopo la tua richiesta e non una rimasta nel buffer. Con flash=1 ne scarta almeno due. Il LED su GPIO4 si accende 150 ms prima del frame e si spegne subito dopo. Quei 150 ms sono lo stesso ritardo dell'esempio CameraWebServer, e il flash è un picco di corrente: se la scheda si resetta quando scatta, leggi la guida al brownout.
Perché lo snapshot è più adatto a una scheda piccola di uno stream?
Per una scheda piccola, la differenza sta in quanto a lungo tieni occupate la camera e la connessione. Il firmware di Gizmo Camera avvia il sensore con un solo frame buffer (fb_count = 1) in PSRAM e CAMERA_GRAB_WHEN_EMPTY, e manda il JPEG al client direttamente da quel buffer, senza copiarlo. L'esempio CameraWebServer, quando trova la PSRAM, usa due buffer e CAMERA_GRAB_LATEST. Il README di esp32-camera dice che più di un buffer in modalità JPEG tiene il driver in cattura continua, il che costa CPU e memoria in cambio di un frame rate più alto: va bene per uno stream, è più di quanto serva a uno snapshot.
Non ho misurato l'uso di memoria né i tempi dei frame, quindi prendila come un ragionamento di progetto basato sul sorgente, non come un benchmark. Ciò che il codice mostra è semplice: tra una richiesta e l'altra, una camera da snapshot sta ferma. Non c'è nessun ciclo che cattura frame per uno spettatore che magari se n'è andato, e non c'è una seconda porta per lo stream. Uno script che vuole una foto all'ora costa alla camera una cattura all'ora.
Cosa succede quando due client chiedono insieme?
La camera risponde al secondo con un errore. Gizmo Camera tiene il frame buffer dal momento in cui scatta uno snapshot fino a quando la risposta è stata inviata, o il client se n'è andato, e si può tenere un solo snapshot alla volta. Una richiesta che arriva nel frattempo riceve HTTP 503 con questo corpo:

{
"errorId": "camera_busy",
"errorMessage": "The camera is taking another snapshot",
"data": null
}
Gli altri errori sono anch'essi JSON: camera_unavailable (503) quando il sensore non è partito, il che in pratica di solito significa il cavo flat, e capture_failed (500) quando il sensore non ha dato nessun frame. Il firmware continua a girare anche senza camera, così la web app può dire cosa non va.
Considera camera_busy come un "riprova tra un attimo", non come un guasto. curl può farlo per te: la sua documentazione elenca HTTP 503 tra gli errori transitori che --retry ripete, con un'attesa che cresce in modo esponenziale.
curl --retry 3 -fsS -o photo.jpg "http://gizmo-camera.local/api/capture?resolution=SVGA"Con -f curl fallisce con qualsiasi codice di errore invece di salvare l'errore JSON come photo.jpg. Attenzione però: ritentare significa una foto nuova ogni volta, e con flash=1 il LED scatta di nuovo. La web app fa il contrario di proposito: il suo useDeviceApi.js imposta retry: 0 per gli snapshot.
Come prendono l'immagine gli script e Home Assistant?
Va bene qualsiasi client HTTP, perché è una semplice GET. Per un time-lapse basta un ciclo con curl e un timestamp nel nome del file, e una riga di cron fa lo stesso a orari programmati. Tieni un solo client per camera, oppure aggiungi il retry di prima, così due job non si scontrano. Un time-lapse con una foto al minuto è un breve ciclo di shell:
while true; do curl -fsS -o "shot-$(date +%s).jpg" "http://gizmo-camera.local/api/capture?resolution=SVGA"; sleep 60; doneFermalo con Ctrl+C. Ogni file ha nel nome l'ora Unix dello scatto.
Per Home Assistant, l'integrazione Generic Camera ha un campo Still Image URL, descritto come l'URL su cui la tua camera serve l'immagine. Mettici l'URL dello snapshot:
http://192.168.1.50/api/capture?resolution=SVGAL'indirizzo IP è un esempio: usa quello della tua camera. Qui l'IP è la scelta più sicura, perché un host Home Assistant non sempre risolve i nomi .local. Non ho provato questa procedura su un'installazione di Home Assistant, e il modo in cui l'integrazione fa il polling non l'ho verificato, quindi controlla ogni quanto scarica l'immagine prima di puntarla su una camera aperta anche nella web app: una seconda richiesta durante una cattura è un camera_busy.
L'URL dello snapshot si può lasciare aperto?
Nessuna autenticazione lo protegge. La camera non ha un login, quindi chiunque la raggiunga sulla tua rete può scattare una foto. Il firmware aggiunge due controlli dalla libreria condivisa gizmo-common: i browser su altri siti web vengono respinti (il controllo Origin), e le richieste devono usare come host il nome o l'indirizzo della camera stessa, il che protegge dal DNS rebinding. Le richieste dirette da curl o da uno script, con il nome o l'IP della camera, funzionano. Questi controlli non sono un login.
Tienila su una rete di cui ti fidi e non inoltrare mai la sua porta sul router. Il post sull'MCP parla dello stesso limite per gli agenti AI. L'esempio CameraWebServer è simile nello spirito: i suoi /capture e /stream rispondono con Access-Control-Allow-Origin: *, quindi qualsiasi pagina web può leggerli.
Cosa ricordare
Una GET /api/capture restituisce un JPEG, scattato dopo la tua richiesta, alla risoluzione e qualità che indichi: ?resolution=SVGA&quality=10 è un buon punto di partenza, e gli header della risposta ti dicono dimensione reale e tempo di cattura. La camera scatta uno snapshot alla volta, quindi una seconda richiesta riceve 503 camera_busy e deve semplicemente ritentare. Il flash si attiva con flash=1.
I limiti: l'endpoint non ha autenticazione, non ho fatto benchmark dei tempi di cattura né delle dimensioni dei file, e i passaggi per Home Assistant qui non sono stati provati. Se una scheda si resetta quando chiedi foto con il flash, il primo sospettato è l'alimentazione. Per i pin che usa la camera, vedi quali GPIO della ESP32-CAM sono davvero liberi, e per la famiglia di progetti, Cos'è OpenGizmo?
Domande frequenti
Trova risposte rapide alle domande più comuni su questo argomento.
Dipende dal firmware. L'esempio Arduino CameraWebServer serve lo snapshot su /capture. Gizmo Camera lo serve su /api/capture, per esempio http://gizmo-camera.local/api/capture?resolution=SVGA, e restituisce un JPEG. Su Gizmo Camera puoi aggiungere le opzioni resolution, quality e flash. Apri l'URL nel browser oppure scaricalo con curl.
Autore
Mauro BrambillaPronto a costruire il tuo gizmo?
Scegli un progetto ESP32 open source e segui la sua guida passo passo, dalla lista dei componenti e dai collegamenti fino al firmware e al primo avvio.





