NOLGIANOLGIADocs

Model APIs

Sets

On this page
  1. Choose a kind
    1. pack
    2. variants
  2. Submit a set
    1. Request fields
  3. Poll the outputs
    1. Set status
    2. List previous sets
  4. Partial acceptance and billing
  5. Next steps

A set groups two to eight labelled image prompts under one model and shared visual settings. Use it for carousel slides, ad variants or an exploration along a named axis. Each member remains its own job with its own credit hold and refund.

One set, independent image jobs Submitting a set fans out into two to eight member jobs with independent credit holds. Poll the set to collect their ready outputs. Accepted members continue if a later member is refused. SHARED VISUAL SETTINGS 2–8 MEMBER JOBS GROUPED OUTPUTS Pack or variants POST /generate/set Member 1 · own hold Member 2 · own hold Further members Jobs + ready assets GET /sets/{id} Each accepted job settles or refunds independently. Refused labels appear in problems.
A set fans out into independent image jobs and collects their outputs
Method Path What it does
POST /generate/set Generate a coordinated set of image Outputs.
GET /sets List sets in your current library, newest first.
GET /sets/{id} Get a set with its jobs and Ready Outputs.

Choose a kind #

pack #

Property Value
Value pack
Default Used when kind is omitted
Purpose A coordinated collection, such as carousel slides or ad variants
Shared settings Model, references, characters, location, saved style, brand kit, product and image settings
Member input Its own label and prompt

Repeat the visual rules each member must preserve in its prompt, and supply shared references and settings on the set. A shared visual system does not make one member's finished image the input to the next.

variants #

Property Value
Value variants
Purpose Explore a named axis, such as emotion or concept
Axis field axis, a string up to 40 characters
Member labels Name each direction so the resulting jobs and outputs remain identifiable
Billing One independently priced image generation per accepted member

Submit a set #

Use a label for each output and keep the same model and visual settings at the top level. These requests and responses are schema-built examples, not production captures. The installed CLI has no set-generation command; use the HTTP endpoint or a generated client.

shellexample — submit a pack
curl --fail-with-body -sS https://api.nolgia.ai/v1/generate/set \
  -H "Authorization: Bearer $NOLGIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model":"flux-pro","name":"Paper mountains","kind":"pack","members":[{"label":"Dawn","prompt":"A paper-cut mountain range at dawn, warm paper, blue shadows"},{"label":"Night","prompt":"A paper-cut mountain range at night, warm paper, blue shadows"}]}'
JSON202 Accepted — example from OutputSet
{
  "id": "b6a72f92-4e05-46b9-a28d-3c69c6d6e1e9",
  "name": "Paper mountains",
  "kind": "pack",
  "model": "flux-pro",
  "status": "generating",
  "labels": ["Dawn", "Night"],
  "members": [
    {
      "label": "Dawn",
      "prompt": "A paper-cut mountain range at dawn, warm paper, blue shadows",
      "sort_order": 0,
      "job": {
        "id": "6df58eed-0617-4f3c-8e87-e2f28d05e37d",
        "user_id": "75976388-3210-42e6-9b39-bf6290a15d4c",
        "model": "flux-pro",
        "modality": "image",
        "status": "queued",
        "created_at": "2026-09-21T04:00:00Z",
        "updated_at": "2026-09-21T04:00:00Z"
      }
    },
    {
      "label": "Night",
      "prompt": "A paper-cut mountain range at night, warm paper, blue shadows",
      "sort_order": 1,
      "job": {
        "id": "a432a04c-cbf1-4cfe-8fdc-ebd4d7a504e8",
        "user_id": "75976388-3210-42e6-9b39-bf6290a15d4c",
        "model": "flux-pro",
        "modality": "image",
        "status": "queued",
        "created_at": "2026-09-21T04:00:01Z",
        "updated_at": "2026-09-21T04:00:01Z"
      }
    }
  ],
  "created_at": "2026-09-21T04:00:00Z",
  "updated_at": "2026-09-21T04:00:01Z"
}
Field Type Required Description
id string Yes
name string Yes
kind OutputSetKind Yes
axis string No
preset_slug string No
project_id string No
model string Yes
shared object No
labels array of string Yes
status OutputSetStatus Yes
members array of OutputSetMember Yes
problems array of OutputSetProblem No
created_at string Yes
updated_at string Yes
Field Type Required Description
label string Yes
prompt string Yes
sort_order integer Yes
job Job Yes
asset Asset No

The nested job uses the Job response. When it succeeds, the member's asset contains the ready output. Store the set id for the group and the member job ids for progress or support.

