ima2-gen 2.0.0 → 2.0.2

package/routes/video.js

@@ -2,7 +2,11 @@ import { mkdir, readFile, unlink, writeFile } from "fs/promises";
 import { atomicWriteJson } from "../lib/atomicWrite.js";
 import { join } from "path";
 import { randomBytes } from "crypto";
-import { startJob, finishJob, registerJobAbortController, isJobCanceled, setJobPhase } from "../lib/inflight.js";
+import { execFile } from "child_process";
+import { tmpdir } from "os";
+import { promisify } from "util";
+const execFileAsync = promisify(execFile);
+import { startJob, finishJob, registerJobAbortController, isJobCanceled, isStartJobFailure, setJobPhase, INFLIGHT_RETRY_AFTER_SECONDS } from "../lib/inflight.js";
 import { isGenerationCanceledError, makeGenerationCanceledError } from "../lib/generationCancel.js";
 import { logEvent, logError } from "../lib/logger.js";
 import { invalidateHistoryIndex } from "../lib/historyIndex.js";
@@ -13,10 +17,23 @@ import { extractGeneratedVideoFrameB64 } from "../lib/videoFrameExtract.js";
 import { normalizeGrokVideoModel, normalizeVideoResolution, normalizeVideoAspectRatio, normalizeVideoDuration, deriveVideoMode, clampVideoDuration, MAX_REF2V_REFERENCES, } from "../lib/imageModels.js";
 import { errInfo } from "../lib/errInfo.js";
 import { requireRuntimeContext } from "../lib/runtimeContext.js";
+import { generateVideoThumbnail } from "../lib/videoThumb.js";
+import { publish } from "../lib/eventBus.js";
+import { publishJobEvent } from "../lib/ssePublish.js";
 function sendSse(res, event, data) {
     res.write(`event: ${event}\n`);
     res.write(`data: ${JSON.stringify(data)}\n\n`);
 }
+function dualEmitVideo(res, requestId, event, data) {
+    if (!res.writableEnded)
+        sendSse(res, event, data);
+    if (event === "done") {
+        publishJobEvent(requestId, event, data);
+    }
+    else {
+        publish(requestId, event, data);
+    }
+}
 function toArray(v) {
     return Array.isArray(v) ? v : [];
 }
@@ -50,6 +67,32 @@ async function resolveSourceImage(ctx, sourceImage, sourceFilename) {
     }
     return { b64: null, filename: null };
 }
