feat: references

CLAUDE.md

@@ -155,13 +155,14 @@ REST API at `https://api.banatie.app` for generating images. Auth via `X-API-Key
 
 **POST `/api/v1/generations`** — create generation:
 - `prompt` (string, required) — image description
-- `aspectRatio` — `1:1`, `16:9`, `9:16`, `3:2`, `21:9` (default: `1:1`)
-- `referenceImages` (string[]) — image IDs as references
+- `aspectRatio` — `1:1`, `16:9`, `9:16`, `3:2`, `4:3`, `3:4`, `21:9` (default: `1:1`)
+- `referenceImages` (string[]) — `@alias` names of reference images
+- `flowId` (string) — associate with a flow (for flow-scoped alias resolution)
 - `autoEnhance` (boolean) — prompt enhancement (default: true)
 
 **POST `/api/v1/images/upload`** — upload image (for use as reference):
-- Multipart form data, field `file` (up to 5MB, JPEG/PNG/WebP)
-- Returns image ID in `data.id`
+- Multipart form data: `file` (up to 5MB, JPEG/PNG/WebP), `alias` (@name), `flowId`
+- Auto-creates a flow, returns `flowId` in response
 
 Response returns JSON with `data.outputImage.storageUrl` (CDN URL to download).
 
@@ -169,7 +170,9 @@ Script `src/scripts/banatie.mjs` CLI:
 ```bash
 node src/scripts/banatie.mjs --prompt "description" --output path.png [--aspect-ratio 1:1] [--ref file.png]...
 ```
-- `--ref` accepts local file paths (auto-uploaded) or existing image IDs (passed as-is). Can be repeated.
+- `--ref` accepts local file paths or `@alias`. Can be repeated
+- Local files are uploaded with auto-generated `@alias` into a shared flow
+- The flow's `flowId` is passed to generation for alias resolution
 
 Rate limit: 100 requests/hour per API key.