Request fields #

Field Type Required Description
confirmation_token string No Optional proof that this exact request and price were shown to the customer, from POST /jobs/cost.…
model ImageModel Yes
members array of OutputSetMemberInput Yes
name string No
kind OutputSetKind No
axis string No A named axis for a variants set, such as emotion or concept.
preset_slug string, nullable No
project_id string No
tags array of string No
reference_asset_ids array of string, nullable No
face_reference_asset_id string, nullable No
face_check_consent boolean, nullable No Applied to every member exactly as on POST /generate/image: records your consent to the face identity check for the face_reference_asset_id photo (once per photo; it stays recorded for later requests).…
character_ids array of string, nullable No
location_id string, nullable No
brand_kit_id string, nullable No
product_id string, nullable No
style_id string, nullable No
negative_prompt string, nullable No
aspect_ratio ImageAspectRatio No
quality string, nullable No
render_quality one of auto, low, medium, high, xhigh, max No
Field Type Required Description
label string Yes
prompt string Yes

members must contain 2–8 entries; each label is 1–40 characters and each prompt 1–4,000 characters. kind defaults to pack. A variants request can name its axis. confirmation_token comes from a set quote through POST /jobs/cost; it covers the exact set request and price.

Poll the outputs #

GET /sets/{id} returns an OutputSet with the latest jobs and ready assets. The following command projects the fields a progress list needs; the JSON is a schema-built completed example of that projection.

shellexample — poll and project the member outcomes
curl -sS "https://api.nolgia.ai/v1/sets/$SET_ID" -H "Authorization: Bearer $NOLGIA_TOKEN"
JSON200 OK — example projection of OutputSet
{
  "id": "b6a72f92-4e05-46b9-a28d-3c69c6d6e1e9",
  "status": "ready",
  "outputs": [
    {
      "label": "Dawn",
      "job_id": "6df58eed-0617-4f3c-8e87-e2f28d05e37d",
      "status": "succeeded",
      "asset_id": "c87cf95c-2975-4d88-976c-234060f95fbf"
    },
    {
      "label": "Night",
      "job_id": "a432a04c-cbf1-4cfe-8fdc-ebd4d7a504e8",
      "status": "succeeded",
      "asset_id": "d25f50c0-ced7-4baa-ad9a-03bdb31766fd"
    }
  ],
  "problems": null
}
Projected field Source Meaning
id OutputSet.id Group identifier to retain and poll.
status OutputSet.status Overall progress; values below.
outputs[].label members[].label Your name for the requested output.
outputs[].job_id members[].job.id The individual generation to follow.
outputs[].status members[].job.status That member's job outcome.
outputs[].asset_id members[].asset.id Ready library output; the projection gives null before it exists.
problems OutputSet.problems Refused labels when present; absent when no member was refused.

Set status #

OutputSetStatus Meaning Next action
generating Member jobs are still running. Poll the same set.
ready All outputs are ready. Read or download the member assets.
partial Some jobs failed. Keep successful outputs; inspect failed jobs and any refused labels.
failed All jobs failed. Inspect each job's failure and refund before deciding what to resubmit.

List previous sets #

GET /sets reads sets in your current library, newest first. project_id filters by project; limit accepts 1–100 and defaults to 25. The empty result below is a schema-built example.

shellexample — list sets
curl --fail-with-body -sS 'https://api.nolgia.ai/v1/sets?limit=25' \
  -H "Authorization: Bearer $NOLGIA_TOKEN"
JSON200 OK — example from OutputSetList
{"sets": []}
Field Type Required Description
sets array of OutputSet Yes
Parameter In Required Description
project_id query No
limit query No Maximum sets to return, 25 when omitted.

Partial acceptance and billing #

If a later member is refused, accepted members keep running and further members are not submitted. The set's problems array lists refused labels, each with its HTTP status and detail. A refusal is different from a member that was accepted and later failed: the latter has a job whose failure.code and failure.credits_refunded describe the outcome.

Field Type Required Description
label string Yes
status integer Yes
detail string Yes
Outcome What to inspect Credit result
Member accepted Its nested job Its own hold, settled on completion.
Member refused at submission problems[].label, status, detail No accepted generation for that member; accepted siblings continue.
Accepted member fails members[].job.failure Its recorded refund is independent of siblings; read credits_refunded.
Remaining members were not submitted Compare requested labels with members and problems No job or hold for the unsubmitted work.

Quote a set before submission using POST /jobs/cost with kind: set and the full set request. That quote covers the run's members at their shared image settings. It does not make acceptance atomic or pool their refunds.

Next steps #