Agnes Multimodal

Agnes AI Multimodale Generierung Skill

Überblick

Dieser Skill kapselt die gesamten Generierungsfähigkeiten von Agnes AI (Sapiens AI) und wird über ein einheitliches CLI-Skript aufgerufen:

• Textgenerierung: agnes-2.5-flash (unterstützt Thinking-Modus, $0)
• Bildverständnis/Vision: agnes-2.5-flash (kompatibel mit OpenAI Vision API, kann Bildinhalte analysieren)
• Text-zu-Bild/Bild-zu-Bild: agnes-image-2.5-flash (neueste Generation, optimiert für hohe Informationsdichte; mit --model agnes-image-2.1-flash auf Vorgängergeneration zurückfallen)
• Video Engine 1 (V2.0): agnes-video-v2.0 – Text-zu-Video / Bild-zu-Video / Keyframe-Animation, freie Bildrate und Auflösung, $0/Sekunde
• Video Engine 2 (Video 2.5 Flash): agnes-video-2.5-flash – Modell der nächsten Generation mit drei Modi: Text/Keyframe/Reference, multimodale Referenzen, zeitlich begrenzt kostenlose 720P; kostenpflichtiges Upgrade mit --model agnes-video-2.5 schaltet 960P/2K und Videoreferenzen frei
• Automatische Übersetzung: Chinesische Prompts werden automatisch ins Englische übersetzt, bevor die API aufgerufen wird
• Asynchrones Polling: Videoaufgaben werden automatisch abgefragt, bis sie abgeschlossen sind

Voraussetzungen

1. Stellen Sie sicher, dass der API-Schlüssel konfiguriert ist:

   • Bevorzugt wird der hartcodierte API_KEY in scripts/agnes_client.py gelesen
   • Wenn es sich um einen Platzhalter YOUR_AGNES_API_KEY_HERE handelt, wird auf die Umgebungsvariable AGNES_API_KEY zurückgegriffen
   • Wenn keines konfiguriert ist, den Benutzer auffordern, den API-Schlüssel im Code oder in einer Umgebungsvariable zu setzen

2. Python 3.8+, Standardbibliothek urllib + json reichen aus, keine zusätzlichen Abhängigkeiten.

CLI-Befehlsübersicht

Skript-Pfad: scripts/agnes_client.py

# Textgenerierung
python scripts/agnes_client.py text "Ihr Prompt"
python scripts/agnes_client.py text "Hallo" --stream
python scripts/agnes_client.py text "Schreibe mir einen Quicksort" --thinking  # 2.5 Thinking-Modus

# Text-zu-Bild (agnes-image-2.5-flash, Standard 1K; empfohlen: Größe + Seitenverhältnis)
python scripts/agnes_client.py image "Eine futuristische Stadt bei Sonnenuntergang, filmischer Realismus" --size 2K --ratio 16:9
python scripts/agnes_client.py image "Eine Katze, die im Mondschein spaziert"
python scripts/agnes_client.py image "..." --model agnes-image-2.1-flash   # Rückfall auf Vorgängergeneration

# Bild-zu-Bild (automatische Seitenverhältniserkennung – Ausgabe standardmäßig im Seitenverhältnis des Hauptreferenzbilds)
python scripts/agnes_client.py image "Transformiere zu Cyberpunk-Nacht" --image-url "https://...input.png" --image-url "https://...ref.png"

# Bild-zu-Bild + manuelle Angabe des Seitenverhältnisses (ohne automatische Erkennung)
python scripts/agnes_client.py image "Transformiere zu Cyberpunk-Nacht" --image-url "https://...input.png" --ratio 16:9

# ── Video Engine 1: V2.0 (freie Bildrate/Auflösung, $0) ──
python scripts/agnes_client.py video "Eine Drohne, die bei Sonnenaufgang über Berge fliegt" --poll          # Text-zu-Video
python scripts/agnes_client.py video "Bewegung zu dieser Szene hinzufügen" --image-url "https://...frame.png" --poll  # Bild-zu-Video
python scripts/agnes_client.py video --keyframes "https://a.com/1.png,https://a.com/2.png,https://a.com/3.png" --poll  # Keyframe-Animation

