Client Libraries

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'])

import asyncio
import higgsfield_client

async def main():
    # Submit and wait for result
    result = await higgsfield_client.subscribe_async(
        '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'])

asyncio.run(main())

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'])

import asyncio
import higgsfield_client

async def main():
    result = await higgsfield_client.subscribe_async(
        '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'])

asyncio.run(main())

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'])

import asyncio
import higgsfield_client

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

    async 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 = await request_controller.get()
    print(result['images'][0]['url'])

asyncio.run(main())

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
)

import asyncio
import higgsfield_client

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

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

async def main():
    await higgsfield_client.subscribe_async(
        '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
    )

asyncio.run(main())

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()

import asyncio
import higgsfield_client

async def main():
    request_controller = await higgsfield_client.submit_async(
        '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 = await request_controller.status()

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

    # Cancel a queued request
    await request_controller.cancel()

asyncio.run(main())

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')

import higgsfield_client

# Async raw data upload
url = await higgsfield_client.upload_async(data, content_type='image/jpeg')

# Async file upload
url = await higgsfield_client.upload_file_async('path/to/example.jpeg')

# Async image upload
url = await higgsfield_client.upload_image_async(image, format='jpeg')

Requirements

Python >= 3.8

Resources

GitHub Repository: higgsfield-ai/higgsfield-client
Homepage: cloud.higgsfield.ai
Package: PyPI

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:

Check our API Documentation
Review the GitHub Repository
Contact support at support@higgsfield.ai

Welcome

API

Guides

Help

Supported Languages

Python

JavaScript/TypeScript

Python SDK

Installation

Authentication

Quick Start

Usage Patterns

Pattern 1: Simple Submit and Wait

Pattern 2: Submit and Track Progress

Pattern 3: Submit with Callbacks

Pattern 4: Manage Existing Requests

File Uploads

Upload Bytes

Requirements

Resources

JavaScript/TypeScript SDK

Support

​Supported Languages

Python

JavaScript/TypeScript

​Python SDK

​Installation

​Authentication

​Quick Start

​Usage Patterns

​Pattern 1: Simple Submit and Wait

​Pattern 2: Submit and Track Progress

​Pattern 3: Submit with Callbacks

​Pattern 4: Manage Existing Requests

​File Uploads

​Upload Bytes

​Requirements

​Resources

​JavaScript/TypeScript SDK

​Support

Supported Languages

Python SDK

Installation

Authentication

Quick Start

Usage Patterns

Pattern 1: Simple Submit and Wait

Pattern 2: Submit and Track Progress

Pattern 3: Submit with Callbacks

Pattern 4: Manage Existing Requests

File Uploads

Upload Bytes

Requirements

Resources

JavaScript/TypeScript SDK

Support