🎨 Higgsfield Pipeline

System Flow

Docker Stack Layout

/srv/stacks/higgsfield/
├── docker-compose.yml      # Service definition
├── Dockerfile              # Playwright 1.52 + stealth + Xvfb
├── scripts/                # Mounted read-only at /app/scripts
│   ├── generate.js         # Main generation script
│   └── login.sh            # Authentication script
├── auth/                   # Mounted at /app/auth
│   └── authenticated.json  # Browser session state
└── output/                 # Mounted at /app/output
    ├── *.png / *.webp      # Generated images
    └── login-result.png    # Auth verification screenshot

Container Specs

Fully automated self-service login via scripts/login.sh — no human interaction required.

Step-by-Step Process

Critical Gotchas

Session Expiry

If generate.js detects a redirect to /auth/, it exits with code 2 to signal session expiry. Re-run login.sh to refresh authentication.

Manual Fallback

Complete Automation Flow

The generate.js script automates the entire Higgsfield web UI workflow:

// Find model button, click, filter, select
await p.evaluate(() => {
  [...document.querySelectorAll("button")]
    .find(e => e.innerText.match(/Nano|Seedream|.../) && e.getBoundingClientRect().top > 550)?.click();
});

p.on("response", async (resp) => {
  const body = await resp.json();
  if (body.job_sets) {
    console.log(`Submitted: ${body.job_sets.map(js => js.type).join(", ")}`);
  }
});

if (url.includes("/status")) {
  const body = await resp.json();
  if (body.status === "completed" && body.job_set_type === primaryType) {
    primaryDone = true;
  }
}

const pngUrl = thumbUrl.replace("_min.webp", ".png");
execSync(`curl -sS -f -o "${filepath}" "${pngUrl}"`);

Response Interception Strategy

Instead of polling external API endpoints (would need auth headers), the script intercepts browser network responses to capture job IDs and completion status in real-time.

How It Works

Reference images are passed via --ref /app/output/filename.png. The file must exist inside the container's shared volume.

Two-Phase Upload Mechanism

Known Issue: Duplicate References

The upload mechanism sometimes creates 2 reference slots instead of 1. The script attempts to detect and clear extras by:

1. Clearing all existing references before upload
2. Counting uploaded refs via img[alt="object image"]
3. Removing extras if count > 1

Impact: Generation still works — it just uses 2 copies of the same reference. Not ideal, but functional.

Usage Example

# 1. Copy reference image into shared volume
cp ~/cat.png /srv/stacks/higgsfield/output/ref-cat.png

# 2. Pass container path to generate.js
docker exec -e DISPLAY=:99 higgsfield-browser node /app/scripts/generate.js \
  --prompt "reimagine as watercolor painting" \
  --ref /app/output/ref-cat.png \
  --model nano-banana-pro

Available Models

Use hyphenated slugs with --model parameter:

Resolution Support

Unlimited Mode Availability

The script automatically detects whether the selected model supports Unlimited mode by checking for the toggle switch in the UI. If unavailable, it warns that credits will be used.

Endpoints (fnf.higgsfield.ai)

POST /jobs/{model}

Submit a generation job. The browser makes this call when you click Generate.

// Response body:
{
  "job_sets": [
    { "id": "...", "type": "nano_banana_2", ... },
    { "id": "...", "type": "seedream_v5_lite", ... }  // bonus job
  ]
}

GET /jobs/{id}/status

Poll job status. The browser calls this automatically (~1-2s intervals).

// Response body:
{
  "id": "abc123",
  "job_set_type": "nano_banana_2",
  "status": "completed",
  ...
}

GET /jobs/{id}

Full job result (not used by script — we extract URLs from page thumbnails instead).

Two-Level Job IDs

Bonus Jobs

Higgsfield may spawn additional free generations alongside your requested model. For example, requesting Nano Banana Pro might also generate Seedream 4.5 and Seedream 5.0 lite at no cost.

CloudFront CDN URLs

Images are served from d8j0ntlcm91z4.cloudfront.net and don't require authentication.

URL Pattern

https://d8j0ntlcm91z4.cloudfront.net/user_{userId}/hf_{timestamp}_{jobId}_min.webp

Resolution Variants

Download Strategy: Script tries PNG first (replace _min.webp with .png), falls back to webp if PNG returns 403.

Host ↔ Container Mapping

Key Files

Passing Files Between Host & Container

# Host → Container (reference image)
cp ~/my-ref.png /srv/stacks/higgsfield/output/ref.png
docker exec ... --ref /app/output/ref.png

# Container → Host (generated image)
# Automatic — generated files appear in /srv/stacks/higgsfield/output/

Common Commands

Authentication

# Self-service login (automated)
bash ~/.openclaw/skills/higgsfield/scripts/login.sh

# Check auth status
docker exec -e DISPLAY=:99 higgsfield-browser node -e '
const { chromium } = require("playwright-extra");
const s = require("puppeteer-extra-plugin-stealth");
chromium.use(s());
(async () => {
  const b = await chromium.launch({headless:false,args:["--no-sandbox"]});
  const c = await b.newContext({storageState:"/app/auth/authenticated.json"});
  const p = await c.newPage();
  await p.goto("https://higgsfield.ai",{timeout:30000,waitUntil:"domcontentloaded"});
  await p.waitForTimeout(3000);
  console.log(p.url().includes("auth") ? "EXPIRED" : "VALID");
  await b.close();
})()'

Image Generation

# Basic generation (Unlimited mode when available)
docker exec -e DISPLAY=:99 higgsfield-browser node /app/scripts/generate.js \
  --prompt "a cat floating in space, oil painting" \
  --model nano-banana-pro --ratio 1:1 --res 1k

# With reference image
cp ~/ref.png /srv/stacks/higgsfield/output/ref.png
docker exec -e DISPLAY=:99 higgsfield-browser node /app/scripts/generate.js \
  --prompt "reimagine as watercolor" \
  --ref /app/output/ref.png \
  --model nano-banana-pro --ratio 3:4 --res 2k

# Different model + aspect ratio
docker exec -e DISPLAY=:99 higgsfield-browser node /app/scripts/generate.js \
  --prompt "cinematic movie poster" \
  --model flux-2-pro --ratio 2:3 --res 4k

Container Management

# Start/rebuild container
cd /srv/stacks/higgsfield && docker compose up -d --build

# Check status
docker ps | grep higgsfield

# View logs
docker logs higgsfield-browser

# Stop container
docker compose down

Exit Codes

Troubleshooting

Session Expired

Model Not Found

Resolution Not Available

Unlimited Mode Unavailable

Reference Image Duplicates

No Images Downloaded