> ## Documentation Index
> Fetch the complete documentation index at: https://docs.square1.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Illustration API

> NovelAI-compatible synchronous image generation

Square1 exposes a **NovelAI-protocol** image endpoint so any client that
speaks NovelAI's `/ai/generate-image` — most notably RisuAI's Lightboard
(삽화) module — can use Square1's GPU pool as its image backend:

```text theme={null}
POST https://inference.square1.dev/v1/images/nai/generate-image
Authorization: Bearer sq-arca-...
```

The request and response follow NovelAI's conventions, not OpenAI's:
you send a NAI-syntax prompt, and you get back a **ZIP archive containing
one PNG**. Errors come as `{statusCode, message}` (the shape NAI clients
already parse), not the OpenAI envelope.

<Note>
  Members-only: your account must be active, and a registered email is
  required while email enforcement is on. Illustration requests draw from
  the image queue's capacity — they do **not** consume your LLM token
  quota.
</Note>

## Your preset does the heavy lifting

The NAI protocol only carries a prompt and a few sampling numbers. The
rest — checkpoint, LoRAs, sampler, scheduler, quality prompt, upscaler —
comes from your **active illustration preset**, configured once in the
dashboard under **Images → ILLUSTRATION**. You can keep up to 10 presets;
exactly one is active, and the API always draws with the active one.

The NAI `model` field is accepted for protocol compatibility and ignored.

## Parameter precedence

| Setting                  | Wins in this order                                                                                                                                          |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Prompt / negative prompt | Request (NAI syntax, converted server-side)                                                                                                                 |
| Steps                    | Request → preset default (clamped to the preset's bounds, 1–60)                                                                                             |
| Guidance scale (CFG)     | **Preset default → request `scale`** — inverted on purpose: NAI clients always send `scale`, so a request-first rule would make your preset's CFG knob dead |
| Resolution               | Request `width`×`height` (both required) → preset default, snapped to the nearest allowed resolution by aspect ratio (e.g. 832×1216 · 1024×1024 · 1216×832) |
| Seed                     | Request                                                                                                                                                     |

## Synchronous semantics

The call blocks until the image is done (up to **180 seconds**, then
`504`). To keep waits bounded, each account may hold at most **2 pending
illustration requests** — a third returns `429` until one finishes.

Generated images are **private**: they appear in your own gallery but
never in the public feed.

## Example

```bash theme={null}
curl https://inference.square1.dev/v1/images/nai/generate-image \
  -H "Authorization: Bearer $SQUARE1_API_KEY" \
  -H "Content-Type: application/json" \
  -o result.zip \
  -d '{
    "input": "1girl, silver hair, looking at viewer, masterpiece",
    "action": "generate",
    "parameters": {
      "negative_prompt": "lowres, bad anatomy",
      "width": 832,
      "height": 1216,
      "steps": 28,
      "seed": 1234567890
    }
  }'
unzip -o result.zip
```

## Errors (NAI shape)

```json theme={null}
{ "statusCode": 429, "message": "생성 대기열이 가득 찼습니다. 잠시 후 다시 시도해 주세요" }
```

| Status | When                                                                                                |
| ------ | --------------------------------------------------------------------------------------------------- |
| 400    | Invalid body, unsupported `action`, or **blocked content** (the message names the blocked category) |
| 401    | Missing or invalid API key                                                                          |
| 403    | Admin-only mode, or your account isn't eligible                                                     |
| 429    | Your pending illustration queue (2) is full                                                         |
| 500    | Generation failed                                                                                   |
| 503    | Feature disabled · maintenance · server queue congested · no GPU worker online                      |
| 504    | Generation exceeded 180 seconds                                                                     |

<Warning>
  Content policy is enforced server-side: prompts matching blocked
  categories are rejected with `400` before anything is queued, and
  gallery-visible content is subject to the same moderation as the web
  app.
</Warning>