# ── Video Engine 2: Video 2.5 Flash (nächste Generation, kostenlos 720P) ──
python scripts/agnes_client.py video25 "Straße einer futuristischen Stadt nach Regen, Neonlichter spiegeln sich, filmische Kameraführung" --poll          # Text Text-zu-Video
python scripts/agnes_client.py video25 "Person dreht sich natürlich um und geht zum Fenster" --first-frame "https://.../f.png" --last-frame "https://.../l.png" --poll  # Keyframe Start/Ende
python scripts/agnes_client.py video25 "Mit <Picture 1> als Charakterreferenz durch ein Blumenfeld rennen" --image-url "https://.../char.png" --poll  # Reference Bildreferenz
python scripts/agnes_client.py video25 "Eine Nachtszene im Rhythmus von <Audio 1> generieren" --audio-url "https://.../music.mp3" --poll  # Reference Audio-Referenz
python scripts/agnes_client.py video25 "..." --model agnes-video-2.5 --size 960P               # Kostenpflichtiges Upgrade (960P/2K)

# Nur Videoaufgabe einreichen, ohne zu warten
python scripts/agnes_client.py video "..." --no-poll
python scripts/agnes_client.py video25 "..." --no-poll

# Videostatus abfragen (V2.5 Aufgaben empfehlen --model)
python scripts/agnes_client.py video-status TASK_ID
python scripts/agnes_client.py video-status TASK_ID --model agnes-video-2.5-flash

# Chinesischen Prompt übersetzen
python scripts/agnes_client.py translate "Eine Katze"

# Bildverständnis / Vision (mit agnes-2.5-flash Bildinhalt analysieren)
python scripts/agnes_client.py vision --image-url "https://example.com/photo.png"
python scripts/agnes_client.py vision --image-url "https://example.com/photo.png" --prompt "Welche Marke ist diese Uhr?"

# Smoke-Test (API-Konnektivität prüfen)
python scripts/agnes_client.py smoke-test

Vollständige Arbeitsabläufe

Text-zu-Bild Arbeitsablauf

1. Empfange chinesischen/englischen Prompt vom Benutzer
2. Wenn Chinesisch enthalten und --no-translate nicht angegeben, automatisch mit agnes-2.5-flash ins Englische übersetzen
3. Rufe POST /v1/images/generations auf (Standardmodell: agnes-image-2.5-flash)
4. Extrahiere die Bild-URL aus der Antwort data[0].url
5. Ergebnis an Benutzer zurückgeben (URL anzeigen, oder versuchen, mit curl/Browser zu öffnen)

Größenempfehlung: Text-zu-Bild empfiehlt sich die Angabe --size 2K --ratio 16:9 im Format "Stufe + Seitenverhältnis", um erwartbare Größen zu erhalten; nicht unterstützte exakte Größen (z. B. 1920x1080) werden vom Server standardisiert, müssen selbst zugeschnitten werden.

Bild-zu-Bild Arbeitsablauf

1. Bestätige, dass der Benutzer eine Bild-URL oder einen lokalen Pfad angegeben hat
2. Falls eine Übersetzung des Prompts erforderlich ist, führe sie aus
3. Rufe denselben Endpunkt auf und übergebe im extra_body.image-Array die Eingabebild-URLs
4. Gib das generierte Ergebnis zurück

Video-Generierungs-Arbeitsablauf (Engine-Auswahl)

Der Skill enthält zwei Video-Engines, Auswahl nach Bedarf:

