Agent quickstart

This guide runs a complete agent turn: create a session, send a task, wait for the answer, and continue the conversation. Use either official SDK below or follow the cURL walkthrough for the raw request lifecycle.

Prerequisites

An API key ID and secret with Agent API access (contact support to enable it)
A credit balance — agent turns and the generations they run are billed to your account

API credentials grant access to your account and credits. Use them only in server-side code and never commit them to source control.

Use the SDK

Install Python SDK 0.2.0 or later:

pip install "higgsfield-client>=0.2.0"

The agents namespace covers the whole flow. run() sends the task and polls with backoff until the turn ends, so one call returns the finished answer:

Python

from higgsfield_client import SyncClient

client = SyncClient(api_key="key-id:key-secret")

# Sessions are durable: keep the id, the agent remembers previous turns.
session = client.agents.sessions.create()

result = client.agents.sessions.run(
    session.session_id,
    "Generate one image of a quiet alpine lake at sunrise, editorial "
    "photography, 4:3. Reply with the image URL.",
    # Answer a clarifying question inline; without the handler run() returns
    # TurnResult(status="awaiting_input") with the question in .text.
    on_question=lambda question: "Photorealistic style.",
)
print(result.status)      # completed | failed | awaiting_input
print(result.text)        # the agent's answer
print(result.asset_urls)  # URLs of generated assets

# Follow-ups reuse the same session (memory persists).
follow_up = client.agents.sessions.run(
    session.session_id, "Now make a 16:9 version of the same scene at dusk."
)

# Give the agent an input file: upload, then reference the URL in the task.
with open("photo.jpeg", "rb") as f:
    url = client.agents.media.upload(f.read(), extension="jpeg", type="image")
client.agents.sessions.run(session.session_id, f"Animate this image: {url}")

SyncClient() also reads credentials from HF_KEY or the pair HF_API_KEY and HF_API_SECRET. AsyncClient exposes the same agent methods; await each call. on_question is a synchronous callback returning an answer string for both clients. Python run() polls with backoff from 2 to 10 seconds and waits up to 30 minutes by default. Override the wait limit with run(..., timeout=seconds). If the limit is reached, it raises AgentTimeoutError; the server-side turn keeps running. Read its messages or explicitly call sessions.interrupt() to request that it stop.

TypeScript

Install JS SDK 0.2.4 or later and use the recommended @higgsfield/client/v2 entry point:

npm install "@higgsfield/client@^0.2.4"

TypeScript

import { readFile } from 'node:fs/promises';
import { createHiggsfieldClient } from '@higgsfield/client/v2';

const client = createHiggsfieldClient({
  credentials: 'key-id:key-secret',
});
const session = await client.agents.sessions.create();
const result = await client.agents.sessions.run(
  session.session_id,
  'Generate one image of a quiet alpine lake at sunrise. Reply with the image URL.',
  {
    onQuestion: () => 'Photorealistic style.',
    timeout: 30 * 60 * 1000,
  }
);
console.log(result.status, result.text, result.assetUrls);

const bytes = await readFile('photo.jpeg');
const url = await client.agents.media.upload(bytes, 'jpeg', 'image');
await client.agents.sessions.run(session.session_id, `Animate this image: ${url}`);

The configured singleton also exposes higgsfield.agents after config({ credentials: 'key-id:key-secret' }). Import both from @higgsfield/client/v2. Explicit clients created with configuration keep their credentials separate. TypeScript run() takes timeout in milliseconds (default: 30 minutes). Its onQuestion handler can return a string or a promise of one. A timeout stops the local wait while the server-side turn continues, just as in Python. Errors are typed: a busy session raises SessionBusyError (a turn is already running — one turn per session at a time), missing access raises AgentAccessDeniedError, and an exhausted balance raises InsufficientCreditsError in Python or NotEnoughCreditsError in TypeScript. Lower-level methods (sessions.send, sessions.messages, sessions.interrupt) are available when you want to drive the poll loop yourself.

Use cURL

The same flow over raw REST — useful to understand what the SDK does. You’ll need curl and jq.

1. Configure credentials

export HF_API_KEY_ID="your-api-key-id"
export HF_API_KEY_SECRET="your-api-key-secret"

2. Create a session

