imraninho366/higgsfield-generate

Higgsfield Generate

Übermittelt Aufträge an jedes Higgsfield-Modell. Kapselt die higgsfield CLI. Deckt die allgemeine Bild-/Video-Generierung und Marketing Studio (Markenanzeigen, Avatare, Produkte, Hooks, Einstellungen) ab.

Schritt 0 — Bootstrap

Stellen Sie vor jedem anderen Befehl sicher, dass die CLI installiert und authentifiziert ist:

1. Wenn higgsfield nicht im $PATH ist, installieren Sie es:

   curl -fsSL https://raw.githubusercontent.com/higgsfield-ai/cli/main/install.sh | sh
   

2. Wenn higgsfield account status mit Session expired / Not authenticated fehlschlägt, bitten Sie den Benutzer, higgsfield auth login (interaktiv, öffnet einen Browser) auszuführen und warten Sie auf seine Bestätigung, bevor Sie fortfahren.

Überspringen Sie beide Prüfungen, wenn higgsfield account status bereits Kontoinformationen ausgibt.

UX-Regeln

1. Seien Sie präzise. Keine Roh-IDs, keine JSON-Dumps im Chat. Geben Sie die Ergebnis-URL aus, sobald sie bereit ist.
2. Kein internes Fachjargon. Erzählen Sie nicht "rufe higgsfield cost auf", "polling job".
3. Erkennen Sie die Sprache des Benutzers aus der ersten Nachricht und antworten Sie darin. Technische Argumente (--aspect_ratio 16:9) bleiben auf Englisch.
4. Nicht stapelweise fragen. Wählen Sie ein sinnvolles Standardmodell und fragen Sie nur dann einzeln, wenn etwas wirklich fehlt.
5. Keine vorherige Kostenschätzung. Reichen Sie einfach ein, es sei denn, der Benutzer fragt danach.
6. Übergeben Sie --wait an generate create, damit der Befehl blockiert, bis er fertig ist, und die Ergebnis-URL selbst ausgibt. Vermeiden Sie das zweistufige Muster create → wait.

Arbeitsablauf — Generische Generierung

1. Modell auswählen. Praktische Standardwerte aus der Produktion:

   Bild:

   • Markenproduktvisual (Pinterest-Pin, Lifestyle, Hero-Banner, Anzeigenpaket, virtuelles Anprobieren) → higgsfield-product-photoshoot verwenden. NICHT dieses Skill.
   • Markenanzeigenbild mit Avatar + Produkt (Marketing Studio-Form) → Marketing Studio Bild (siehe Marketing Studio unten)
   • Ästhetischer UGC / Mode-Editorial / Lifestyle-Charakter → Soul 2.0
   • Kinematografisches Standbild → Soul Cinema
   • Hochgradig charakteristische kreative Persona (nur Text, unverwechselbar) → Soul Cast
   • Orte / Umgebungen / Szenen ohne Personen → Soul Location (beste Klasse)
   • Vektorillustrationen ODER Gesichtsbearbeitung + komplexer Szenenwechsel → Seedream 4.5
   • Soul Character (Referenz-ID von higgsfield-soul-id) → Soul 2.0 für Standbilder, Soul Cinema für Kinematografie
   • Schnelle und günstige Iteration → Z Image
   • Charakter- oder Cartoon-Arbeit → Nano Banana 2; bei schwierigen Fällen auf Nano Banana Pro upgraden
   • Standard für alles andere → GPT Image 2. Grafikdesign, UI, Banner, Typografie und hochwertige allgemeine Generierung.

   Video:

   • Alle Werbe-/ kommerziellen/ Marken-Anzeigenvideos → Marketing Studio (siehe Marketing Studio unten)
   • Standard-Allzweck-Serious-Video (mehrere Einstellungen, konsistente Identität, bewegungsintensiv) → Seedance 2.0. SOTA.
   • Einzel-Ebenen-Szene ohne starke Dynamik, günstiger als Seedance 2.0 → Kling 3.0
   • Günstiger, sauberer Shot ohne Schnitte → Seedance 1.5 Pro
   • Kinoreife, höchste Wiedergabetreue → Cinema Studio Video 3.0
   • Günstig mit starker Physik, kein Audio nötig → Minimax Hailuo
   • Schnelle Stapelverarbeitung / Volumen → Veo 3.1 Lite

   Um die tatsächliche --model-ID zu finden, die an higgsfield generate create übergeben wird, führen Sie higgsfield model list --json | jq aus, um Anzeigenamen auf IDs abzubilden. Die vollständige Tabelle finden Sie in references/model-catalog.md.

