How does the Higgsfield API work? Requests, limits, billing

The Higgsfield API works asynchronously: your server sends JSON parameters to a model endpoint on https://api.higgsfield.ai, stores the request_id it gets back, then polls the status_url or waits for a webhook, and downloads the output once the status is completed. You pay per successful generation from a balance you top up, and the main limit is how many requests you have open at once.

These facts come from Higgsfield's own docs pages (How the API works, Requests and lifecycle, Webhooks, Billing and retention, Rate limits and the FAQ), read on 2026-09-29. Getting and sending the key is covered in Higgsfield API key.

What happens when I send a Higgsfield API request?

Every call is server-side and authenticated with Authorization: Key YOUR_KEY_ID:YOUR_KEY_SECRET, not a Bearer token. Then:

• Submit JSON parameters to a model endpoint. Which endpoints you can use depends on your account.
• The request returns at once with status, request_id, status_url and cancel_url. Store the request_id: polling, cancellation, webhook deduplication and support all use it.
• Poll status_url, using the URLs from the response rather than building them yourself, or wait for a webhook.
• When the status is completed, read the output URL (images, video or audio, depending on the model) and download the file.

{
  "status": "queued",
  "request_id": "d7e6c0f3-...",
  "status_url": "https://api.higgsfield.ai/requests/d7e6c0f3-.../status",
  "cancel_url": "https://api.higgsfield.ai/requests/d7e6c0f3-.../cancel"
}

What statuses can a Higgsfield request have?

Four of the six statuses are terminal. Stop polling when you reach one:

How do Higgsfield webhooks work?

Pass an HTTPS endpoint in the hf_webhook query parameter when you submit. Higgsfield posts to it after the request reaches completed, failed or nsfw, with the output nested in payload. Your endpoint must be publicly reachable over HTTPS, accept JSON and respond within ten seconds. Return a 2xx after recording the event: network failures and 5xx responses are retried for up to two hours, and 4xx responses are treated as permanent. Duplicate deliveries are possible, so deduplicate by request_id and terminal status.

How is the Higgsfield API billed?

Pay-as-you-go by default: you top up a balance and pay per generation, and invoice billing is for customers on a committed-use contract. The estimate endpoint and credit expiry are covered in Higgsfield API key. The rules that affect a production budget:

• Only successful generations are charged: requests ending failed or nsfw, and requests that pass their model's timeout, aren't charged; reserved credits are refunded automatically.
• A request can be canceled only before processing starts; a canceled queued request is refunded.
• Outputs stay available for at least seven days and may be removed after that, so copy them to your own storage.

What are the Higgsfield API rate limits?

Limits depend on your account and the model, and you see yours in the Higgsfield Console. The main one is concurrency: how many requests may be queued or processing at once. At the limit, the API currently returns 400 Bad Request with a message like "Maximum number of concurrent requests (4) has been reached" (the number in the example isn't a published limit). It sends no rate-limit headers or Retry-After, so wait for an open request to finish, cap submissions with a worker pool, and back off with jitter.

APIs differ here. On Sume, for comparison, a workspace at its concurrency limit still has valid jobs accepted as `queued`, and only a full queue is refused. See Sume vs Higgsfield for the rest of that comparison.