Model APIs

Keep a subject's identity and a place's appearance in reusable Library records. A character carries its name, canonical description and reference images; a location does the same for a room, storefront or set. Generation attaches their references and folds their canonical descriptions into the prompt verbatim.

Characters #

Read readiness before selecting a reference: ready means one front-facing face. needs_front_view, no_face, multiple_faces and unverified are advisory states, not a promise that the identity gate will pass. GET /characters/{id} also includes recent fidelity_history; list and write responses omit that history.

Locations #

A location needs no training. Its canonical description stays unchanged across scenes, and its primary reference uses an image-reference slot on an image model or an element-reference slot on a video model. A location without an image contributes its description only.

Use them in a generation #

The image request fields are generated from the contract:

The video fields include the explicit voice opt-in:

When both character_id and character_ids are supplied, the single id must be a member of the cast. The first member is the lead, including for use_character_voice. Voice opt-in may change the cost on models billed by the reference audio's length; quote the full request first.

Autopilot #

Autopilot rolls heritage, age band, hair color, build, hair style, eye color, wardrobe and an anchor detail. Consecutive rolls differ on at least two of the four core axes. It starts a portrait job; it does not create the character record for you. Store its returned canonical_description unchanged when creating that record.

$ curl -sS -X POST https://api.nolgia.ai/v1/characters/autopilot \
  -H "Authorization: Bearer $NOLGIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

This illustrative response is built from AutopilotCharacterResponse, not a production capture.

{
  "job": {
    "id": "b9f4319a-239e-4907-a9bb-406be1f0c2b8",
    "user_id": "4961eaef-70a6-4e9b-b746-c86ad3e62077",
    "modality": "image",
    "model": "grok-imagine-image",
    "status": "queued",
    "created_at": "2026-09-21T04:00:00Z",
    "updated_at": "2026-09-21T04:00:00Z"
  },
  "canonical_description": "A middle-aged woman with short dark curls, brown eyes, a sturdy build, a navy work jacket and a small silver brooch.",
  "axes": {
    "heritage": "mixed heritage",
    "age_band": "middle-aged",
    "hair_color": "dark",
    "build": "sturdy",
    "hair_style": "short curls",
    "eye_color": "brown",
    "wardrobe": "navy work jacket",
    "anchor": "small silver brooch"
  }
}

For an existing character, POST /characters/{id}/sheets creates a split, turnaround or expression sheet on gpt-image-2, billed like that model's image generation. It needs at least one reference image. Wearable references and a named wardrobe outfit share a budget of three extra references; overflow is refused instead of trimming the outfit.

The identity gate #

Characters without a reference image contribute only their description and remain unscored. Locations are not scored by the face gate.

Related reusable inputs #

Products carry reusable product images and details into a generation through product_id.

Brand kits carry palettes, fonts, logos and never-rules through brand_kit_id.

Elements provide reusable reference inputs through element_ids; they count against the selected model's reference budget.

Next steps #