ima2-gen 1.1.20 → 1.1.21

package/bin/commands/video.ts

@@ -4,11 +4,56 @@ import { streamSse } from "../lib/sse.js";
 import { out, die, color, json, exitCodeForError } from "../lib/output.js";
 import { config } from "../../config.js";
 import { readFile, writeFile, mkdir } from "node:fs/promises";
-import { dirname, join } from "node:path";
+import { basename, dirname, join } from "node:path";
 
 const VALID_RESOLUTIONS = new Set(["480p", "720p"]);
 const VALID_ASPECT_RATIOS = new Set(["1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3", "auto"]);
 const VALID_MODELS = new Set(["grok-imagine-video", "grok-imagine-video-1.5-preview"]);
+const ACTIVE_VIDEO_PROMPT_GUIDANCE = "Active video prompt required: describe visual flow, motion flow, sound/no-music intent, dialogue/no-dialogue intent, and the desired ending frame. Pace the scene to naturally fill the selected duration with an opening composition, connected motion/emotion change, and stable ending frame.";
+
+function parseIntegerFlag(value: unknown, fallback: number, label: string): number {
+  const raw = value === undefined ? String(fallback) : String(value);
+  if (!/^\d+$/.test(raw)) die(2, `${label} must be an integer`);
+  return Number(raw);
+}
+
+function rejectUnknownFlags(args: { _unknown?: string[] }): void {
+  if (args._unknown?.length) die(2, `unknown option: ${args._unknown[0]}`);
+}
+
+async function readJsonResponse(res: Response, label: string): Promise<Record<string, unknown>> {
+  const text = await res.text();
+  try {
+    return text ? JSON.parse(text) as Record<string, unknown> : {};
+  } catch {
+    die(1, `${label} failed: expected JSON response, got ${text.slice(0, 120) || `HTTP ${res.status}`}`);
+  }
+}
+
+function parseTimeoutSeconds(seconds: unknown): number {
+  const sec = parseIntegerFlag(seconds, 600, "--timeout");
+  if (sec < 1) die(2, "--timeout must be at least 1");
+  return sec;
+}
+
+function timeoutSignal(seconds: unknown): AbortSignal {
+  const sec = parseTimeoutSeconds(seconds);
+  return AbortSignal.timeout(sec * 1000);
+}
+
+async function writeBuffer(path: string, buf: Buffer): Promise<void> {
+  await mkdir(dirname(path), { recursive: true }).catch(() => {});
+  await writeFile(path, buf);
+}
+
+async function downloadReturnedVideo(serverBase: string, data: Record<string, unknown>, outPath: string, signal: AbortSignal): Promise<void> {
+  const rawUrl = typeof data.url === "string" ? data.url : "";
+  const url = rawUrl.startsWith("/") ? `${serverBase}${rawUrl}` : rawUrl;
+  if (!url) die(1, "server did not return a video url");
+  const res = await fetch(url, { signal });
+  if (!res.ok) die(1, `failed to download video: HTTP ${res.status}`);
+  await writeBuffer(outPath, Buffer.from(await res.arrayBuffer()));
+}
 
 const SPEC = {
   flags: {
@@ -30,11 +75,24 @@ const SPEC = {
 
 const HELP = `
   ima2 video <prompt...> [options]
+  ima2 video edit <prompt> --video <url|file_id|generated-file>
+  ima2 video extend <prompt> --video <url|file_id|generated-file> [--duration 6]
+  ima2 video continue <prompt> --video <generated-file>
+  ima2 video frame <file> [--last] [-o output.png]
+  ima2 video analyze <generated-file>
 
-  Generate a video via the Grok video provider (SSE streaming).
+  Generate, edit, extend, or analyze video via Grok.
 
-  Options:
-        --duration <1..15>              Duration in seconds. Default: 5
+  Subcommands:
+    (default)   Generate video (T2V / I2V / Ref2V)
+    edit        Edit existing video with text prompt (V2V)
+    extend      Continue video from last frame
+    continue    Generate a new I2V clip from a generated video's last frame with lineage
+    frame       Extract a frame from video (requires ffmpeg on server)
+    analyze     Analyze video with Grok 4.3 vision
+
+  Options (generate mode):
+        --duration <1..15>              Duration in seconds. Default: 5. Prompt motion should naturally fill this length
         --resolution <480p|720p>        Default: 480p
         --aspect-ratio <ratio|auto>     1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, auto. Default: auto
         --model <name>                  grok-imagine-video, grok-imagine-video-1.5-preview
@@ -47,6 +105,10 @@ const HELP = `
         --server <url>                  Override server URL
         --session <id>                  Session ID
 
+  Edit/extend subcommands:
+        --video <value>                 HTTPS URL, xAI file_id, data URL, or generated filename
+        --duration <2..10>              Extension duration only. Default: 6
+
   Modes (auto-detected from --ref count):
     0 refs  → text-to-video
     1 ref   → image-to-video
@@ -55,17 +117,29 @@ const HELP = `
   Examples:
     ima2 video "a cat playing piano"
     ima2 video "animate this" --ref photo.png --duration 10
-    ima2 video "cinematic" --resolution 720p --aspect-ratio 16:9 -o out.mp4
+    ima2 video edit "make it sunset" --video https://vidgen.x.ai/.../clip.mp4
+    ima2 video extend "camera pulls back" --video https://vidgen.x.ai/.../clip.mp4 --duration 5
+    ima2 video continue "she turns back as the music cuts to room tone" --video 1780226256355_50252101.mp4
+    ima2 video frame 1780226256355_50252101.mp4 --last -o lastframe.png
+    ima2 video analyze 1780226256355_50252101.mp4
 `;
 
 export default async function videoCmd(argv: string[]) {
+  const sub = argv[0];
+  if (sub === "edit") return videoEditCmd(argv.slice(1));
+  if (sub === "extend") return videoExtendCmd(argv.slice(1));
+  if (sub === "continue") return videoContinueCmd(argv.slice(1));
+  if (sub === "frame") return videoFrameCmd(argv.slice(1));
+  if (sub === "analyze") return videoAnalyzeCmd(argv.slice(1));
+
   const args = parseArgs(argv, SPEC);
+  rejectUnknownFlags(args);
   if (args.help) { out(HELP); return; }
 
   const prompt = args.positional.join(" ");
-  if (!prompt) die(2, "prompt is required");
+  if (!prompt.trim()) die(2, ACTIVE_VIDEO_PROMPT_GUIDANCE);
 
-  const duration = parseInt(String(args.duration)) || 5;
+  const duration = parseIntegerFlag(args.duration, 5, "--duration");
   if (duration < 1 || duration > 15) die(2, "--duration must be between 1 and 15");
 
   const resolution = String(args.resolution);
@@ -80,6 +154,11 @@ export default async function videoCmd(argv: string[]) {
 
   const refs = (Array.isArray(args.ref) ? args.ref : []) as string[];
   if (refs.length > 7) die(2, "max 7 --ref attachments for video");
+  if (refs.length >= 2 && duration > 10) die(2, "--duration must be between 1 and 10 when using 2 or more --ref attachments");
+
+  const timeoutSeconds = parseIntegerFlag(args.timeout, 600, "--timeout");
+  if (timeoutSeconds < 1) die(2, "--timeout must be at least 1");
+  const timeoutMs = timeoutSeconds * 1000;
 
   let server;
   try { server = await resolveServer({ serverFlag: args.server }); }
@@ -90,7 +169,6 @@ export default async function videoCmd(argv: string[]) {
     return buf.toString("base64");
   }));
 
-  const timeoutMs = (parseInt(String(args.timeout)) || 600) * 1000;
   const requestId = `req_cli_video_${Date.now().toString(36)}`;
 
   const body: Record<string, unknown> = {
@@ -145,7 +223,7 @@ export default async function videoCmd(argv: string[]) {
           break;
         case "error":
           if (!args.json && lastProgress >= 0) process.stdout.write("\n");
-          die(1, `video error: ${ev.data.error || ev.data}${ev.data.code ? ` (${ev.data.code})` : ""}`);
+          die(1, `video error: ${ev.data.error || ev.data}${ev.data.guidance ? `\n${ev.data.guidance}` : ""}${ev.data.code ? ` (${ev.data.code})` : ""}`);
       }
     }
   } catch (e: unknown) {
@@ -175,11 +253,10 @@ export default async function videoCmd(argv: string[]) {
 
   // Download the video file from server
   const videoUrl = `${server.base}${doneData.url || `/generated/${encodeURIComponent(filename)}`}`;
-  const dlRes = await fetch(videoUrl, { signal: AbortSignal.timeout(30_000) });
+  const dlRes = await fetch(videoUrl, { signal: timeoutSignal(args.timeout) });
   if (!dlRes.ok) die(1, `failed to download video: HTTP ${dlRes.status}`);
   const videoBuf = Buffer.from(await dlRes.arrayBuffer());
-  await mkdir(dirname(target), { recursive: true }).catch(() => {});
-  await writeFile(target, videoBuf);
+  await writeBuffer(target, videoBuf);
 
   if (args.json) {
     json({
@@ -203,3 +280,163 @@ function renderBar(pct: number): string {
   const filled = Math.round((pct / 100) * width);
   return color.green("█".repeat(filled)) + color.dim("░".repeat(width - filled));
 }
+
+async function runVideoGenerateRequest(serverBase: string, body: Record<string, unknown>, timeout: unknown, silent: boolean): Promise<Record<string, unknown>> {
+  let doneData: Record<string, unknown> | null = null;
+  let lastProgress = -1;
+  for await (const ev of streamSse(`${serverBase}/api/video/generate`, {
+    body: { provider: "grok", ...body },
+    signal: timeoutSignal(timeout),
+    headers: typeof body.requestId === "string" ? { "X-Request-Id": body.requestId } : undefined,
+  })) {
+    if (ev.event === "progress") {
+      const pct = typeof ev.data.progress === "number" ? Math.round(ev.data.progress * 100) : null;
+      if (pct !== null && pct !== lastProgress && !silent) {
+        process.stdout.write(`\r  ${renderBar(pct)} ${pct}%`);
+        lastProgress = pct;
+      }
+    } else if (ev.event === "done") {
+      if (!silent && lastProgress >= 0) process.stdout.write("\n");
+      doneData = ev.data;
+    } else if (ev.event === "error") {
+      if (!silent && lastProgress >= 0) process.stdout.write("\n");
+      die(1, `video error: ${ev.data.error || ev.data}${ev.data.guidance ? `\n${ev.data.guidance}` : ""}${ev.data.code ? ` (${ev.data.code})` : ""}`);
+    }
+  }
+  if (!doneData) die(1, "server did not return a video result");
+  return doneData;
+}
+
+// --- Subcommands ---
+
+async function videoEditCmd(argv: string[]) {
+  const spec = { flags: { video: { type: "string" }, out: { short: "o", type: "string" }, output: { type: "string" }, json: { type: "boolean" }, timeout: { type: "string", default: "600" }, server: { type: "string" }, help: { short: "h", type: "boolean" } } };
+  const args = parseArgs(argv, spec);
+  rejectUnknownFlags(args);
+  if (args.help) { out(`  ima2 video edit <prompt> --video <url|file_id|generated-file>\n\n  Edit existing video with text prompt (real V2V).\n  Model: grok-imagine-video only. Input: mp4, max 8.7s.\n\n  Options:\n        --video <value>   Source video HTTPS URL, xAI file_id, data URL, or generated filename (required)\n    -o, --out <file>      Download edited video to file\n        --output <file>   Alias for --out\n        --json            Print JSON result\n        --timeout <sec>   Default: 600\n        --server <url>    Override server URL`); return; }
+  const prompt = args.positional.join(" ");
+  if (!prompt.trim()) die(2, ACTIVE_VIDEO_PROMPT_GUIDANCE);
+  if (!args.video) die(2, "--video <url> is required");
+  parseTimeoutSeconds(args.timeout);
+  let server;
+  try { server = await resolveServer({ serverFlag: args.server }); } catch (e: unknown) { die(exitCodeForError(e), (e as Error).message); throw e; }
+  const res = await fetch(`${server.base}/api/video/edit`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ prompt, videoUrl: args.video }), signal: timeoutSignal(args.timeout) });
+  const data = await readJsonResponse(res, "edit");
+  if (!res.ok) die(1, `edit failed: ${data.error ?? res.status}`);
+  const outPath = (args.out || args.output) as string | undefined;
+  if (outPath) await downloadReturnedVideo(server.base, data, outPath, timeoutSignal(args.timeout));
+  if (args.json) { out(JSON.stringify(data, null, 2)); } else { out(color.green("✓ ") + `Edited video: ${data.url}`); }
+}
+
+async function videoExtendCmd(argv: string[]) {
+  const spec = { flags: { video: { type: "string" }, duration: { type: "string", default: "6" }, out: { short: "o", type: "string" }, output: { type: "string" }, json: { type: "boolean" }, timeout: { type: "string", default: "600" }, server: { type: "string" }, help: { short: "h", type: "boolean" } } };
+  const args = parseArgs(argv, spec);
+  rejectUnknownFlags(args);
+  if (args.help) { out(`  ima2 video extend <prompt> --video <url|file_id|generated-file> [--duration 6]\n\n  Extend video from its last frame.\n  Model: grok-imagine-video only. Extension: 2-10s.\n\n  Options:\n        --video <value>   Source video HTTPS URL, xAI file_id, data URL, or generated filename (required)\n        --duration <2-10> Extension duration (default: 6)\n    -o, --out <file>      Download extended video to file\n        --output <file>   Alias for --out\n        --json            Print JSON result\n        --timeout <sec>   Default: 600\n        --server <url>    Override server URL`); return; }
+  const prompt = args.positional.join(" ");
+  if (!prompt.trim()) die(2, ACTIVE_VIDEO_PROMPT_GUIDANCE);
+  if (!args.video) die(2, "--video <url> is required");
+  const duration = parseIntegerFlag(args.duration, 6, "--duration");
+  if (duration < 2 || duration > 10) die(2, "--duration must be between 2 and 10");
+  parseTimeoutSeconds(args.timeout);
+  let server;
+  try { server = await resolveServer({ serverFlag: args.server }); } catch (e: unknown) { die(exitCodeForError(e), (e as Error).message); throw e; }
+  const res = await fetch(`${server.base}/api/video/extend`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ prompt, videoUrl: args.video, duration }), signal: timeoutSignal(args.timeout) });
+  const data = await readJsonResponse(res, "extend");
+  if (!res.ok) die(1, `extend failed: ${data.error ?? res.status}`);
+  const outPath = (args.out || args.output) as string | undefined;
+  if (outPath) await downloadReturnedVideo(server.base, data, outPath, timeoutSignal(args.timeout));
+  if (args.json) { out(JSON.stringify(data, null, 2)); } else { out(color.green("✓ ") + `Extended video (${data.duration}s): ${data.url}`); }
+}
+
+async function videoContinueCmd(argv: string[]) {
+  const spec = {
+    flags: {
+      video: { type: "string" },
+      duration: { type: "string", default: "5" },
+      resolution: { type: "string", default: "720p" },
+      "aspect-ratio": { type: "string", default: "auto" },
+      model: { type: "string" },
+      out: { short: "o", type: "string" },
+      output: { type: "string" },
+      json: { type: "boolean" },
+      timeout: { type: "string", default: "600" },
+      server: { type: "string" },
+      help: { short: "h", type: "boolean" },
+    },
+  };
+  const args = parseArgs(argv, spec);
+  rejectUnknownFlags(args);
+  if (args.help) {
+    out(`  ima2 video continue <prompt> --video <generated-file>\n\n  Generate a new clip from a generated video's last frame and carry branch-local revisedPrompt lineage.\n\n  Prompt must describe visual flow, motion, sound/music/no-music, dialogue/no-dialogue, ending frame, and how the selected duration should feel naturally filled.\n\n  Options:\n        --video <file>                 Generated .mp4 filename (required)\n        --duration <1..15>             Default: 5. Prompt motion should naturally fill this length\n        --resolution <480p|720p>       Default: 720p\n        --aspect-ratio <ratio|auto>    Default: auto\n        --model <name>                 grok-imagine-video, grok-imagine-video-1.5-preview\n    -o, --out <file>                   Download continued video to file\n        --output <file>                Alias for --out\n        --json                         Print JSON result\n        --timeout <sec>                Default: 600\n        --server <url>                 Override server URL`);
+    return;
+  }
+  const prompt = args.positional.join(" ");
+  if (!prompt.trim()) die(2, ACTIVE_VIDEO_PROMPT_GUIDANCE);
+  if (!args.video) die(2, "--video <generated-file> is required");
+  const duration = parseIntegerFlag(args.duration, 5, "--duration");
+  if (duration < 1 || duration > 15) die(2, "--duration must be between 1 and 15");
+  const resolution = String(args.resolution);
+  if (!VALID_RESOLUTIONS.has(resolution)) die(2, "--resolution must be one of: 480p, 720p");
+  const aspectRatio = String(args["aspect-ratio"]);
+  if (!VALID_ASPECT_RATIOS.has(aspectRatio)) die(2, "--aspect-ratio must be one of: 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, auto");
+  if (args.model && !VALID_MODELS.has(String(args.model))) {
+    die(2, "--model must be one of: grok-imagine-video, grok-imagine-video-1.5-preview");
+  }
+  parseTimeoutSeconds(args.timeout);
+  let server;
+  try { server = await resolveServer({ serverFlag: args.server }); } catch (e: unknown) { die(exitCodeForError(e), (e as Error).message); throw e; }
+  const requestId = `req_cli_video_continue_${Date.now().toString(36)}`;
+  const body: Record<string, unknown> = {
+    prompt,
+    requestId,
+    duration,
+    resolution,
+    aspectRatio,
+    continueFromVideo: args.video,
+  };
+  if (args.model) body.model = args.model;
+  const data = await runVideoGenerateRequest(server.base, body, args.timeout, Boolean(args.json));
+  const outPath = (args.out || args.output) as string | undefined;
+  if (outPath) await downloadReturnedVideo(server.base, data, outPath, timeoutSignal(args.timeout));
+  if (args.json) out(JSON.stringify(data, null, 2));
+  else out(color.green("✓ ") + `Continued video: ${data.url}`);
+}
+
+async function videoFrameCmd(argv: string[]) {
+  const spec = { flags: { last: { type: "boolean" }, position: { type: "string" }, out: { type: "string" }, output: { short: "o", type: "string" }, timeout: { type: "string", default: "60" }, server: { type: "string" }, help: { short: "h", type: "boolean" } } };
+  const args = parseArgs(argv, spec);
+  rejectUnknownFlags(args);
+  if (args.help) { out(`  ima2 video frame <generated-file> [--last] [--position <sec>] [-o output.png]\n\n  Extract a frame from a generated video file.\n\n  Options:\n        --last            Extract last frame (default)\n        --position <sec>  Extract frame at specific second\n    -o, --output <path>   Output file path\n        --out <path>      Alias for --output\n        --timeout <sec>   Default: 60\n        --server <url>    Override server URL`); return; }
+  const file = args.positional[0];
+  if (!file) die(2, "file argument required");
+  if (args.last && args.position) die(2, "use either --last or --position, not both");
+  const position = args.last ? "last" : (String(args.position || "last"));
+  if (position !== "last" && !/^\d+(\.\d+)?$/.test(position)) die(2, "--position must be a non-negative number");
+  parseTimeoutSeconds(args.timeout);
+  let server;
+  try { server = await resolveServer({ serverFlag: args.server }); } catch (e: unknown) { die(exitCodeForError(e), (e as Error).message); throw e; }
+  const url = `${server.base}/api/video/frame?file=${encodeURIComponent(file)}&position=${encodeURIComponent(position)}`;
+  const res = await fetch(url, { signal: timeoutSignal(args.timeout) });
+  if (!res.ok) { const d = await readJsonResponse(res, "frame extraction"); die(1, `frame extraction failed: ${(d as any).error || res.status}`); }
+  const buf = Buffer.from(await res.arrayBuffer());
+  const outPath = (args.output || args.out) as string || `frame-${basename(file).replace(/\.[^.]+$/, "")}.png`;
+  await writeBuffer(outPath, buf);
+  out(color.green("✓ ") + `Frame saved: ${outPath} (${buf.length} bytes)`);
+}
+
+async function videoAnalyzeCmd(argv: string[]) {
+  const spec = { flags: { json: { type: "boolean" }, timeout: { type: "string", default: "180" }, server: { type: "string" }, help: { short: "h", type: "boolean" } } };
+  const args = parseArgs(argv, spec);
+  rejectUnknownFlags(args);
+  if (args.help) { out(`  ima2 video analyze <generated-file>\n\n  Analyze first/last frames from a generated .mp4 with Grok 4.3 image understanding. Outputs structured recreation prompt.\n\n  Options:\n        --json            Print JSON result\n        --timeout <sec>   Default: 180\n        --server <url>    Override server URL`); return; }
+  const videoUrl = args.positional[0];
+  if (!videoUrl) die(2, "generated video filename required");
+  parseTimeoutSeconds(args.timeout);
+  let server;
+  try { server = await resolveServer({ serverFlag: args.server }); } catch (e: unknown) { die(exitCodeForError(e), (e as Error).message); throw e; }
+  const res = await fetch(`${server.base}/api/video/analyze`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ videoUrl }), signal: timeoutSignal(args.timeout) });
+  const data = await readJsonResponse(res, "analyze");
+  if (!res.ok) die(1, `analyze failed: ${(data as any).error || res.status}`);
+  if (args.json) { out(JSON.stringify(data, null, 2)); } else { out((data as any).analysis); }
+}

