# AI Generator — API

**Port:** 19001
**Base URL:** http://localhost:19001

## Providers and models

| Provider  | Model           | Internal                       | Status      | Notes                              |
| --------- | --------------- | ------------------------------ | ----------- | ---------------------------------- |
| gemini    | nano-banana     | gemini-2.5-flash-image         | ✅ Works    | Fast, 1024px                       |
| gemini    | nano-banana-pro | gemini-3-pro-image-preview     | ⚠️ Slow     | Higher quality, up to 4K, ~30s     |
| replicate | ideogram        | ideogram-ai/ideogram-v3-turbo  | ✅ Works    | Good for text in images            |
| replicate | recraft         | recraft-ai/recraft-v3          | ✅ Works    | High-quality illustrations         |
| replicate | flux-dev        | black-forest-labs/flux-dev     | ✅ Works    | Artistic                           |
| replicate | flux-pro        | black-forest-labs/flux-1.1-pro | ✅ Works    | Highest quality                    |

## Automatic fallback

If the requested model fails, the service tries the next one in the chain automatically.

Default chain (best → worst):

    1. gemini / nano-banana-pro
    2. replicate / flux-pro
    3. gemini / nano-banana
    4. replicate / recraft
    5. replicate / ideogram
    6. replicate / flux-dev

You can override from the request via the `fallback` field (array of `{provider, model}` objects).

If a fallback was used, the response includes:

    "fallbackUsed": { "provider": "gemini", "model": "nano-banana" }
    "originalRequest": { "provider": "gemini", "model": "nano-banana-pro" }

## Aspect ratios (nano-banana)

1:1, 4:5, 9:16, 16:9, 3:2, 2:3, 3:4, 4:3, 5:4, 21:9

## Endpoints

### Session

    POST   /session                  → Create session
    GET    /session/:id              → Status
    DELETE /session/:id              → Remove
    GET    /sessions                 → List all

### Generation

    POST /session/:id/generate       → Initial image
    POST /session/:id/iterate        → Modify image
    GET  /session/:id/history        → History

### Layers (layered mode)

    POST /session/:id/separate       → Split into layers
    POST /session/:id/lock           → Lock a layer
    POST /session/:id/unlock         → Unlock a layer

### Direct generation (sessionless)

    POST /generate                   → Generate an image without a session
    GET  /providers                  → List providers
    GET  /models                     → List models

## Common generation fields

These fields apply to generate, iterate, and direct generation:

| Field           | Type   | Required | Default                | Description                              |
| --------------- | ------ | -------- | ---------------------- | ---------------------------------------- |
| prompt          | string | ✅ yes   | —                      | Generation prompt                        |
| provider        | string | no       | config.defaultProvider | "gemini" or "replicate"                  |
| model           | string | no       | config.defaultModel    | See the model table above                |
| fallback        | array  | no       | config.fallbackChain   | Array of `{provider, model}` fallbacks   |
| aspectRatio     | string | no       | "1:1"                  | "1:1", "4:5", "9:16", etc.               |
| referenceImages | array  | no       | []                     | Base64 strings or `{data, mimeType}`     |

IMPORTANT: if you don't send provider/model, the config default is used (currently gemini/nano-banana).
To use the best model, send provider and model explicitly.

Example request for max quality with fallback:

    {
      "prompt": "...",
      "provider": "gemini",
      "model": "nano-banana-pro",
      "fallback": [
        { "provider": "replicate", "model": "flux-pro" },
        { "provider": "gemini", "model": "nano-banana" }
      ]
    }

## Create session

Input:

    {
      "project": "name",
      "mode": "single|layered",
      "config": {
        "aspectRatio": "1:1|9:16|16:9|story|feed",
        "imageSize": "1K|2K|4K",
        "provider": "gemini",
        "model": "nano-banana-pro"
      }
    }

Output:

    { "sessionId": "sess_xxx", "status": "ready" }

## Generate initial image (session)

    POST /session/:id/generate

Input:

    {
      "prompt": "Blue planet with rings",
      "provider": "gemini",
      "model": "nano-banana-pro",
      "fallback": [{"provider":"gemini","model":"nano-banana"}],
      "referenceImages": []
    }

- **prompt** — required
- **provider** / **model** — optional, overrides the session config
- **fallback** — optional, fallback chain
- **referenceImages** — optional, array of base64

## Iterate on image (session)

    POST /session/:id/iterate

Input:

    {
      "instructions": "Change the color to red",
      "referenceImages": ["...base64..."],
      "aspectRatio": "1:1|4:5|9:16",
      "provider": "gemini|replicate",
      "model": "nano-banana|nano-banana-pro|ideogram|recraft|flux-dev|flux-pro",
      "fallback": [{"provider":"gemini","model":"nano-banana"}]
    }

- **instructions** — required
- **referenceImages** — optional, array of base64
- **aspectRatio** — optional
- **provider** / **model** — optional, overrides the default
- **fallback** — optional, fallback chain

## referenceImages format

    "iVBORw0KGgoAAAANSUhEUgAA..."                    # raw base64 (assumes PNG)
    "data:image/jpeg;base64,/9j/4AAQ..."              # data URI (auto-cleaned)
    { "data": "...", "mimeType": "image/jpeg" }       # structured object

Limit: 14 images (Gemini Pro constraint)

## CURL examples

Create a session:

    curl -X POST http://localhost:19001/session \
      -H "Content-Type: application/json" \
      -d '{"project":"test","mode":"single"}'

Generate:

    curl -X POST http://localhost:19001/session/sess_xxx/generate \
      -H "Content-Type: application/json" \
      -d '{"prompt":"Blue planet with rings"}'

Iterate with Gemini Flash (recommended):

    curl -X POST http://localhost:19001/session/sess_xxx/iterate \
      -H "Content-Type: application/json" \
      -d '{"instructions":"Remove the gold badge","aspectRatio":"4:5","provider":"gemini","model":"nano-banana"}'

Iterate with Replicate Recraft:

    curl -X POST http://localhost:19001/session/sess_xxx/iterate \
      -H "Content-Type: application/json" \
      -d '{"instructions":"Make it more vibrant","provider":"replicate","model":"recraft"}'

Iterate with Ideogram (good for text):

    curl -X POST http://localhost:19001/session/sess_xxx/iterate \
      -H "Content-Type: application/json" \
      -d '{"instructions":"Add text SALE 50% OFF","provider":"replicate","model":"ideogram"}'