ESP32-CAM Snapshot per URL: eine Anfrage, ein JPEG

Ein ESP32-CAM-Foto per GET-Anfrage holen: URL /api/capture, Auflösung und Qualität, die Busy-Antwort, Beispiele mit curl und Home Assistant.

Veroffentlicht
Lesezeit
8 Min.
Kategorie
Projekte
Eine Frau mit langen Zöpfen hält eine Tasse, während eine ESP32-CAM auf eine Topfpflanze zeigt und ein Browserfenster mit der Adresse /api/capture dieselbe Pflanze zeigt.

Kurz gesagt

Ein ESP32-CAM-Snapshot ist eine GET-Anfrage, die ein JPEG liefert. Gizmo Camera antwortet auf /api/capture?resolution=SVGA, macht ein Foto nach dem anderen und beantwortet eine zweite Anfrage mit 503 camera_busy. Kein Login.

Ein ESP32-CAM-Snapshot ist eine einzelne HTTP-GET-Anfrage, die ein einzelnes JPEG zurückgibt. Mit der Firmware von Gizmo Camera lautet die URL http://gizmo-camera.local/api/capture?resolution=SVGA: Die ESP32-CAM macht ein frisches Foto, sendet es und schließt die Verbindung. Dieselbe Anfrage funktioniert im Browser, mit curl, in einem Skript oder in Home Assistant.

Brauchst du ein Foto der ESP32-CAM in einem Skript und keine Videoseite, die du offen halten musst? Dieser Beitrag zeigt die echten Endpunkte von Gizmo Camera, curl-Befehle zum Kopieren, die Optionen für Auflösung und Qualität und was die Kamera antwortet, wenn zwei Clients gleichzeitig fragen. Alles stammt aus dem Firmware-Quellcode im gizmo-camera-Repository, aus dem Arduino-Beispiel CameraWebServer, mit dem ich vergleiche, und aus der Dokumentation des esp32-camera-Treibers. Ich habe nichts gemessen, deshalb gibt es hier keine Geschwindigkeitswerte.

Open-Source-Projekt mit ESP32-CAM
Gizmo Camera

WLAN-Kamera mit ESP32-CAM, die bei jeder Anfrage ein JPEG-Foto macht, mit Web-App für die Einrichtung per Smartphone und einem MCP-Server für KI-Agenten.

  • JPEG-Fotos bis 1600 × 1200
  • Einfache HTTP-API
  • MCP-Server für KI-Agenten
Ansehen

Was ist der Unterschied zwischen Snapshot und Stream?

Ein Snapshot ist eine Anfrage und ein Bild: Der Client fragt, die Kamera nimmt einen Frame auf, und die Verbindung endet. Ein Stream ist eine Verbindung, die offen bleibt, während die Kamera weiter Frames sendet. Im Standardbeispiel CameraWebServer ist /capture der Snapshot (sein Handler liest keine Query-Parameter, es gibt also keine Optionen, die du an die URL hängen könntest), und /stream ist eine multipart/x-mixed-replace-Antwort, die in einer Schleife läuft, bis der Client geht, und von einem zweiten HTTP-Server einen Port über dem ersten ausgeliefert wird.

Damit sind es zwei verschiedene Werkzeuge. Die Tabelle vergleicht, wofür jedes taugt, auf Basis des CameraWebServer-Quellcodes und des Gizmo-Camera-Quellcodes.

Snapshot (/capture, /api/capture)MJPEG-Stream (/stream)
VerbindungNach einem JPEG geschlossenOffen, bis der Client geht
Client-CodeEin GET, jede HTTP-BibliothekEin Client, der Multipart-Teile auswertet
Arbeit der KameraNur wenn jemand fragtEine Schleife, die nie stoppt, solange jemand zuschaut
Am besten fürSkripte, Cronjobs, Home Assistant, AgentenLive-Ansicht im Browser
In Gizmo CameraJa: /api/captureNein: nicht vorgesehen

Gizmo Camera hat absichtlich keinen Stream: Im README steht, die Kamera "answers every request with a fresh photo". Wenn du doch Live-Video willst, ist das Beispiel CameraWebServer der einfachere Startpunkt, und der Rest dieses Beitrags dreht sich um den Snapshot.

Wie holt man ein JPEG mit curl?

Du brauchst eine Kamera mit der Gizmo-Camera-Firmware im selben Netzwerk wie dein Computer. Wenn du noch beim Flashen bist, hilft dir die Anleitung zum ESP32-CAM-MB. Danach reicht ein Befehl:

