Concepts

Providers & Models

The core registry includes OpenAI OAuth and API, Grok OAuth and API, Gemini/Antigravity CLI, direct Gemini API, AtlasCloud, MiniMax, NovelAI, and registered ComfyUI workflows. Runway and Higgsfield are separate MCP-backed integrations described below.

Provider paths

• provider: "oauth" — calls ChatGPT's Codex backend from the server with your ChatGPT session. A GPT-6 model plans the prompt and gpt-image-2 renders it. The default path; no API key needed.
• provider: "api" — calls the OpenAI Responses API with the hosted image_generation tool. Requires OPENAI_API_KEY.
• provider: "grok" — calls api.x.ai directly with the xAI OAuth session in ~/.progrok/auth.json, runs mandatory xAI Web Search and a planner pass (default grok-4.3, configurable in settings or via --planner-model), then calls xAI Images API. Grok 4.5 and 4.6 are selectable.
• provider: "grok-api" — same xAI pipeline as grok but uses a direct XAI_API_KEY instead of the OAuth session.
• provider: "gemini-api" — calls the Google Gemini image API directly. Supports two models (nano-banana-2 and nano-banana-pro), aspect ratio and resolution controls, and two auth modes: a GEMINI_API_KEY or a Vertex AI service-account JSON (VERTEX_SERVICE_ACCOUNT_JSON). When both are configured, Vertex AI takes priority unless overridden by the last-saved auth mode. Cost varies by model and resolution (see Gemini API section below).
• provider: "agy" — spawns the Antigravity CLI (agy -p) to generate via Google Gemini (nano-banana-2). Fixed 1024×1024 JPEG output, max 3 refs. Free (no token cost).
• provider: "atlascloud" — calls AtlasCloud with ATLASCLOUD_API_KEY for GPT Image 2 generation and edit, with up to 10 references.
• provider: "minimax" — calls MiniMax with MINIMAX_API_KEY for image-01 and image-01-live, with one reference.
• provider: "nai" — calls NovelAI with a persistent token. It is text-to-image only and exposes a dedicated negativePrompt plus native sampling controls; references and edits fail closed.
• provider: "comfy" — executes a registered ComfyUI image workflow; each workflow is a runtime-discovered model.

The core lanes cover Classic, Node, and Agent Mode. Agent Mode is web-UI only; Classic and Node also have CLI commands.

Per-request override

Generation commands use the explicit core lane IDs below. Where a command still accepts auto, it is a routing mode, not a provider lane.

Prompt Builder backend

Prompt Builder routing is independent from the current image provider. Settings > Providers offers Auto plus GPT OAuth, OpenAI API, Grok, and Grok API, along with a backend-scoped Builder model. Auto chooses the first ready backend in the order oauth → grok → api → grok-api. An explicit selection pins routing and returns a typed error, such as a missing-key error, instead of falling back. The via <backend> badge reports the answering backend.

Models

The GPT OAuth lane defaults to gpt-6-luna; the API-key lane keeps gpt-5.6-luna. Prompt Builder has a separate backend preference; when its backend resolves to GPT, Luna is the default GPT Builder model.

The app also exposes quality (low, medium, high) and moderation (auto, low) controls. Reasoning effort accepts none, low, medium, high, and xhigh.

Gemini API provider

The gemini-api provider calls Google's image generation API directly without the Antigravity CLI. It supports two models selectable in the UI or via --model:

• nano-banana-2 (default) — Gemini Flash; faster, lower cost.
• nano-banana-pro — Gemini Pro; higher quality, higher cost.

Auth modes. Configure either a Gemini API key (GEMINI_API_KEY env var or via the Settings UI) or a Google Cloud service-account JSON (VERTEX_SERVICE_ACCOUNT_JSON env var or via the Settings UI Vertex JSON input). When both are present the server respects the last-saved mode (geminiAuthMode: "apikey" or "vertex" in config), defaulting to Vertex when both are configured and no mode is saved.