package/bin/ima2.js

@@ -88,7 +88,7 @@ async function setup() {
         saveConfig(config);
         console.log("\n  Starting Grok OAuth login...\n");
         try {
-            execSync(`node ${JSON.stringify(join(ROOT, "bin", "ima2.js"))} grok login`, { stdio: "inherit" });
+            execSync(`node ${JSON.stringify(join(ROOT, "bin", "ima2.js"))} grok login --manual-paste`, { stdio: "inherit" });
         }
         catch {
             console.log("\n  Grok login failed or cancelled. You can retry with 'ima2 grok login'.\n");
@@ -121,7 +121,7 @@ async function setup() {
         // Grok OAuth
         console.log("  Running Grok OAuth login...\n");
         try {
-            execSync(`node ${JSON.stringify(join(ROOT, "bin", "ima2.js"))} grok login`, { stdio: "inherit" });
+            execSync(`node ${JSON.stringify(join(ROOT, "bin", "ima2.js"))} grok login --manual-paste`, { stdio: "inherit" });
         }
         catch {
             console.log("\n  Grok login failed. You can retry with 'ima2 grok login'.\n");
@@ -135,7 +135,7 @@ async function setup() {
         config.oauth.disableAutoStart = false;
         delete config.apiKey;
         saveConfig(config);
-        console.log("\n  Starting OAuth login...\n");
+        console.log("\n  Starting GPT OAuth login...\n");
         const auth = detectCodexAuth();
         const hasAuth = auth.authed;
         if (!hasAuth) {
@@ -154,10 +154,10 @@ async function setup() {
         }
         else {
             const how = auth.probe === "authed" ? "codex CLI" : "auth file";
-            console.log(`  Existing OAuth session found (${how}).\n`);
+            console.log(`  Existing GPT OAuth session found (${how}).\n`);
         }
         saveConfig(config);
-        console.log("  OAuth configured. Starting server...\n");
+        console.log("  GPT OAuth configured. Starting server...\n");
     }
     rl.close();
     return config;
@@ -222,7 +222,7 @@ async function showStatus() {
     }
     // Check OAuth auth files + codex CLI probe
     const auth = detectCodexAuth();
-    console.log(`  OAuth sessions:`);
+    console.log(`  GPT OAuth sessions:`);
     console.log(`    ${auth.files.codex}          ${auth.fileHits.codex ? "✓" : "✗"}`);
     console.log(`    ${auth.files.chatgpt}  ${auth.fileHits.chatgpt ? "✓" : "✗"}`);
     if (auth.fileHits.xdgCodex) {
@@ -255,7 +255,7 @@ function showHelp() {
 
   Server commands:
     serve [--dev]  Start the image generation server
-    setup, login   Configure API key or OAuth (interactive)
+    setup, login   Configure API key or GPT OAuth (interactive)
     status         Show current configuration status
     doctor         Diagnose environment and setup
     open           Open web UI in browser
@@ -283,8 +283,8 @@ function showHelp() {
     storage <sub>  Storage status / open-dir       (ima2 storage --help)
     billing        API usage / quota
     providers      Configured providers
-    oauth <sub>    OAuth proxy status              (ima2 oauth --help)
-    grok <sub>     Bundled progrok login/status     (ima2 grok --help)
+    oauth <sub>    GPT OAuth proxy status              (ima2 oauth --help)
+    grok <sub>     Bundled Grok auth/status         (ima2 grok --help)
     config <sub>   Config get/set/ls/path/rm       (ima2 config --help)
     defaults <sub> Inspect/change model defaults   (ima2 defaults --help)
     capabilities   Agent capability metadata       (ima2 capabilities --help)

package/bin/ima2.ts

@@ -91,7 +91,7 @@ async function setup() {
     saveConfig(config);
     console.log("\n  Starting Grok OAuth login...\n");
     try {
-      execSync(`node ${JSON.stringify(join(ROOT, "bin", "ima2.js"))} grok login`, { stdio: "inherit" });
+      execSync(`node ${JSON.stringify(join(ROOT, "bin", "ima2.js"))} grok login --manual-paste`, { stdio: "inherit" });
     } catch {
       console.log("\n  Grok login failed or cancelled. You can retry with 'ima2 grok login'.\n");
       rl.close();
@@ -119,7 +119,7 @@ async function setup() {
     // Grok OAuth
     console.log("  Running Grok OAuth login...\n");
     try {
-      execSync(`node ${JSON.stringify(join(ROOT, "bin", "ima2.js"))} grok login`, { stdio: "inherit" });
+      execSync(`node ${JSON.stringify(join(ROOT, "bin", "ima2.js"))} grok login --manual-paste`, { stdio: "inherit" });
     } catch {
       console.log("\n  Grok login failed. You can retry with 'ima2 grok login'.\n");
     }
@@ -131,7 +131,7 @@ async function setup() {
     config.oauth.disableAutoStart = false;
     delete config.apiKey;
     saveConfig(config);
-    console.log("\n  Starting OAuth login...\n");
+    console.log("\n  Starting GPT OAuth login...\n");
 
     const auth = detectCodexAuth();
     const hasAuth = auth.authed;
@@ -152,11 +152,11 @@ async function setup() {
       }
     } else {
       const how = auth.probe === "authed" ? "codex CLI" : "auth file";
-      console.log(`  Existing OAuth session found (${how}).\n`);
+      console.log(`  Existing GPT OAuth session found (${how}).\n`);
     }
 
     saveConfig(config);
-    console.log("  OAuth configured. Starting server...\n");
+    console.log("  GPT OAuth configured. Starting server...\n");
   }
 
   rl.close();
@@ -234,7 +234,7 @@ async function showStatus() {
 
   // Check OAuth auth files + codex CLI probe
   const auth = detectCodexAuth();
-  console.log(`  OAuth sessions:`);
+  console.log(`  GPT OAuth sessions:`);
   console.log(`    ${auth.files.codex}          ${auth.fileHits.codex ? "✓" : "✗"}`);
   console.log(`    ${auth.files.chatgpt}  ${auth.fileHits.chatgpt ? "✓" : "✗"}`);
   if (auth.fileHits.xdgCodex) {
@@ -269,7 +269,7 @@ function showHelp() {
 
   Server commands:
     serve [--dev]  Start the image generation server
-    setup, login   Configure API key or OAuth (interactive)
+    setup, login   Configure API key or GPT OAuth (interactive)
     status         Show current configuration status
     doctor         Diagnose environment and setup
     open           Open web UI in browser
@@ -297,8 +297,8 @@ function showHelp() {
     storage <sub>  Storage status / open-dir       (ima2 storage --help)
     billing        API usage / quota
     providers      Configured providers
-    oauth <sub>    OAuth proxy status              (ima2 oauth --help)
-    grok <sub>     Bundled progrok login/status     (ima2 grok --help)
+    oauth <sub>    GPT OAuth proxy status              (ima2 oauth --help)
+    grok <sub>     Bundled Grok auth/status         (ima2 grok --help)
     config <sub>   Config get/set/ls/path/rm       (ima2 config --help)
     defaults <sub> Inspect/change model defaults   (ima2 defaults --help)
     capabilities   Agent capability metadata       (ima2 capabilities --help)

package/bin/lib/error-hints.js

@@ -3,11 +3,11 @@ const HINTS = {
     APIKEY_DISABLED: "API-key generation is supported in current builds; switch providers or update the configured API key.",
     IMAGE_MODEL_UNSUPPORTED: "This model is visible but cannot generate images here. Use gpt-5.4 or gpt-5.4-mini.",
     INVALID_IMAGE_MODEL: "Use one of: gpt-5.5, gpt-5.4, gpt-5.4-mini.",
-    OAUTH_UNAVAILABLE: "OAuth proxy is unavailable. Check `ima2 doctor` and restart `ima2 serve`.",
+    OAUTH_UNAVAILABLE: "GPT OAuth proxy is unavailable. Check `ima2 doctor` and restart `ima2 serve`.",
     NETWORK_FAILED: "Network/proxy failed. This is not a moderation refusal.",
     SAFETY_REFUSAL: "The image backend refused this generation.",
     MODERATION_REFUSED: "The prompt or image was rejected by moderation.",
-    AUTH_CHATGPT_EXPIRED: "Run `npx @openai/codex login`, then restart `ima2 serve`.",
+    AUTH_CHATGPT_EXPIRED: "Re-run `ima2 setup` (option 1), then restart `ima2 serve`.",
     REF_TOO_LARGE: "Reference image is too large. Resize/compress it and retry.",
     REF_NOT_BASE64: "Reference payload is invalid. Use a normal PNG/JPEG/WebP file.",
 };

package/bin/lib/error-hints.ts

@@ -4,11 +4,11 @@ const HINTS: Record<string, string> = {
   IMAGE_MODEL_UNSUPPORTED:
     "This model is visible but cannot generate images here. Use gpt-5.4 or gpt-5.4-mini.",
   INVALID_IMAGE_MODEL: "Use one of: gpt-5.5, gpt-5.4, gpt-5.4-mini.",
-  OAUTH_UNAVAILABLE: "OAuth proxy is unavailable. Check `ima2 doctor` and restart `ima2 serve`.",
+  OAUTH_UNAVAILABLE: "GPT OAuth proxy is unavailable. Check `ima2 doctor` and restart `ima2 serve`.",
   NETWORK_FAILED: "Network/proxy failed. This is not a moderation refusal.",
   SAFETY_REFUSAL: "The image backend refused this generation.",
   MODERATION_REFUSED: "The prompt or image was rejected by moderation.",
-  AUTH_CHATGPT_EXPIRED: "Run `npx @openai/codex login`, then restart `ima2 serve`.",
+  AUTH_CHATGPT_EXPIRED: "Re-run `ima2 setup` (option 1), then restart `ima2 serve`.",
   REF_TOO_LARGE: "Reference image is too large. Resize/compress it and retry.",
   REF_NOT_BASE64: "Reference payload is invalid. Use a normal PNG/JPEG/WebP file.",
 };

package/docs/API.md

@@ -234,6 +234,8 @@ Generate a video via the Grok video provider. Returns Server-Sent Events.
   "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"
 }
@@ -263,16 +265,67 @@ Generate a video via the Grok video provider. Returns Server-Sent Events.
 | `sourceFilename` | string | — | Existing generated file for image-to-video |
 | `referenceImages` | string[] | — | Base64 images for reference-to-video |
 | `referenceFilenames` | string[] | — | Existing generated files for reference-to-video |
+| `continueFromVideo` | string | — | Generated `.mp4` parent; server extracts its last frame and rebuilds lineage from sidecar |
+| `continuityLineage` | object | — | Optional client hint; used only when `continueFromVideo` is absent |
+
+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.
+
+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:
+
+```json
+{
+  "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:
+
+| Surface | Model | Responsibility |
+|---|---|---|
+| Video planner | `grok-4.3` | Converts user prompt, search context, refs, and optional continuity lineage into the final English video prompt. It must structure core subject, action/motion, camera/composition, environment/style, dialogue/audio, ending-frame handoff, and constraints. |
+| Video generation | xAI video model | Receives the planner prompt plus `sourceImage` or `referenceImages` when present. |
+| Video analysis | `grok-4.3` | Reads first/last frame images from `/api/video/analyze` and returns recreation/continuation guidance. |
 
 **SSE events**:
 
 | Event | Data | Description |
 |---|---|---|
 | `planning` | `{ requestId }` | Preparing video generation |
-| `submitted` | `{ requestId, xaiVideoRequestId }` | Submitted to xAI |
+| `submitted` | `{ requestId, xaiVideoRequestId, requestedModel, effectiveModel, modelFallback }` | Submitted to xAI |
 | `progress` | `{ requestId, progress, stalled }` | Progress 0.0–1.0 |
-| `done` | `{ requestId, filename, url, mediaType, revisedPrompt, elapsed, usage, video }` | Video ready |
-| `error` | `{ error, code, status, requestId }` | Generation failed |
+| `done` | `{ requestId, filename, url, mediaType, revisedPrompt, elapsed, usage, requestedModel, effectiveModel, modelFallback, video, videoContinuity }` | Video ready |
+| `error` | `{ error, code, status, requestId, guidance? }` | Generation failed |
 
 **Video error codes**:
 
@@ -286,6 +339,57 @@ Generate a video via the Grok video provider. Returns Server-Sent Events.
 | `INVALID_VIDEO_DURATION` | Duration not 1–15 integer |
 | `GROK_VIDEO_REF_TOO_MANY` | More than 7 reference images |
 | `GROK_VIDEO_FAILED` | Upstream xAI video generation failed |
+| `GROK_VIDEO_FRAME_FAILED` | Server could not extract the parent video's last frame |
+
+### `POST /api/video/edit`
+
+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.
+
+```json
+{
+  "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.
+
+### `POST /api/video/extend`
+
+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.
+
+```json
+{
+  "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.
+
+### `GET /api/video/frame`
+
+Extract a PNG frame from a generated `.mp4` file.
+
+| Query | Notes |
+|---|---|
+| `file` | Required generated `.mp4` filename or generated-dir absolute path |
+| `position` | `last` (default) or non-negative seconds |
+
+### `POST /api/video/analyze`
+
+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.
+
+```json
+{
+  "videoUrl": "1780226256355_50252101.mp4"
+}
+```
+
+Remote URLs and `data:` inputs are intentionally rejected to avoid server-side URL fetching through `ffmpeg`.
 
 ## History
 
@@ -368,6 +472,11 @@ Most server routes under `/api/*` have a CLI wrapper. The exception is **Agent M
 | `POST /api/edit` | `ima2 edit` |
 | `POST /api/generate/multimode` (SSE) | `ima2 multimode` |
 | `POST /api/video/generate` (SSE) | `ima2 video` |
+| `POST /api/video/generate` with `continueFromVideo` | `ima2 video continue` |
+| `POST /api/video/edit` | `ima2 video edit` |
+| `POST /api/video/extend` | `ima2 video extend` |
+| `GET /api/video/frame` | `ima2 video frame` |
+| `POST /api/video/analyze` | `ima2 video analyze` |
 | `POST /api/node/generate` (SSE) / `GET /api/node/:id` | `ima2 node generate` / `ima2 node show` |
 | `GET /api/history` | `ima2 ls` |
 | `DELETE /api/history/:name` / `…/permanent` | `ima2 history rm [--permanent]` |