Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.higgsfield.ai/docs/llms.txt

Use this file to discover all available pages before exploring further.

Higgsfield provides official client libraries to simplify integration with our API. These libraries handle authentication, request management, and provide a developer-friendly interface for all platform features.

​
Supported Languages

We currently support the following languages:

Python

Full-featured SDK with sync and async support

JavaScript/TypeScript

Coming soon
Have a specific language in mind? Let us know in our community channels, and we’ll consider adding support for it in future releases.

​
Python SDK

The official Python SDK for Higgsfield AI. Supports both synchronous and asynchronous usage.

​
Installation

Install the Higgsfield Python client using pip: 
pip install higgsfield-client

​
Authentication

Before using the client, set your API credentials as environment variables. You can use either a single key or separate API key and secret: Option 1: Single Key 
export HF_KEY="your-api-key:your-api-secret"
Option 2: API Key + Secret 
export HF_API_KEY="your-api-key"
export HF_API_SECRET="your-api-secret"
Get your credentials from the Higgsfield Cloud.

​
Quick Start

import higgsfield_client

# Submit and wait for result
result = higgsfield_client.subscribe(
    'higgsfield-ai/soul/standard',
    arguments={
        'prompt': 'A serene lake at sunset with mountains',
        'resolution': '2K',
        'aspect_ratio': '16:9',
        'camera_fixed': False
    }
)

print(result['images'][0]['url'])

​
Usage Patterns

​
Pattern 1: Simple Submit and Wait

Submit a request and wait for the result. 
import higgsfield_client

result = higgsfield_client.subscribe(
    'higgsfield-ai/soul/standard',
    arguments={
        'prompt': 'A serene lake at sunset with mountains',
        'resolution': '2K',
        'aspect_ratio': '16:9',
        'camera_fixed': False
    }
)

print(result['images'][0]['url'])

​
Pattern 2: Submit and Track Progress

Submit a request and monitor its status in real-time. 
import higgsfield_client

request_controller = higgsfield_client.submit(
    'higgsfield-ai/soul/standard',
    arguments={
        'prompt': 'Football ball',
        'resolution': '2K',
        'aspect_ratio': '16:9',
        'camera_fixed': False
    },
    webhook_url='https://example.com/webhook'  # Optional webhook
)

for status in request_controller.poll_request_status():
    if isinstance(status, higgsfield_client.Queued):
        print('Queued')
    elif isinstance(status, higgsfield_client.InProgress):
        print('In progress')
    elif isinstance(status, higgsfield_client.Completed):
        print('Completed')
    elif isinstance(status, (higgsfield_client.Failed, higgsfield_client.NSFW, higgsfield_client.Cancelled)):
        print('Oops!')

result = request_controller.get()
print(result['images'][0]['url'])

​
Pattern 3: Submit with Callbacks

Use callbacks to handle status updates. 
import higgsfield_client

def on_enqueue(request_id):
    print(f'Request {request_id} was enqueued')

def on_status_update(status):
    print(f'Status: {status}')

result = higgsfield_client.subscribe(
    'higgsfield-ai/soul/standard',
    arguments={
        'prompt': 'A serene lake at sunset with mountains',
        'resolution': '2K',
        'aspect_ratio': '16:9',
        'camera_fixed': False
    },
    on_enqueue=on_enqueue,
    on_queue_update=on_status_update
)

​
Pattern 4: Manage Existing Requests

Work with request controllers to manage requests. 
import higgsfield_client

request_controller = higgsfield_client.submit(
    'higgsfield-ai/soul/standard',
    arguments={
        'prompt': 'A serene lake at sunset with mountains',
        'resolution': '2K',
        'aspect_ratio': '16:9',
        'camera_fixed': False
    },
    webhook_url='https://example.com/webhook'
)

# Check status
status = request_controller.status()

# Wait for completion and get result
result = request_controller.get()

# Cancel a queued request
request_controller.cancel()

​
File Uploads

Upload files to use in your requests.

​
Upload Bytes

import higgsfield_client

image_path = 'path/to/example.jpeg'
content_type = 'image/jpeg'

with open(image_path, 'rb') as f:
    data = f.read()

url = higgsfield_client.upload(data, content_type)

# Upload path
image_path = 'path/to/example.jpeg'

url = higgsfield_client.upload_file(image_path)


# Upload PIL image

from PIL import Image
import higgsfield_client

image = Image.open('example.jpeg')
url = higgsfield_client.upload_image(image, format='jpeg')

​
Requirements

  • Python >= 3.8

​
Resources

​
JavaScript/TypeScript SDK

Coming Soon - Our JavaScript/TypeScript SDK is currently in development and will be available soon. The upcoming SDK will feature:
  • Full TypeScript support with type definitions
  • Promise-based async API
  • Support for Node.js and browser environments
  • Webhook utilities
  • Built-in retry logic
In the meantime, you can use the REST API directly.

​
Support

If you encounter any issues or have questions: