Foto-Sidecars mit einem Vision-Modell

Das Skript vision.ts meiner alten Website: EXIF-Daten und Alt-Text, Titel und Tags von einem Vision-Modell in einer JSON-Datei neben jedem Foto, lokal erzeugt vor dem Deployment.

Der Fotostream meiner alten Astro-Website brauchte für jedes Bild einen Alt-Text, einen Titel und die Kameradaten. Das Skript scripts/vision.ts hat sie in ein JSON-Sidecar neben jede JPG-Datei geschrieben. Diese Seite fasst drei Beiträge aus dem März 2026 zusammen: wo das Skript läuft, wie es mit Rate Limits zurechtkommt und wie es von OpenAI zu Claude umgezogen ist.

Was das Skript macht

Für jede JPG-Datei ohne .json-Sidecar:

  1. liest es die EXIF-Daten mit exiftool (Kamera, Objektiv, Blende, ISO, Brennweite, Belichtungszeit, GPS);
  2. schickt es das Bild an ein Vision-Modell und bekommt Alt-Text, Titelvorschläge und Tags zurück;
  3. schreibt es beides in eine JSON-Datei neben dem Bild.

Das Sidecar speist die Fotoseiten: Alt-Text für die Barrierefreiheit, Titel für die Detailseite, EXIF für die Metadaten-Leiste.

Dort ausführen, wo die Originale liegen

Anfangs hat der VPS die Sidecars selbst erzeugt. Das Deployment lief durch, aber es kamen keine Sidecars an. Das Skript hat die Fotos im Repository gelesen, das Deployment hat aber einen anderen Ordner synchronisiert: die Fotobibliothek in meinem Obsidian-Vault auf dem Mac. Und rsync kann keine Dateien hochladen, die in dem Ordner, den es synchronisiert, nie entstanden sind.

Die Lösung: Der VPS ist nur noch Ziel. Der Mac hat die Originale, den API-Schlüssel und exiftool, also erzeugt er die Sidecars, und der Server bekommt fertige Dateien. vision.ts hat einen optionalen Quellordner bekommen, und das Deploy-Skript ruft es als Erstes auf:

pnpm run vision -- "$PHOTO_SRC"

rsync -az --delete \
  --include='*/' \
  --include='*.md' --include='*.mdx' \
  --include='*.jpg' --include='*.jpeg' --include='*.JPG' --include='*.JPEG' \
  --include='*.json' \
  --exclude='.DS_Store' --exclude='*' \
  "$PHOTO_SRC" "$VPS:$REMOTE_PHOTOS/"

Danach holt der Server das Repository und baut den Container mit podman-compose neu. Der VPS braucht für die Metadaten keinen API-Schlüssel mehr, kein exiftool und kein Node.1

Rate Limits bei großen Stapeln

Der erste Lauf über die Fotos einer ganzen Reise ist an 429 Too Many Requests gescheitert, bei noch 3,16 $ Guthaben. Ein positiver Kontostand hilft nicht gegen das Limit an Tokens pro Minute, das für das Konto gilt. Das Skript hatte schon begrenzte Parallelität und Wiederholungen mit exponentiellem Backoff. Es ging also darum, Werte zu finden, mit denen es vorankommt:

pnpm vision -- --concurrency=1 --retries=10 --backoff-ms=2000

Fang damit an, achte im Log auf 429-Wiederholungen und geh erst nach einem sauberen Lauf auf --concurrency=2. Über 2 verbringt das Skript auf einem Konto ohne höhere Limit-Stufe mehr Zeit im Backoff, als es spart. Für mehr Durchsatz hilft nur eine höhere Stufe. Damals noch offen: die Bilder vor dem Hochladen verkleinern (1024 px an der langen Kante reichen, um eine Szene zu beschreiben), was Tokens und Zeit spart.2

Von OpenAI zu Claude

Der Umzug auf die Claude API hat vor allem die Anfrage verändert. EXIF, Parallelität, Stapelverarbeitung und die Kommandozeilen-Optionen blieben gleich.

  • Paket und Schlüssel: @anthropic-ai/sdk statt openai, ANTHROPIC_API_KEY statt OPENAI_API_KEY.
  • Client: new Anthropic({ maxRetries: 0 }), weil das Skript seine eigene Backoff-Schleife hat und zwei Ebenen von Wiederholungen Kontingent verschwenden.
  • Strukturierte Ausgabe: OpenAI hat response_format mit einem json_schema und danach ein JSON.parse benutzt. Claude bekommt ein Tool vision_response mit einem input_schema (title_ideas, description, tags) und tool_choice: { type: "tool", name: "vision_response" }. Die Antwort kommt als toolUseBlock.input an, als Objekt, ohne Parsen.
  • Bild-Block: OpenAI nimmt eine Data-URL in image_url, Anthropic einen source-Block mit type: "base64" und eigenem media_type.
  • Rate Limits: statt einen rohen status zu prüfen und den Fehlertext zu zerlegen, error instanceof Anthropic.RateLimitError, mit der Wartezeit aus dem retry-after-Header der Exception.
function extractRetryAfterMs(error: unknown): number | null {
  if (!(error instanceof Anthropic.RateLimitError)) return null;
  const retryAfter = error.headers?.get("retry-after");
  if (retryAfter) {
    const seconds = Number.parseFloat(retryAfter);
    if (Number.isFinite(seconds) && seconds > 0) return Math.ceil(seconds * 1000);
  }
  return null;
}

Das Modell war claude-opus-4-6. Bei einem Stapel, der vor einem Deployment läuft, war mir Qualität wichtiger als Tempo.3

In aktuellen Versionen des SDK ist error.headers ein Headers-Objekt aus der Fetch-API, der Wert muss also mit .get("retry-after") gelesen werden. Ein Indexzugriff wie headers["retry-after"] liefert undefined, und das Skript fällt dann ohne Meldung auf seinen eigenen Backoff zurück.4

Zum Mitnehmen

  • Die Vorverarbeitung muss auf dem Ordner laufen, den das Deployment synchronisiert, nicht auf einer Kopie im Repository.
  • Arbeit, die Schlüssel und Werkzeuge braucht, gehört auf den Rechner mit den Originalen. Der Server braucht nur das, was er ausliefert.
  • Ein 429 ist meistens das Durchsatzlimit und nicht das Guthaben.

  1. Generating Photo Sidecars Locally Before a VPS Deploy, 14. März 2026. ↩

  2. Vision Rate-Limit Runbook for Photo Sidecars, 15. März 2026. ↩

  3. Migrating the Vision Script from OpenAI to Claude, 19. März 2026. ↩

  4. Anthropic TypeScript SDK, APIError in src/core/error.ts, Stand November 2026. ↩

Mehr dazu

Thema
  • KI / Sprachmodelle Wofür ich Sprachmodelle einsetze: Agenten, lokale Modelle, RAG und kleine Programme, in denen ein Modell eine Aufgabe übernimmt.
Nutzt
  • Claude API Die Programmierschnittstelle von Anthropic zu den Claude-Modellen. Wird getrennt von einem claude.ai-Abo abgerechnet, mit Schlüsseln aus der Claude Console.

In der Graph-Ansicht zeigen →