> ## Documentation Index
> Fetch the complete documentation index at: https://docs.higgsfield.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent overview

> Drive an autonomous creative agent through the API: multi-turn sessions, generations, and file handling billed to your account.

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.

<Note>
  The Agent API is in limited availability. Contact [support](mailto:support@higgsfield.ai) to enable it for your account.
</Note>

## 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

```
POST /v1/agent/sessions            -> session_id            (status: idle)
POST /v1/agent/sessions/{id}/messages  -> message accepted  (status: processing)
GET  /v1/agent/sessions/{id}/messages  -> poll until the assistant message is completed
POST /v1/agent/sessions/{id}/messages  -> next turn (memory persists)
```

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](/docs/agent/reference#interrupt-a-turn).

## Session statuses

| Status           | Meaning                                                                              |
| ---------------- | ------------------------------------------------------------------------------------ |
| `idle`           | No turn running. The session accepts a new message.                                  |
| `processing`     | A turn is running. Poll messages for progress.                                       |
| `awaiting_input` | The agent asked you a question and parked the turn. Answer by sending a new message. |

## 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](/docs/models), 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](/docs/agent/reference#billing).

## Next steps

* [Quickstart](/docs/agent/quickstart) — run your first session with the SDK or cURL.
* [API reference](/docs/agent/reference) — endpoints, schemas, errors, and billing.


## Related topics

- [Agent quickstart](/docs/agent/quickstart.md)
- [Agent API reference](/docs/agent/reference.md)
- [Client libraries](/docs/how-to/sdk.md)