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 :
preset_idest obligatoire quandenhance_promptest àtrue, et au moins une image dansimage_urls.- L'ordre de
image_urlsa un sens : le produit d'abord, le modèle ensuite. Inversés, tu obtiens une pub pour un mannequin. - En enhanced,
qualityest ignoré, tout sort enhigh. Et si tu laissesaspect_ratioàautoou 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.
durationva 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_urlte 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_audioproduit un son synchronisé. Utile pour tester, à remplacer par ta vraie piste pour diffuser.- Résolutions :
480pou720pseulement 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_idplus statut terminal. - Un
5xxde ta part est retenté pendant deux heures. Un4xxest 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
- 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.
- 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.
- 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.
- Traiter le
400de concurrence comme une erreur de requête. C'est une limite, pas un bug de ton payload. Sémaphore, file, patience. - 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 ».
- Compter sur le webhook seul. Garde le polling en secours, sinon une indisponibilité de dix minutes chez toi te coûte un batch entier.
- 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
/estimatesur 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.