Aspect ratio and resolution. The direct API path exposes 10 aspect ratios (1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9) and 4 resolution tiers (512px, 1K, 2K, 4K). Selections are mapped to exact pixel dimensions and passed as aspect_ratio and image_size protobuf enum values. The Vertex AI path ignores these controls — the Vertex endpoint does not accept the response_format field, so output defaults to 1K / 1:1 regardless.

Per-image cost estimates (based on output token counts × official rates):

The agy provider (Antigravity CLI) uses nano-banana-2 only, at fixed 1024×1024 with no resolution or aspect controls, and is estimated as free (no API token charge in the cost estimator).

Grok pipeline

Grok Classic, Node, and Agent requests run a three-step pipeline: mandatory xAI Web Search, planner pass (default grok-4.3, overridable via IMA2_GROK_PLANNER_MODEL, settings UI, or --planner-model on video commands) with an English final image prompt, then xAI image creation. Grok 4.3 remains available as a compatibility override. Text-only requests use /v1/images/generations; requests with reference images, a Node parent image, or an Agent current image use /v1/images/edits so image-to-image context is preserved. Grok accepts up to three total input images in this path.

ima2 maps OpenAI-style sizes to xAI aspect_ratio and resolution controls. Grok mask edit is not wired in this release and returns GROK_MASK_UNSUPPORTED.

Model and size pickers. The UI exposes a two-button image model picker ("Grok" / Fast = grok-imagine-image; "Grok+" / Best = grok-imagine-image-quality) and a size picker with native xAI aspect_ratio and resolution (1k/2k) values.

Billing and quota. When Grok is authorized, GET /api/quota returns a grok object with a monthly usage bar and a billing field (usedUsd / limitUsd) displayed as "$used/$limit" in the QuotaCard header (e.g. "$134.80/$1500.00").

Switch Account. The QuotaCard exposes a "Switch Account" button for Grok that starts a server-side xAI device-code flow (POST /api/auth/switch → GET /api/auth/switch/:sessionId). The button opens the verification URL in a new tab, displays the user code, and the server polls until complete. The same flow is available for Codex/GPT OAuth.

Grok video

Grok video generation defaults to canonical grok-imagine-video-1.5 ("Grok V1.5"). The base grok-imagine-video model remains available for Ref2V, edit, and extension. A two-button video model picker at the top of the video controls panel lets you switch between them. Three modes are auto-detected from reference count: text-to-video (0 refs), image-to-video (1 ref), and reference-to-video (2–14 refs; max 15s on 1.5, 10s on base). Controls include duration (1–15s), resolution (480p, 720p, and 1080p for 1.5 single-image/frame I2V), and aspect ratio. The old grok-imagine-video-1.5-preview value is accepted as a compatibility alias. 1.5 does not add Ref2V, V2V edit, or extension support, so those routes remain base-model only. Choose the planner model in video settings or pass --planner-model on CLI video commands. The endpoint POST /api/video/generate streams SSE events: planning → submitted → progress → done. From the CLI: ima2 video "prompt" --model grok/grok-imagine-video-1.5 --duration 5 --resolution 720p (or set a persistent target once with ima2 defaults set video grok/grok-imagine-video-1.5).

MCP lanes (Runway, Higgsfield)

Since 3.0.0 the CLI routes two additional lanes through remote MCP providers: runway (Gen-4/4.5, Veo 3.1, Seedance 2, Kling — image and video) and higgsfield (catalog-only until a paid plan unlocks execution). Inspect live lane status and per-model capabilities with ima2 models, then target them like any other lane: ima2 video "prompt" --model runway/veo-3.1 --duration 8. MCP jobs are asynchronous — the CLI submits to POST /api/mcp/generate and waits on the shared SSE event stream until the file lands in the gallery.

API-provider defaults

When the API path is used without explicit options, these defaults apply:

See Configuration for the full environment table.