Algovate/agnes-image

Agnes Bildgenerierung

agnes-img ist ein Wrapper um agnes image generate: gleiche Parameter, zusätzliche Unterstützung für das 2.5-Modell und automatischen Fallback. Aktuell ist 2.5 (agnes-image-2.5-flash) die Voreinstellung, 2.1 (agnes-image-2.1-flash) dient als Fallback- und Kompatibilitätsstufe.

Voraussetzungsprüfung

agnes key status

• "status": "missing" bedeutet, dass kein Key konfiguriert ist. Bitte den Benutzer auffordern, unter https://platform.agnes-ai.com einen API-Key zu generieren und dann agnes key set <KEY> auszuführen (schreibt die lokale Konfiguration) oder die Umgebungsvariable AGNES_API_KEY zu setzen.
• Keinen Key erfinden und den Key nicht in Projektdateien oder den Antworttext schreiben.

Modellauswahl

Anforderung	Verwendung
Standard (produktive Auslieferung)	Nichts übergeben → agnes-image-2.5-flash
2.1 angeben	--model 2.1
Standard ändern	Umgebungsvariable AGNES_IMAGE_MODEL=2.1
Automatischen Fallback deaktivieren	--no-fallback (oder AGNES_IMAGE_FALLBACK=0)

• Priorität: --model > AGNES_IMAGE_MODEL > Standard 2.5.
• Bei einem 5xx-Fehler von 2.5 wird automatisch einmal mit 2.1 wiederholt; stderr gibt role=fallback aus. In der Antwort sollte das tatsächlich verwendete Modell angegeben werden.
• stderr gibt immer generated with <model> aus, daran kann das Modell in der Antwort erkannt werden.

Text-zu-Bild

agnes-img --prompt "Beschreibung" --size 2K

• Bei Erfolg enthält stdout nur die Bild-URL, Modellname/Aufgaben-ID/Fallback-Informationen/Fehler werden auf stderr ausgegeben.
• --size unterstützt die Stufen 1K / 2K / 3K / 4K sowie auch genaue Werte wie 1024x768 (Standard 1024x768).
• Stufen standardmäßig 1:1; für 16:9, 9:16 usw. die entsprechenden nativen Abmessungen übergeben, z.B. für 16:9 1312x736 (1K) oder 2624x1472 (2K), für 9:16 736x1312.

Bild-zu-Bild und Mehrfachbild-Synthese

agnes-img --prompt "Ändere zu Cyberpunk-Nachtszene" --image ./ref.png
agnes-img --prompt "Fusioniere diese zwei Referenzbilder zu einem Poster" --image ./a.png --image ./b.png

• --image kann wiederholt werden; lokale Pfade, öffentliche URLs oder Data-URIs werden unterstützt; lokale Dateien werden automatisch in Data-URIs umgewandelt.
• Bei der Bildbearbeitung ist ein Prompt wie "Was beibehalten, was ändern" stabiler.

Speichern und Anzeigen (erforderlich)

Die URL ist ein temporärer Link; sie muss in den Arbeitsbereich heruntergeladen werden:

mkdir -p output output/drafts
curl -sSL "<URL>" -o "output/agnes-$(date +%Y%m%d-%H%M%S).png"
ls -l output/*.png

• Sicherstellen, dass die Datei nicht leer ist (file / Größe > 0), bevor sie ausgeliefert wird.
• Das erzeugte Bild mit read_image als Vorschau anzeigen; in der Antwort mit ![Beschreibung](output/xxx.png) anzeigen oder bei Bedarf present verwenden.

Ausgabeverzeichnis-Konvention (muss eingehalten werden)

output/                       Auslieferungsbilder, dauerhaft behalten
  <thema>.png                 Hauptbild des Themas, z.B. adler-hase.png
  <thema>-<variante>.png      Alternative Auslieferungsvariante desselben Themas, z.B. adler-hase-tinte.png
output/drafts/                Zwischenentwürfe / ersetzte Versionen, nach 7 Tagen löschbar
  <thema>-<variante>-<YYYYMMDD-HHMM>.png

Regeln:

1. Auslieferungsbilder direkt nach output/<thema>.png ablegen; Benennung in Kleinbuchstaben mit Bindestrichen, englisch und semantisch, keine temporären Suffixe wie -v2, -final, -kopie.
2. Alte Bilder, die durch eine neue Version ersetzt werden, nach Bestätigung der neuen Auslieferung mit mv nach output/drafts/<thema>-<zeitstempel>.png verschieben, nicht in output/ liegen lassen, um Verwechslungen zu vermeiden.
3. Nicht zur Auslieferung bestimmte Testentwürfe (Kompositionsskizzen, Parameter-Tests) direkt in output/drafts/ ablegen.
4. Bereinigung immer mit agnes-gc durchführen, nicht manuell das gesamte output löschen:

agnes-gc              # Vorschau: Entwürfe älter als 7 Tage
agnes-gc --apply      # Ausführen
agnes-gc --all        # Vorschau: `drafts` komplett leeren

agnes-gc wirkt nur auf Verzeichnisse mit dem Namen drafts; Auslieferungsbilder in output/ werden dadurch nie gelöscht.

Häufige Probleme

• {"ok":false,"error":{"type":"auth",...}}: Key nicht konfiguriert oder ungültig; zuerst agnes key status ausführen.
• type: "validation": Parameter ungültig (z.B. nicht unterstütztes Modell, fehlendes --prompt); entsprechend hint korrigieren, nicht blind wiederholen.
• 2.5 meldet 5xx: Automatischer Fallback auf 2.1; wenn in stderr role=fallback erscheint, handelt es sich um ein Fallback-Produkt; bei der Auslieferung darauf hinweisen.
• Generierung dauert meist 10–60 Sekunden; Bash-Timeout mindestens auf 180.000 ms setzen.
• Jeweils nur eine Generierungsaufgabe ausführen, um Parallelitätslimits nicht zu überschreiten.

Kompatibilitätshinweis

Der alte Befehl agnes image generate ist weiterhin verfügbar, akzeptiert --model aber nur mit agnes-image-2.1-flash / agnes-image-2.0-flash und unterstützt 2.5 nicht. Für 2.5 oder automatischen Fallback immer agnes-img verwenden.