Higgsfield SDK (Python)

Source: Higgsfield Docs Sdk 2026 04 17 (Higgsfield docs — https://docs.higgsfield.ai/how-to/sdk)

Higgsfield ships an official Python client (higgsfield-client) that wraps the async submit/status/cancel API. Offers four interaction patterns from fire-and-forget to fine-grained controller access, plus file-upload helpers for bytes, paths, and PIL images. JavaScript/TypeScript support is “Coming soon”; non-Python clients use the REST API directly.

Key Takeaways

• One language right now: Python. JS/TS on the roadmap. Non-Python apps hit the REST endpoints directly (see Higgsfield Overview).
• Python 3.8+ required.
• Install: pip install higgsfield-client
• Auth via env vars. Either combined HF_KEY="key:secret" or separate HF_API_KEY + HF_API_SECRET. No hardcoded credentials path documented.
• Four usage patterns cover from “just give me the result” to “let me manage my own poll loop”:
  1. Simple submit-and-wait (blocking)
  2. Submit + polling (progress visibility)
  3. Callback-based (event-driven)
  4. Request Management (direct controller manipulation for status/cancel)
• Sync and async modes on every pattern. Use async in production for high-throughput pipelines.
• File uploads: raw bytes (with content-type), file paths, or PIL Image objects (with format control). All async-compatible.
• Published on PyPI. Source on GitHub at higgsfield-ai/higgsfield-client.
• Support: support@higgsfield.ai.

Usage patterns at a glance

Pattern	When to use
Simple Submit-and-Wait	Scripts, notebooks, quick experiments — you just want the result
Submit + Polling	UI showing progress, ETL jobs that log status
Callback-Based	Event-driven systems — SDK invokes your callback on state change
Request Management	Advanced: manage many parallel requests, cancel conditionally, custom poll logic

For production web services the recommended combination is: async submit → webhook for result (see Higgsfield Webhooks), not SDK polling. The SDK patterns above are best for direct-script or CLI-style integrations.

File upload helpers

Three entry points, all with async variants:

• Raw bytes — for programmatic pipelines where the image is already in memory
• File path — straightforward local file ingestion
• PIL Image object — common path for Python ML pipelines that already have images as PIL objects

Implementation

• Tool/Service: higgsfield-client Python package
• Setup:
  1. Obtain API key + secret from https://cloud.higgsfield.ai
  2. pip install higgsfield-client
  3. Set env vars: export HF_KEY="your_key:your_secret" (or the separated pair)
  4. Import and use one of the four patterns above
• Cost: SDK is free; per-request credits consumed against your Higgsfield account (see Overview)
• Integration notes:
  • For server-side production use, prefer async + webhook over sync + poll. The SDK supports the polling path but webhook is lower-cost and more reliable.
  • PIL upload is the cleanest path from any existing Python image pipeline into Higgsfield generation.
  • request_id returned from submit should be persisted for webhook idempotency — see Webhooks.

Related

• Higgsfield Overview — platform primer, request lifecycle
• Higgsfield Webhooks — the async completion path most production apps should use instead of SDK polling
• Higgsfield Image-to-Video — the models SDK submits jobs to
• HeyGen Studio Automation — comparable Claude Code orchestration pattern (could be adapted to Higgsfield)
• Essential MCP Servers — no Higgsfield MCP listed yet; candidate for future MCP wrapper
• Cross-Topic Connections — Routines could trigger Higgsfield submits on a schedule

Open Questions

• Rate-limit handling. Does the SDK retry on 429, or surface the error to the caller?
• Webhook-SDK composition. Can you use the SDK to submit with hf_webhook query param, then use SDK for downstream status verification — or is it one-or-the-other?
• Cancellation semantics. SDK “Request Management” pattern mentions cancellation — is it only while queued, matching the REST behavior?
• TypeScript ETA. “Coming soon” with no date.
• Multipart upload limits. File size maximums not specified for bytes/PIL uploads.

Try It

1. Install and authenticate. pip install higgsfield-client and set HF_KEY. Verify with a submit-and-wait on a trivial prompt.
2. Measure patterns. Run the same prompt through each of the 4 usage patterns. Time them. Confirm the callback model is the cleanest for event-driven integration.
3. Pipe a PIL image. Take any existing PIL-based image workflow (screenshot tool, matplotlib figure, cv2 capture) and feed the Image object straight to Higgsfield. Demonstrates the one-step path from existing Python code.
4. Compose with Claude Code. Write a Claude Code skill or routine that uses the SDK. The skill becomes reusable across projects.
5. For production, combine SDK + webhook. Submit via SDK, receive completion via webhook. Don’t block a production server thread on the SDK’s wait call.