NOLGIA
Developers

How do I run a preset from my own code?

September 19, 2026 · 3 min read

Every preset you can run in the app can also run from your own code. The Agent Sessions API starts a NOLGIA Agent session under a preset, so the agent works with that preset's guardrails and output on every turn, exactly as it does in the chat.

This guide uses the Static ad formats preset, which makes static ads for paid social from your product photos and your own words. Swap the preset slug to run any other public preset.

An example made with the Static ad formats preset
Made with Static ad formats.

What you need

  • Product photos

    Required

    One to three clear photos of the product. It appears exactly as shown.

  • What is the product?

    Required

    Name it, what it is made of and roughly how big it is.

  • Which ad format?

    Required

    Pick the layout. Each one is a proven direct to consumer ad format.

  • The words on the ad

    Required

    Headline first, then up to three short lines, exactly as they should read. Only things that are true: we never invent claims, prices, ratings or reviews.

  • Brand colors or mood

    Optional

    Color names or codes, or a feeling in a few words. You can skip this.

  • Your logo

    Optional

    Shown exactly as it is. You can skip this.

  • Where will it run?

    Optional

    The shape of the ad.

  • How many versions?

    Optional

    Each version is the same format with its own take on the layout.

Step by step

  1. Create a Personal Access Token

    Create a token in Settings, API tokens, and send it as Authorization: Bearer <token> on every request. The base URL is https://api.nolgia.ai/v1.

  2. Upload the product photos

    Send small images to POST /assets as base64, or use POST /assets/uploads and its signed upload URL for larger files. Keep the asset ids.

  3. Start a session under the preset with the brief

    Call POST /agent/messages with new_session: { "preset_slug": "dtc-ad-formats" }, the brief in content (the product, the ad format and the exact words on the ad) and the photos in attachments. The accepted response carries session_id and agent_message_id.

  4. Wait for the reply

    Poll GET /agent/messages/{id} with backoff until the reply leaves pending, or stream GET /agent/sessions/{id}/events for a live transcript.

  5. Answer the agent's questions

    When the session's turn_status is awaiting_input, read question.text and question.options and reply with a normal message in the same session.

  6. Collect the ads

    GET /agent/sessions/{id}/assets returns what the session made, newest first. To stop a turn, call POST /agent/sessions/{id}/interrupt.

What it costs

The preset's estimate
8 credits per ad, 32 for four versions, 21 each at 2K
Time
under 2 min

  • GPT Image 2.5 Flare

    Every plan

    Per image

    Native 8 credits · 2K 21 credits · 4K 58 credits

New accounts start with 350 free credits.

See every rate on the pricing page

Checklist

  • A Personal Access Token stored as a secret, never in client code.
  • Product photos uploaded and ready before the first message.
  • A brief that names the product, the ad format and the exact words.
  • A handler for awaiting_input questions.
  • An overall timeout in your code. A polling timeout does not stop the turn; interrupt does.

FAQ

Questions and answers.

Is there an SDK helper?
Yes. The TypeScript, Python and Go SDKs include helpers that send a message and wait for the reply with backoff: runAgent, nolgia.agent_run.run and RunAgent.
Can I run any preset this way?
Any public preset. The session must name an existing public preset slug, and the API refuses one it does not know.
Do I need a particular plan?
The Agent Sessions API talks to your hosted NOLGIA Agent, which comes with Studio plans. Generations and agent turns spend credits from your account.
Which models does Static ad formats use?
Static ad formats runs on GPT Image 2.5 Flare. The agent picks the model; you do not pass one.
Where is the full reference?
The Agent Sessions API guide and the API reference live at docs.nolgia.ai.

Make it yourself.

Try this preset freeSee pricing

More guides