Higgsfield (image and video generation)

Module id: higgsfield · Kind: provider · Configured by: HIGGSFIELD_API_KEY + HIGGSFIELD_API_SECRET · Provider: higgsfield

Higgsfield is a cinematic media provider: Soul and Reve for text-to-image, DoP and Kling 2.1 for image-to-video. Synaplan can talk to it with one set of platform credentials that every user shares, or each user can connect their own Higgsfield account. Only the platform pair switches this module on.

What it adds

  • Higgsfield image and video models in the catalog, selectable in chat and in multi-task plans ("make a short clip from this picture").
  • A platform key pair so the operator can offer the models to everyone — metered against each user's tier and budget like any other provider.
  • A personal connection card in each user's Settings, so users can bring their own account even when the operator has not set platform keys.

Without it

Higgsfield models are hidden from users who have not connected a personal account. The connection card stays visible on purpose: it is the way a user brings their own key. The card's hint reads "Higgsfield models will be hidden until either you add a personal key here or the platform operator sets a global HIGGSFIELD_API_KEY / HIGGSFIELD_API_SECRET".

How to enable

Platform credentials (switches the module on)

  1. Create an API key + secret at cloud.higgsfield.ai.
  2. Add both to the backend environment and restart backend + worker:
HIGGSFIELD_API_KEY=hf_…
HIGGSFIELD_API_SECRET=…

Both values are required — one without the other leaves the module Not installed.

  1. Check that the Higgsfield rows are active under Operate → System configuration → AI Models, and optionally make one the default for image or video generation.

Personal credentials (per user, does not flip the module)

Settings → Higgsfield Connection: paste key and secret, Test, Save. The key is stored encrypted for that user only and wins over the platform pair for that user's requests. Remove falls back to the platform key, if any.

Check it works

  • Operate → Feature Status → Higgsfield video generation shows Available / Higgsfield platform credentials present. There is no network probe — the credential card's Test button is the live check. HIGGSFIELD_API_KEY and HIGGSFIELD_API_SECRET are not both set means the module is off.
  • The connection card shows which source is in use: Using your personal Higgsfield key or the platform key.
  • Ask chat for an image with a Higgsfield model selected.

Configuration reference

Setting Where Meaning
HIGGSFIELD_API_KEY environment Platform API key.
HIGGSFIELD_API_SECRET environment Platform API secret.
Personal key + secret Settings → Higgsfield Connection Per-user credentials, encrypted; override the platform pair for that user.

API: GET / PUT / DELETE /api/v1/ai-providers/higgsfield/credentials and POST …/credentials/test manage the personal connection; these routes are never gated because they are how a user configures the feature.

Troubleshooting

  • Models missing for one user but not another. The other user has a personal key. Either set platform keys or have the user connect their account.
  • Test fails with an authentication error. Key and secret belong together — copy both from the same key entry at cloud.higgsfield.ai.
  • Generation runs but the result never arrives. Video jobs are asynchronous and can take minutes; the task card in chat updates when the clip is ready. Check the worker container is running (docker compose ps worker).

Related