This document lists the local HTTP API exposed by ima2 serve.

Base URL:

http://localhost:3333

Image generation supports OAuth, API-key, Grok, and Gemini (agy and gemini-api) providers.

• provider: "oauth" uses the local Codex OAuth proxy.
• provider: "api" uses the OpenAI Responses API with the hosted image_generation tool.
• provider: "grok" uses the bundled progrok xAI proxy. Classic, Node, and Agent generation run mandatory xAI Web Search through /v1/responses, then run a grok-4.3 planner call with a forced local generate_image function, then ima2 executes xAI /v1/images/generations. If reference images, a Node parent image, or an Agent current image are attached, the final step switches to xAI /v1/images/edits so image-to-image context is preserved.
• provider: "agy" spawns the Antigravity CLI (agy -p) to generate images via Google Gemini's default_api:generate_image tool. Model is nano-banana-2. Output is fixed at 1024×1024 JPEG. Max 3 reference images (i2i). No web search, quality, size, or mask controls. Multimode returns a single image. Video is unsupported (AGY_VIDEO_UNSUPPORTED).
• provider: "grok-api" uses a direct xAI API key instead of the bundled progrok OAuth proxy. Same pipeline as grok (Web Search → planner → /v1/images/generations), same aspect ratio and resolution options. Requires an xAI API key configured via the web UI key management or XAI_API_KEY env var. Also supports video generation.
• provider: "gemini-api" calls the Google Generative Language API directly (or Vertex AI with a service account JSON). Supports models nano-banana-2 (Gemini 3.1 Flash Image) and nano-banana-pro (Gemini 3 Pro Image). Supports variable aspect ratios (1:1 through 21:9) and four resolution tiers (512px, 1K, 2K, 4K) on both auth paths — the direct API path sends generation_config.response_format.image (snake_case) while the Vertex AI endpoint (aiplatform.googleapis.com) sends generationConfig.imageConfig (camelCase). With size: "auto" the image config is omitted entirely and the model decides ratio/size. Auth: GEMINI_API_KEY env var, web UI key management (/api/keys/gemini), or a Vertex AI service account JSON (VERTEX_SERVICE_ACCOUNT_JSON or /api/keys/vertex). When both Vertex credentials and an API key are configured, Vertex takes priority. The chosen auth mode (apikey or vertex) persists to ~/.ima2/config.json as geminiAuthMode and is restored on server startup. Per-model cost: nano-banana-2 (Flash): 512=$0.001, 1K=$0.003, 2K=$0.004, 4K=$0.006; nano-banana-pro: 1K=$0.007, 2K=$0.007, 4K=$0.013. No web search or mask controls.
• API-key generation covers classic generate, edit, mask-guided edit, multimode, and node generation.
• If provider: "api" is requested without an API key, routes fail before upstream with 401 and API_KEY_REQUIRED.
• Grok generation maps size to xAI aspect_ratio and resolution; it does not send an OpenAI-style size field upstream. Grok edit uses xAI /v1/images/edits; Grok mask edit remains unsupported and returns GROK_MASK_UNSUPPORTED.
• Mask edits are mask/selection guided edits, not pixel-perfect inpaint guarantees.

Grok video generation uses POST /api/video/generate (SSE). See the Video Generation section below for the full endpoint specification.

The Switch Account flow opens a browser verification URL. Once the user completes the device-code step, the server saves the new credentials (Grok: ~/.progrok/auth.json; Codex: via codex login --device-auth) and the session transitions to complete. This endpoint is surfaced as a Switch Account button in the Settings QuotaCard for Grok and Codex providers.

GET /api/storage/status returns a support-safe summary, not raw legacy path arrays by default.

{
  "ok": true,
  "data": {
    "generatedDirLabel": "~/.ima2/generated",
    "generatedCount": 0,
    "legacyCandidatesScanned": 18,
    "legacySourcesFound": 0,
    "legacyFilesFound": 0,
    "state": "not_found",
    "messageKind": "apology",
    "recoveryDocsPath": "docs/RECOVER_OLD_IMAGES.md",
    "doctorCommand": "ima2 doctor",
    "overrides": {
      "generatedDir": false,
      "configDir": false
    }
  }
}

Storage state values:

POST /api/storage/open-generated-dir opens the generated image folder on the machine running ima2 serve. If the browser is connected to a remote server, VM, container, WSL instance, or another computer on the network, this action targets that server machine, not necessarily the browser device.

