ima2-gen 3.8.2 → 3.9.0

package/bin/commands/gen.js

@@ -14,6 +14,7 @@ import { out, die, dieWithError, color, err, fail, json } from "../lib/output.js
 import { createCliRequestId, recoverGeneratedOutputs, formatRecoveryHint } from "../lib/recover-output.js";
 import { deriveProviderIds } from "../../lib/providers/derive.js";
 import { listProviders } from "../../lib/mcp/providerRegistry.js";
+import { BACKGROUND_PRESETS } from "../../lib/backgroundPresets.js";
 const VALID_MODES = new Set(["auto", "direct"]);
 const VALID_MODERATION = new Set(["auto", "low"]);
 const MAX_GENERATION_COUNT = Math.max(1, Math.trunc(Number(config.limits.maxGeneratedImages) || 24));
@@ -71,6 +72,9 @@ const HELP = `
                                             'auto' was removed; choose a lane explicitly
         --mode <auto|direct>                Core lanes only. Default: auto
         --moderation <auto|low>             Core lanes only. Default: low
+        --bg <chroma-green|white|black|transparent>
+                                            Core lanes only. 'transparent' asks GPT Image 2
+                                            for a real alpha channel (saved as PNG)
         --session <id>                      Core lanes only
         --reasoning-effort <none|low|medium|high|xhigh|max>
                                             Core lanes only
@@ -80,6 +84,7 @@ const HELP = `
     ima2 defaults set image oauth/gpt-5.6-luna
     ima2 gen "a shiba in space"
     ima2 gen "poster" --model oauth/luna --mode direct
