Génération Higgsfield

Que fait Génération Higgsfield ?

Soumettez des travaux à n'importe quel modèle Higgsfield. Encapsule la CLI higgsfield. Couvre la génération générique d'images/vidéos et le Marketing Studio (publicités de marque, avatars, produits, accroches, décors).

Étape 0 — Initialisation

Avant toute autre commande, assurez-vous que la CLI est installée et authentifiée :

1. Si higgsfield n'est pas dans le $PATH, installez-la :

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

2. Si higgsfield account status échoue avec Session expirée / Non authentifié, demandez à l'utilisateur d'exécuter higgsfield auth login (interactif, ouvre un navigateur) et attendez sa confirmation avant de continuer.

Ignorez les deux vérifications si higgsfield account status affiche déjà les informations du compte.

Règles UX

1. Soyez concis. Pas d'identifiants bruts, pas de vidage JSON dans le chat. Affichez l'URL du résultat quand il est prêt.
2. Pas de jargon interne. Ne décrivez pas "appel à higgsfield cost", "interrogation du travail".
3. Détectez la langue de l'utilisateur à partir du premier message et répondez dans cette langue. Les arguments techniques (--aspect_ratio 16:9) restent en anglais.
4. Ne posez pas plusieurs questions à la fois. Choisissez un modèle par défaut raisonnable et ne posez qu'une seule question à la fois si une information manque vraiment.
5. N'estimez pas le coût à l'avance. Soumettez simplement, sauf si l'utilisateur le demande.
6. Passez --wait à generate create pour que la commande bloque jusqu'à la fin et affiche elle-même l'URL du résultat. Évitez le modèle en deux étapes create → wait.

Flux de travail — génération générique

1. Choisissez un modèle. Valeurs par défaut pratiques issues de l'utilisation en production :

   Image :

   • Visuel produit de marque (épingle Pinterest, style de vie, bannière héros, pack publicitaire, essayage virtuel) → utilisez higgsfield-product-photoshoot à la place. PAS cette compétence.
   • Image publicitaire de marque avec avatar + produit (format Marketing Studio) → Image Marketing Studio (voir Marketing Studio ci-dessous)
   • UGC esthétique / éditorial de mode / personnage de style de vie → Soul 2.0
   • Image de cinéma → Soul Cinema
   • Persona créatif très caractérisé (texte uniquement, distinctif) → Soul Cast
   • Lieux / environnements / scènes sans personne → Soul Location (meilleur de sa catégorie)
   • Illustrations vectorielles OU édition de visage + changement de scène complexe → Seedream 4.5
   • Personnage Soul (identifiant de référence provenant de higgsfield-soul-id) → Soul 2.0 pour les images fixes, Soul Cinema pour le cinéma
   • Itération rapide et économique → Z Image
   • Travail de personnage ou de style cartoon → Nano Banana 2 ; passez à Nano Banana Pro pour les cas difficiles
   • Par défaut pour tout le reste → GPT Image 2. Design graphique, UI, bannières, typographie et génération générale haute fidélité.

   Vidéo :

   • Toute vidéo publicitaire / commerciale / de marque → Marketing Studio (voir Marketing Studio ci-dessous)
   • Vidéo sérieuse polyvalente par défaut (multi-plans, identité cohérente, mouvement intense) → Seedance 2.0. SOTA.
   • Scène à plan unique sans forte dynamique, moins cher que Seedance 2.0 → Kling 3.0
   • Prise de vue propre et économique sans coupure → Seedance 1.5 Pro
   • Plus haute fidélité de qualité cinéma → Cinema Studio Video 3.0
   • Économique avec une physique solide, pas de son nécessaire → Minimax Hailuo
   • Lot rapide / volume → Veo 3.1 Lite

   Pour l'ID --model réel à passer à higgsfield generate create, exécutez higgsfield model list --json | jq pour mapper les noms d'affichage aux identifiants. Voir references/model-catalog.md pour le tableau complet.

2. Passez les entrées multimédia directement comme drapeaux. Les drapeaux multimédia acceptent un chemin de fichier local ou un UUID. La CLI télécharge automatiquement les chemins et détecte automatiquement le travail par rapport au téléchargement pour les UUID. Pas besoin de pré-télécharger. Chaque modèle déclare les rôles acceptés (image, start_image, end_image, video, audio) — voir references/media-inputs.md.

3. Validez rapidement. En cas de doute sur les paramètres, exécutez higgsfield model get <jst> --json une fois et ne passez que ce qui est nécessaire. Utilisez les valeurs par défaut du schéma pour le reste. Le serveur renvoie des adjustments pour les coercitions non fatales (par exemple aspect_ratio=99:99 → la correspondance la plus proche) et une erreur structurée pour les valeurs de paramètres déclarés invalides.