Ein Foto aufnehmen und speichern
curl -o photo.jpg "http://gizmo-camera.local/api/capture?resolution=SVGA"

Das ist der Befehl aus dem README des Projekts. Öffne photo.jpg: Du solltest sehen, was die Kamera sieht, mit 800 x 600. Wenn sich gizmo-camera.local auf deinem Computer nicht auflösen lässt, nimm stattdessen die IP-Adresse der Kamera, die du in deinem Router und auf der Kameraseite der Web-App findest. Die Gründe stehen in der Anleitung zum .local-Hostnamen.

Bevor du jubelst, wirf auch einen Blick auf die Header. Mit -D - werden sie ausgegeben (die Option -D schreibt die empfangenen Header in eine Datei, und - steht für die Standardausgabe):

Die Antwort-Header lesen
curl -sS -D - -o /dev/null "http://gizmo-camera.local/api/capture?resolution=SVGA"

Die Antwort sollte ungefähr so aussehen, mit deiner eigenen Aufnahmezeit:

Code
Code
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>
Zeile 6, Spalte 1UTF-8http

Die Header stammen direkt aus capture.get.cpp: X-Resolution ist die tatsächliche Größe des Frames, den der Sensor geliefert hat, X-Capture-Time-Ms ist die Dauer der Aufnahme auf der Kamera (nicht der Übertragung), und Cache-Control: no-store sagt Proxys, dass jede Anfrage ein neues Foto ist.

Welche Optionen kennt /api/capture?

Drei Query-Parameter, alle optional und kombinierbar. Die Firmware liest sie in capture_options.cpp.

ParameterWerteStandard
resolutionEin Name aus der Tabelle unten, Groß- oder Kleinschreibung egalDie größte Auflösung, die der Sensor liefert (UXGA beim OV2640)
qualityEine ganze Zahl von 4 bis 63, niedriger ist schärfer und größer10
flash1, true, 0 oder falseAus

Ein vollständiges Beispiel ist /api/capture?resolution=XGA&quality=12&flash=1. Ein ungültiger Wert wird mit HTTP 400 und einem JSON-Fehler abgelehnt, und es wird kein Foto gemacht: invalid_resolution, resolution_not_supported (eine Größe, die der Sensor nicht liefert), invalid_quality oder invalid_flash. Der Body sieht so aus: { "errorId": "invalid_quality", "errorMessage": "...", "data": null }, dieselbe Form wie bei jedem OpenGizmo-Gerät. Was eine bestimmte Kamera unterstützt, erfährst du mit GET /api/camera: Die Antwort enthält den Sensornamen, die Liste der Auflösungen mit ihren Größen, den Qualitätsbereich und hasFlash.

Die fünf Schritte von GET /api/capture: Optionen prüfen, Kamera belegen, alte Frames verwerfen, ein JPEG erfassen, senden und den Buffer freigeben

Wie wählt man Auflösung und JPEG-Qualität?

Die Größen sind die framesize_t-Werte des esp32-camera-Treibers, die die Firmware in capture_options.h und camera.cpp auf Namen abbildet. Das README listet diese neun für den OV2640; die Firmware kennt größere für leistungsfähigere Sensoren wie OV3660 und OV5640 und kürzt die Liste auf das, was der angeschlossene Sensor meldet.