+    ima2 gen "fox logo mark" --bg transparent -o logo.png
     ima2 gen "campaign still" --model runway/gen-4 --ref 1780000000000_abcd.png
 `;
 function failServer(jsonMode, error) {
@@ -216,6 +221,11 @@ function validateCoreFlags(args) {
         die(2, "--mode must be one of: auto, direct");
     if (!VALID_MODERATION.has(String(args.moderation)))
         die(2, "--moderation must be one of: auto, low");
+    // Fail locally on a typo instead of spending a round trip to learn the
+    // server rejected it.
+    if (args.bg && !BACKGROUND_PRESETS.includes(String(args.bg))) {
+        die(2, `--bg must be one of: ${BACKGROUND_PRESETS.join(", ")}`);
+    }
     const validReasoning = new Set(["none", "low", "medium", "high", "xhigh", "max"]);
     if (args["reasoning-effort"] && !validReasoning.has(String(args["reasoning-effort"])))
         die(2, "--reasoning-effort must be one of: none, low, medium, high, xhigh, max");

package/docs/migration/runtime-test-inventory.md

@@ -4,7 +4,7 @@ Generated by `npm run test:inventory` (script: `scripts/classify-tests.mjs`).
 
 _Tests considered "runtime-importing" if they import from `../lib/`, `../routes/`, `../bin/`, `../server`, or `../config`._
 
-Total: 372 (runtime: 169, contract: 203)
+Total: 376 (runtime: 172, contract: 204)
 
 ## Runtime-importing tests
 - `tests/agent-mode-auto-planner-contract.test.ts`
@@ -162,6 +162,9 @@ Total: 372 (runtime: 169, contract: 203)
 - `tests/style-sheet.test.ts`
 - `tests/terminal-jobs-restart.test.ts`
 - `tests/thumb-backfill.test.ts`
+- `tests/transparent-alpha-verification.test.ts`
+- `tests/transparent-background-contract.test.ts`
+- `tests/transparent-background-route.test.ts`
 - `tests/video-chroma-key.test.ts`
 - `tests/video-concat.test.ts`
 - `tests/video-history-item.test.ts`
@@ -370,6 +373,7 @@ Total: 372 (runtime: 169, contract: 203)
 - `tests/subprocess-deadline-contract.test.ts`
 - `tests/toast-stack-contract.test.js`
 - `tests/tools-cli-contract.test.ts`
+- `tests/transparent-background-ui-contract.test.js`
 - `tests/ui-error-code-contract.test.js`
 - `tests/ui-glyph-policy.test.ts`
 - `tests/video-continuity-ui-contract.test.js`

package/lib/alphaDecode.js

@@ -0,0 +1,18 @@
+/**
+ * sharp-backed raw decoder for alpha verification.
+ *
+ * Kept in its own module so lib/imageBackgroundParam.ts stays pure and
+ * synchronously testable: the verifier takes the decoder as a parameter, and
+ * tests can drive decode failures without stubbing sharp itself.
+ */
+import sharp from "sharp";
+export async function decodeRawForAlpha(buffer) {
+    const image = sharp(buffer);
+    const meta = await image.metadata();
+    if (!meta.hasAlpha) {
+        // No alpha channel at all: skip the raw decode, the answer is already known.
+        return { data: Buffer.alloc(0), channels: 0, hasAlpha: false };
+    }
+    const { data, info } = await image.ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+    return { data, channels: info.channels, hasAlpha: true };
+}

package/lib/atlasCloudImageAdapter.js

@@ -166,7 +166,10 @@ export async function generateViaAtlasCloud(prompt, ctx, options = {}) {
         prompt,
         size: options.size || "1024x1024",
         quality: options.quality || "medium",
-        output_format: options.outputFormat || "jpeg",
+        // JPEG cannot carry an alpha channel, so a transparent request must never
+        // fall back to it. gpt-image-2 accepts png/webp with transparency.
+        output_format: options.outputFormat || (options.background === "transparent" ? "png" : "jpeg"),
+        ...(options.background ? { background: options.background } : {}),
         enable_base64_output: false,
         enable_sync_mode: false,
     };
@@ -177,6 +180,8 @@ export async function generateViaAtlasCloud(prompt, ctx, options = {}) {
         model,
         size: body.size,
         refs: imageUrls.length,
+        background: options.background ?? null,
+        outputFormat: body.output_format,
     });
     const predictionId = await submitGeneration(apiKey, body, options.signal);
     const output = await pollOutputUrl(apiKey, predictionId, options.signal);

package/lib/backgroundPresets.js

@@ -4,8 +4,31 @@
  * The prompt suffix keeps generated backgrounds uniform enough for a
  * deterministic color key. Prompt assembly is server-owned so the UI, CLI,
  * and integrations share one contract (devlog/_plan/260715_asset_gen_mode/020).
+ *
+ * "transparent" is a different KIND of preset: the other three ask the model
+ * for a uniform matte that a later color-key pass removes, while transparent
+ * asks for a real alpha channel up front. GPT-Image-2 can do this now
+ * (devlog/_plan/260821_gpt_image2_transparent_background), so the transparent
+ * preset drives BOTH a prompt suffix and the image_generation `background`
+ * parameter. It is deliberately NOT color-keyable: there is no matte to key.
+ */
+export const BACKGROUND_PRESETS = ["chroma-green", "white", "black", "transparent"];
+/**
+ * Presets that produce a solid matte for downstream color keying. Transparent
+ * is excluded because it already carries alpha; keying it would be a no-op at
+ * best and would eat anti-aliased edges at worst.
+ */
+export const COLOR_KEYABLE_PRESETS = ["chroma-green", "white", "black"];
+export function isColorKeyablePreset(preset) {
+    return COLOR_KEYABLE_PRESETS.includes(preset);
+}
+/**
+ * Alpha-bearing presets cannot be encoded as JPEG. Callers that pick an output
+ * format must consult this before defaulting to a lossy opaque format.
  */
-export const BACKGROUND_PRESETS = ["chroma-green", "white", "black"];
+export function presetRequiresAlpha(preset) {
+    return preset === "transparent";
+}
 export function parseBackgroundPreset(raw) {
     if (raw === undefined || raw === null || raw === "")
         return { preset: null };
@@ -21,6 +44,7 @@ const SUFFIX_BY_PRESET = {
     "chroma-green": "The entire background must be a completely uniform solid chroma key green, perfectly flat like a professional green screen, with even studio lighting and no shadows, gradients, or texture on the background. The subject must have absolutely no green color cast, no green rim lighting, no green reflections, and no green spill from the background.",
     white: "The entire background must be a pure seamless white studio background, perfectly uniform, with even lighting and no shadows, gradients, or texture on the background.",
     black: "The entire background must be a pure seamless black studio background, perfectly uniform, with even lighting and no gradients or texture on the background.",
+    transparent: "The background must be fully transparent with a real alpha channel: an isolated cutout of the subject with no backdrop, no backdrop color, no ground plane, no drop shadow, and no checkerboard pattern drawn into the image. Keep edges cleanly anti-aliased against transparency, and preserve genuine partial transparency in glass, smoke, hair, and other translucent areas.",
 };
 export function backgroundPromptSuffix(preset, kind) {
     const base = SUFFIX_BY_PRESET[preset];
@@ -29,6 +53,9 @@ export function backgroundPromptSuffix(preset, kind) {
         : base;
 }
 export function backgroundPlannerConstraint(preset) {
+    if (preset === "transparent") {
+        return "Hard constraint: the final prompt MUST explicitly require a fully transparent background with a real alpha channel — an isolated cutout with no backdrop, no ground plane, and no drop shadow. Never drop, weaken, or reinterpret this requirement, and never substitute a solid color background for transparency.";
+    }
     const color = preset === "chroma-green" ? "chroma key green" : preset;
     return `Hard constraint: the final prompt MUST explicitly require a completely uniform solid ${color} background with even lighting and no shadows, gradients, or texture on the background.${preset === "chroma-green" ? " The subject must have no green color cast, green rim lighting, green reflections, or green spill from the background." : ""} Never drop, weaken, or reinterpret this requirement.`;
 }

package/lib/generatePipeline.js

@@ -27,6 +27,8 @@ import { errInfo } from "./errInfo.js";
 import { requireRuntimeContext } from "./runtimeContext.js";
 import { STORYBOARD_PREFIX } from "./storyboardPrefix.js";
 import { parseBackgroundPreset, backgroundPromptSuffix, backgroundPlannerConstraint } from "./backgroundPresets.js";
+import { resolveImageBackgroundParams, validateTransparentFormat, validateTransparentProvider, verifyBufferAlpha, makeTransparentResultError } from "./imageBackgroundParam.js";
+import { decodeRawForAlpha } from "./alphaDecode.js";
 import { validateModeration, imageFormatFromMime, upstreamErrorFields } from "./routeHelpers.js";
 import { publish } from "./eventBus.js";
 import { publishJobEvent } from "./ssePublish.js";
@@ -135,6 +137,15 @@ export async function runGeneratePipeline(req, res, ctx) {
             return fail(400, { error: backgroundParse.error, code: backgroundParse.code });
         }
         const backgroundPreset = backgroundParse.preset;
+        // `format` is the canonical request field (default "png"). Validating
+        // req.body.outputFormat instead would let format:"jpeg" slip past and
+        // then get transcoded to JPEG on save, destroying the alpha channel.
+        const formatConflict = validateTransparentFormat(backgroundPreset, format);
+        if (formatConflict) {
+            return fail(400, { error: formatConflict.error, code: formatConflict.code });
+        }
+        // Atlas Cloud talks to the gpt-image-2 API directly and accepts the
+        // forced value; the OAuth proxy does not (see lib/imageBackgroundParam.ts).
         const composerPrompt = normalizeComposerPrompt(req.body?.composerPrompt);
         const composerInsertedPrompts = normalizeComposerInsertedPrompts(req.body?.composerInsertedPrompts);
         const { quality, warnings: qualityWarnings } = normalizeOAuthParams({ provider, quality: rawQuality });
@@ -153,6 +164,23 @@ export async function runGeneratePipeline(req, res, ctx) {
         const effectiveSize = providerOptions.size;
         const webSearchEnabled = providerOptions.webSearchEnabled;
         const activeProvider = providerOptions.provider;
+        // Resolved AFTER provider resolution on purpose: the raw request `provider`
+        // defaults to "auto", so only `activeProvider` names the lane that will
+        // actually run. Atlas Cloud talks to the gpt-image-2 API directly and
+        // accepts a forced transparent background; the OAuth proxy rejects it
+        // (see lib/imageBackgroundParam.ts).
+        const backgroundParams = resolveImageBackgroundParams({
+            preset: backgroundPreset,
+            supportsForcedTransparent: activeProvider === "atlascloud",
+            requestedFormat: typeof format === "string" ? format : undefined,
+        });
+        // Grok/Gemini/Agy/MiniMax have no background parameter and their branches
+        // force JPEG, so a transparent request there would return an opaque image
+        // recorded as a cutout. Refuse instead of billing for a wrong result.
+        const providerConflict = validateTransparentProvider(backgroundPreset, activeProvider);
+        if (providerConflict) {
+            return fail(400, { error: providerConflict.error, code: providerConflict.code });
+        }
         // --- Element injection (after provider resolution) ---
         const rawElementIds = Array.isArray(req.body?.elementIds)
             ? req.body.elementIds.filter((id) => typeof id === "string" && id)
@@ -330,7 +358,13 @@ export async function runGeneratePipeline(req, res, ctx) {
         });
         const startTime = Date.now();
         const mimeMap = { png: "image/png", jpeg: "image/jpeg", webp: "image/webp" };
-        const effectiveFormat = activeProvider === "grok" || activeProvider === "agy" || activeProvider === "grok-api" || activeProvider === "gemini-api" || activeProvider === "atlascloud" || activeProvider === "minimax" ? "jpeg" : String(format);
+        const providerForcesJpeg = activeProvider === "grok" || activeProvider === "agy" || activeProvider === "grok-api" || activeProvider === "gemini-api" || activeProvider === "atlascloud" || activeProvider === "minimax";
+        // An alpha-bearing result must never be persisted through a lossy opaque
+        // format: embedImageMetadata re-encodes with sharp.toFormat(), so a JPEG
+        // here silently flattens the transparency we just asked for.
+        const effectiveFormat = backgroundParams
+            ? (backgroundParams.outputFormat ?? "png")
+            : (providerForcesJpeg ? "jpeg" : String(format));
         const mime = mimeMap[effectiveFormat] || "image/png";
         await mkdir(ctx.config.storage.generatedDir, { recursive: true });
         const grokDirectApiKey = activeProvider === "grok-api" ? ctx.xaiApiKey : undefined;
@@ -376,6 +410,8 @@ export async function runGeneratePipeline(req, res, ctx) {
                     signal: cancelController.signal,
                     requestId,
                     references: refCheck.refDetails,
+                    ...(backgroundParams ? { background: backgroundParams.background } : {}),
+                    ...(backgroundParams?.outputFormat ? { outputFormat: backgroundParams.outputFormat } : {}),
                 });
                 throwIfJobCanceled(requestId);
                 return r;
@@ -416,6 +452,8 @@ export async function runGeneratePipeline(req, res, ctx) {
                         webSearchEnabled,
                         signal: cancelController.signal,
                         allowPromptOnlyOAuthFallback: activeProvider !== "api",
+                        ...(backgroundParams ? { background: backgroundParams.background } : {}),
+                        ...(backgroundParams?.outputFormat ? { outputFormat: backgroundParams.outputFormat } : {}),
                     });
                     throwIfJobCanceled(requestId);
                     if (r.b64)
@@ -440,6 +478,22 @@ export async function runGeneratePipeline(req, res, ctx) {
         };
         const results = await Promise.allSettled(Array.from({ length: count }, generateOne));
         throwIfJobCanceled(requestId);
+        // Alpha is verified for EVERY result before anything is written. Doing it
+        // inside the write loop would let an earlier image land on disk before a
+        // later opaque one failed the batch, so the error would claim "nothing was
+        // saved" while an orphan file existed (adversarial review 260821 round 4).
+        if (backgroundParams) {
+            for (const r of results) {
+                if (r.status !== "fulfilled" || !r.value.b64)
+                    continue;
+                const verdict = await verifyBufferAlpha(Buffer.from(r.value.b64, "base64"), decodeRawForAlpha);
+                if (verdict.hasAlpha === false) {
+                    const { reason } = verdict;
+                    logEvent("generate", "transparent_result_opaque", { requestId, provider: activeProvider, reason });
+                    throw makeTransparentResultError(activeProvider, reason);
+                }
+            }
+        }
         const images = [];
         let totalUsage = null;
         let totalWebSearchCalls = 0;
@@ -448,10 +502,25 @@ export async function runGeneratePipeline(req, res, ctx) {
             if (r.status === "fulfilled" && r.value.b64) {
                 throwIfJobCanceled(requestId);
                 const valueWithMime = r.value;
-                const resultMime = activeProvider === "grok" || activeProvider === "agy" || activeProvider === "grok-api" || activeProvider === "gemini-api" || activeProvider === "atlascloud" || activeProvider === "minimax"
-                    ? (valueWithMime.mime || detectImageMimeFromB64(r.value.b64) || mime)
-                    : mime;
-                const resultFormat = activeProvider === "grok" || activeProvider === "agy" || activeProvider === "grok-api" || activeProvider === "gemini-api" || activeProvider === "atlascloud" || activeProvider === "minimax" ? imageFormatFromMime(resultMime) : effectiveFormat;
+                // When alpha was requested, trust the BYTES, never a provider-supplied
+                // Content-Type. Atlas reads its mime from the download response header
+                // (lib/atlasCloudImageAdapter.ts), and a transparent PNG mislabeled
+                // "image/jpeg" would otherwise be re-encoded to JPEG by
+                // embedImageMetadata's sharp.toFormat() and lose its alpha channel.
+                const providerReportsMime = activeProvider === "grok" || activeProvider === "agy" || activeProvider === "grok-api" || activeProvider === "gemini-api" || activeProvider === "atlascloud" || activeProvider === "minimax";
+                // Lazily decoded: only alpha requests always need the byte check, and
+                // the provider-mime path keeps its original short-circuit order.
+                const detectMime = () => detectImageMimeFromB64(r.value.b64);
+                const resultMime = backgroundParams
+                    ? (detectMime() || mime)
+                    : providerReportsMime
+                        ? (valueWithMime.mime || detectMime() || mime)
+                        : mime;
+                const resultFormat = backgroundParams
+                    ? imageFormatFromMime(resultMime)
+                    : providerReportsMime
+                        ? imageFormatFromMime(resultMime)
+                        : effectiveFormat;
                 const retryValue = r.value;
                 if (!firstRetryMeta && retryValue.retryKind) {
                     firstRetryMeta = {

package/lib/imageBackgroundParam.js

@@ -0,0 +1,108 @@
+export const VALID_BACKGROUND_VALUES = ["auto", "opaque", "transparent"];
+/** Formats that can carry an alpha channel. JPEG cannot. */
+export const ALPHA_CAPABLE_FORMATS = ["png", "webp"];
+export function isAlphaCapableFormat(value) {
+    return typeof value === "string" && ALPHA_CAPABLE_FORMATS.includes(value);
+}
+/**
+ * Image lanes that can actually return an alpha channel.
+ *
+ * Only the GPT image tool (OAuth/API) and the gpt-image-2 API surface expose a
+ * background parameter. Grok, Gemini, Agy, and MiniMax have no equivalent and
+ * their pipeline branches force JPEG, so a transparent request there would bill
+ * the user for an opaque image labeled as a cutout.
+ */
+export const ALPHA_CAPABLE_PROVIDERS = ["oauth", "api", "atlascloud"];
+export function providerSupportsTransparent(provider) {
+    return typeof provider === "string" && ALPHA_CAPABLE_PROVIDERS.includes(provider);
+}
+/** Refuse a transparent request on a lane that cannot deliver alpha. */
+export function validateTransparentProvider(preset, provider) {
+    if (preset !== "transparent")
+        return null;
+    if (providerSupportsTransparent(provider))
+        return null;
+    return {
+        error: `transparent backgrounds are not supported on the "${String(provider)}" lane (no alpha channel); use ${ALPHA_CAPABLE_PROVIDERS.join(", ")}, or pick a solid background and key it`,
+        code: "TRANSPARENT_PROVIDER_UNSUPPORTED",
+    };
+}
+/** Fast pre-check: JPEG can never carry alpha, so skip the decode entirely. */
+export function isJpegBuffer(buffer) {
+    return buffer.length >= 3 && buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff;
+}
+/**
+ * @param decode injected so tests can drive failure paths without stubbing sharp
+ */
+export async function verifyBufferAlpha(buffer, decode) {
+    if (isJpegBuffer(buffer))
+        return { hasAlpha: false, reason: "jpeg" };
+    let decoded;
+    try {
+        decoded = await decode(buffer);
+    }
+    catch {
+        // Unreadable bytes are not evidence of transparency.
+        return { hasAlpha: false, reason: "undetectable" };
+    }
+    if (!decoded.hasAlpha)
+        return { hasAlpha: false, reason: "no-alpha-channel" };
+    const { data, channels } = decoded;
+    if (channels < 4 || data.length < channels)
+        return { hasAlpha: false, reason: "no-alpha-channel" };
+    // One non-opaque pixel is enough: partial alpha (glass, hair, anti-aliased
+    // edges) counts as transparency just as much as a fully cut-out background.
+    for (let i = channels - 1; i < data.length; i += channels) {
+        if (data[i] < 255)
+            return { hasAlpha: true };
+    }
+    return { hasAlpha: false, reason: "fully-opaque" };
+}
+/** Operational error for a transparency request that came back opaque. */
+export function makeTransparentResultError(provider, reason) {
+    const detail = reason === "jpeg"
+        ? "the provider returned JPEG, which cannot carry an alpha channel"
+        : reason === "no-alpha-channel"
+            ? "the returned image has no alpha channel"
+            : reason === "fully-opaque"
+                ? "the returned image has an alpha channel but every pixel is fully opaque"
+                : "the returned image could not be decoded to verify transparency";
+    const err = new Error(`transparent background requested but ${detail} (lane: ${String(provider)}). Nothing was saved; retry, or use a solid background and key it.`);
+    err.status = 502;
+    err.code = "TRANSPARENT_RESULT_OPAQUE";
+    err.isOperational = true;
+    return err;
+}
+/**
+ * Resolve the tool parameters for a preset. Returns `null` when the preset
+ * implies no explicit background handling, so existing callers keep their
+ * current payload byte-for-byte.
+ */
+export function resolveImageBackgroundParams(input) {
+    if (input.preset !== "transparent")
+        return null;
+    const requested = input.requestedFormat;
+    // JPEG cannot hold alpha: silently honoring it would ship an opaque image
+    // while the UI claims transparency. Fall back to PNG instead.
+    const outputFormat = isAlphaCapableFormat(requested) ? requested : "png";
+    return {
+        background: input.supportsForcedTransparent ? "transparent" : "auto",
+        outputFormat,
+    };
+}
+/**
+ * Reject an explicit alpha-incapable format paired with a transparent
+ * background instead of quietly producing an opaque image.
+ */
+export function validateTransparentFormat(preset, requestedFormat) {
+    if (preset !== "transparent")
+        return null;
+    if (requestedFormat === undefined || requestedFormat === null || requestedFormat === "")
+        return null;
+    if (isAlphaCapableFormat(requestedFormat))
+        return null;
+    return {
+        error: `a transparent background requires an alpha-capable output format (${ALPHA_CAPABLE_FORMATS.join(", ")}); received "${String(requestedFormat)}"`,
+        code: "TRANSPARENT_FORMAT_CONFLICT",
+    };
+}

package/lib/promptImport/gptImageHints.js

@@ -39,7 +39,10 @@ export function extractGptImageHints(text) {
     const qualityHints = matches(value, QUALITY_HINTS);
     const warnings = [];
     if (/\btransparent|alpha channel|no background|cutout\b/i.test(value)) {
-        warnings.push("transparent-unsupported-gpt-image-2");
+        // gpt-image-2 supports real alpha since 2026-08-21; the remaining hazard is
+        // asking for it in bare prompt text instead of the background parameter,
+        // which can bake a fake checkerboard into an opaque image.
+        warnings.push("transparent-needs-background-param");
     }
     if (/\bexact text|small text|dense text|legal copy\b/i.test(value)) {
         warnings.push("text-rendering-sensitive");

package/lib/responsesFallback.js

@@ -3,7 +3,7 @@ import { imageToolChoice, tools } from "./responsesTools.js";
 import { emptyResponseError } from "./responsesErrors.js";
 import { GENERATE_DEVELOPER_PROMPT, GENERATE_NO_SEARCH_DEVELOPER_PROMPT, buildUserTextPrompt, } from "./oauthProxy.js";
 const MAX_RETRIES = 2;
-export async function retryPromptOnlyJsonImage({ postResponses, ctx, provider, prompt, mode, model, quality, size, moderation, requestId, signal, initial, referenceInputs = [], webSearchDroppedOnRetry, reasoningEffort, }) {
+export async function retryPromptOnlyJsonImage({ postResponses, ctx, provider, prompt, mode, model, quality, size, moderation, requestId, signal, initial, referenceInputs = [], webSearchDroppedOnRetry, reasoningEffort, background, outputFormat, }) {
     if (provider === "api")
         return null;
     const developerPrompt = webSearchDroppedOnRetry
@@ -62,7 +62,13 @@ export async function retryPromptOnlyJsonImage({ postResponses, ctx, provider, p
                         ...(plan.developerPromptDroppedOnRetry ? [] : [{ role: "developer", content: developerPrompt }]),
                         { role: "user", content: userContent },
                     ],
-                    tools: tools(false, { quality, size, moderation }),
+                    tools: tools(false, {
+                        quality,
+                        size,
+                        moderation,
+                        ...(background ? { background } : {}),
+                        ...(outputFormat ? { output_format: outputFormat } : {}),
+                    }),
                     tool_choice: imageToolChoice(true),
                     reasoning: { effort: reasoningEffort || "low" },
                     // OAuth/Codex proxy returns empty output[] for non-stream image requests; SSE required.

package/lib/responsesImageAdapter.js

@@ -211,7 +211,14 @@ export async function generateViaResponses(provider, prompt, quality, size, mode
     const ctx = requireRuntimeContext(ctxRaw);
     const model = options.model || ctx.config?.imageModels?.default || "gpt-5.6-luna";
     const webSearchEnabled = options.webSearchEnabled !== false && options.searchMode !== "off";
-    const requestTools = tools(webSearchEnabled, { quality, size, moderation, ...(options.partialImages ? { partial_images: options.partialImages } : {}) });
+    const requestTools = tools(webSearchEnabled, {
+        quality,
+        size,
+        moderation,
+        ...(options.partialImages ? { partial_images: options.partialImages } : {}),
+        ...(options.background ? { background: options.background } : {}),
+        ...(options.outputFormat ? { output_format: options.outputFormat } : {}),
+    });
     const toolChoice = imageToolChoice(options.forceImageToolChoice ?? ctx.config?.oauth?.forceImageToolChoice !== false);
     const toolChoiceKind = imageToolChoiceKind(toolChoice);
     const referenceInputs = references.map(normalizeRef);
@@ -258,6 +265,8 @@ export async function generateViaResponses(provider, prompt, quality, size, mode
                 referenceInputs,
                 webSearchDroppedOnRetry: webSearchEnabled,
                 ...(options.reasoningEffort !== undefined ? { reasoningEffort: options.reasoningEffort } : {}),
+                ...(options.background !== undefined ? { background: options.background } : {}),
+                ...(options.outputFormat !== undefined ? { outputFormat: options.outputFormat } : {}),
             });
             if (fallback)
                 return fallback;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ima2-gen",
-  "version": "3.8.2",
+  "version": "3.9.0",
   "packageManager": "npm@11.18.0",
   "description": "Local-first visual generation runtime and studio for people and coding agents, with reproducible image and video workflows across multiple providers.",
   "type": "module",
@@ -119,5 +119,5 @@
     "tsx": "^4.23.12",
     "typescript": "^5.9.3"
   },
-  "gitHead": "19b682ffdeaedb38fda2ee4be45726abb5f47390"
+  "gitHead": "3883482f57e132376dd7cd078a3f1e11791e94c0"
 }

package/routes/video.js

@@ -143,6 +143,13 @@ export function registerVideoRoutes(app, ctxRaw) {
                 return fail(400, backgroundParse.code, backgroundParse.error);
             }
             const backgroundPreset = backgroundParse.preset;
+            // "transparent" is an image-only preset: it depends on the GPT image
+            // tool's alpha-capable output, and Grok video has no such parameter.
+            // Accepting it here would append a cutout suffix that the model cannot
+            // honor and hand back an opaque clip that claims transparency.
+            if (backgroundPreset === "transparent") {
+                return fail(400, "TRANSPARENT_VIDEO_UNSUPPORTED", "transparent backgrounds are image-only; video generation has no alpha channel — use chroma-green and key the clip instead");
+            }
             const clientNodeId = typeof req.body?.clientNodeId === "string" ? req.body.clientNodeId : null;
             const topic = typeof req.body?.topic === "string" ? req.body.topic.trim() : "";
             if (provider !== "grok" && provider !== "grok-api")

package/skills/ima2/SKILL.md

@@ -263,8 +263,29 @@ discouraged.
 
 ### Cutout Assets and Background Strategy
 
-GPT Image 2 does not reliably produce true transparent (alpha) backgrounds.
-Use the solid-background-then-remove strategy for cutout assets:
+GPT Image 2 CAN produce true transparent (alpha) backgrounds. Prefer
+`--bg transparent` for cutout assets:
+
+```bash
+ima2 gen "a minimal geometric fox head logo mark, flat vector style" \
+  --bg transparent --quality high --mode direct -o logo.png
+```
+
+This asks for a real alpha channel instead of a matte you have to key out
+later. Verified on the live OAuth path 2026-08-21: 5/5 generations returned
+RGBA PNGs with all four corners at alpha 0 and 42-56% fully transparent
+pixels, including genuine PARTIAL alpha on glass and leaf veins. Saved as PNG;
+JPEG is refused because it cannot carry alpha.
+
+Mechanics worth knowing: ChatGPT-session models pin the image tool to the
+`gpt-image-2-codex` variant, which rejects a FORCED `background: "transparent"`
+with a 400. ima2 therefore sends `background: "auto"` and puts the cutout
+intent in the prompt, which is what actually produces the alpha. You do not
+need to hand-write that suffix — `--bg transparent` adds it.
+
+**Use the solid-background-then-remove strategy only when you need a matte**
+(chroma keying a video, compositing pipelines that expect green screen), or
+when a specific generation refuses to isolate the subject cleanly:
 
 **Generate on a pure solid background:**
 - **Black** (`#000000`) for reflective/metallic/glass subjects
