Skip to main content
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(
    'bytedance/seedream/v4/text-to-image',
    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(
    'bytedance/seedream/v4/text-to-image',
    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(
    'bytedance/seedream/v4/text-to-image',
    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(
    'bytedance/seedream/v4/text-to-image',
    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(
    'bytedance/seedream/v4/text-to-image',
    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: