Skip to main content
The Agent API gives your application a full creative agent instead of a single model call. You open a session, send it a task in plain language, and poll for the result. Inside one turn the agent can plan, generate images, video, and audio with Higgsfield models, analyze media, run code in an isolated sandbox (for example ffmpeg assembly), and return finished assets as URLs.
The Agent API is in limited availability. Contact support to enable it for your account.

​
When to use it

Use the direct model endpoints when you know exactly which model and parameters you want — they are cheaper and faster for single generations. Use the Agent API when the task spans multiple steps or requires judgment:
  • “Make a 30-second faceless video about X” — the agent writes the script, generates scenes, voiceover, and assembles the final cut.
  • “Take this product photo and produce a set of ad creatives in different aspect ratios.”
  • Iterative work: the session keeps memory, so follow-up messages refine previous results.

​
How a session works

One session processes one turn at a time. Sending a message while a turn is running returns 409 session_busy — wait for the current turn to finish or interrupt it.

​
Session statuses

​
What the agent can do

The agent runs with a fixed tool set scoped to creative work:
  • Generation — image, video, audio, and 3D models from the sellable catalog, plus upscaling, outpainting, background removal, and enhancement. Every generation is billed to your account at the model’s normal price.
  • Media analysis — vision over images, video, and audio it produced or you uploaded.
  • Sandbox — an isolated terminal and filesystem for scripting and assembly (ffmpeg, file manipulation). No network access to your infrastructure.
  • Files — uploads inputs and final artifacts to CDN URLs it returns in its answer.
It deliberately has no web browsing, no web search, and no access to resources outside your API account.

​
Billing

Each message you send places a fixed credit reserve. When the turn completes, the reserve is reconciled down to the actual LLM cost of the turn and the difference is refunded automatically; a failed turn is refunded in full. Generations the agent runs are billed separately at each model’s listed price, exactly as if you had called the model endpoints yourself. See billing details.

​
Next steps

  • Quickstart — run your first session with the SDK or cURL.
  • API reference — endpoints, schemas, errors, and billing.