@@ -288,8 +309,11 @@ ima2 gen "3D chrome splash on PURE SOLID BLACK background hex #000000. \
 - `ima2 edit asset.png --prompt "remove the background, keep only the subject"`
 - Programmatic: `sharp` / ImageMagick / `rembg`
 
-**Anti-pattern:** requesting "transparent background" or "PNG with alpha" in the
-prompt — the model often produces a fake checkerboard burned into the image.
+**Anti-pattern:** hand-writing "transparent background" into a prompt WITHOUT
+`--bg transparent`. Bare prompt wording sometimes yields a checkerboard
+pattern painted into an opaque image; the flag sends the real API parameter and
+the tuned suffix together. Always verify alpha rather than trusting the look of
+a preview: `sharp(file).metadata()` should report `channels: 4, hasAlpha: true`.
 
 ### Korean Text in Images
 

package/skills/ima2-front/references/asset-requirements.md

@@ -322,10 +322,25 @@ When generating images with Korean text:
 
 ### Asset Background Strategy (FE-ASSET-BG-01, DEFAULT)
 
-GPT Image 2 does not reliably produce true transparent (alpha) backgrounds.
-Requesting "transparent background" or "PNG with alpha" yields unpredictable
-results — sometimes a faint checkerboard pattern, sometimes a solid color
-pretending to be transparent. Use the solid-background-then-remove strategy:
+GPT Image 2 CAN produce true transparent (alpha) backgrounds. For cutout
+assets, reach for `--bg transparent` FIRST:
+
+```bash
+ima2 gen "3D render of a liquid chrome splash blob, organic starburst shape, \
+  mirror-polished surface with iridescent cyan and gold reflections." \
+  --bg transparent --model oauth/luna --quality high --mode direct -o chrome-splash.png
+```
+
+The flag sends the real API background parameter plus a tuned cutout suffix,
+and the asset is saved as PNG (JPEG is refused — it cannot carry alpha).
+Verified 2026-08-21 on the live OAuth path: 5/5 generations returned RGBA with
+corners at alpha 0 and 42-56% fully transparent pixels, preserving PARTIAL
+alpha on glass and foliage. Always confirm with `sharp(file).metadata()`
+(`channels: 4, hasAlpha: true`) rather than trusting a preview.
+
+**Still use the solid-background-then-remove strategy when** you specifically
+need a matte (chroma-key video pipelines, compositing tools that expect green
+screen), or when one generation refuses to isolate its subject cleanly:
 
 **Generation: pure solid background.**
 
