Skip to main content
SDKs

Client libraries

Use the official Python and TypeScript SDKs.

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

#Python

#Install

bash
pip install higgsfield-client

#Configure credentials

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

#Submit and wait

Synchronous
import higgsfield_client

result = higgsfield_client.subscribe(
    "xai/grok-imagine-image-2.0",
    arguments={
        "prompt": "Editorial portrait in soft daylight",
    },
)

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

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

bash
npm install @higgsfield/client

#Configure credentials

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

#Submit and wait

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

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

const result = await higgsfield.subscribe(
  "xai/grok-imagine-image-2.0",
  {
    input: {
      prompt: "Editorial portrait in soft daylight",
    },
    withPolling: true,
  },
);

if (result.status === "completed") {
  console.log(result.images?.[0]?.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.

Was this page helpful?
Navigation