Name in der URLTreiber-KonstanteGröße (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

Wie wählt man? Fang bei SVGA an: Das empfiehlt die Agenten-Anleitung von Gizmo Camera selbst, um eine Szene zu verstehen, und der MCP-Server nimmt es als Standard. Geh nur auf UXGA, wenn du kleine Details brauchst, denn das README warnt, dass ein JPEG mit 1600 x 1200 über WLAN einige hundert KB groß ist. Für ein Status-Vorschaubild reichen VGA oder QVGA.

Die JPEG-Qualität funktioniert andersherum, als viele erwarten. Das README von esp32-camera sagt, der Bereich reicht bei OV-Sensoren von 0 bis 63 und "lower number means higher quality". Gizmo Camera akzeptiert 4 bis 63, und ein Kommentar in capture_options.h erklärt die Untergrenze: Unter 4 kann der Frame-Buffer bei der höchsten Auflösung überlaufen. Auch die Dateigröße hängt von der Szene ab, deshalb nenne ich keine Zahlen: Ändere quality und vergleiche Content-Length selbst.

Zwei Details, wie die Kamera deine Optionen anwendet, sind gut zu wissen. Nach einer Änderung von Auflösung oder Qualität verwirft die Firmware drei Frames vor dem, den sie sendet, weil die ersten Frames nach einer Einstellungsänderung beschädigt sein oder noch die alten Einstellungen nutzen können. Bei einer unveränderten Anfrage verwirft sie einen veralteten Frame, du bekommst also ein Foto, das nach deiner Anfrage aufgenommen wurde, und nicht eines, das im Buffer wartete. Mit flash=1 verwirft sie mindestens zwei. Die LED an GPIO4 wird 150 ms vor dem Frame eingeschaltet und gleich danach wieder aus. Diese 150 ms sind dieselbe Verzögerung wie im Beispiel CameraWebServer, und der Blitz ist eine Stromspitze: Wenn das Board beim Auslösen neu startet, lies die Anleitung zum Brownout.

Warum passt ein Snapshot besser zu einem kleinen Board als ein Stream?

Bei einem kleinen Board liegt der Unterschied darin, wie lange du Kamera und Verbindung belegst. Die Gizmo-Camera-Firmware startet den Sensor mit einem Frame-Buffer (fb_count = 1) im PSRAM und CAMERA_GRAB_WHEN_EMPTY und streamt das JPEG direkt aus diesem Buffer zum Client, ohne es zu kopieren. Das Beispiel CameraWebServer nutzt, wenn PSRAM gefunden wird, zwei Buffer und CAMERA_GRAB_LATEST. Das README von esp32-camera sagt, dass mehr als ein Buffer im JPEG-Modus den Treiber dauerhaft aufnehmen lässt, was CPU und Speicher kostet und dafür eine höhere Bildrate bringt: passend für einen Stream, mehr als ein Snapshot braucht.

Ich habe weder Speicherverbrauch noch Frame-Zeiten gemessen, nimm das also als Design-Überlegung aus dem Quellcode, nicht als Benchmark. Was der Code zeigt, ist einfach: Zwischen den Anfragen tut eine Snapshot-Kamera nichts. Es gibt keine Schleife, die Frames für einen Zuschauer holt, der vielleicht längst weg ist, und keinen zweiten Port für den Stream. Ein Skript, das einmal pro Stunde ein Foto will, kostet die Kamera eine Aufnahme pro Stunde.

Was passiert, wenn zwei Clients gleichzeitig fragen?

Die Kamera beantwortet den zweiten mit einem Fehler. Gizmo Camera hält den Frame-Buffer von dem Moment an, in dem ein Snapshot aufgenommen wird, bis die Antwort gesendet wurde oder der Client weg ist, und es kann immer nur ein Snapshot gehalten werden. Eine Anfrage, die in der Zwischenzeit eintrifft, bekommt HTTP 503 mit diesem Body:

Ein Smartphone und ein Laptop schicken beide eine Anfrage an eine ESP32-CAM auf einem Stativ mit dem Schild busy, die zweite Anfrage wartet mit einem Uhrsymbol

Code
Code
{
  "errorId": "camera_busy",
  "errorMessage": "The camera is taking another snapshot",
  "data": null
}
Zeile 5, Spalte 1UTF-8JSON

Die Anfrage von Client A belegt den Frame-Buffer und bekommt ein 200-JPEG, während die Anfrage von Client B in der Zwischenzeit 503 camera_busy erhält

Die anderen Fehler sind ebenfalls JSON: camera_unavailable (503), wenn der Sensor nicht gestartet ist, was in der Praxis meist auf das Flachbandkabel hinweist, und capture_failed (500), wenn der Sensor keinen Frame geliefert hat. Die Firmware läuft auch ohne Kamera weiter, damit die Web-App sagen kann, was nicht stimmt.

Betrachte camera_busy als "versuch es gleich noch mal", nicht als Defekt. curl kann das für dich übernehmen: Seine Dokumentation führt HTTP 503 unter den vorübergehenden Fehlern auf, die --retry wiederholt, mit exponentiell wachsender Wartezeit.

curl wiederholen lassen, solange die Kamera belegt ist
curl --retry 3 -fsS -o photo.jpg "http://gizmo-camera.local/api/capture?resolution=SVGA"

Mit -f bricht curl bei jedem Fehlerstatus ab, statt den JSON-Fehler als photo.jpg zu speichern. Eine Warnung: Wiederholen bedeutet jedes Mal ein neues Foto, und mit flash=1 blitzt die LED erneut. Die Web-App macht absichtlich das Gegenteil: Ihr useDeviceApi.js setzt für Snapshots retry: 0.

Wie holen Skripte und Home Assistant das Bild?

Jeder HTTP-Client funktioniert, denn es ist ein einfaches GET. Für einen Zeitraffer reicht eine Schleife mit curl und einem Zeitstempel im Dateinamen, und ein cron-Eintrag erledigt dasselbe nach Zeitplan. Nimm einen Client pro Kamera oder füge die obige Wiederholung hinzu, damit zwei Jobs nicht kollidieren. Ein Zeitraffer mit einem Foto pro Minute ist eine kurze Shell-Schleife:

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

Beende es mit Strg+C. Jede Datei trägt die Unix-Zeit der Aufnahme im Namen.

Für Home Assistant hat die Generic-Camera-Integration ein Feld Still Image URL, beschrieben als die URL, unter der deine Kamera das Bild ausliefert. Trag dort die Snapshot-URL ein:

Code
Code
http://192.168.1.50/api/capture?resolution=SVGA
Zeile 1, Spalte 1UTF-8Nur-Text

Die IP-Adresse ist ein Beispiel: Nimm die deiner Kamera. Eine IP ist hier die sicherere Wahl, denn ein Home-Assistant-Host löst .local-Namen nicht immer auf. Ich habe das nicht auf einer Home-Assistant-Installation getestet, und das Abfrageverhalten der Integration habe ich nicht überprüft. Sieh also nach, wie oft sie das Bild abruft, bevor du sie auf eine Kamera richtest, die auch in der Web-App offen ist: Eine zweite Anfrage während einer Aufnahme ergibt camera_busy.

Ist die Snapshot-URL sicher, wenn man sie offen lässt?

Keine Authentifizierung schützt sie. Die Kamera hat keinen Login, also kann jeder, der sie in deinem Netzwerk erreicht, ein Foto machen. Die Firmware ergänzt zwei Prüfungen aus der gemeinsamen Bibliothek gizmo-common: Browser auf anderen Websites werden abgewiesen (die Origin-Prüfung), und Anfragen müssen den eigenen Namen oder die Adresse der Kamera als Host verwenden, was vor DNS-Rebinding schützt. Direkte Anfragen von curl oder aus einem Skript, unter dem Namen oder der IP der Kamera, funktionieren. Diese Prüfungen sind kein Login.

Halte sie in einem Netzwerk, dem du vertraust, und leite ihren Port niemals am Router weiter. Der MCP-Beitrag behandelt dieselbe Grenze für KI-Agenten. Das Beispiel CameraWebServer ist ähnlich gelagert: Seine Pfade /capture und /stream antworten mit Access-Control-Allow-Origin: *, sodass jede Webseite sie lesen kann.

Was du dir merken solltest

Ein GET /api/capture liefert ein JPEG, das nach deiner Anfrage aufgenommen wurde, in der Auflösung und Qualität, die du angibst: ?resolution=SVGA&quality=10 ist ein guter Startpunkt, und die Antwort-Header nennen dir die tatsächliche Größe und die Aufnahmezeit. Die Kamera macht einen Snapshot nach dem anderen, eine zweite Anfrage bekommt also 503 camera_busy und sollte es einfach nochmal versuchen. Den Blitz schaltest du mit flash=1 ein.

Die Grenzen: Der Endpunkt hat keine Authentifizierung, ich habe weder Aufnahmezeiten noch Dateigrößen gemessen, und die Home-Assistant-Schritte sind hier nicht getestet. Wenn ein Board neu startet, sobald du Fotos mit Blitz anforderst, ist die Stromversorgung der erste Verdächtige. Welche Pins die Kamera belegt, steht in welche GPIO-Pins der ESP32-CAM wirklich frei sind, und zur Projektfamilie gehört Was ist OpenGizmo?

Haufig gestellte Fragen

Finden Sie schnelle Antworten auf die haufigsten Fragen zu diesem Thema.

Das hängt von der Firmware ab. Das Arduino-Beispiel CameraWebServer liefert den Snapshot unter /capture. Gizmo Camera liefert ihn unter /api/capture, zum Beispiel http://gizmo-camera.local/api/capture?resolution=SVGA, und gibt ein JPEG zurück. Bei Gizmo Camera kannst du die Optionen resolution, quality und flash anhängen. Öffne die URL im Browser oder lade sie mit curl herunter.

Veroffentlicht

Lust, dein eigenes Gizmo zu bauen?

Such dir ein Open-Source-Projekt mit dem ESP32 aus und folge der Schritt-für-Schritt-Anleitung, von der Teileliste und der Verkabelung bis zur Firmware und zum ersten Start.

Lies auch

Kategorien entdecken