Agent API reference

All endpoints live under https://api.higgsfield.ai/v1/agent and use the standard Authorization: Key {key_id}:{key_secret} header. Requests and responses are JSON. The Python and TypeScript v2 SDKs wrap this surface as client.agents.sessions / client.agents.media. See the quickstart for installation and usage; the reference below is the raw HTTP contract.

Create a session

POST /v1/agent/sessions → 201

// Request (all fields optional)
{ "config": {} }

// Response
{ "session_id": "50eeb94c-c396-439d-b504-aee2147b7ec0", "status": "idle" }

Sessions are durable and keep conversation memory across turns. Create one session per logical conversation or workflow and reuse it.

Send a message

POST /v1/agent/sessions/{session_id}/messages → 202

// Request
{ "content": "Generate a 10-second teaser video for..." }

// Response
{ "message_id": "4bf91fcb-abb3-44f4-815c-a74dda7817d3", "status": "processing" }

content is plain text, 1–20,000 characters. The turn runs asynchronously — poll for the result. One turn runs per session at a time. A message sent while a turn is in flight returns 409 session_busy; the losing request is not charged. Retry after the current turn finishes, or interrupt it.

Read messages

GET /v1/agent/sessions/{session_id}/messages → 200 Optional query parameter after={message_id} returns only messages created after that message — use it to poll incrementally.

{
  "status": "idle",
  "messages": [
    {
      "message_id": "…",
      "role": "user",
      "status": "completed",
      "message": { "type": "text", "text": "…" },
      "created_at": "2026-09-01T14:37:53.000Z"
    },
    {
      "message_id": "…",
      "role": "assistant",
      "status": "completed",
      "message": { "id": "…", "role": "assistant", "parts": [ { "type": "text", "text": "…" } ] },
      "created_at": "2026-09-01T14:38:41.000Z"
    }
  ]
}

Top-level status is the session status: idle, processing, or awaiting_input.
Message status is processing, completed, or failed.
A user message settles to completed or failed together with the assistant message that answers it.
The assistant message is structured; concatenate its parts entries with "type": "text" for the answer text. Other part types (reasoning, tool activity) may appear and can be ignored.

Poll with backoff: start at two seconds, increase gradually to ten, and stop when the assistant message for your turn is terminal. See Polling for the general strategy.

Interrupt a turn

POST /v1/agent/sessions/{session_id}/interrupt → 202

{ "session_id": "…", "status": "processing" }

Asks the running turn to stop at the next safe point. The turn still settles normally (its assistant message reaches a terminal status), after which the session accepts new messages. Interrupting does not undo generations that already ran.

Questions from the agent

When the agent needs a decision it parks the turn and the session status becomes awaiting_input. The parked assistant message contains the question. Answer with a regular POST …/messages — the reply resumes the same turn. Nothing times out on our side, but the session stays parked until you answer or interrupt.

Upload input files

Give the agent input files by uploading them first and referencing the returned URL in your message content. POST /v1/agent/media → 201

// Request
{ "extension": "png", "type": "image" }

// Response
{
  "id": "ab12cd….png",
  "type": "image",
  "content_type": "image/png",
  "upload_url": "https://…presigned…",
  "url": "https://cdn.higgsfield.ai/agent-media/…/ab12cd….png"
}

Then PUT the file bytes to upload_url with the returned Content-Type header, and confirm: POST /v1/agent/media/{id}/confirm with { "type": "image" }. The confirmation response contains status: "uploaded" when the file is ready, or status: "not_ready" when it is not yet available. The SDKs return the URL only after uploaded; otherwise they raise AgentError in Python or HiggsfieldError in TypeScript. Use the url in your message: "content": "Animate this image: https://cdn.higgsfield.ai/agent-media/…". Supported types: image, video, audio, file.

Errors

Code	Meaning
`401`	Missing or invalid credentials.
`402`	Insufficient credit balance for the message reserve.
`403`	Agent API is not enabled for this account.
`404`	Session not found, or owned by a different account.
`409`	`session_busy` — a turn is already running on this session.
`502`	The agent backend is temporarily unavailable; the message was refunded — retry with backoff.

A failed assistant message means the turn itself errored; the message reserve is refunded automatically and the session returns to idle.

Billing

Two independent meters apply:

Turn cost. Sending a message places a fixed credit reserve (the per-message ceiling). When the turn completes, the reserve is reconciled to the turn’s actual LLM usage and the difference is refunded automatically. Failed turns are refunded in full. The turn’s actual LLM cost appears on the user message as llm_cost_usd (US dollars; converted to credits at your account’s rate for the refund).
Generations. Every model the agent runs is billed separately at that model’s listed price, identical to calling the model endpoint yourself. Failed generations are auto-refunded. The agent only uses models from the public catalog.

All charges and refunds appear in your account’s transaction history with the message or request id as the reference.

Get started

Model API reference

Core concepts

Agent

SDKs

Organizations

API reference

Resources

Create a session

Send a message

Read messages

Interrupt a turn

Questions from the agent

Upload input files

Errors

Billing

​Create a session

​Send a message

​Read messages

​Interrupt a turn

​Questions from the agent

​Upload input files

​Errors

​Billing

Create a session

Send a message

Read messages

Interrupt a turn

Questions from the agent

Upload input files

Errors

Billing