Higgsfield (Open API, pay-per-use)
Unofficial; not affiliated with Higgsfield AI. Every generation spends real money from the
user's prepaid cloud.higgsfield.ai balance. The plugin's guard hook makes Claude Code ask
before any submit, upload or cancel, in every permission mode. Never route around it: no
inline curl to the API, no new scripts that call it, never read or print the key.
Tool
scripts/hf.sh in this skill's base directory. Call it by its absolute path.
| Command |
Cost |
Guard |
hf.sh setup |
free |
runs; opens a hidden-input dialog, the user types the key there |
hf.sh status |
free |
runs; says where the key is stored and verifies it, never prints it |
hf.sh prices |
free |
runs; per-account prices for the core models |
hf.sh estimate <endpoint> @<file.json> |
free |
runs; exact cost of that request |
hf.sh submit <endpoint> @<file.json> |
spends credits |
asks |
hf.sh upload <local-file> → public URL |
free, sends the file to Higgsfield |
asks |
hf.sh wait <request_id> <out_dir> → saved paths |
free |
runs |
hf.sh get <endpoint> (presets, Soul ID status) |
free |
runs |
hf.sh cancel <request_id> (queued only, refunded) |
— |
asks |
Write each request body to a JSON file (e.g. ./higgsfield-output/req-<n>.json) and pass
@file to both estimate and submit, so the price quoted is for the exact request sent.
Model inputs take public URLs, never local paths: upload local files first.
First use
Run hf.sh status. If no key is connected, tell the user they need a key ID and secret
from cloud.higgsfield.ai (API keys), then run hf.sh setup: a dialog opens (macOS) for
them to paste into. Never ask them to paste the key into chat. On Linux without a GUI,
setup needs a terminal: ask them to run ! <abs path>/hf.sh setup themselves.
After setup, show hf.sh prices so they see what things cost on their account.
Pick the route
| The user wants… |
Read |
Default model |
| A realistic person, creator, influencer, lifestyle or UGC still |
references/models.md |
Soul 2 |
| The same person across many images and videos |
references/characters.md |
Soul ID → Soul 2 |
| Product photo, lifestyle scene, hero banner, Pinterest pin, ad pack, try-on, restyle |
references/product-photoshoot.md |
Marketing Studio Sunburst (+ preset) |
| A graphic, banner or anything with text in the image |
references/models.md |
Marketing Studio Sunburst |
| UGC, talking, selfie or handheld video, product demo |
references/video.md |
Kling 3.0 image-to-video |
| Premium, cinematic, motion-heavy or 4K video |
references/video.md |
Seedance 2.0 |
Read references/prompting.md before writing a prompt, and the chosen model's live schema
before building the request (links in references/models.md) — fields change.
Every job, in order
- Interview only the gaps: at most 4 short questions with labeled options, skipping
anything obvious from context.
- Price it: write the body file, run
hf.sh estimate, and confirm in one line:
model, prompt, count / duration / resolution, and the estimated cost from the API.
Never quote prices from memory; they differ per account and change. Marketing Studio and
Seedance are token-metered: estimate returns a pricing rule, not a number — quote it as
"metered, billed on actual usage" with the rule's rough figure, and point to the user's
console for claimed discounts.
- Drafts first: 1 image on Flare or Soul 2, video at 5s on the standard tier, unless
the user asked for more.
- Submit once. Never loop, batch or retry a submit on your own. Failed and
nsfw
requests are refunded, but a retry is a new charge: report and let the user decide.
- Wait and save to the folder the user named, else
./higgsfield-output/. Output
URLs expire after about 7 days, so always download.
- Let the user pick. Never choose the winners yourself. Show every option the user
paid for, numbered and grouped by what each batch is for (one labelled contact sheet
per batch, sent to the user, not only read by you). You may mark a recommendation,
labelled as yours. Don't place, rename, commit or keep any image as "the" pick, and
don't delete the raw outputs, until the user has chosen. If they ask to see a past
round,
wait on its request IDs re-downloads it free while the URLs last (~7 days).
- Deliver the picked ones: file paths and what it cost, and one suggestion for the
next iteration. No JSON or request IDs in chat.
Terminal statuses: completed, failed (refunded), nsfw (moderation, refunded — rephrase,
don't resubmit the same prompt), canceled (refunded).
Portions adapted from higgsfield-ai/skills (MIT, © 2026 Higgsfield AI); see NOTICE.
1---2name: higgsfield3description: Generate images and videos with the Higgsfield Open API on the user's own API key — realistic creator and UGC photos (Soul 2), product photoshoots and ad creatives (Marketing Studio GPT Image 2.5 with presets), recurring characters (Soul ID), UGC video (Kling 3.0) and premium video (Seedance 2.0) — quoting the exact price on their account before every spend. Use when the user asks to generate, make, render or animate an image, photo, product shot, ad, UGC clip or video with Higgsfield, asks what Higgsfield costs them, or wants to connect a Higgsfield API key.4metadata:5 source: https://skillmd.com/skills/nkrrish/higgsfield6---78# Higgsfield (Open API, pay-per-use)910Unofficial; not affiliated with Higgsfield AI. Every generation spends real money from the11user's prepaid cloud.higgsfield.ai balance. The plugin's guard hook makes Claude Code ask12before any submit, upload or cancel, in every permission mode. Never route around it: no13inline curl to the API, no new scripts that call it, never read or print the key.1415## Tool1617`scripts/hf.sh` in this skill's base directory. Call it by its absolute path.1819| Command | Cost | Guard |20|---|---|---|21| `hf.sh setup` | free | runs; opens a hidden-input dialog, the user types the key there |22| `hf.sh status` | free | runs; says where the key is stored and verifies it, never prints it |23| `hf.sh prices` | free | runs; per-account prices for the core models |24| `hf.sh estimate <endpoint> @<file.json>` | free | runs; exact cost of that request |25| `hf.sh submit <endpoint> @<file.json>` | spends credits | asks |26| `hf.sh upload <local-file>` → public URL | free, sends the file to Higgsfield | asks |27| `hf.sh wait <request_id> <out_dir>` → saved paths | free | runs |28| `hf.sh get <endpoint>` (presets, Soul ID status) | free | runs |29| `hf.sh cancel <request_id>` (queued only, refunded) | — | asks |3031Write each request body to a JSON file (e.g. `./higgsfield-output/req-<n>.json`) and pass32`@file` to both `estimate` and `submit`, so the price quoted is for the exact request sent.33Model inputs take public URLs, never local paths: `upload` local files first.3435## First use3637Run `hf.sh status`. If no key is connected, tell the user they need a key ID and secret38from cloud.higgsfield.ai (API keys), then run `hf.sh setup`: a dialog opens (macOS) for39them to paste into. Never ask them to paste the key into chat. On Linux without a GUI,40setup needs a terminal: ask them to run `! <abs path>/hf.sh setup` themselves.41After setup, show `hf.sh prices` so they see what things cost on their account.4243## Pick the route4445| The user wants… | Read | Default model |46|---|---|---|47| A realistic person, creator, influencer, lifestyle or UGC still | `references/models.md` | Soul 2 |48| The same person across many images and videos | `references/characters.md` | Soul ID → Soul 2 |49| Product photo, lifestyle scene, hero banner, Pinterest pin, ad pack, try-on, restyle | `references/product-photoshoot.md` | Marketing Studio Sunburst (+ preset) |50| A graphic, banner or anything with text in the image | `references/models.md` | Marketing Studio Sunburst |51| UGC, talking, selfie or handheld video, product demo | `references/video.md` | Kling 3.0 image-to-video |52| Premium, cinematic, motion-heavy or 4K video | `references/video.md` | Seedance 2.0 |5354Read `references/prompting.md` before writing a prompt, and the chosen model's live schema55before building the request (links in `references/models.md`) — fields change.5657## Every job, in order58591. **Interview only the gaps**: at most 4 short questions with labeled options, skipping60 anything obvious from context.612. **Price it**: write the body file, run `hf.sh estimate`, and confirm in one line:62 model, prompt, count / duration / resolution, and the estimated cost from the API.63 Never quote prices from memory; they differ per account and change. Marketing Studio and64 Seedance are token-metered: `estimate` returns a pricing rule, not a number — quote it as65 "metered, billed on actual usage" with the rule's rough figure, and point to the user's66 console for claimed discounts.673. **Drafts first**: 1 image on Flare or Soul 2, video at 5s on the standard tier, unless68 the user asked for more.694. **Submit once.** Never loop, batch or retry a submit on your own. Failed and `nsfw`70 requests are refunded, but a retry is a new charge: report and let the user decide.715. **Wait and save** to the folder the user named, else `./higgsfield-output/`. Output72 URLs expire after about 7 days, so always download.736. **Let the user pick.** Never choose the winners yourself. Show every option the user74 paid for, numbered and grouped by what each batch is for (one labelled contact sheet75 per batch, sent to the user, not only read by you). You may mark a recommendation,76 labelled as yours. Don't place, rename, commit or keep any image as "the" pick, and77 don't delete the raw outputs, until the user has chosen. If they ask to see a past78 round, `wait` on its request IDs re-downloads it free while the URLs last (~7 days).797. **Deliver** the picked ones: file paths and what it cost, and one suggestion for the80 next iteration. No JSON or request IDs in chat.8182Terminal statuses: `completed`, `failed` (refunded), `nsfw` (moderation, refunded — rephrase,83don't resubmit the same prompt), `canceled` (refunded).8485Portions adapted from higgsfield-ai/skills (MIT, © 2026 Higgsfield AI); see NOTICE.