Engine	Unterbefehl	Modell	Merkmale	Preis
V2.0	video	agnes-video-v2.0	t2v/ti2vid/keyframes, freie Bildrate (num_frames 8n+1) und Auflösung	$0/Sekunde
Video 2.5	video25	agnes-video-2.5-flash (Standard) / agnes-video-2.5 (kostenpflichtig)	Nächste Generation: text/keyframe/reference, Referenzbilder/Audio, kontrollierbarere Kameraführung	flash zeitlich begrenzt kostenlos

Video 2.5 Flash (video25) Arbeitsablauf:

1. Modus automatisch aus Material ableiten (--mode auto), oder explizit angeben:
   • text: reiner Text → keine Medienspezifikationen
   • keyframe: --first-frame / --last-frame (mindestens eines) begrenzt Start-/Endkomposition
   • reference: --image-url (≤5) / --audio-url (≤3 Segmente); im Prompt Platzhalter <Picture N> / <Audio N> verwenden, um auf Material zu verweisen
2. Sende POST /v1/videos mit Parametern: mode + seconds("4"~"12") + size(flash nur 720P) + aspect_ratio + seed
3. Frage GET /agnesapi?video_id=<ID>&model_name=agnes-video-2.5-flash ab (bei keyframe/reference muss model_name angegeben werden)
4. Nach Status completed extrahiere die Video-URL aus der Antwort

⚠️ video25 und video haben völlig unterschiedliche Parametersysteme: video25 akzeptiert keine num_frames/width/height/fps/negative_prompt (sonst Fehler 400).

Video-Parameter-Einschränkungen (Engine 1 V2.0)

• num_frames muss 8n + 1 erfüllen, maximal 441
• Standard: num_frames=121, frame_rate=24 (ca. 5 Sekunden)
• Schnelltest mit --num-frames 81 (ca. 3,4 Sekunden)

Video-Parameter-Einschränkungen (Engine 2 Video 2.5)

• seconds als String "4"~"12", Standard "5"
• size: flash fest 720P; kostenpflichtiges agnes-video-2.5 wählbar 720P/960P/2K
• aspect_ratio: 21:9 / 16:9(Standard) / 4:3 / 1:1 / 3:4 / 9:16
• Flash-Einschränkungen: Referenzbilder ≤5, Audio ≤3 Segmente, keine Videoreferenzen (kostenpflichtige Version unterstützt videos)
• Getestet: 720P 16:9 Ausgabe ca. 1280x704

Bildverständnis (Vision) Arbeitsablauf

agnes-2.5-flash unterstützt multimodale Eingaben im OpenAI Vision API-Format, kann Bildinhalte analysieren und Textbeschreibungen zurückgeben. Dies ist eine Brückenlösung, um Modellen ohne visuelle Fähigkeiten "Augen" zu geben. Die Bildverständnisfähigkeiten der Version 2.5 sind stärker als 2.0 und erkennen Details genauer.

1. Stelle sicher, dass das Bild unter einer öffentlich zugänglichen HTTP(S)-URL hochgeladen ist
2. Rufe den vision-Befehl mit der Bild-URL und optionalem Analyse-Prompt auf
3. Die Textbeschreibung wird zurückgegeben, kann direkt als Kontext an andere Modelle übergeben werden (z. B. "Gib Verbesserungsvorschläge für das Design dieser Uhr auf dem Bild" – zuerst Vision für die Beschreibung, dann an ein beliebiges Textmodell zur Analyse)

Vision-Befehlsparameter:

• --image-url (erforderlich, mehrfach angeben): zu analysierende Bild-URL
• --prompt (optional): Analyse-Prompt, Standard "Describe this image in detail."
• --system (optional): System-Prompt
• --max-tokens (optional): Maximale Ausgabe-Tokens, Standard 1000
• --no-translate (optional): Automatische Übersetzung überspringen (für englische Prompts empfohlen)

Prompt-Best Practices

Bild-Prompt-Struktur

[Subjekt] + [Szene] + [Stil] + [Beleuchtung] + [Komposition] + [Qualität]

Beispiel:

