Guide gratuit23 min de lecture

Créer tes pubs avec Higgsfield

La méthode complète pour produire tes créas publicitaires avec Higgsfield, à la main d'abord, puis en automatique avec leur nouvelle API.

Higgsfield a sorti son API. Tout le monde a retenu le prix. Le prix, ce n'est pas le sujet.

Le sujet, c'est que tu peux enfin brancher un pipeline de créas publicitaires sur ton propre système : ton catalogue produit entre d'un côté, trente visuels prêts à uploader dans le gestionnaire de pubs sortent de l'autre, sans qu'un humain ouvre quoi que ce soit.

Ce guide te montre exactement comment. D'abord à la main pour comprendre ce qui fait une bonne créa, ensuite en automatique pour ne plus jamais le refaire à la main.


1. Ce que Higgsfield fait vraiment

Higgsfield n'est pas un modèle de génération. C'est une couche au-dessus de plusieurs modèles : SOUL 2 et SOUL Cinema (les leurs), Seedance 2.0 et 2.5 de ByteDance, Kling 3.0, Wan 3.0 d'Alibaba, Recraft, Grok Image. Une seule authentification, un seul cycle de requête, et tu changes de moteur en changeant une chaîne de caractères.

Ça c'est le confort. Le vrai avantage est ailleurs.

Un modèle brut ne sait pas ce qu'est une publicité. Tu lui écris « photo de mon produit » et il te rend une photo de produit : correcte, morte, inutilisable en ads. Ce qui transforme une image en créa, c'est tout ce que tu ne penses pas à écrire : la hauteur de caméra, la direction de la lumière, la place laissée pour le texte, la distance qui donne envie de toucher le produit.

Higgsfield a écrit ces prompts de cadrage à ta place et les a rangés dans des presets. Quand tu appelles leur modèle Marketing Studio avec un preset, tu ne prompt pas une image, tu choisis une grammaire publicitaire déjà écrite par des gens dont c'est le métier.

C'est ça que tu achètes. Pas des pixels pas chers.

Sur le prix, justement. Le tarif dépend du modèle et des paramètres (résolution, qualité, audio, durée). Les chiffres qui circulent valent pour une configuration précise et pas pour une autre. Le seul chiffre qui compte, c'est celui de ton compte, et tu l'obtiens avant de dépenser quoi que ce soit :

curl --request POST \
  --url https://api.higgsfield.ai/estimate/higgsfield-ai/soul/v2/standard \
  --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
  --header "Content-Type: application/json" \
  --data '{"prompt": "Editorial portrait in soft daylight"}'

Réponse : {"credits": "1.500", "usd": "0.094"}. Fais tourner cet appel sur les trois configurations que tu envisages avant de lancer un batch de deux cents images. Ça prend une minute et ça t'évite la mauvaise surprise en fin de mois.

Deux règles de facturation à connaître : une requête qui finit en failed ou en nsfw n'est pas facturée, et les crédits expirent un an après leur achat.


2. Les trois actifs à préparer avant de générer quoi que ce soit

C'est l'étape que tout le monde saute et c'est celle qui décide de la qualité finale. Une génération, c'est un amplificateur : elle amplifie aussi la médiocrité de ce que tu lui donnes.

Le packshot produit

Une photo de ton produit, fond neutre, une seule source de lumière, aucune ombre portée dure, aucun reflet de la pièce dans laquelle tu l'as shootée. Idéalement un PNG détouré.

Pourquoi ça compte autant : en mode enhanced, le modèle ne redessine pas ton produit, il le réinstalle dans une scène. Si ton image source a une dominante jaune parce que tu l'as prise sous un plafonnier, cette dominante se retrouve dans les trente créas. Si l'étiquette est floue, elle reste floue partout.

Si tu n'as qu'une photo moyenne, passe-la d'abord en édition simple (mode direct, une seule image_url, prompt du type « isolate the product on a clean neutral background, even studio lighting ») et sers-toi du résultat comme source pour la suite.

Le visage, si tu fais de l'UGC

Une pub qui ressemble à un post, ça veut dire un humain dedans. Higgsfield accepte une seconde image de modèle en mode enhanced. Prépare-la comme le produit : cadrage net, lumière neutre, expression disponible plutôt que figée.

Si tu veux le même visage sur toute une campagne, regarde du côté des identités persistantes de SOUL plutôt que de rejouer ta chance à chaque appel.

L'angle

Le plus important et le seul qui ne se génère pas.

Un angle, ce n'est pas un style, c'est une promesse. « Photo lifestyle lumineuse » n'est pas un angle. « Ce que tu portes le dimanche matin quand tu ne veux voir personne » en est un.

Écris-en cinq avant d'ouvrir quoi que ce soit. Tes cinq angles multipliés par trois presets multipliés par deux formats, ça fait trente créas, et c'est un test publicitaire réel. Cinq variations de la même image, c'est cinq fois la même pub.


3. La pub statique, en quatre temps

Le modèle : Marketing Studio Image, endpoint POST https://api.higgsfield.ai/marketing-studio/image.

Il a deux modes et c'est toute la subtilité.

Mode direct

Tu écris le prompt, tu reçois l'image. Jusqu'à 16 images de référence acceptées. C'est le mode à utiliser quand tu sais exactement ce que tu veux, ou pour retoucher (« place the product in a bright poolside campaign scene »).

curl --request POST \
  --url https://api.higgsfield.ai/marketing-studio/image \
  --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
  --header "Content-Type: application/json" \
  --data '{
    "prompt": "Place the product on a warm travertine ledge, late afternoon light, single hard shadow, negative space at the top third",
    "image_urls": ["https://cdn.example.com/packshot.png"],
    "resolution": "2k",
    "aspect_ratio": "3:4",
    "quality": "high"
  }'

Mode enhanced

Tu passes enhance_prompt: true et un preset_id. Higgsfield prend ton prompt et le fond dans une composition publicitaire déjà écrite. Ton prompt devient une intention (« premium, minimal, warm morning light ») et le preset s'occupe du reste.

Trois contraintes à ne pas rater, parce qu'elles cassent silencieusement :

  1. preset_id est obligatoire quand enhance_prompt est à true, et au moins une image dans image_urls.
  2. L'ordre de image_urls a un sens : le produit d'abord, le modèle ensuite. Inversés, tu obtiens une pub pour un mannequin.
  3. En enhanced, quality est ignoré, tout sort en high. Et si tu laisses aspect_ratio à auto ou vide, c'est le ratio du preset qui gagne, pas le tien.

Trouver les presets

curl --request GET \
  --url "https://api.higgsfield.ai/marketing-studio/image/presets?size=50&cursor=0" \
  --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}"

Attention, la documentation officielle montre cet appel sans header d'authentification. Tel quel, il répond {"detail":"Invalid credentials"}. Ajoute l'Authorization, c'est un endpoint authentifié comme les autres.

Tu récupères une liste de {id, type, name, metadata: {aspect_ratio, group_name}}. Pagine avec cursor jusqu'à ce que la réponse renvoie cursor: null.

Fais-le une fois, mets le résultat au chaud dans ta base. Ces UUID ne changent pas tous les jours, et tu ne veux pas taper cet endpoint à chaque génération. Garde le name et le group_name à côté : c'est ce qui te permettra de dire « donne-moi trois presets du groupe Editorial » au lieu de coller des UUID à la main.

Le format de sortie

Ratios acceptés : auto, 1:1, 3:2, 2:3, 4:3, 3:4, 16:9, 9:16, 21:9. Résolutions : 1k, 2k, 4k.

Le piège : le 4:5, format roi du fil Meta, n'est pas dans la liste. Génère en 3:4 en 2k et recadre au centre, ou génère en 1:1. Ne t'obstine pas à envoyer "4:5", ça ne passera pas.

Pour le reste : 9:16 pour les stories et les Reels, 1:1 pour le fil, 16:9 pour YouTube et les display. Génère en 2k même si tu diffuses plus petit, tu garderas de la marge pour recadrer.


4. Passer le statique en vidéo

Une créa statique validée est un excellent point de départ de vidéo, parce qu'elle a déjà fait son travail de composition. Tu la donnes comme première image et tu demandes juste du mouvement.

Modèle : Seedance 2.5 image-to-video, endpoint POST https://api.higgsfield.ai/bytedance/seedance-2.5/image-to-video.

curl --request POST \
  --url https://api.higgsfield.ai/bytedance/seedance-2.5/image-to-video \
  --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
  --header "Content-Type: application/json" \
  --data '{
    "prompt": "Slow push-in on the product, dust motes drifting through the light, subtle parallax",
    "image_url": "https://cdn.example.com/creative-validated.jpg",
    "duration": 6,
    "resolution": "720p",
    "generate_audio": true,
    "output_format": "mp4"
  }'