2. Medieneingaben direkt an Flags übergeben. Medien-Flags akzeptieren einen lokalen Dateipfad oder eine UUID. Die CLI lädt Pfade automatisch hoch und erkennt automatisch, ob es sich bei UUIDs um einen Job oder einen Upload handelt. Kein Vorab-Upload nötig. Jedes Modell deklariert akzeptierte Rollen (image, start_image, end_image, video, audio) – siehe references/media-inputs.md.

3. Schnell validieren. Wenn Sie sich bei den Parametern unsicher sind, führen Sie higgsfield model get <jst> --json einmal aus und übergeben Sie nur das Nötigste. Verwenden Sie ansonsten die Schema-Standardwerte. Der Server gibt adjustments für nicht fatale Umwandlungen (z. B. aspect_ratio=99:99 → nächstgelegener Treffer) und eine strukturierte Fehlermeldung für ungültige deklarierte Parameterwerte zurück.

4. Einreichen und in einem Durchgang warten. higgsfield generate create <jst> --prompt "..." [Medien-Flags] [Parameter-Flags] --wait. Blockiert bis zum Endstatus und gibt die Ergebnis-URL auf stdout aus. Einstellbar: --wait-timeout 20m (Standard 10m), --wait-interval 5s (Standard 3s).

5. Ausliefern. Senden Sie die URL plus eine einzeilige Zusammenfassung (Modell, Dauer bei Video).

Zur späteren Überprüfung oder Wiederholung funktionieren higgsfield generate list --json und higgsfield generate get <id> --json für die Nachbetrachtung. higgsfield generate wait <id> ist weiterhin verfügbar, falls Sie zu einem Job zurückkehren müssen, der ohne --wait gestartet wurde.

Medien-Flags

Flag	Verwendung	Modelle, die es akzeptieren
--image <pfad-oder-id>	Referenzbild	die meisten Bildmodelle, seedance_2_0, veo3, marketing_studio_video
--start-image <pfad-oder-id>	Erstes Bild für Bild-zu-Video-Übergänge	kling3_0, kling2_6, veo3_1, seedance_2_0, marketing_studio_video
--end-image <pfad-oder-id>	Letztes Bild für Übergänge	kling3_0, seedance_2_0, marketing_studio_video
--video <pfad-oder-id>	Referenzvideo	seedance_2_0
--audio <pfad-oder-id>	Referenzaudio (Lippensynchronisation, Soundtrack-Abstimmung)	seedance_2_0 (dieses verwenden, NICHT --generate-audio)

Jedes Flag akzeptiert entweder einen lokalen Dateipfad (automatisch hochgeladen) oder eine UUID (Upload-ID von higgsfield upload create oder eine vorherige Job-ID). Jedes Modell deklariert seinen eigenen Rollensatz über MEDIA_ROLES. Die vollständige Tabelle finden Sie in references/media-inputs.md.

Häufige Parameter

Flags werden an das Modellschema übergeben. Verwenden Sie higgsfield model get <jst> zur Ermittlung.

higgsfield generate create gpt_image_2 --prompt "neon city at dusk" --aspect_ratio 16:9 --resolution 2k --wait
higgsfield generate create nano_banana_2 --prompt "anime character concept, expressive pose" --image ./ref.png --wait
higgsfield generate create seedance_2_0 --prompt "camera dollies in" --start-image ./first.png --duration 8 --wait
higgsfield generate create text2image_soul_v2 --prompt "..." --soul-id <soul_ref_id> --quality 2k --wait

Für maschinenlesbare Ausgabe (verkettete Pipelines, Agentenkontext) fügen Sie --json hinzu. Mit --wait --json erhalten Sie das endgültige Job-Objekt-Array. Ohne --wait erhalten Sie die Job-IDs.