Eine Luxusuhr mit schwarzem Lederarmband auf Marmoroberfläche, weiches Studio-Licht, Makrofotografie, 8K-Detail, hohe visuelle Dichte

Bild-zu-Bild Prompt

Formuliere klar, was geändert + was beibehalten werden soll:

Transformiere den Hintergrund in ein dunkles, luxuriöses Setting, während das Design und der Winkel der Uhr erhalten bleiben.

Video-Prompt

Füge Kamerabewegung und zeitliche Elemente hinzu:

Eine langsame 360-Grad-Drehung um die Uhr, die jedes Detail enthüllt, filmische Beleuchtung, sanfte Bewegung

Preise

Modell	Preis
agnes-2.5-flash (Text/Vision/Thinking)	Kostenlos ($0/1M Tokens)
agnes-image-2.5-flash (Bild, neueste Generation)	Kostenlos ($0/Bild, alle 1K~4K Stufen)
agnes-image-2.1-flash (Bild, Vorgängergeneration)	Kostenlos ($0/Bild)
agnes-video-v2.0 (Video Engine 1)	Kostenlos ($0/Sekunde)
agnes-video-2.5-flash (Video Engine 2)	Zeitlich begrenzt kostenlos ($0/Sekunde, 720P)
agnes-video-2.5 (Video, kostenpflichtiges Upgrade)	$0.025/Sekunde(720P) / $0.040/Sekunde(960P) / $0.055/Sekunde(2K)

Die Preise basieren auf der offiziellen Website https://www.agnes-ai.com/en/docs/pricing; die Kostenpolitik kann sich je nach Plattformankündigung ändern.

Bekannte Einschränkungen

• 2.5 Thinking-Modus gibt das Feld reasoning_content zurück (Denkprozess), was die Ausgabe-Tokens leicht erhöht
• Vereinzelt serverseitige Fehler division by zero bei Videogenerierung
• V2.0 Multi-Bild-Videos/Keyframe-Animationen sind noch nicht vollständig End-to-End verifiziert
• Bild-API akzeptiert nur HTTP(S)-URLs als Eingabe, kein base64 (Eingabe); Ausgabe optional URL oder Base64
• agnes-video-2.5-flash nur 720P, keine Videoreferenzen; für 960P/2K oder Videoreferenzen ist das kostenpflichtige --model agnes-video-2.5 erforderlich
• Abfragen von keyframe/reference-Aufgaben bei video25 müssen --model agnes-video-2.5-flash enthalten

Automatische Seitenverhältniserkennung (i2i)

Wenn bei i2i kein --ratio angegeben ist, erkennt das Skript automatisch das Seitenverhältnis des Hauptreferenzbilds (d. h. des ersten --image-url) und ordnet es einem der 8 offiziellen, von agnes-image-2.5-flash unterstützten Seitenverhältnisse zu (1:1 / 3:4 / 4:3 / 16:9 / 9:16 / 2:3 / 3:2 / 21:9), um Verzerrungen durch inkonsistente Leinwand-Seitenverhältnisse mit dem Eingabesubjekt zu vermeiden.

# Automatische Erkennung: Gibt [INFO] Main reference image: ... → auto ratio: ... aus
python scripts/agnes_client.py image "prompt" --image-url MODEL_URL --image-url REF_URL --size 2K

# Manuelle Angabe (überspringt automatische Erkennung)
python scripts/agnes_client.py image "prompt" --image-url MODEL_URL --ratio 16:9

Hauptreferenzbild-Konvention: Das erste --image-url wird als das Subjekt betrachtet, das die Komposition/das Seitenverhältnis bestimmt (normalerweise ein Model/Produktfoto); das zweite und folgende werden als Stil-/Detailreferenz angesehen. Um das Hauptreferenzbild zu wechseln, tausche die Reihenfolge der --image-url-Angaben.

Referenzen

• Detaillierte API-Dokumentation: references/api_reference.md
• Offizielle Website: https://agnes-ai.com/
• API-Plattform: https://platform.agnes-ai.com/