Higgsfield API in Production: Webhooks, Limits, Spend Caps

Calling the Higgsfield API once is easy: a key, a POST, a request ID. Running it behind a paid product is where the details matter, and some of them are not where you would look. The API has no spending cap, so you build your own. Webhooks are unsigned until you reveal a secret in the Console. A retry without an Idempotency-Key can pay twice. And at the concurrency limit the live API answers with a different error than the docs describe.

Below is what we found in Higgsfield’s documentation and in calls to the real API in October 2026, marked live where the two differ. The full notes, with a source link for each fact, are in docs/higgsfield-api.md of Higgsfield Gateway. For what the API is and how it differs from Higgsfield’s MCP and CLI, start with Higgsfield API vs MCP vs CLI.

Keys and requests

• Auth: the header Authorization: Key KEY_ID:KEY_SECRET. Keys have no scopes, so a key bills the whole account; to rotate, create a new key, deploy it, then delete the old one.
• Never ship the key in a browser or mobile app. Higgsfield’s Terms of Use forbid it, and a leaked key spends your balance.
• Submit returns request_id, status_url, cancel_url and expires_after: 604800. Every response carries an X-Correlation-ID; keep it with the job for support.
• The API rejects null (live). Leave optional fields out instead. Seedance 2.5 schemas also forbid unknown keys and empty arrays.
• Seedance 2.5 has no auto aspect ratio. It defaults to 16:9, so a vertical source rebuilt without aspect_ratio: "9:16" comes back horizontal.

Statuses, polling and what is charged

A request moves through queued and in_progress to one of four terminal states: completed, failed, nsfw or canceled. Accept cancelled too, and treat an unknown status as still running (live).

• Polling: GET /requests/{id}/status. Start at 2 seconds, back off ×1.5 up to 10 seconds with jitter, keep going on 5xx and network errors, stop on 401 and 404.
• Cancel works only while the request is queued: 202 with an empty body, then 400 once processing has started (live).
• Charges: failed, nsfw, canceled and timed-out requests cost nothing, and any reserved amount comes back.
• A completed answer without video.url is a paid request with a missing result. Don’t treat it as free.
• Outputs are kept for 7 days. Copy them to your own storage; Hf-Expires-After shortens the window per request, down to one hour.

Idempotency: retry without paying twice

Send an Idempotency-Key header, 1 to 255 visible ASCII characters, on every generation request. A replay with the same key returns the original request_id with no new charge.

• The key’s fingerprint covers the endpoint, the body, the webhook URL and Hf-Expires-After. The same key with different parameters returns 422 "Idempotency-Key was already used with different request parameters". Don’t recover from that by making a new key, or you pay twice.
• Field order does not matter; array order, omitted fields and different URLs do.
• A replay may say queued for a request that has already finished (live), so read status_url for the current state.
• Requests rejected before acceptance, such as 401 or a validation error, don’t use up the key (live).

The simplest rule: use your own job ID as the key, and build the request body the same way every time.

Webhooks and signature verification

Set the webhook per request with ?hf_webhook=<url-encoded HTTPS URL>. It fires on completed, failed and nsfw, with request_id, status, error, expires_at and the video URL in the body.

Higgsfield signs deliveries with Standard Webhooks:

1. Read the webhook-id, webhook-timestamp and webhook-signature headers. The signature header holds one or more v1,<base64> values separated by spaces.
2. Compute HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw body}. The key is your whsec_ secret without the prefix, base64-decoded.
3. Accept if any v1 value matches, compared in constant time, and the timestamp is within 5 minutes.
4. Deduplicate by webhook-id.

Two things catch people out:

• Deliveries are unsigned until the secret is first revealed in Console › Settings. Reveal it before you go live, or there is nothing to verify.
• Retries: your endpoint must answer 2xx within 10 seconds. Network errors and 5xx are retried for up to two hours; 4xx is never retried. Answer fast and do the work afterwards.

Keep polling as a fallback anyway: a webhook can be lost, and the request still finishes. The signature and retry details above come from the docs; we have not yet checked them against live deliveries.

Rate limits and the 429 you may not get

The limit is on concurrency per account, sometimes per model. Requests over it wait as queued, and the queue is capped at a multiple of the limit.

Funds added in the last 28 days	Concurrent requests
New account	2
$25 or more	10
$100 or more	20
$1,000 or more	40

The docs say a full queue answers 429 account_queue_full with Retry-After, and nothing is charged. In live calls at the limit, the API answered 400 {"detail": "Maximum number of concurrent requests (N) has been reached"} instead, with no Retry-After and no rate-limit headers. Match that text before you treat other 400s as validation errors, and count your own running jobs so you rarely hit either.

Spending caps: build your own

This is the part to plan before launch. As of October 2026 the Higgsfield API has:

• no spending limit and no low-balance alert;
• no balance endpoint (GET /models/usage returns analytics that “is not a billing record”);
• no cost on a finished request and no history endpoint;
• a 403 once the balance is empty.

What works instead:

Layer	What it stops
Prepaid balance, auto top-up off	Everything else failing: it is the only hard cap
Daily caps per client and overall, checked before submit	A runaway client or a loop that keeps creating jobs
A price ceiling per job, checked with /estimate	Wrong parameters, such as 1080p instead of 480p, and price changes
An allow-list of models and resolutions per client	Clients reaching for premium models
Idempotency-Key on every submit	Duplicate charges on retry

POST /estimate/<model path> with the same body as the submit returns the price in dollars and charges nothing. The body includes the input URLs, so the exact price exists only once the inputs are uploaded.

What it costs

The API bills from a prepaid dollar balance, and added funds expire after a year. Two models, as of October 26, 2026:

• Genjutsu Light motion transfer bills output seconds plus input video seconds: $0.05, $0.10 and $0.20 a second at 480p, 720p and 1080p, half that at the maximum discount. A 10-second clip from a 10-second video is 20 billable seconds, $2.00 at 720p.
• Seedance 2.5 is priced in tokens; text-to-video at 16:9 works out to about $0.21, $0.46 and $1.14 a second at 480p, 720p and 1080p.

Every model’s price is in the Higgsfield price table, and how API dollars compare with plan credits is in Higgsfield credits explained.

An open-source gateway that does all of this

Higgsfield Gateway is our MIT-licensed gateway for the Higgsfield API on Cloudflare Workers. It owns the key, reserves budget in D1 before every submit, runs each job as a Cloudflare Workflow that waits for the signed webhook and falls back to polling, stores results on R2, and delivers them to your bots and apps through Queues. It sends an Idempotency-Key with every submit and tracks your concurrency tier itself.

It is alpha: tested against a mocked API, with the live observations above collected separately, and not yet run end to end against the real API. Read it as a working reference for the patterns here, and test it with a small prepaid balance first.

If you would rather make videos than build on the API, Jutsu Studio runs Higgsfield’s models from a Mac with your own account and keeps every result on your disk.