Model APIs

Presets describe an outcome and the model or Studio lane that makes it. Read the public catalog to choose one, resolve its intake to collect the right inputs, and assemble a prompt before generating. The catalog's time and credit hints help you browse; a current estimate or quote supplies the price for a run.

List and read #

The public catalog is anonymous. GET /presets lists public root presets in ascending sort_order, with slug as the tiebreaker. Children belong to a parent's detail instead of appearing as root cards. Admin accounts can also see private presets and children.

The next two commands select a few fields for readability. Their JSON is built from the Preset schema and illustrates a catalog entry; it is not a captured catalog response. Choose PRESET_SLUG from your own catalog result.

$ curl -sS https://api.nolgia.ai/v1/presets

[
  {
    "slug": "logo-design",
    "name": "Design a logo",
    "output_type": "image",
    "target": {
      "kind": "create_image",
      "params": {"model": "gpt-image-2.5-flare"}
    },
    "estimated_credits": "See the current intake estimate"
  }
]

$ curl -sS "https://api.nolgia.ai/v1/presets/$PRESET_SLUG"

{
  "slug": "logo-design",
  "long_description": "Create a logo from your brief and reference images.",
  "use_cases": ["Explore a wordmark for a coffee roaster"],
  "model_ids": ["gpt-image-2.5-flare"],
  "options": [{"label": "Wordmark", "description": "The name set in type, nothing else."}]
}

The same detail contains the preset family, authored examples and page content. /presets/{slug}/page is a PATCH route for authorized page authors; there is no separate GET page route. Customers read page content through GET /presets/{slug}.

Intake and assemble #

Read the intake context #

Use intake.steps to build the questions and model to enforce supported input choices. The following response is a shortened, schema-built form of the spec's logo-design intake example, with one text step to keep the sequence readable.

$ curl --fail-with-body -sS "https://api.nolgia.ai/v1/presets/$PRESET_SLUG/intake/context" \
  -H "Authorization: Bearer $NOLGIA_TOKEN"

{
  "slug": "logo-design",
  "intake_from_parent": false,
  "intake": {
    "version": 1,
    "steps": [
      {
        "id": "brand",
        "kind": "text",
        "label": "What is the brand?",
        "required": true,
        "max_chars": 600,
        "binds_to": "prompt_slot:THE BRAND"
      }
    ],
    "submit": {"kind": "generate"}
  },
  "target": {
    "kind": "create_image",
    "model": "gpt-image-2.5-flare",
    "endpoint": "POST /generate/image"
  },
  "options": [],
  "prompt_slots": ["THE BRAND"],
  "assembly": {"doctrine": false, "doctrine_from_parent": false, "hold_credits": 0}
}

Assemble the prompt #

Send answers keyed by the actual step ids from the returned intake. chips contains published option labels; unknown labels are refused and repeated choices are deduplicated. The example below continues the illustrative one-step intake above.

$ curl --fail-with-body -sS "https://api.nolgia.ai/v1/presets/$PRESET_SLUG/assemble" \
  -H "Authorization: Bearer $NOLGIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"answers":{"brand":"Ember, a small coffee roaster: warm, quiet, honest"},"brief":"A simple wordmark on a plain background","count":1}' \
  | tee assembled.json

{
  "prompt": "THE BRAND: Ember, a small coffee roaster: warm, quiet, honest. A simple wordmark on a plain background",
  "params": {"model": "gpt-image-2.5-flare", "num_images": 1},
  "notes": ["Your answers were placed into the preset's own prompt as written."],
  "mode": "slot_fill",
  "credits_charged": 0,
  "model": "gpt-image-2.5-flare",
  "endpoint": "POST /generate/image"
}

slot_fill #

doctrine #

Generate from the assembled result #

For an assembly whose endpoint is POST /generate/image, merge prompt and optional negative_prompt into params. Keep the returned reference and model settings intact. Choose the corresponding video or audio endpoint when assembly names one of those instead.

$ curl -sS https://api.nolgia.ai/v1/generate/image \
  -H "Authorization: Bearer $NOLGIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model":"<params.model from the assembled response>","prompt":"<prompt from the assembled response>"}'

{
  "id": "9b09f1a0-e856-4275-bb83-7a6cc5e304d8",
  "user_id": "75976388-3210-42e6-9b39-bf6290a15d4c",
  "model": "gpt-image-2.5-flare",
  "modality": "image",
  "status": "queued",
  "created_at": "2026-09-21T04:00:00Z",
  "updated_at": "2026-09-21T04:00:00Z"
}

Follow that job through submit and poll. If the intake's target kind is set, use the set request instead; the assembly operation documented here supports the three create_* targets.

Suggestions #

Ask for directions before choosing a final prompt. This is POST /presets/{slug}/suggestions; it is not a catalog read.

The writer uses the preset's own description, guardrails, options and children. Invalid suggestions are dropped, so fewer than count can be returned. A child_slug points to an existing public child when one matches; it is null for a new direction. The following is an illustrative schema-built response with one validated direction remaining.

$ curl --fail-with-body -sS "https://api.nolgia.ai/v1/presets/$PRESET_SLUG/suggestions" \
  -H "Authorization: Bearer $NOLGIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"brief":"Ember, a small coffee roaster: warm, quiet, honest","count":3}'

The response excerpt omits model, which names the suggestion writer, not the generation model the preset selects.

{
  "suggestions": [
    {
      "title": "Quiet wordmark",
      "description": "A warm, restrained wordmark for the coffee roaster.",
      "prompt": "Design a logo for Ember, a small coffee roaster. Set the word Ember in warm, restrained lettering on a plain background. Keep the letterforms clear at a small size.",
      "options": {},
      "child_slug": null
    }
  ],
  "credits_charged": 1
}

The ledger labels this charge Preset suggestions · {slug}. Suggestions return prompt options; they do not create a generation job or a finished asset.

Presets that run in an app on your computer #

Film assistant presets (page_category film-assistant, target kind desktop_app) do their work inside a desktop app on your own computer, such as Blender. NOLGIA generates nothing and charges nothing when one runs: the preset carries a written workflow, instructions, which your agent follows in the app through the NOLGIA plugin for that app. Anything the workflow makes with NOLGIA along the way, like a 3D model or a background, is priced as usual.

In an MCP client, every public Film assistant preset is also a prompt; see Run MCP.

Next steps #