Reference

Server API

The CLI is a thin shell over the local server — most /api/* routes have a CLI wrapper. Agent Mode is web-UI only; prompt builder is also available through ima2 prompt build. This page maps the endpoint groups; for full request and response shapes, see API.md.

Base URL

All endpoints are served locally. The default base is http://localhost:3333; the actual bound port is advertised in ~/.ima2/server.json (prefer backend.url).

Generation

Endpoint	Purpose
`POST /api/generate`	Text-to-image and reference-guided root generation.
`POST /api/edit`	Image edit / image-to-image generation.
`POST /api/generate/multimode`	Multimode batch. Supports async POST (202) + SSE multiplexing.
`POST /api/node/generate`	Node-mode generation and child edits. Supports async POST (202) + SSE multiplexing.
`GET /api/node/:nodeId`	Fetch stored node metadata and asset URL.
`GET /api/events`	Persistent SSE multiplex channel for all async generation progress.
`POST /api/video/generate`	Video generation via Grok (T2V/I2V/Ref2V). Supports async POST (202) + SSE multiplexing.
`POST /api/video/edit`	Video-to-video edit via Grok; saves a generated MP4 artifact.
`POST /api/video/extend`	Extend a generated or remote MP4 from its last frame.
`GET /api/video/frame`	Extract a PNG frame from a generated MP4.
`POST /api/video/analyze`	Analyze first/last frames with the configured planner model (Grok 4.3 by default).

POST /api/generate — request body

{
  "prompt": "a shiba in space",
  "quality": "medium",
  "size": "1024x1024",
  "format": "png",
  "moderation": "low",
  "provider": "oauth",
  "model": "gpt-5.4",
  "references": [],
  "requestId": "optional-client-id"
}

Quality: low, medium, high. Moderation: auto, low. Provider: auto, oauth, api, grok, grok-api, agy, gemini-api, atlascloud, minimax, nai, comfy. GPT OAuth defaults to gpt-6-luna (also gpt-6-sol, gpt-6-astra); the API-key lane defaults to gpt-5.6-luna. Grok image models: grok-imagine-image-2.0 (default), grok-imagine-image and grok-imagine-image-quality. Gemini API models: nano-banana-2 (default) and nano-banana-pro. The web UI uses GET /api/events (SSE multiplexing) for all generation progress: POST routes accept { async: true, requestId } and respond 202; events (phase, partial, done, error) are multiplexed through the shared event bus. CLI clients that send Accept: text/event-stream still receive per-request SSE.

NovelAI requests use provider: "nai" and may include negativePrompt plus provider-native sampling controls. NovelAI is text-to-image only; references and edits return explicit NAI_*_UNSUPPORTED errors.

Video generation. POST /api/video/generate (SSE) generates videos via Grok. The default is canonical grok-imagine-video-1.5; grok-imagine-video remains for compatibility paths and grok-imagine-video-1.5-preview is accepted only as a compatibility alias. Modes: text-to-video, image-to-video, reference-to-video (2–14 refs). 1080p is available for 1.5 prompt-only T2V through the canvas shim and for I2V with one image/frame source; Ref2V, V2V edit, and extension remain base-model paths. CLI: ima2 video. Extended CLI/API surfaces include ima2 video edit, ima2 video extend, ima2 video frame, and ima2 video analyze. Request body accepts plannerModel (default grok-4.3; Grok 4.5 and 4.6 are selectable) and storyboard for sequential clip continuity. Frame/analyze accept generated MP4 files; analyze rejects arbitrary remote URLs.

History

Endpoint	Notes
`GET /api/history`	List generated assets; `?groupBy=session` groups by session title.
`DELETE /api/history/:filename`	Tombstone a generated asset.
`POST /api/history/:filename/restore`	Restore a recently deleted asset.

Assets & vectorize

Endpoint	Notes
`POST /api/assets/derived`	`kind=vector-svg` traces a stored PNG/JPEG/WebP with `source`, `preset`, and optional tuning query parameters. The request body is empty.

Sessions & graphs

Endpoint	Notes
`GET /api/sessions` · `POST /api/sessions`	List or create graph sessions.
`GET /api/sessions/:id`	Load a session and its graph.
`PATCH /api/sessions/:id` · `DELETE /api/sessions/:id`	Rename or delete a session.
`PUT /api/sessions/:id/graph`	Save a graph snapshot.

Optimistic concurrency. Graph saves require an If-Match header with the current version. A stale version returns GRAPH_VERSION_CONFLICT plus the current version — it only means you saved against a stale snapshot, not that another tab changed the graph.

Agent Mode & discovery

Agent Mode is a conversational image workspace (sessions, turns, and a durable per-session queue). These routes are always registered but have no CLI wrapper — drive Agent Mode from the web UI.

Endpoint	Purpose
`GET /api/capabilities`	Agent-facing discovery: supported models, valid values, limits, version (`ima2 capabilities`).
`GET · POST /api/agent/sessions`	List or create agent sessions.
`GET · PATCH · DELETE /api/agent/sessions/:id`	Load, update, or delete a session.
`POST /api/agent/sessions/:id/turns`	Run an agent turn; supports slash commands and `/question`.
`GET · POST /api/agent/sessions/:id/queue`	Inspect or enqueue durable queue work (`/api/agent/queue/:itemId/cancel` · `retry` manage items).
`POST /api/prompt-builder/chat`	Prompt Builder assistant (`ima2 prompt build`). The response returns `requestedBackend`, the answering `backend`, and `model`.
`GET · PUT /api/prompt-builder/config`	Read or update the persisted Prompt Builder backend/model pair. GET returns backend/model catalogs, `autoOrder`, and environment-lock bits.

Health, storage & jobs

Endpoint	Notes
`GET /api/health`	Health check (`ima2 ping`). Includes `grok: { auth: "oauth" \| "none" }`, mirrored in `~/.ima2/server.json`.
`GET /api/providers`	Provider availability and runtime ports (`ima2 providers`).
`GET /api/oauth/status`	GPT OAuth status (`ima2 oauth status`).
`GET /api/grok/status`	xAI OAuth session status and image-model probe (`ima2 grok status`). Returns `ready`, `no_image_model`, `error`, or `offline` with reason `login_required` when no session exists.
`GET /api/storage/status`	Storage inspection.
`POST /api/storage/open-generated-dir`	Open the generated directory in the OS file manager.
`GET /api/inflight` · `DELETE /api/inflight/:id`	List or force-remove in-flight jobs.

Keys & auth

Endpoint	Notes
`GET /api/keys/status`	Key status for all providers (openai, xai, gemini, vertex) — masked key and source.
`PUT /api/keys/:provider`	Save and validate an API key for openai, xai, or gemini. Validates against the provider API before saving to config.
`DELETE /api/keys/:provider`	Remove a config-layer API key (env-sourced keys are immutable).
`PUT /api/keys/vertex`	Save and validate a Google Cloud service-account JSON for Vertex AI auth. Sets `geminiAuthMode: "vertex"` in config.
`DELETE /api/keys/vertex`	Remove the Vertex AI service-account from config.
`GET /api/quota`	Usage bars for Codex (GPT OAuth) and Grok. Grok result includes `billing.usedUsd` / `billing.limitUsd` for the dollar display.
`POST /api/auth/switch`	Start a device-code auth flow for `grok` or `codex`. Returns `sessionId`, `userCode`, and `verificationUrl`.
`GET /api/auth/switch/:sessionId`	Poll auth flow status: `pending`, `complete`, `error`, or `expired`.

Common error codes

Code	Meaning
`API_KEY_REQUIRED`	API path requested without a configured key.
`INVALID_IMAGE_MODEL`	Model name is unknown or unsupported.
`IMAGE_MODEL_UNSUPPORTED`	Model exists but cannot use image generation.
`SAFETY_REFUSAL` · `MODERATION_REFUSED`	Upstream safety / moderation refusal.
`AUTH_CHATGPT_EXPIRED`	Codex/ChatGPT OAuth session expired.
`AUTH_API_KEY_INVALID`	API key is invalid, revoked, or out of quota.
`NETWORK_FAILED`	Network, proxy, VPN, or firewall failure.
`OAUTH_UNAVAILABLE`	GPT OAuth is not available.
`GRAPH_VERSION_CONFLICT`	Save made against a stale graph version.
`NODE_NOT_FOUND`	Node metadata was not found.
`GROK_REF_TOO_MANY`	Grok request included more than three total input images.
`GROK_MASK_UNSUPPORTED`	Grok edit was requested with a mask.
`INVALID_GROK_IMAGE_MODEL`	Grok request used an unsupported image model.
`GROK_RATE_LIMITED` · `GROK_AUTH_FAILED`	xAI rate-limit, or an auth failure on the xAI OAuth session or API key.
`GROK_SEARCH_TIMEOUT` · `GROK_PLANNER_TIMEOUT` · `GROK_IMAGE_TIMEOUT`	One Grok phase exceeded its timeout budget.
`GEMINI_API_KEY_MISSING`	Gemini API provider requested without a configured API key or Vertex AI credentials.
`INVALID_GEMINI_API_IMAGE_MODEL`	Gemini API model is not one of the valid values (nano-banana-2, nano-banana-pro).
`GENERATION_TIMEOUT`	Gemini API generation timed out (120s limit).

The full endpoint → CLI mapping, reference-image error codes, and style-sheet routes are in API.md.

Configuration