Stdin-Eingabeaufforderung: echo "..." | higgsfield generate create z_image --wait.

Bildqualität bei Soul: Übergeben Sie für text2image_soul_v2 und soul_cinematic --quality 1.5k oder --quality 2k. Dies sind UI-seitige Stufen; das Backend bildet sie auf 720p/1080p und modellspezifische Abmessungen aus dem gewählten --aspect_ratio ab. soul_location hat keinen Qualitätswähler; es verwendet feste Abmessungen pro Seitenverhältnis.

Marketing Studio

Generierung von Markenbildern/-videos: Avatare + Produkte + optionale Setup-Hooks/Einstellungen + Anzeigenmodi. Verwenden Sie die Modelle marketing_studio_video und marketing_studio_image.

Konzepte

• Avatar — Präsentationsgesicht. Kuratierter preset (durchsuchen mit higgsfield marketing-studio avatars list) oder custom (hochgeladene Fotos via higgsfield marketing-studio avatars create). Bei UGC-Modi ist ein Avatar optional, wenn die Aufgabenbeschreibung klar eine Person erwähnt; das Backend kann automatisch einen Soul Character erstellen. Übergeben Sie einen Avatar, wenn der Benutzer einen bestimmten Präsentator wünscht.
• Produkt — Markenartikel mit Titel + Referenzbildern. Importiert von einer URL (higgsfield marketing-studio products fetch --url ...) oder aus hochgeladenen Bildern erstellt (higgsfield marketing-studio products create).
• Webprodukt — App Store / Webseiten-Version. Wird beim Abrufen von App Store-URLs automatisch weitergeleitet.
• Hook — Wiederverwendbarer Eröffnungswinkel / Anzeigen-Hook. Durchsuchen mit higgsfield marketing-studio hooks list. Der Hook-Text wird der Benutzereingabe vorangestellt; er ersetzt nicht --prompt.
• Setting — Wiederverwendbarer Umgebungs-/Szenenkontext. Durchsuchen mit higgsfield marketing-studio settings list.

Erkundungsbefehle

Verwenden Sie diese genauen Listenbefehle, wenn der Benutzer fragt, was bereits existiert:

higgsfield marketing-studio avatars list --json
higgsfield marketing-studio products list --json
higgsfield marketing-studio hooks list --json
higgsfield marketing-studio settings list --json

--hook_id und --setting_id werden nur von marketing_studio_video unterstützt; übergeben Sie sie nicht an marketing_studio_image.

UX-Regeln (zusätzlich)

• Eine Frage pro Phase. Fragen Sie nicht gleichzeitig nach Produkt+Avatar+Modus.

Arbeitsablauf — Schnelles Anzeigenvideo

1. Produkt holen.
   • Bestehendes Produkt → higgsfield marketing-studio products list --json
   • URL → higgsfield marketing-studio products fetch --url <url> --wait (pollt, bis der Import abgeschlossen ist)
   • Lokale Bilder → higgsfield upload create <foto>... dann higgsfield marketing-studio products create --title "..." --image <id>... Produkt-ID erfassen. Wenn Sie --hook_id verwenden, ziehen Sie es stark vor, --product_ids zu übergeben; Hooks sind darauf ausgelegt, auf ein Produkt umzuschwenken, und funktionieren ohne Produktkontext schlecht.
2. Avatar auswählen, falls nötig.
   • Standard: higgsfield marketing-studio avatars list und einen Preset passend zur Markenstimme auswählen.
   • Benutzerdefiniert: higgsfield marketing-studio avatars create --name "..." --image <upload_id>. Bei UGC-Modi können Sie --avatars weglassen, wenn kein bestimmter Präsentator erforderlich ist und die Aufgabenbeschreibung eine Person erwähnt; das Backend kann einen Soul Character synthetisieren.
3. Optional Setup-Elemente auswählen.
   • Hook: higgsfield marketing-studio hooks list --json
   • Setting: higgsfield marketing-studio settings list --json Übergeben Sie die ausgewählten IDs als --hook_id <hook_id> und --setting_id <setting_id> nur für marketing_studio_video. Kopieren Sie den Prompt des Hooks nicht in --prompt, es sei denn, der Benutzer möchte explizit denselben Wortlaut verstärken.