+const STORYBOARD_TRIM_SECONDS = "1.0";
+async function trimStoryboardLeadIn(buffer, requestId) {
+    const tmpIn = join(tmpdir(), `ima2_sb_trim_in_${requestId.replace(/[^a-zA-Z0-9_-]/g, "_")}.mp4`);
+    const tmpOut = join(tmpdir(), `ima2_sb_trim_out_${requestId.replace(/[^a-zA-Z0-9_-]/g, "_")}.mp4`);
+    try {
+        await writeFile(tmpIn, buffer);
+        logEvent("video", "storyboard:trim-start", { requestId, inputBytes: buffer.length, trimSeconds: STORYBOARD_TRIM_SECONDS });
+        await execFileAsync("ffmpeg", [
+            "-y", "-ss", STORYBOARD_TRIM_SECONDS, "-i", tmpIn,
+            "-c:v", "libx264", "-preset", "fast", "-crf", "18",
+            "-c:a", "aac", "-b:a", "128k",
+            "-avoid_negative_ts", "make_zero", tmpOut,
+        ], { timeout: 60_000 });
+        const trimmed = await readFile(tmpOut);
+        logEvent("video", "storyboard:trimmed", { requestId, originalBytes: buffer.length, trimmedBytes: trimmed.length, trimSeconds: STORYBOARD_TRIM_SECONDS });
+        return trimmed;
+    }
+    catch (trimError) {
+        logEvent("video", "storyboard:trim-exec-error", { requestId, error: trimError.message, stderr: trimError.stderr?.slice?.(0, 500) });
+        throw trimError;
+    }
+    finally {
+        await unlink(tmpIn).catch(() => { });
+        await unlink(tmpOut).catch(() => { });
+    }
+}
 export function registerVideoRoutes(app, ctxRaw) {
     const ctx = requireRuntimeContext(ctxRaw);
     app.post("/api/video/generate", async (req, res) => {
@@ -58,30 +101,39 @@ export function registerVideoRoutes(app, ctxRaw) {
             : typeof req.body?.clientRequestId === "string"
                 ? req.body.clientRequestId
                 : req.id;
+        const asyncMode = req.body?.async === true;
         let finishStatus = "completed";
         let finishHttpStatus = 200;
         let finishErrorCode;
         let finishMeta = {};
         let finishCanceled = false;
         const cancelController = new AbortController();
-        res.setHeader("Content-Type", "text/event-stream; charset=utf-8");
-        res.setHeader("Cache-Control", "no-cache, no-transform");
-        res.setHeader("Connection", "keep-alive");
-        res.flushHeaders?.();
+        if (!asyncMode) {
+            res.setHeader("Content-Type", "text/event-stream; charset=utf-8");
+            res.setHeader("Cache-Control", "no-cache, no-transform");
+            res.setHeader("Connection", "keep-alive");
+            res.flushHeaders?.();
+        }
         const fail = (status, code, error, extra = {}) => {
             const httpStatus = status ?? 500;
             finishStatus = "error";
             finishHttpStatus = httpStatus;
             finishErrorCode = code;
-            sendSse(res, "error", { error, code, status: httpStatus, requestId, ...extra });
+            const payload = { error, code, status: httpStatus, requestId, ...extra };
+            publish(requestId, "error", payload);
+            if (asyncMode && !res.headersSent) {
+                return res.status(httpStatus).json(payload);
+            }
+            if (!res.writableEnded)
+                sendSse(res, "error", payload);
         };
         try {
             const { prompt, provider = "grok", model: rawModel } = req.body || {};
             const sessionId = typeof req.body?.sessionId === "string" ? req.body.sessionId : null;
             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")
-                return fail(400, "VIDEO_PROVIDER_UNSUPPORTED", "video generation requires provider 'grok'");
+            if (provider !== "grok" && provider !== "grok-api")
+                return fail(400, provider === "agy" ? "AGY_VIDEO_UNSUPPORTED" : "VIDEO_PROVIDER_UNSUPPORTED", provider === "agy" ? "Gemini (agy) does not support video generation" : "video generation requires provider 'grok' or 'grok-api'");
             const storyboardActive = req.body?.storyboard === true;
             const storyboardPrefix = storyboardActive
                 ? [
@@ -98,6 +150,14 @@ export function registerVideoRoutes(app, ctxRaw) {
                     "- Lock lighting direction, color palette, environment, and style.",
                     "- Describe ONLY what changes: action, camera movement, dialogue, sound.",
                     "",
+                    "STORYBOARD IMAGE SOURCE RULE (HIGHEST PRIORITY — OVERRIDES ALL OTHER RULES):",
+                    "- The source image is a 3x3 storyboard grid. Panel 1 (top-left) is a BLACK LEAD-IN FRAME — it contains no scene content.",
+                    "- The video starts from black (Panel 1), then transitions into the action scene from Panel 2.",
+                    "- Panels 2-9 contain the action sequence. Describe and animate only Panels 2-9.",
+                    "- Start your rewritten prompt with: 'Fading in from black into the full-screen scene of [Panel 2 description],' — the server auto-trims the black lead-in.",
+                    "- The storyboard grid must NEVER appear as a visible grid in any frame. The output is a single continuous cinematic clip.",
+                    "- Do NOT reference Panel 1 in the action description — it is only a technical black frame.",
+                    "",
                     "PROMPT STRUCTURE (layered caption format):",
                     "- Shot foundation: type + camera motion (dolly, pan, tracking, crane, static).",
                     "- Subject: action with intensity modifiers (crashes violently, drifts gently).",
@@ -164,25 +224,36 @@ export function registerVideoRoutes(app, ctxRaw) {
             }
             if (resolved.length > MAX_REF2V_REFERENCES)
                 return fail(400, "GROK_VIDEO_REF_TOO_MANY", `at most ${MAX_REF2V_REFERENCES} reference images`);
-            const mode = deriveVideoMode(resolved.length);
+            const incomingProviderUrl = typeof req.body?.providerUrl === "string" && req.body.providerUrl.startsWith("http") ? req.body.providerUrl : null;
+            const mode = incomingProviderUrl ? "image-to-video" : deriveVideoMode(resolved.length);
             const duration = clampVideoDuration(durationCheck.duration, mode);
             const referenceImages = mode === "reference-to-video" ? resolved.map((r) => r.b64) : undefined;
-            const sourceB64 = mode === "image-to-video" ? resolved[0]?.b64 : undefined;
+            const sourceB64 = incomingProviderUrl || (mode === "image-to-video" ? resolved[0]?.b64 : undefined);
             const sourceFilename = resolved[0]?.filename ?? null;
-            startJob({
+            const started = startJob({
                 requestId,
                 kind: "video",
                 prompt: activePrompt,
                 meta: { kind: "video", sessionId, clientNodeId, model: modelCheck.model, mode, duration, resolution: resolutionCheck.resolution },
             });
+            if (started && isStartJobFailure(started)) {
+                if (started.code === "TOO_MANY_JOBS") {
+                    res.setHeader("Retry-After", String(INFLIGHT_RETRY_AFTER_SECONDS));
+                }
+                return fail(started.code === "TOO_MANY_JOBS" ? 429 : 409, started.code, started.code === "TOO_MANY_JOBS"
+                    ? "Too many concurrent generation jobs"
+                    : "Request ID already in use");
+            }
             registerJobAbortController(requestId, cancelController);
+            if (asyncMode)
+                res.status(202).json({ requestId });
             await mkdir(ctx.config.storage.generatedDir, { recursive: true });
             logEvent("video", "request", { requestId, mode, duration, resolution: resolutionCheck.resolution, aspectRatio: aspectCheck.aspectRatio });
             const startTime = Date.now();
             const onEvent = (ev) => {
                 if (ev.phase === "submitted") {
                     setJobPhase(requestId, "streaming");
-                    sendSse(res, "submitted", {
+                    dualEmitVideo(res, requestId, "submitted", {
                         requestId,
                         xaiVideoRequestId: ev.xaiVideoRequestId,
                         requestedModel: ev.requestedModel,
@@ -191,11 +262,11 @@ export function registerVideoRoutes(app, ctxRaw) {
                     });
                 }
                 else if (ev.phase === "progress") {
-                    sendSse(res, "progress", { requestId, progress: typeof ev.progress === "number" ? ev.progress / 100 : null, stalled: Boolean(ev.stalled) });
+                    dualEmitVideo(res, requestId, "progress", { requestId, progress: typeof ev.progress === "number" ? ev.progress / 100 : null, stalled: Boolean(ev.stalled) });
                 }
                 else {
                     setJobPhase(requestId, "planning");
-                    sendSse(res, "planning", { requestId });
+                    dualEmitVideo(res, requestId, "planning", { requestId });
                 }
             };
             // Build prompt with series chain context
@@ -205,6 +276,7 @@ export function registerVideoRoutes(app, ctxRaw) {
                 : activePrompt;
             const effectivePrompt = storyboardPrefix + basePrompt;
             const plannerModel = typeof req.body?.plannerModel === "string" ? req.body.plannerModel.trim() : undefined;
+            const directApiKey = provider === "grok-api" ? ctx.xaiApiKey : undefined;
             const result = await generateVideoViaGrok(effectivePrompt, ctx, {
                 model: modelCheck.model,
                 mode,
@@ -217,7 +289,9 @@ export function registerVideoRoutes(app, ctxRaw) {
                 requestId,
                 continuityLineage: parentLineage,
                 plannerModel: plannerModel || undefined,
+                directApiKey,
                 onEvent,
+                storyboardActive,
             });
             const rand = randomBytes(ctx.config.ids.generatedHexBytes).toString("hex");
             const filename = `${Date.now()}_${rand}.mp4`;
@@ -231,13 +305,14 @@ export function registerVideoRoutes(app, ctxRaw) {
             const meta = {
                 kind: "video",
                 mediaType: "video",
+                providerUrl: result.url,
                 requestId,
                 sessionId,
                 clientNodeId,
                 prompt: activePrompt,
                 userPrompt: activePrompt,
                 revisedPrompt: result.revisedPrompt,
-                provider: "grok",
+                provider,
                 model: result.effectiveModel,
                 requestedModel: result.requestedModel,
                 effectiveModel: result.effectiveModel,
@@ -260,14 +335,25 @@ export function registerVideoRoutes(app, ctxRaw) {
                 ...(topic ? { videoSeries: { topic, chainIndex: chain.length } } : {}),
                 ...(storyboardActive ? { storyboard: true } : {}),
             };
-            await saveGeneratedVideoArtifact(ctx, filename, result.videoBuffer, meta);
+            let finalBuffer = result.videoBuffer;
+            if (storyboardActive) {
+                try {
+                    finalBuffer = await trimStoryboardLeadIn(result.videoBuffer, requestId);
+                }
+                catch (trimErr) {
+                    logEvent("video", "storyboard:trim-failed", { requestId, error: trimErr.message });
+                }
+            }
+            await saveGeneratedVideoArtifact(ctx, filename, finalBuffer, meta);
+            generateVideoThumbnail(join(ctx.config.storage.generatedDir, filename)).catch(() => { });
             invalidateHistoryIndex();
             finishMeta = { filename, xaiVideoRequestId: result.xaiVideoRequestId };
             logEvent("video", "saved", { requestId, filename, bytes: result.videoBuffer.length, elapsedMs: Date.now() - startTime });
-            sendSse(res, "done", {
+            dualEmitVideo(res, requestId, "done", {
                 requestId,
                 filename,
                 url: `/generated/${encodeURIComponent(filename)}`,
+                providerUrl: result.url,
                 mediaType: "video",
                 revisedPrompt: result.revisedPrompt,
                 elapsed,
@@ -287,19 +373,20 @@ export function registerVideoRoutes(app, ctxRaw) {
                 finishCanceled = true;
                 finishHttpStatus = canceled.status;
                 finishErrorCode = canceled.code;
-                sendSse(res, "error", { error: canceled.message, code: canceled.code, status: canceled.status, requestId });
+                dualEmitVideo(res, requestId, "error", { error: canceled.message, code: canceled.code, status: canceled.status, requestId });
             }
             else {
                 finishStatus = "error";
                 finishHttpStatus = err.status || 500;
                 finishErrorCode = err.code || "GROK_VIDEO_FAILED";
                 logError("video", "error", err.raw, { requestId, code: finishErrorCode });
-                sendSse(res, "error", { error: err.message, code: finishErrorCode, status: finishHttpStatus, requestId });
+                dualEmitVideo(res, requestId, "error", { error: err.message, code: finishErrorCode, status: finishHttpStatus, requestId });
             }
         }
         finally {
             finishJob(requestId, { canceled: finishCanceled, status: finishStatus, httpStatus: finishHttpStatus, errorCode: finishErrorCode, meta: finishMeta });
-            res.end();
+            if (!res.writableEnded)
+                res.end();
         }
     });
 }

package/server.js

@@ -42,6 +42,92 @@ async function loadApiKey() {
     }
     return { apiKey: null, apiKeySource: "none" };
 }
+async function loadXaiApiKey() {
+    if (process.env.XAI_API_KEY) {
+        return { apiKey: process.env.XAI_API_KEY, apiKeySource: "env" };
+    }
+    const candidates = [
+        config.storage.configFile,
+        join(rootDir, ".ima2", "config.json"),
+    ];
+    for (const cfgPath of candidates) {
+        if (!existsSync(cfgPath))
+            continue;
+        try {
+            const cfg = JSON.parse(await readFile(cfgPath, "utf-8"));
+            if (cfg.xaiApiKey)
+                return { apiKey: cfg.xaiApiKey, apiKeySource: "config" };
+        }
+        catch { }
+    }
+    return { apiKey: null, apiKeySource: "none" };
+}
+async function loadGeminiApiKey() {
+    if (process.env.GEMINI_API_KEY) {
+        return { apiKey: process.env.GEMINI_API_KEY, apiKeySource: "env" };
+    }
+    const candidates = [
+        config.storage.configFile,
+        join(rootDir, ".ima2", "config.json"),
+    ];
+    for (const cfgPath of candidates) {
+        if (!existsSync(cfgPath))
+            continue;
+        try {
+            const cfg = JSON.parse(await readFile(cfgPath, "utf-8"));
+            if (cfg.geminiApiKey)
+                return { apiKey: cfg.geminiApiKey, apiKeySource: "config" };
+        }
+        catch { }
+    }
+    return { apiKey: null, apiKeySource: "none" };
+}
+async function loadVertexKey() {
+    const envJson = process.env.VERTEX_SERVICE_ACCOUNT_JSON;
+    if (envJson) {
+        try {
+            const parsed = JSON.parse(envJson);
+            return { json: envJson, projectId: parsed.project_id || null, source: "env" };
+        }
+        catch {
+            return { json: null, projectId: null, source: "none" };
+        }
+    }
+    const candidates = [
+        config.storage.configFile,
+        join(rootDir, ".ima2", "config.json"),
+    ];
+    for (const cfgPath of candidates) {
+        if (!existsSync(cfgPath))
+            continue;
+        try {
+            const cfg = JSON.parse(await readFile(cfgPath, "utf-8"));
+            if (cfg.vertexServiceAccountJson) {
+                const parsed = JSON.parse(cfg.vertexServiceAccountJson);
+                return { json: cfg.vertexServiceAccountJson, projectId: parsed.project_id || null, source: "config" };
+            }
+        }
+        catch { }
+    }
+    return { json: null, projectId: null, source: "none" };
+}
+async function loadGeminiAuthMode() {
+    const candidates = [
+        config.storage.configFile,
+        join(rootDir, ".ima2", "config.json"),
+    ];
+    for (const cfgPath of candidates) {
+        if (!existsSync(cfgPath))
+            continue;
+        try {
+            const cfg = JSON.parse(await readFile(cfgPath, "utf-8"));
+            if (cfg.geminiAuthMode === "vertex" || cfg.geminiAuthMode === "apikey")
+                return cfg.geminiAuthMode;
+        }
+        catch { }
+    }
+    return undefined;
+}
 async function createOpenAI(apiKey) {
     if (!apiKey)
         return null;
@@ -143,6 +229,10 @@ export async function createRuntimeContext(overrides = {}) {
             apiKeySource: overrides.apiKeySource ?? (overrides.apiKey ? "env" : "none"),
         }
         : await loadApiKey();
+    const loadedXaiKey = await loadXaiApiKey();
+    const loadedGeminiKey = await loadGeminiApiKey();
+    const loadedVertexKey = await loadVertexKey();
+    const geminiAuthMode = await loadGeminiAuthMode();
     const apiKey = loadedKey.apiKey;
     const openai = overrides.openai ?? await createOpenAI(apiKey);
     const oauthPort = config.oauth.proxyPort;
@@ -170,6 +260,16 @@ export async function createRuntimeContext(overrides = {}) {
         openai,
         startedAt: overrides.startedAt ?? Date.now(),
         packageVersion: overrides.packageVersion ?? readPackageVersion(),
+        xaiApiKey: loadedXaiKey.apiKey ?? undefined,
+        xaiApiKeySource: loadedXaiKey.apiKeySource,
+        hasXaiApiKey: !!loadedXaiKey.apiKey,
+        geminiApiKey: loadedGeminiKey.apiKey ?? undefined,
+        geminiApiKeySource: loadedGeminiKey.apiKeySource,
+        hasGeminiApiKey: !!loadedGeminiKey.apiKey,
+        vertexServiceAccountJson: loadedVertexKey.json ?? undefined,
+        vertexProjectId: loadedVertexKey.projectId ?? undefined,
+        hasVertexKey: !!loadedVertexKey.json,
+        geminiAuthMode,
         oauthReadyPromise: oauthReadyPromise,
         markGrokProxyPort: ({ url, port } = {}) => {
             if (port)
@@ -194,6 +294,13 @@ export async function createRuntimeContext(overrides = {}) {
     };
     if (!config.oauth.autoStart)
         ctx.markOAuthReady({ url: ctx.oauthUrl, port: ctx.oauthPort });
+    if (loadedVertexKey.json) {
+        try {
+            const { initVertexAuth } = await import("./lib/vertexAuth.js");
+            initVertexAuth(loadedVertexKey.json);
+        }
+        catch { /* vertex init failure is non-fatal */ }
+    }
     return ctx;
 }
 export async function startServer(overrides = {}) {
@@ -283,6 +390,22 @@ export async function startServer(overrides = {}) {
         const err = errInfo(e);
         console.error("[db] bootstrap failed:", err.message);
     }
+    // Background thumbnail backfill for updated users (recursive — covers video
+    // series subdirectories like continuous_*/clip_NN.mp4, not just top level).
+    (async () => {
+        try {
+            const { backfillThumbnails } = await import("./lib/thumbBackfill.js");
+            const r = await backfillThumbnails(ctx.config.storage.generatedDir);
+            if (r.created > 0) {
+                console.log(`[thumbs] backfill: ${r.created} created, ${r.skipped} skipped, ${r.failed} failed (${r.total} media files)`);
+                const { invalidateHistoryIndex } = await import("./lib/historyIndex.js");
+                invalidateHistoryIndex();
+            }
+        }
+        catch (e) {
+            console.warn("[thumbs] backfill failed:", e instanceof Error ? e.message : e);
+        }
+    })();
     server.on("error", (err) => {
         console.error("[server] Failed to start:", err?.message || err);
         process.exit(1);

package/skills/ima2/SKILL.md

@@ -143,13 +143,22 @@ Do not use positional edit prompts. `ima2 edit` requires `--prompt`.
 
 ## Parallel Generation
 
-There is no `--parallel` flag. For CLI-controlled parallel work, start several normal jobs:
+There is no `--parallel` flag. For multiple candidates from the same prompt,
+prefer one server-side batch request:
 
 ```bash
-ima2 gen "variation 1" --quality high
-ima2 gen "variation 2" --quality high
-ima2 gen "variation 3" --quality high
-ima2 gen "variation 4" --quality high
+ima2 gen "four poster candidates" -n 4 -d ./out --quality high
+ima2 multimode "four different poster directions" --max-images 4
+```
+
+For truly different prompts, independent CLI jobs can run concurrently against
+the same server. Capture request IDs with JSON output, then monitor or cancel:
+
+```bash
+ima2 gen "variation 1" --quality high --json
+ima2 gen "variation 2" --quality high --json
+ima2 ps --json
+ima2 cancel <requestId>
 ```
 
 Treat `capabilities.limits.maxParallel` as advisory client-side queue guidance only.
@@ -402,6 +411,12 @@ Generate a high-quality still image first, then animate it. This produces better
 
 **Critical rule for i2v**: Compose ALL characters and the environment together in ONE image. Do NOT use individual portrait refs for i2v — the video model needs a single composed scene to animate from.
 
+**Keyframe image provider rule (MANDATORY)**:
+- **Primary**: GPT Image 2 (OpenAI, `provider: oauth`) with `quality: high`, maximum resolution matching the target video aspect ratio. For 16:9 video use `1792x1024`. For 1:1 use `1024x1024`. For 9:16 use `1024x1792`.
+- **Fallback**: Grok (`provider: grok`, model `grok-imagine-image-quality`). Only aspect ratio must match — resolution does not matter because i2v accepts any resolution source image and internally rescales.
+- GPT Image 2 produces superior keyframes: better lighting coherence, character consistency, and fine detail that survives i2v animation. Always try GPT first.
+- The i2v model internally rescales the source image to its native resolution regardless of input size, so there is no benefit to upscaling a Grok fallback image.
+
 **ref2v vs i2v decision**:
 
 | Scenario | Use | Why |
@@ -412,8 +427,12 @@ Generate a high-quality still image first, then animate it. This produces better
 
 ```bash
 # Multi-character scene: compose BOTH characters in one image first
+# Primary: GPT Image 2 at high quality, max resolution, aspect ratio matching 16:9 video
 ima2 gen "cinematic wide shot of Bruce Lee in yellow tracksuit facing Elon Musk in dark gi, underground fight arena, dramatic lighting, 16:9" --quality high --size 1792x1024 -o scene.png
 
+# Fallback if GPT fails: Grok quality model, match aspect ratio only
+# ima2 gen "same prompt" --provider grok --model grok-imagine-image-quality --size 1824x1024 -o scene.png
+
 # Then animate from the composed scene
 ima2 video "Bruce throws a rapid jeet kune do combination" --ref scene.png --duration 10 --resolution 720p --aspect-ratio 16:9
 ```
@@ -438,30 +457,88 @@ ima2 video "close-up of rain drops on a neon sign reflection" \
 
 The planner receives previous prompts from the same topic as continuity context. This is best-effort prompt guidance, not a guarantee that subjects, palette, or style will remain identical. For branch-local continuation, use `ima2 video continue` instead.
 
-#### Storyboard-to-Video Chaining (image→video→lastframe loop)
+#### Storyboard-to-Video Chaining (9-panel storyboard → i2v loop)
+
+The highest-quality video production workflow. Since Grok i2v accepts only **one image input**, pack the entire action sequence into a single 3×3 (9-panel) storyboard grid image. The i2v model reads the panels as a visual script and animates the progression.
+
+**Full workflow**:
+
+```
+keyframe image (GPT high)
+    → GPT i2i with reference → 9-panel storyboard grid
+        → Grok i2v (reads panels, animates sequence)
+            → extract last frame
+                → GPT i2i with last frame → next 9-panel storyboard
+                    → Grok i2v
+                        → repeat
+```
+
+**Step 1 — Opening keyframe** (GPT Image 2, `quality: high`, max resolution matching target aspect ratio):
+
+```bash
+ima2 gen "cinematic wide shot of two fighters in a dojo, dramatic lighting" \
+  --quality high --size 1792x1024 --storyboard
+```
+
+Fallback: Grok `grok-imagine-image-quality`, match aspect ratio only — resolution does not matter because i2v internally rescales.
 
-For maximum control, generate each keyframe as a GPT Image 2 still, animate it, extract the last frame, and use it as the anchor for the next keyframe:
+**Step 2 — 9-panel storyboard grid** (GPT Image 2 with keyframe as reference):
 
 ```bash
-# Step 1: Generate composed keyframe
-ima2 gen "Bruce and Elon face off in underground arena, dramatic lighting" --quality high --size 1792x1024 -o frame1.png
+# Use the keyframe as reference, prompt describes 9 sequential panels
+ima2 gen "Using this scene as reference, create a 3x3 storyboard grid (9 panels, thin black borders) showing a 15-second action sequence. Panel 1 (0s): ... Panel 2 (2s): ... Panel 9 (15s): ... Maintain identical character designs across all panels." \
+  --ref keyframe.png --quality high --size 1024x1024
+```
 
-# Step 2: Animate (i2v, 10s clip)
-ima2 video "Bruce throws JKD combination" --ref frame1.png --duration 10 --resolution 720p
+**9-panel storyboard rules**:
+- Grid layout: 3×3, thin black borders between panels
+- Read order: left-to-right, top-to-bottom (panels 1-9)
+- **Panel 1 (top-left) MUST be solid black** — this is a lead-in frame, not content. The i2v model starts from Panel 1's pixels; a black frame ensures the video begins with a clean fade-in instead of showing the grid. The 1-second black lead-in is auto-trimmed by the server.
+- Panels 2-9 carry the action sequence (8 key moments with timestamps)
+- Character designs MUST be identical across all panels
+- Vary camera angle per panel for dynamic energy
+- Each panel should look like a film still, not a sketch
+- Do NOT add timestamp labels or text to panels — they burn into the video
+- Square format (1024×1024) works best — i2v rescales internally
 
-# Step 3: Continue from last frame (sequential, not parallel)
-CLIP1=$(ima2 ls -n 1 --json | jq -r '.items[0].filename')
-ima2 video continue "Elon counterattacks with haymaker" --video "$CLIP1" --duration 10
+**Step 3 — Animate storyboard via i2v**:
 
-# Repeat: each clip's last frame seeds the next
+```bash
+ima2 video "This is a 9-panel storyboard. Animate the full sequence as one continuous 15-second clip following panels left-to-right, top-to-bottom. Panel 1: ... Panel 9: ... Sound: [describe music, SFX, dialogue]. Camera: [describe movement per beat]." \
+  --ref storyboard.png --duration 15 --resolution 720p --model grok-imagine-video-1.5-preview
 ```
 
-**GPT Image 2 storyboard prompting rules** (from production research):
-- Copy character visual descriptions **verbatim** across all frame prompts — do not paraphrase
-- First frame is the **anchor**: all subsequent frames inherit its composition, lighting, and character designs
-- Change **one variable per step**: shot scale, action, or camera — keep everything else constant
-- Use the `images.edit` API with `image[]` array or Responses API `input_image` content blocks for multi-ref
-- ChatGPT Thinking mode (not API) can produce up to 8 consistent frames from one prompt; API users should generate frames sequentially with shared character descriptions
+**i2v prompt rules for storyboard input**:
+- Explicitly state "This is a 9-panel storyboard" at the start
+- Reference each panel by number with its action description
+- Always include Sound/Music direction — never leave audio undefined
+- Include Camera direction per beat (wide, close-up, tracking, handheld, slow-mo)
+- Describe the end frame explicitly for continuation
+
+**Step 4 — Extract last frame and repeat**:
+
+```bash
+# Extract last frame via ffmpeg
+ffmpeg -sseof -0.1 -i clip.mp4 -frames:v 1 -q:v 2 -update 1 lastframe.jpg -y
+
+# Generate next storyboard using last frame as reference
+ima2 gen "Using this fight scene last frame as reference, create a 3x3 storyboard grid..." \
+  --ref lastframe.jpg --quality high --size 1024x1024
+
+# Animate next storyboard
+ima2 video "This is a 9-panel storyboard..." --ref storyboard2.png --duration 15
+```
+
+**Fallback: continueFromVideo** — If a storyboard image triggers content moderation (common with intense action/fight scenes), fall back to `video continue` with a detailed text prompt instead:
+
+```bash
+ima2 video continue "detailed action description with sound and camera direction" \
+  --video "$PREV_CLIP" --duration 15
+```
+
+**Clip duration is flexible** — use 15s for action-dense sequences with many beats, 10s for transitions, 5s for quick cuts. The 9-panel storyboard works best with 15s clips (each panel ≈ 1.5-2s of screen time).
+
+**Music and sound are MANDATORY** in i2v prompts — describe the score (orchestral, percussion, taiko drums), sound effects (impacts, whooshes, crashes), dialogue lines, and audio transitions. "No music" or undefined audio produces flat, lifeless output.
 
 #### Video Continuation (extend/sequel)