Client libraries

Official SDKs handle authentication, submission, polling, cancellation, and file uploads. Use them only in trusted server-side environments.

Python

Synchronous and asynchronous APIs for Python 3.8+.

Node.js and TypeScript

Typed server-side client with automatic polling and retries.

Python

Install

pip install higgsfield-client

Configure credentials

export HF_KEY="your-api-key-id:your-api-key-secret"

Submit and wait

import higgsfield_client

result = higgsfield_client.subscribe(
    "higgsfield-ai/soul/v2/standard",
    arguments={
        "prompt": "Editorial portrait in soft daylight",
    },
)

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

import asyncio

import higgsfield_client


async def main():
    result = await higgsfield_client.subscribe_async(
        "higgsfield-ai/soul/v2/standard",
        arguments={
            "prompt": "Editorial portrait in soft daylight",
        },
    )
    print(result["images"][0]["url"])


asyncio.run(main())

Use submit or submit_async when you need a request controller for explicit polling, status checks, or cancellation. The Python SDK also provides upload, upload_file, and upload_image helpers.

Node.js and TypeScript

Install

npm install @higgsfield/client

Configure credentials

export HF_CREDENTIALS="your-api-key-id:your-api-key-secret"

Submit and wait

import { config, higgsfield } from "@higgsfield/client/v2";

config({
  credentials: process.env.HF_CREDENTIALS,
});

const result = await higgsfield.subscribe(
  "higgsfield-ai/soul/v2/standard",
  {
    input: {
      prompt: "Editorial portrait in soft daylight",
    },
    withPolling: true,
  },
);

if (result.isCompleted) {
  console.log(result.jobs[0].results?.raw.url);
}

The v2 TypeScript client is server-side only and blocks browser use to prevent credential exposure.

Choose an integration style

Requirement	Recommended API
Script or prototype	`subscribe` / `subscribe_async`
Worker with explicit lifecycle control	`submit` / `submit_async`
Existing request ID	`status`, `result`, or `cancel`
Production event-driven integration	Submit with a webhook and keep status polling as recovery

See the Python SDK repository and TypeScript SDK repository for the complete client APIs.

Agent API

The Agent API is available through client.agents.sessions (create, run() with automatic polling and question handling, send, messages, interrupt) and client.agents.media (one-call input upload):

Python 0.2.0+: SyncClient and AsyncClient.
TypeScript 0.2.4+: createHiggsfieldClient(...).agents and the configured higgsfield.agents singleton from the recommended @higgsfield/client/v2 entry point.

See the agent quickstart for installation and complete examples, or use the REST API.

Get started

Model API reference

Core concepts

Agent

SDKs

Organizations

API reference

Resources

Python

Node.js and TypeScript

Python

Install

Configure credentials

Submit and wait

Node.js and TypeScript

Install

Configure credentials

Submit and wait

Choose an integration style

Agent API

Python

Node.js and TypeScript

​Python

​Install

​Configure credentials

​Submit and wait

​Node.js and TypeScript

​Install

​Configure credentials

​Submit and wait

​Choose an integration style

​Agent API

Python

Install

Configure credentials

Submit and wait

Node.js and TypeScript

Install

Configure credentials

Submit and wait

Choose an integration style

Agent API