Ce qu'il faut retenir :

  • Le prompt ne décrit plus la scène, il décrit le mouvement. La scène, c'est ton image. Si tu re-décris le décor, tu te bats contre ta propre image et tu obtiens une dérive visuelle au bout de deux secondes.
  • Le cadrage suit l'image d'entrée. Tu veux du 9:16 en vidéo ? Génère ta créa en 9:16 en amont.
  • duration va de 4 à 30 secondes. Pour une pub, reste entre 5 et 8 : au-delà, la génération dérive et tu payes plus cher un plan que tu vas couper.
  • end_image_url te donne la dernière image. Mets la même que la première et tu obtiens une boucle propre, ce qui est exactement ce que tu veux pour un Reel.
  • generate_audio produit un son synchronisé. Utile pour tester, à remplacer par ta vraie piste pour diffuser.
  • Résolutions : 480p ou 720p seulement sur ce modèle. Pour du 4K, va voir Kling 3.0.

5. Brancher l'API, pour de vrai

Toute l'API tient en quatre gestes : tu postes, tu reçois un identifiant, tu attends, tu télécharges.

Les clés

Tu les crées sur console.higgsfield.ai. Une clé, c'est un identifiant et un secret, et ils partent ensemble dans un seul header :

Authorization: Key YOUR_KEY_ID:YOUR_KEY_SECRET

Les vieux headers hf-api-key et hf-secret marchent encore, ne les utilise pas pour du neuf.

Jamais côté navigateur. Une clé dans du code front, c'est ton solde offert à qui ouvre l'inspecteur. Le client TypeScript officiel bloque d'ailleurs l'usage navigateur. Deux jeux de clés, un dev et un prod, et une rotation immédiate à la moindre fuite.

Le cycle de vie

Toute génération répond immédiatement, en queued :

{
  "status": "queued",
  "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff",
  "status_url": "https://api.higgsfield.ai/requests/d7e6c0f3-.../status",
  "cancel_url": "https://api.higgsfield.ai/requests/d7e6c0f3-.../cancel"
}

Tu stockes le request_id et tu interroges status_url jusqu'à un état terminal. Les états terminaux sont completed, failed, nsfw et canceled. Un nsfw sur une pub, ça arrive : un mannequin en maillot suffit. Ce n'est pas facturé, mais ton pipeline doit savoir passer à la suite au lieu de boucler.

Rythme de polling recommandé : deux secondes au départ, tu augmentes progressivement jusqu'à dix, avec un peu d'aléatoire si plusieurs workers interrogent en même temps.

import random, time, httpx

TERMINAL = {"completed", "failed", "nsfw", "canceled"}
delay = 2.0

while True:
    r = httpx.get(status_url, headers={"Authorization": f"Key {key_id}:{secret}"}, timeout=30)
    r.raise_for_status()
    result = r.json()
    if result["status"] in TERMINAL:
        break
    time.sleep(delay + random.uniform(0, 0.5))
    delay = min(delay * 1.5, 10.0)

Les webhooks, dès que c'est sérieux

Le polling, c'est bien pour un script. En production, tu passes une URL HTTPS dans le paramètre de requête hf_webhook au moment de soumettre :

POST https://api.higgsfield.ai/marketing-studio/image?hf_webhook=https%3A%2F%2Fton-domaine.com%2Fwebhooks%2Fhiggsfield

Higgsfield te poste le résultat. Quatre choses à savoir avant de le brancher :

  • Ton endpoint doit répondre en moins de dix secondes. Enregistre et réponds 2xx, traite après.
  • Les doublons sont possibles. Déduplique sur request_id plus statut terminal.
  • Un 5xx de ta part est retenté pendant deux heures. Un 4xx est définitif, tu as perdu l'événement.
  • Garde le polling comme filet : si la livraison échoue pour de bon, le statut authentifié reste la source de vérité.

La charge utile est enveloppée : {request_id, status, error, payload}, avec payload.images[] pour une image et payload.video pour une vidéo.

Envoyer tes propres fichiers

Ton packshot doit être accessible en HTTPS public. S'il ne l'est pas, Higgsfield te donne une URL de dépôt signée :

curl --request POST \
  --url https://api.higgsfield.ai/files/generate-upload-url \
  --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
  --header "Content-Type: application/json" \
  --data '{"content_type":"image/jpeg"}'

Tu reçois un upload_url, un public_url et des upload_headers. Tu envoies le fichier en PUT sur upload_url avec tous les headers renvoyés (dont le x-amz-tagging), puis tu passes public_url au modèle. L'URL de dépôt expire au bout d'une heure, et le content_type du dépôt doit être identique à celui déclaré.

Et surtout : aucune clé Higgsfield sur l'URL de stockage signée. Elle n'en a pas besoin et tu ne veux pas l'envoyer à un tiers.

Les deux limites qui vont te tomber dessus

La concurrence. C'est la vraie limite, pas le nombre d'appels par minute. Tu as un nombre maximum de requêtes en attente ou en traitement en même temps, visible dans ta console. Au-delà, tu ne reçois pas un 429 mais un 400 avec un message du genre « Maximum number of concurrent requests (4) has been reached ». Si ton code ne retente que sur les 429, il va jeter des générations sans comprendre pourquoi. Mets un sémaphore côté client et suis chaque request_id jusqu'à son état terminal.

La rétention. Les fichiers produits sont disponibles au moins sept jours, et après, ils peuvent disparaître. Une URL de CDN Higgsfield collée dans un Google Sheet, c'est une bibliothèque de créas qui s'évapore. Télécharge systématiquement vers ton propre stockage dans le webhook, avant même de notifier qui que ce soit.

Les SDK

pip install higgsfield-client
npm install @higgsfield/client
import higgsfield_client

result = higgsfield_client.subscribe(
    "marketing-studio/image",
    arguments={"prompt": "...", "resolution": "2k", "aspect_ratio": "3:4"},
)
print(result["images"][0]["url"])

subscribe fait le polling pour toi : parfait pour un script, à éviter dans un worker où tu veux garder la main sur le cycle de vie (là, tu prends submit).


6. Le batch : trente créas pendant que tu dors

C'est là que l'API cesse d'être un gadget.

La structure est toujours la même, et elle n'a rien de compliqué :

const ANGLES = [
  "le cadeau qu'on garde pour soi",
  "ce que tu prends quand tu n'as que trois minutes",
  "la version adulte d'un truc d'enfant",
  "ce qui reste quand tu as tout enlevé",
  "le détail que personne ne remarque sauf toi",
];
const PRESETS = ["<uuid-editorial>", "<uuid-lifestyle>", "<uuid-studio>"];
const RATIOS = ["1:1", "9:16"];

const jobs = ANGLES.flatMap((angle) =>
  PRESETS.flatMap((preset) =>
    RATIOS.map((ratio) => ({ angle, preset, ratio })),
  ),
);
// 5 x 3 x 2 = 30 créas

Tu pousses ces trente jobs dans une file avec un sémaphore calé sur ta limite de concurrence, chaque soumission part avec le hf_webhook, et ton endpoint de réception fait trois choses dans cet ordre : il télécharge le fichier chez toi, il écrit la ligne en base avec l'angle, le preset et le ratio, il répond 2xx.

Le point qui change tout : stocke les métadonnées à côté du fichier. Dans trois semaines, quand une créa tournera deux fois mieux que les autres, la seule question qui vaudra c'est « c'était quel angle, quel preset ? ». Sans ça, tu as une jolie galerie et zéro apprentissage. Avec ça, tu as une machine qui s'améliore.

Le coût d'un batch de trente, tu le connais avant de le lancer : POST /estimate/... avec exactement les mêmes paramètres, multiplié par trente.


7. Écrire des prompts qui donnent des pubs

Un prompt de créa publicitaire tient en cinq blocs, dans cet ordre.

Bloc Ce que tu écris Exemple
Sujet le produit, tel quel « a matte black ceramic mug »
Contexte où, avec quoi, quelle heure « on a linen-covered table, morning kitchen »
Lumière la direction avant tout « hard side light from the left, single shadow »
Cadrage distance et hauteur de caméra « three-quarter view, slightly above eye level, close »
Intention ce que la pub doit faire « negative space in the upper third for a headline »

Ce dernier bloc est celui que personne n'écrit et c'est celui qui fait la différence entre une belle image et une créa exploitable. Si tu ne réserves pas la place du texte, ton graphiste devra la voler, et il la volera au produit.