SESSION=$(curl --silent --show-error --fail-with-body \
  --request POST \
  --url https://api.higgsfield.ai/v1/agent/sessions \
  --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
  --header "Content-Type: application/json" \
  --data '{}')

echo "$SESSION" | jq
export SESSION_ID=$(echo "$SESSION" | jq --raw-output '.session_id')

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

Sessions are durable: keep the session_id and reuse it — the agent remembers previous turns.

3. Send a task

MESSAGE=$(curl --silent --show-error --fail-with-body \
  --request POST \
  --url "https://api.higgsfield.ai/v1/agent/sessions/${SESSION_ID}/messages" \
  --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
  --header "Content-Type: application/json" \
  --data '{
    "content": "Generate one image of a quiet alpine lake at sunrise, editorial photography, 4:3. Reply with the image URL."
  }')

echo "$MESSAGE" | jq

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

The request is accepted with 202 and the turn runs asynchronously. If the session is already running a turn you get 409 session_busy.

4. Poll for the result

curl --silent --show-error --fail-with-body \
  --url "https://api.higgsfield.ai/v1/agent/sessions/${SESSION_ID}/messages" \
  --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" | jq

Poll every few seconds (start at two, back off to ten) until the assistant message for your turn has "status": "completed". A simple turn finishes in under a minute; a turn with several generations can take considerably longer.

{
  "status": "idle",
  "messages": [
    {
      "message_id": "4bf91fcb-abb3-44f4-815c-a74dda7817d3",
      "role": "user",
      "status": "completed",
      "message": { "type": "text", "text": "Generate one image of..." },
      "created_at": "2026-09-01T14:37:53.000Z"
    },
    {
      "message_id": "a0600bbf-b0c8-4c13-b0ff-83df14a2aa2d",
      "role": "assistant",
      "status": "completed",
      "message": {
        "id": "a0600bbf-b0c8-4c13-b0ff-83df14a2aa2d",
        "role": "assistant",
        "parts": [
          { "type": "text", "text": "Here is your image: https://cdn.higgsfield.ai/..." }
        ]
      },
      "created_at": "2026-09-01T14:38:41.000Z"
    }
  ]
}

The assistant’s message is a structured object; the answer text lives in its parts array. To extract it:

curl --silent --show-error --fail-with-body \
  --url "https://api.higgsfield.ai/v1/agent/sessions/${SESSION_ID}/messages" \
  --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
  | jq --raw-output '
      [.messages[] | select(.role == "assistant" and .status == "completed")]
      | last
      | [.message.parts[] | select(.type == "text") | .text]
      | join("\n")'

5. Continue the conversation

The session keeps memory. Send a follow-up the same way:

curl --silent --show-error --fail-with-body \
  --request POST \
  --url "https://api.higgsfield.ai/v1/agent/sessions/${SESSION_ID}/messages" \
  --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
  --header "Content-Type: application/json" \
  --data '{"content": "Now make a 16:9 version of the same scene at dusk."}'

If the agent asks a question

When a task is ambiguous, the agent may ask for a decision instead of guessing. The session status becomes awaiting_input and the turn parks. Answer with a regular message — your reply resumes the same turn:

curl --silent --show-error --fail-with-body \
  --request POST \
  --url "https://api.higgsfield.ai/v1/agent/sessions/${SESSION_ID}/messages" \
  --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
  --header "Content-Type: application/json" \
  --data '{"content": "Use the photorealistic style."}'

Next steps

API reference — all endpoints, media uploads, interrupts, errors, and billing.
Agent overview — what the agent can and cannot do.

Get started

Model API reference

Core concepts

Agent

SDKs

Organizations

API reference

Resources

Prerequisites

Use the SDK

TypeScript

Use cURL

1. Configure credentials

2. Create a session

3. Send a task

4. Poll for the result

5. Continue the conversation

If the agent asks a question

Next steps

​Prerequisites

​Use the SDK

​TypeScript

​Use cURL

​1. Configure credentials

​2. Create a session

​3. Send a task

​4. Poll for the result

​5. Continue the conversation

​If the agent asks a question

​Next steps

Prerequisites

Use the SDK

TypeScript

Use cURL

1. Configure credentials

2. Create a session

3. Send a task

4. Poll for the result

5. Continue the conversation

If the agent asks a question

Next steps