4. Soumettez et attendez en une seule fois. higgsfield generate create <jst> --prompt "..." [drapeaux médias] [drapeaux paramètres] --wait. Bloque jusqu'au statut final et affiche l'URL du résultat sur stdout. Options réglables : --wait-timeout 20m (par défaut 10m), --wait-interval 5s (par défaut 3s).

5. Livrez. Envoyez l'URL plus un résumé d'une ligne (modèle, durée si vidéo).

Pour inspecter ou relancer plus tard, higgsfield generate list --json et higgsfield generate get <id> --json fonctionnent pour la rétrospection. higgsfield generate wait <id> est toujours disponible si vous devez rejoindre un travail démarré sans --wait.

Drapeaux multimédia

Drapeau	Utilisation	Modèles qui l'acceptent
--image <chemin-ou-id>	image de référence	la plupart des modèles d'image, seedance_2_0, veo3, marketing_studio_video
--start-image <chemin-ou-id>	première image pour les transitions image-vers-vidéo	kling3_0, kling2_6, veo3_1, seedance_2_0, marketing_studio_video
--end-image <chemin-ou-id>	dernière image pour les transitions	kling3_0, seedance_2_0, marketing_studio_video
--video <chemin-ou-id>	vidéo de référence	seedance_2_0
--audio <chemin-ou-id>	audio de référence (synchronisation labiale, correspondance sonore)	seedance_2_0 (utilisez CECI, PAS --generate-audio)

Chaque drapeau accepte soit un chemin de fichier local (téléchargement automatique) soit un UUID (identifiant de téléchargement de higgsfield upload create, ou un identifiant de travail précédent). Chaque modèle déclare son propre ensemble de rôles via MEDIA_ROLES. Voir references/media-inputs.md pour le tableau complet.

Paramètres courants

Les drapeaux sont transmis au schéma du modèle. Utilisez higgsfield model get <jst> pour les découvrir.

higgsfield generate create gpt_image_2 --prompt "ville néon au crépuscule" --aspect_ratio 16:9 --resolution 2k --wait
higgsfield generate create nano_banana_2 --prompt "concept de personnage anime, pose expressive" --image ./ref.png --wait
higgsfield generate create seedance_2_0 --prompt "la caméra fait un travelling avant" --start-image ./first.png --duration 8 --wait
higgsfield generate create text2image_soul_v2 --prompt "..." --soul-id <soul_ref_id> --quality 2k --wait