In-flight logs and responses use requestId for correlation. Logs should not include raw prompts, reference data URLs, generated base64, tokens, cookies, auth headers, or raw upstream bodies.

Single persistent Server-Sent Events channel that carries progress for all async generation jobs. The browser UI opens one EventSource here instead of holding a per-request SSE connection for each job, avoiding browser per-origin connection limits.

Response: text/event-stream (persistent). Each frame uses standard SSE fields id, event, and data (JSON).

Connection limits: When active listeners reach 512, the server returns 503 with SSE_CAPACITY before opening the stream.

Heartbeat: Every 15 seconds the server writes a comment frame:

: ping

Replay: On reconnect, the server replays events from an in-memory ring buffer (size 2000) for IDs newer than lastEventId. Large image payloads (>1000 characters) are omitted from replay with _imageOmitted: true in the data payload. If the requested ID is older than the oldest buffered event, the server emits a replay-gap event before live fan-out:

Job routing: Every data payload includes jobId (same value as the job's requestId). Event bodies also carry requestId where applicable. Clients filter events by matching data.jobId or data.requestId to the job they started.

Event types (fan-out to all connected clients):

Example SSE frame:

id: 42
event: phase
data: {"requestId":"req_abc","jobId":"req_abc","phase":"streaming"}

POST /api/node/generate, POST /api/generate/multimode, and POST /api/video/generate support an async POST mode for clients that already hold GET /api/events:

{
  "async": true,
  "requestId": "req_xxx",
  "...": "other route fields"
}

Progress events are published on GET /api/events. The POST response returns immediately; clients must not expect SSE on the POST connection when async: true.

CLI and legacy clients omit async and keep the original behavior: per-request SSE on the same POST response (Accept: text/event-stream where applicable). The server dual-emits in that mode — it writes SSE to the POST response and also publishes the same events on GET /api/events.

Text-to-image and reference-guided root generation.

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

Supported quality values: low, medium, high.

Supported moderation values: auto, low.

When storyboard is true, the server prepends storyboard keyframe instructions so image generations maintain character and scene continuity for multi-shot video production.

Recommended model: gpt-5.4. Current app default: gpt-5.4-mini. gpt-5.5 is the strongest quality option when supported, but callers should expect higher quota pressure and possible Codex CLI/backend capability requirements.

When provider is "grok", supported models are grok-imagine-image and grok-imagine-image-quality. The server uses grok-4.3 as the search/planner model by default (IMA2_GROK_PLANNER_MODEL) and times the mandatory search and planner steps separately from the image call (IMA2_GROK_PLANNER_TIMEOUT_MS). For n > 1, search and planning run once and the planned prompt is reused for the image requests. Successful Grok classic generations report one mandatory web-search call in metadata.

If references are present on a Grok classic request, ima2 still performs the mandatory search and grok-4.3 planning phases. The planner receives the reference images as multimodal image_url inputs, and its forced generate_image.prompt argument is instructed to be English-only except for exact visible text requested by the user. The final image call then uses xAI /v1/images/edits with the same reference images instead of /v1/images/generations. This keeps image-to-image/reference context alive through the three-phase pipeline. xAI currently documents up to three source images for image editing, so Grok classic requests with more than three references return GROK_REF_TOO_MANY.

Grok size mapping:

Custom sizes are reduced to the closest xAI-supported aspect ratio and use 2k when the requested longest edge or pixel budget is closer to a 2K image.

Image edit / image-to-image generation.

The request includes a prompt and image payload. provider: "api" sends the prompt and image through the shared Responses image adapter. Optional masks are forwarded as mask guidance, not a pixel-perfect edit guarantee.

With provider: "grok", edit requests are sent to xAI /v1/images/edits through the bundled progrok proxy. Masked Grok edits are rejected before upstream with GROK_MASK_UNSUPPORTED.

Grok multimode currently sends each image request directly to xAI Images API with the mapped aspect_ratio/resolution; the mandatory search + planner pipeline is limited to classic /api/generate.

Node-mode generation and child edits.

Body fields:

{
  "parentNodeId": "optional-server-node-id",
  "prompt": "continue this image",
  "quality": "medium",
  "size": "1024x1024",
  "format": "png",
  "moderation": "low",
  "model": "grok-imagine-image",
  "references": [],
  "externalSrc": "optional-history-url",
  "sessionId": "session-id",
  "clientNodeId": "client-node-id",
  "requestId": "request-id",
  "provider": "grok"
}

When parentNodeId is present, the server loads the stored parent node image and uses the edit path. Node-local references are allowed on both root and child/edit nodes; for child/edit nodes the parent image is sent first, then references, then the text prompt.

With provider: "grok", Node Mode uses the same xAI search + grok-4.3 planner + Images API pipeline as classic generation. A parent node image, externalSrc, or extra references are passed to the planner and then to xAI /v1/images/edits; otherwise the final call uses /v1/images/generations. Grok Node requests are capped at three total input images, counting the parent/current image plus references, and return GROK_REF_TOO_MANY before upstream when that limit is exceeded. quality: "high" promotes the final image model to grok-imagine-image-quality.

The route can stream Server-Sent Events when the client sends Accept: text/event-stream. Possible events include phase, partial, done, and error. Alternatively, send { "async": true, "requestId": "req_xxx" } in the body to receive 202 { requestId } immediately and follow progress on GET /api/events (see Events section).

Grok Node SSE responses do not include Responses API partial image events because the xAI Images API call is synchronous JSON. They still emit phase and done/error events so the Node UI can use the same in-flight lifecycle.

Multi-image sequence generation. SSE-only on the POST response unless async mode is used.

{
  "prompt": "a story in four panels",
  "maxImages": 4,
  "quality": "medium",
  "size": "1024x1024",
  "format": "png",
  "moderation": "low",
  "model": "gpt-5.4",
  "provider": "oauth",
  "references": [],
  "requestId": "optional-client-id",
  "async": false
}

Send Accept: text/event-stream for per-request SSE on the POST connection. Or set "async": true with a client requestId to get 202 { requestId } and receive events on GET /api/events.

SSE events:

Fetch stored node metadata and asset URL.

Reference uploads are capped at 5 items. The frontend compresses large JPEG/PNG files before sending them. HEIC/HEIF files are rejected with a user-facing conversion hint.

Server-side validation may return these reference codes:

Generate a video via the Grok video provider. Returns Server-Sent Events on the POST connection, or accepts async mode ({ "async": true, "requestId": "req_xxx" }) for 202 { requestId } with progress on GET /api/events (see Events section).

{
  "prompt": "a cat playing piano",
  "provider": "grok",
  "model": "grok-imagine-video",
  "duration": 5,
  "resolution": "480p",
  "aspectRatio": "auto",
  "sourceImage": "<base64>",
  "referenceImages": ["<base64>", "<base64>"],
  "referenceFilenames": ["existing-file.png"],
  "continueFromVideo": "1780226256355_50252101.mp4",
  "continuityLineage": { "lineageId": "optional-client-hint", "entries": [] },
  "sessionId": "optional",
  "requestId": "optional-client-id"
}

Models: grok-imagine-video (default), grok-imagine-video-1.5-preview.

Mode is auto-detected from reference inputs:

Parameters:

Blank prompts return PROMPT_REQUIRED with a guidance string. The active prompt should describe visual flow, motion flow, sound/music/no-music, dialogue/no-dialogue, ending frame, and duration pacing. The video planner uses the selected duration as the full clip runtime and expands short requests into a production-level sequence with opening composition, connected motion/emotion change, and a stable ending frame suitable for continuation. For multi-character scenes, the planner identifies speakers by visual appearance (clothing, physique, position, props) rather than names, and attributes each dialogue line accordingly.

When continueFromVideo is present, the server treats the generated .mp4 sidecar as authoritative. Client continuityLineage cannot override it. The saved child sidecar includes videoContinuity, a branch-local max-4 stack using keep-start-plus-latest-3 retention.

videoContinuity shape:

{
  "lineageId": "lineage:parent",
  "parentFilename": "parent.mp4",
  "sourceFrame": "last",
  "maxEntries": 4,
  "retention": "keep-start-plus-latest-3",
  "entries": [
    {
      "id": "clip:parent.mp4",
      "ordinal": 1,
      "role": "start",
      "filename": "parent.mp4",
      "userPrompt": "original user prompt",
      "revisedPrompt": "planner prompt actually sent to Grok video",
      "createdAt": 1780300000000
    }
  ]
}

Entry role is start, ancestor, parent, or current. The first clip is kept as the start anchor; later generations keep only the latest three entries. lineageId uses the generated video basename without the .mp4 extension. This metadata is stored in the generated .mp4.json sidecar and returned in history rows and video done events; /generated/*.json remains private.

Grok prompt surfaces used by video APIs:

SSE events:

Video error codes:

Edit an existing video via Grok V2V. This is a blocking JSON endpoint that starts the xAI edit job, polls it, downloads the final MP4, and saves it as a generated video artifact.

{
  "prompt": "make it sunset",
  "videoUrl": "https://vidgen.x.ai/.../clip.mp4",
  "model": "grok-imagine-video"
}

videoUrl may be an HTTPS video URL, xAI file_id, data:video/* URL, or generated .mp4 filename. Generated-file inputs are restricted to real .mp4 files under the generated directory.

Extend a video from its last frame. This is a blocking JSON endpoint that starts the xAI extension job, polls it, downloads the combined output MP4, and saves it as a generated video artifact.

{
  "prompt": "camera pulls back",
  "videoUrl": "1780226256355_50252101.mp4",
  "duration": 6,
  "model": "grok-imagine-video"
}

duration must be an integer from 2 to 10 seconds. Edit and extension support grok-imagine-video only; grok-imagine-video-1.5-preview is not accepted for these endpoints.

Extract a PNG frame from a generated .mp4 file.

Analyze first and last frames from a generated .mp4 using Grok 4.3 image understanding. This does not upload the video as temporal video; it extracts two PNG frames and asks the vision model to infer likely motion.

{
  "videoUrl": "1780226256355_50252101.mp4"
}

Remote URLs and data: inputs are intentionally rejected to avoid server-side URL fetching through ffmpeg.

History rows can include node metadata such as sessionId, nodeId, clientNodeId, requestId, and refsCount.

PUT /api/sessions/:id/graph requires an If-Match header containing the current graph version.

Version mismatch returns GRAPH_VERSION_CONFLICT and the current version. This only means the client saved against a stale graph version; it is not proof that another browser tab changed the graph.

Graph save requests may include observability headers:

X-Ima2-Graph-Save-Id
X-Ima2-Graph-Save-Reason
X-Ima2-Tab-Id

Style-sheet extraction can require an API key/openai client. Image generation also supports provider: "api" through the shared Responses API image adapter when an API key is configured.

API key management endpoints for configuring provider credentials at runtime through the web UI or HTTP API.

Keys saved via PUT are stored in config.json and hot-updated in the runtime context (no server restart required). Keys loaded from environment variables (OPENAI_API_KEY, XAI_API_KEY, GEMINI_API_KEY, VERTEX_SERVICE_ACCOUNT_JSON) take precedence and are immutable through the API.

Thumbnails are also generated automatically on server startup for any media files that lack them.

Most server routes under /api/* have a CLI wrapper. The exception is Agent Mode (/api/agent/*), which is server + web-UI-only and has no ima2 subcommand. The prompt builder HTTP route (POST /api/prompt-builder/chat) is wrapped by ima2 prompt build. Use this table to find the command that calls a given endpoint. (See README.md "Client" section for full flag lists.)

Notes:

• ima2 history favorite and ima2 annotate … send X-Ima2-Browser-Id: cli-<sha1prefix> derived from the config dir, so CLI activity does not collide with browser sessions.
• ima2 session graph save performs a GET-then-PUT with If-Match: "<version>" to guard against GRAPH_VERSION_CONFLICT.
• ima2 history import and ima2 canvas-versions save/update send raw bytes with Content-Type: image/<png|jpeg|webp>; the SSE endpoints (multimode, node generate, video) use Accept: text/event-stream. The web UI instead uses GET /api/events plus async: true on POST routes.
• ima2 cardnews … checks runtimeConfig.features.cardNews before calling the gated endpoints; when disabled the CLI exits 2 with a clear message instead of producing a 404.

The server writes an advertisement file at:

~/.ima2/server.json

CLI commands such as ima2 ping, ima2 gen, and ima2 ls use this file unless --server or IMA2_SERVER is provided.

Current shape:

{
  "port": 3334,
  "url": "http://localhost:3334",
  "pid": 12345,
  "startedAt": 1777180000000,
  "version": "1.0.0",
  "backend": {
    "configuredPort": 3333,
    "actualPort": 3334,
    "url": "http://localhost:3334"
  },
  "oauth": {
    "configuredPort": 10531,
    "actualPort": 10532,
    "url": "http://127.0.0.1:10532",
    "status": "ready"
  }
}

Top-level port and url are kept for older CLI clients. New code should prefer backend.url.