@@ -393,10 +408,10 @@ ima2 gen "Flat illustration of a coffee cup with steam, centered. \
 **`ima2 gen` fallback:** same solid-background prompting strategy applies.
 No Canvas Mode available; use CSS blend modes or programmatic removal only.
 
-**Anti-pattern:** requesting "transparent background" or "PNG with alpha channel"
-directly in the prompt. The model will often produce a fake checkerboard pattern
-burned into the image, or ignore the request entirely. Always use the
-solid-background strategy above.
+**Anti-pattern:** hand-writing "transparent background" or "PNG with alpha
+channel" into a prompt WITHOUT `--bg transparent`. Bare wording can still bake
+a fake checkerboard into an opaque image; the flag pairs the API parameter with
+the tuned suffix. Verify the alpha channel instead of eyeballing the preview.
 
 ### Prompt Iteration
 

package/skills/ima2-uiux/SKILL.md

@@ -437,8 +437,17 @@ mockups is NOT a skip; it becomes generation input via `--ref`.
 When concept exploration (UX-CONCEPT-GEN-01) or image-first ism discovery
 (UX-IMAGE-FIRST-01) generates component/element mockups that need to float
 over arbitrary backgrounds — icons, 3D objects, product shots, stickers,
-UI chrome elements — use the cutout asset pipeline. GPT Image 2 cannot
-produce transparent backgrounds reliably; solid-bg-then-remove is mandatory.
+UI chrome elements — use the cutout asset pipeline. GPT Image 2 CAN produce
+real transparent backgrounds: pass `--bg transparent` and the asset comes back
+as an RGBA PNG, no keying pass required.
+
+```bash
+ima2 gen "3D render of [subject], [material], [composition]" \
+  --bg transparent --quality high --mode direct -o concept-01.png
+```
+
+Fall back to solid-bg-then-remove when you need a matte for a chroma-key
+pipeline, or when a subject refuses to isolate cleanly.
 
 **Cutout asset prompt template (concept pass):**
 
@@ -467,8 +476,10 @@ ima2 gen "[subject], centered. PURE SOLID background hex #[target]. \
 - Wrap in `isolation: isolate` container to prevent bleed
 - Programmatic: `sharp`, ImageMagick, `rembg`. Interactive: ima2 Canvas Mode.
 
-**Anti-pattern:** requesting "transparent background" or "PNG with alpha" in
-the prompt. The model produces fake checkerboard burned into the image.
+**Anti-pattern:** hand-writing "transparent background" or "PNG with alpha"
+into the prompt WITHOUT `--bg transparent` — bare wording can bake a fake
+checkerboard into an opaque image. Verify alpha (`channels: 4`) rather than
+trusting the preview.
 
 Full pipeline reference: `ima2-front/references/asset-requirements.md`
 § Asset Background Strategy (FE-ASSET-BG-01).