4. Modus auswählen, falls nötig. Standard ist ugc; --mode ist nicht allein wegen --hook_id erforderlich. Weitere aktuelle Slugs: ugc_how_to, ugc_unboxing, product_showcase, product_review, tv_spot, wild_card, ugc_virtual_try_on, virtual_try_on. Siehe references/marketing-modes.md.
5. Generieren (One-Shot).

   PRODUCT_IDS_JSON=$(mktemp)
   AVATARS_JSON=$(mktemp)
   printf '["<product_id>"]' > "$PRODUCT_IDS_JSON"
   printf '[{"id":"<avatar_id>","type":"preset"}]' > "$AVATARS_JSON"
   
   higgsfield generate create marketing_studio_video \
     --prompt "..." \
     --avatars @"$AVATARS_JSON" \
     --product_ids @"$PRODUCT_IDS_JSON" \
     --mode ugc \
     --duration 15 \
     --resolution 720p \
     --aspect_ratio 9:16 \
     --wait
   

   Fügen Sie --hook_id <hook_id> und/oder --setting_id <setting_id> hinzu, wenn ein Setup-Hook/Setting ausgewählt wurde. product_ids und avatars sind JSON-Arrays; übergeben Sie sie via @/pfad/zu/datei.json. Übergeben Sie keine reine UUID an --product_ids. Die Auflösung ist 480p oder 720p. Das Seitenverhältnis ist eines von auto/21:9/16:9/4:3/1:1/3:4/9:16. --generate-audio true wird hier unterstützt (anders als bei seedance_2_0). --wait blockiert bis zur Fertigstellung; erhöhen Sie --wait-timeout 30m für längere Anzeigenläufe.
6. Ausliefern. URL + einzeilige Zusammenfassung (Modus, Dauer).

Click-to-Ad-Verknüpfung (URL-gesteuert)

Wenn der Benutzer eine Produkt-URL angibt und in einem Durchgang ein Marketing-Video wünscht:

# 1. Fetch auslösen (gibt die Produkt-ID zurück und startet Hintergrund-Scrape)
higgsfield marketing-studio products fetch --url https://shop.example.com/sneakers --wait

# 2. Marketing-Video gegen dieselbe URL generieren – Backend verwendet die Entität wieder
higgsfield generate create marketing_studio_video \
  --url https://shop.example.com/sneakers \
  --mode ugc \
  --duration 15 \
  --aspect_ratio 9:16 \
  --wait

Das Backend dedupliziert nach URL, sodass wiederholte Ausführungen die vorhandene Entität wiederverwenden, anstatt sie erneut abzurufen.

Arbeitsablauf — Marketing-Bild

Gleich wie oben, aber mit dem Modell marketing_studio_image:

higgsfield generate create marketing_studio_image \
  --prompt "..." \
  --aspect_ratio 1:1 \
  --resolution 2k \
  --wait

Fehler

• Missing required params: prompt → Benutzer hat keine Eingabeaufforderung gegeben; fragen Sie danach.
• Invalid values: aspect_ratio=99:99 (allowed: ...) → schlechter Enum-Wert; wählen Sie aus den erlaubten Werten.
• Unknown params: foo → Schema akzeptiert dieses Flag nicht; überprüfen Sie mit higgsfield model get <jst>. Wenn dies für hook_id oder setting_id passiert, unterstützt das ausgewählte Modell/job_set_type keine Marketing Studio-Setup-Elemente.
• Session expired → higgsfield auth login.

Weitere Informationen finden Sie in references/troubleshooting.md.

Referenzdokumente

Auf Anfrage laden:

• references/model-catalog.md — das richtige Modell für die Aufgabe auswählen
• references/prompt-engineering.md — Eingabeaufforderungen schreiben, die funktionieren
• references/media-inputs.md — Bild/Video-Referenzflüsse
• references/troubleshooting.md — häufige Fehler und Behebungen
• references/marketing-avatars.md — Preset vs. benutzerdefinierte Avatare
• references/marketing-products.md — URL-Abruf vs. manuelle Produkterstellung
• references/marketing-setup-items.md — Hooks/Einstellungen erkennen und verwenden
• references/marketing-modes.md — jeder Marketing Studio-Modus