Unlimited the API can’t reach

On Higgsfield, an ultraplan with “Active unlimited models (Beta)” lets you generate certain models for free - in the web app. The API does not honor it: every generate_image / generate_videocall bills credits, plan or not. And the API’s own job status carries no cost field, so a tool can’t even tell you what a call cost after the fact - the real charge only shows up in the credit ledger.

That single fact drove the whole design. We don’t try to make the API cheaper - we can’t. We route generation through the one place the unlimited plan is real: the web app.

Even inthe web app, “unlimited” is easy to lose by accident. The UI has two traps that silently charge you, and we baked the fixes into the higgsfield-web-free-genskill so an agent doesn’t fall into them:

• The “Unlimited” toggle is the only thing that controls billing - and it resets OFF on every page reload. Off bills credits even on an unlimited-eligible model; on is free. The Generate button label is the truth, not the price: ✦ N means it will charge N; Unlimited means free. The ✦ N number shown next to a model is nominal and appears even for free-eligible models - trust the toggle, not the number.
• The dropdown labels don’t match the entitled backend models.“Nano Banana Pro” is the backend nano_banana_2, which isentitled (free). The friendlier-sounding “Nano Banana 2” is nano_banana_flash, which is not entitled and charges even with the toggle on. For stills, you want “Nano Banana Pro.”

You can verify you’re on the free lane at zero cost: the subscription page’s “Free generations used”counter should move while credits don’t; the read-only show_generations MCP call reports a generation’s true backend model id; and list_workspaces gives a live credit balance you can diff before and after (free = zero delta).

Because the API can’t reach the free tier, the work has to split across two kinds of agent: one that can drive a browser (to use the web app) and one that runs the pipeline. Studio coordinates them with a small job-board:

• Queue - the pipeline side (Studio, or an API/CLI agent like the render driver) drops jobs on the board: generate this still / this shot, with this prompt and model.
• Generate - a CoWork agent (Claude in a real Chrome session), connected to Studio over MCP, claims a job and makes it free in the Higgsfield web app.
• Harvest- the agent reports the result’s generation id back; Studio downloads it (listing and download are free API ops) and files it into the episode target - a character still or a video shot - with the same provenance and caching as any cloud artifact.

It’s deliberately semi-automated. Generation has to happen in a genuine browser session for the unlimited plan to apply - that’s the entire point - so an agent does the clicking instead of an API call. Everything around it is automated: the queue, the hand-off, the download, and the filing. You queue work and watch the board; you don’t move files by hand.

The board lives in Studio (persisted at ~/.config/macu-studio/cowork_jobs.json, per install) and is exposed three ways:

• MCP tools the CoWork agent drives: cowork_jobs_list, cowork_job_claim, cowork_job_complete (one call to finish a job and attach its result), and cowork_recent_generations (find the id of the gen you just made in the web app). cowork_jobs_create queues work.
• The CoWork tab in Studio - a live view of the queue (pending / running / done / failed), with re-queue, delete, and clear. Watch jobs flow through and land in the episode.
• A REST surface under /api/cowork/jobs for the UI and for queuing from a script.

When a job is marked done with its result generation id, a placement hook fires automatically and harvests it - a still job lands as stills/<key>.png, a video job as clips/hf_<shot>.mp4. The same hook fires whether the job was completed through the MCP tool or the REST API, so there’s one path and no drift. The browser-side know-how is two skills shipped in the box: cowork-harvest (the loop) and higgsfield-web-free-gen (how to stay free in the web UI).

1. Connect a CoWork agent to Studio’s MCP.Point a browser-capable Claude agent at your Studio’s MCP endpoint:

   http://<studio-host>:8774/mcp

   The cowork_*tools appear alongside the rest of Studio’s MCP. No token to set - see Security below.
2. Sign in to the Higgsfield web appin that agent’s browser, on the account whose unlimited tier covers the models you’ll use.
3. Queue work - from Studio, an API/CLI agent, or cowork_jobs_create - then let the CoWork agent work the board. Results land in the episode as they finish.

The skill follows the shipped ↗ higgsfield-web-free-genrules every session - the Unlimited toggle, the model-label trap, and the zero-cost checks - because a single missed reset-to-OFF on a video batch can burn a plan’s worth of credits.

The cowork_* tools have no per-tool auth- the same trust model as the rest of Studio’s MCP, whose render and billing tools are unauthenticated too. The boundary is the LAN-only bind: Studio listens on your machine / LAN, so do not tunnel :8774 (or /mcp) to an untrusted network. Keep the agent and Studio on the same trusted LAN and the surface stays private.