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 from a generated MP4 with Grok 4.3 vision. |
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. Recommended OpenAI model gpt-5.4; app default
gpt-5.4-mini. Grok image models: 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.
Video generation.
POST /api/video/generate (SSE) generates videos
via Grok. Models: grok-imagine-video and canonical
grok-imagine-video-1.5; grok-imagine-video-1.5-preview is accepted
only as a compatibility alias. Modes: text-to-video, image-to-video, reference-to-video
(2–7 refs). 1080p is available only for 1.5 image-to-video 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) 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. |
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). |
Health, storage & jobs
| Endpoint | Notes |
|---|---|
GET /api/health | Health check (ima2 ping). |
GET /api/providers | Provider availability and runtime ports (ima2 providers). |
GET /api/oauth/status | OAuth proxy status (ima2 oauth status). |
GET /api/grok/status | Bundled progrok status and xAI model probe (ima2 grok status). |
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 | Local OAuth proxy 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 auth failure through progrok. |
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.