Pour une sortie lisible par machine (pipelines chaînés, contexte d'agent), ajoutez --json. Avec --wait --json, vous obtenez le tableau d'objets de travail final. Sans --wait, vous obtenez les identifiants de travail.

Invite via stdin : echo "..." | higgsfield generate create z_image --wait.

Qualité de l'image Soul : pour text2image_soul_v2 et soul_cinematic, passez --quality 1.5k ou --quality 2k. Ce sont des niveaux orientés interface utilisateur ; le backend les mappe à 720p/1080p et aux dimensions spécifiques au modèle en fonction du --aspect_ratio sélectionné. soul_location n'a pas de sélecteur de qualité ; il utilise des dimensions fixes par rapport d'aspect.

Marketing Studio

Génération d'images/vidéos de marque : avatars + produits + accroches/décors optionnels + modes publicitaires. Utilisez les modèles marketing_studio_video et marketing_studio_image.

Concepts

• Avatar — visage du présentateur. preset organisé (parcourir higgsfield marketing-studio avatars list) ou custom (photos téléchargées via higgsfield marketing-studio avatars create). Pour les modes UGC, un avatar est facultatif si le brief mentionne clairement une personne ; le backend peut créer un personnage Soul automatiquement. Passez un avatar lorsque l'utilisateur souhaite un présentateur spécifique.
• Produit — article de marque avec titre + images de référence. Importé depuis une URL (higgsfield marketing-studio products fetch --url ...) ou créé à partir d'images téléchargées (higgsfield marketing-studio products create).
• Webproduct — version App Store / page web. Acheminement automatique lors de la récupération d'URL App Store.
• Hook (accroche) — angle d'ouverture / accroche publicitaire réutilisable. Parcourir avec higgsfield marketing-studio hooks list. Le texte de l'accroche est ajouté au début de l'invite de l'utilisateur ; il ne remplace pas --prompt.
• Setting (décor) — contexte d'environnement / scène réutilisable. Parcourir avec higgsfield marketing-studio settings list.

Commandes de découverte

Utilisez ces commandes de liste exactes lorsque l'utilisateur demande ce qui existe déjà :

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 et --setting_id sont pris en charge par marketing_studio_video uniquement ; ne les passez pas à marketing_studio_image.

Règles UX (supplémentaires)

• Une question par phase. Ne demandez pas le produit+avatar+mode d'un coup.

Flux de travail — vidéo publicitaire rapide

1. Obtenez le produit.
   • Produit existant → higgsfield marketing-studio products list --json
   • URL → higgsfield marketing-studio products fetch --url <url> --wait (interroge jusqu'à la fin de l'importation)
   • Images locales → higgsfield upload create <photo>... puis higgsfield marketing-studio products create --title "..." --image <id>... Capturez l'id du produit. Lorsque vous utilisez --hook_id, privilégiez fortement le passage de --product_ids ; les accroches sont conçues pour pivoter vers un produit et fonctionnent mal sans contexte de produit.
2. Choisissez un avatar si nécessaire.
   • Par défaut : higgsfield marketing-studio avatars list et choisissez un préréglage correspondant à la voix de la marque.
   • Personnalisé : higgsfield marketing-studio avatars create --name "..." --image <upload_id>. Pour les modes UGC, vous pouvez omettre --avatars lorsqu'aucun présentateur spécifique n'est requis et que le brief mentionne une personne ; le backend peut synthétiser un personnage Soul.
3. Choisissez optionnellement des éléments de configuration.
   • Accroche : higgsfield marketing-studio hooks list --json
   • Décor : higgsfield marketing-studio settings list --json Passez les identifiants sélectionnés sous forme de --hook_id <hook_id> et --setting_id <setting_id> pour marketing_studio_video uniquement. Ne copiez pas l'invite de l'accroche dans --prompt sauf si l'utilisateur souhaite explicitement renforcer le même libellé.
4. Choisissez le mode si nécessaire. La valeur par défaut est ugc ; --mode n'est pas requis simplement parce que --hook_id est présent. Autres slugs actuels : ugc_how_to, ugc_unboxing, product_showcase, product_review, tv_spot, wild_card, ugc_virtual_try_on, virtual_try_on. Voir references/marketing-modes.md.
5. Générez (en une seule fois).

   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
   

   Ajoutez --hook_id <hook_id> et/ou --setting_id <setting_id> lorsqu'une accroche/décor de configuration a été sélectionné. product_ids et avatars sont des tableaux JSON ; passez-les via @/chemin/vers/fichier.json. Ne passez pas un UUID nu à --product_ids. La résolution est 480p ou 720p. Le rapport d'aspect est l'un de auto/21:9/16:9/4:3/1:1/3:4/9:16. --generate-audio true est pris en charge ici (contrairement à seedance_2_0). --wait bloque jusqu'à la fin ; augmentez --wait-timeout 30m pour des exécutions publicitaires plus longues.
6. Livrez. URL + résumé d'une ligne (mode, durée).

Raccourci Click-to-Ad (piloté par URL)

Lorsque l'utilisateur fournit une URL de produit et souhaite une vidéo marketing en une seule fois :

# 1. Déclenchez la récupération (renvoie l'id du produit et démarre le scraping en arrière-plan)
higgsfield marketing-studio products fetch --url https://shop.example.com/sneakers --wait

# 2. Générez la vidéo marketing pour la même URL — le backend réutilise l'entité
higgsfield generate create marketing_studio_video \
  --url https://shop.example.com/sneakers \
  --mode ugc \
  --duration 15 \
  --aspect_ratio 9:16 \
  --wait

Le backend déduplique par URL, donc les exécutions répétées réutilisent l'entité existante au lieu de récupérer à nouveau.

Flux de travail — image marketing

Identique à ci-dessus mais utilisez le modèle marketing_studio_image :

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

Erreurs

• Missing required params: prompt → l'utilisateur n'a pas fourni d'invite ; demandez-la.
• Invalid values: aspect_ratio=99:99 (allowed: ...) → mauvaise énumération ; choisissez parmi les valeurs autorisées.
• Unknown params: foo → le schéma n'accepte pas ce drapeau ; vérifiez higgsfield model get <jst>. Si cela se produit pour hook_id ou setting_id, le modèle/job_set_type sélectionné ne prend pas en charge les éléments de configuration Marketing Studio.
• Session expirée → higgsfield auth login.

Voir references/troubleshooting.md pour plus d'informations.

Documents de référence

Chargez à la demande :

• references/model-catalog.md — choisir le bon modèle pour la tâche
• references/prompt-engineering.md — rédiger des invites qui fonctionnent
• references/media-inputs.md — flux de référence image/vidéo
• references/troubleshooting.md — erreurs courantes et solutions
• references/marketing-avatars.md — avatars prédéfinis ou personnalisés
• references/marketing-products.md — récupération d'URL ou création manuelle de produit
• references/marketing-setup-items.md — découverte et utilisation des accroches/décors
• references/marketing-modes.md — tous les modes Marketing Studio