Quatre prompts prêts à adapter :

Produit seul, premium. « [produit] on a warm travertine ledge, late afternoon sunlight raking from the left, one clean hard shadow, muted sand and bone palette, three-quarter view slightly above, shallow depth of field, generous negative space in the upper third »

UGC, tenu en main. « hand holding [produit] toward the camera, bright overcast daylight, real apartment kitchen softly out of focus behind, slight motion blur on the hand, shot on a phone, imperfect framing, no studio lighting »

Comparaison avant/après. « split composition, [produit] on the right side against a calm deep green background, empty matching space on the left, even frontal lighting, no props, flat graphic feel »

Saisonnier. « [produit] half-buried in dry autumn leaves, low golden hour sun flaring into the lens, warm amber and rust palette, top-down view, negative space bottom left »

Et pour la vidéo, rappelle-toi : tu ne décris que le mouvement. « Slow push-in, subtle parallax, dust in the light beam », « slow orbit around the product, shallow focus holding the label », « handheld drift with a small natural sway ». Trois mots de mouvement valent mieux qu'un paragraphe de décor que le modèle va vouloir réinventer.


8. Les sept pièges qui coûtent cher

  1. Décrire un style au lieu de décrire un plan. « Moderne et épuré » ne veut rien dire pour un modèle. « Vue de trois quarts, légèrement en plongée, lumière latérale dure » veut dire quelque chose.
  2. Attendre du texte propre dans l'image. Même les meilleurs modèles cassent une typo sur un slogan un peu long. Génère l'image sans texte, incruste le texte par-dessus. Tu y gagnes aussi la possibilité de tester dix accroches sur une seule créa.
  3. Croire que le produit est reproduit à l'identique. Il est réinterprété. Sur un produit à étiquette, à logo ou à forme signée, vérifie créa par créa avant de diffuser. Une bouteille dont le nom a perdu une lettre, ça se voit.
  4. Traiter le 400 de concurrence comme une erreur de requête. C'est une limite, pas un bug de ton payload. Sémaphore, file, patience.
  5. Ne pas rapatrier les fichiers. Sept jours, et c'est parti. Le téléchargement fait partie du pipeline, pas du « on verra plus tard ».
  6. Compter sur le webhook seul. Garde le polling en secours, sinon une indisponibilité de dix minutes chez toi te coûte un batch entier.
  7. Générer trente variations d'un seul angle. Ce n'est pas un test publicitaire, c'est trente fois la même hypothèse. Le modèle t'a rendu la production gratuite, ce qui rend la stratégie plus importante, pas moins.

9. Ta checklist de lancement

  • Packshot propre, fond neutre, disponible en HTTPS public ou déposé via l'URL signée
  • Cinq angles écrits, sur papier, avant toute génération
  • Liste des presets récupérée une fois et mise en base, avec les noms de groupe
  • Coût d'une génération vérifié avec /estimate sur tes vrais paramètres
  • Clés stockées côté serveur, deux jeux séparés dev et prod
  • Webhook branché, réponse en moins de dix secondes, déduplication sur request_id
  • Téléchargement automatique vers ton stockage dans les minutes qui suivent
  • Sémaphore calé sur ta limite de concurrence
  • Angle, preset et ratio enregistrés à côté de chaque fichier
  • Les trois meilleures créas passées en vidéo avec Seedance, en boucle propre

10. Ce que ça donne une fois branché

Le moment où ça bascule, ce n'est pas quand tu génères une belle image. C'est quand ta fiche produit entre d'un côté et que trente créas taguées sortent de l'autre, sans que personne n'ouvre un outil.

À partir de là, ton budget créa ne dépend plus de ta capacité de production. Il dépend uniquement de ta capacité à écrire de bons angles, et ça, c'est du travail de marque, pas du travail de pixel.

C'est exactement le type de pipeline qu'on branche chez nos clients : leur catalogue, leur charte, leurs formats, et une boucle qui tourne toute seule.

Vous préférez qu'on le fasse pour vous ?

On le met en place dans votre boîte

30 minutes de call. On regarde vos outils et vos process, et on vous dit ce qu'on peut livrer en 7 jours.

Réserver un appel

Prêt à passer à l'action ?

30 minutes de call. On regarde votre stack, vos pain points, on vous dit ce qu'on peut livrer en 7 jours.

Avant

Treize outils. Aucun ne se parle.