videodraft 0.25.2 → 0.26.0

package/dist/index.js

@@ -24,8 +24,8 @@ function readVersionFromDisk() {
   }
 }
 function resolveVersion() {
-  if ("0.25.2") {
-    return "0.25.2";
+  if ("0.26.0") {
+    return "0.26.0";
   }
   return readVersionFromDisk();
 }
@@ -1756,507 +1756,6 @@ ${fmt.bold(ctxOut, "Open this URL to log in:")}
   });
 }
 
-// src/commands/account.ts
-function registerAccountCommands(program) {
-  program.command("credits").description("Show your credit balance").action(async function() {
-    const ctx = buildContext(this);
-    const balance = await ctx.client.callTool("get_credits_balance");
-    emit(ctx.out, balance, (o) => {
-      kv(o, [
-        ["Plan", balance?.planId],
-        ["Available credits", balance?.availableCredits],
-        ["Monthly allowance", balance?.totalCreditsMonthly],
-        ["Used this month", balance?.monthlyCreditsUsed],
-        ["Bonus credits", balance?.bonusCredits],
-        ["Bonus expiry", balance?.bonusCreditsExpiry],
-        ["Last monthly reset", balance?.lastMonthlyReset],
-        ["Next monthly reset", balance?.nextMonthlyReset]
-      ]);
-    });
-  });
-  program.command("costs [model]").description(
-    "Show credit costs. Pass a model id, or an image display name, plus settings for an exact estimate"
-  ).option("--type <type>", "image | video | audio").option("--duration <seconds>", "video/audio duration in seconds").option(
-    "--length <seconds>",
-    "ElevenLabs Music output length in seconds (for a composition plan, the sum of its sections)"
-  ).option(
-    "--chars <n>",
-    'character count (ElevenLabs Dialogue, or voiceover TTS via model id "voiceover")'
-  ).option("--resolution <res>", 'e.g. "720p", "1080p", "1K", "2K"').option("--quality <tier>", 'e.g. "standard", "pro", "fast"').option("--ar <ratio>", "image aspect ratio for accurate credit quotes").option(
-    "--rendering-speed <tier>",
-    'image speed/cost tier, e.g. Ideogram V4 "Turbo"/"Balanced"/"Quality"'
-  ).option("--audio", "include native model audio in the estimate").option("--no-audio", "exclude native model audio").option(
-    "--voice-control",
-    "Kling element voice_id pricing (V3 Standard/Pro only; O3/4K are unavailable)"
-  ).option(
-    "--allow-real-people",
-    "Seedance 2.x: estimate the higher tier-specific Fal rate (the default, matching AI Studio)"
-  ).option(
-    "--no-allow-real-people",
-    "Seedance 2.x: estimate the lower Byteplus-only rate"
-  ).option(
-    "--ref-images <n>",
-    "input/reference image count for MiniMax H3, MiniMax H3 Max, or Grok 1.5"
-  ).option(
-    "--ref-video-seconds <seconds>",
-    "MiniMax H3 / H3 Max combined reference-video duration"
-  ).option("--num <n>", "image batch size").option(
-    "--width <px>",
-    "Topaz: source width (with --height gives an exact quote)"
-  ).option("--height <px>", "Topaz: source height").option(
-    "--source-fps <n>",
-    "Topaz video upscale: source frame rate (>30 bills the 60fps rate)"
-  ).option("--scale <factor>", 'Topaz: "1x" | "2x" | "4x" or a factor 1-4').option("--fps <n>", "Topaz: delivered / target frame rate").option(
-    "--mode <mode>",
-    "Topaz upscale mode: generative | precision | creative"
-  ).option(
-    "--topaz-model <name>",
-    'Topaz model inside the mode, or "Apollo" | "Chronos" | "Aion" for interpolation'
-  ).option("--slowdown <1-8>", "Topaz interpolate: slow-motion factor").action(async function(model) {
-    const ctx = buildContext(this);
-    const opts = this.opts();
-    const result = await ctx.client.callTool(
-      "get_model_costs",
-      compact({
-        model_id: model,
-        type: opts.type,
-        duration_seconds: opts.duration ? Number(opts.duration) : void 0,
-        length_seconds: opts.length ? Number(opts.length) : void 0,
-        characters: opts.chars ? Number(opts.chars) : void 0,
-        resolution: opts.resolution,
-        quality: opts.quality,
-        aspect_ratio: opts.ar,
-        rendering_speed: opts.renderingSpeed,
-        generate_audio: opts.audio,
-        voice_control: opts.voiceControl,
-        allow_real_people: opts.allowRealPeople,
-        reference_image_count: opts.refImages ? Number(opts.refImages) : void 0,
-        reference_video_duration_seconds: opts.refVideoSeconds ? Number(opts.refVideoSeconds) : void 0,
-        num_images: opts.num ? Number(opts.num) : void 0,
-        source_width: opts.width ? Number(opts.width) : void 0,
-        source_height: opts.height ? Number(opts.height) : void 0,
-        source_fps: opts.sourceFps ? Number(opts.sourceFps) : void 0,
-        scale: opts.scale,
-        target_resolution: opts.resolution && /^(720p|1080p|4k)$/i.test(opts.resolution) ? opts.resolution.toLowerCase() : void 0,
-        target_fps: opts.fps ? Number(opts.fps) : void 0,
-        mode: opts.mode,
-        topaz_model: opts.topazModel,
-        slowdown_factor: opts.slowdown ? Number(opts.slowdown) : void 0
-      })
-    );
-    emit(ctx.out, result);
-  });
-  program.command("models [kind]").description(
-    "List available models: image | video | audio | 3d | voices | styles (default: image + video + audio)"
-  ).option(
-    "--category <name>",
-    "video only: generation | video_edit | motion_control | avatar_lipsync | upscale"
-  ).action(async function(kind) {
-    const ctx = buildContext(this);
-    const opts = this.opts();
-    const wanted = kind ?? "all";
-    if (!["all", "image", "video", "audio", "3d", "voices", "styles"].includes(
-      wanted
-    )) {
-      throw new UsageError(
-        `Unknown model kind "${wanted}". Use image, video, audio, 3d, voices, or styles.`
-      );
-    }
-    const videoCategories = /* @__PURE__ */ new Set([
-      "generation",
-      "video_edit",
-      "motion_control",
-      "avatar_lipsync",
-      "upscale"
-    ]);
-    if (opts.category && !videoCategories.has(opts.category)) {
-      throw new UsageError(
-        `Unknown video category "${opts.category}". Use generation, video_edit, motion_control, avatar_lipsync, or upscale.`
-      );
-    }
-    if (opts.category && wanted !== "video" && wanted !== "all") {
-      throw new UsageError(
-        "--category is only valid for the video model catalog."
-      );
-    }
-    const result = {};
-    if (wanted === "image" || wanted === "all") {
-      result.image = await ctx.client.callTool("list_available_image_models");
-    }
-    if (wanted === "video" || wanted === "all") {
-      const video = await ctx.client.callTool(
-        "list_available_video_models"
-      );
-      result.video = opts.category ? {
-        ...video,
-        // A card may belong to more than one category — gemini-omni-1.1-flash
-        // is both the generation default and the preferred video_edit
-        // model — and declares that in `categories`. Match either field so
-        // dual-category cards surface under both.
-        models: (video?.models ?? []).filter(
-          (model) => Array.isArray(model.categories) ? model.categories.includes(opts.category) : model.category === opts.category
-        ),
-        selected_category: opts.category
-      } : video;
-    }
-    if (wanted === "audio" || wanted === "all") {
-      result.audio = await ctx.client.callTool("list_available_audio_models");
-    }
-    if (wanted === "3d") {
-      result["3d"] = await ctx.client.callTool("get_3d_models");
-    }
-    if (wanted === "voices") {
-      result.voices = await ctx.client.callTool("list_available_voices");
-    }
-    if (wanted === "styles") {
-      result.styles = await ctx.client.callTool("list_available_styles");
-    }
-    emit(ctx.out, result, (o) => {
-      for (const [section, payload] of Object.entries(result)) {
-        const models = Array.isArray(payload) ? payload : payload?.models ?? payload?.voices ?? payload?.styles ?? [];
-        process.stdout.write(`
-${section.toUpperCase()}
-`);
-        if (!Array.isArray(models) || models.length === 0) {
-          process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
-          continue;
-        }
-        if (section === "3d") {
-          table(
-            o,
-            ["model", "input", "default credits", "Fal endpoint"],
-            models.flatMap(
-              (model) => (model.inputs ?? []).map((input) => [
-                String(model.id ?? ""),
-                String(input.input_mode ?? ""),
-                String(input.default_credits ?? ""),
-                String(input.endpoint_id ?? "")
-              ])
-            )
-          );
-          const rig = payload?.rigging;
-          if (rig)
-            note(
-              o,
-              `Humanoid rigging: ${rig.credits} credits; preset animation adds ${rig.animation_addon_credits} credits.`
-            );
-          note(
-            o,
-            "Use --json for exact options, defaults, input limits, and pricing notes. Use generate 3d --estimate for your selected recipe and BYOK status."
-          );
-          continue;
-        }
-        const rows = models.map((m) => [
-          String(m.id ?? m.model_id ?? m.voice_id ?? ""),
-          String(m.name ?? "").slice(0, 40),
-          String(m.category ?? ""),
-          String(m.tool ?? ""),
-          String(m.credit_cost ?? m.cost ?? m.pricing?.summary ?? "")
-        ]);
-        table(
-          o,
-          section === "video" ? ["id", "name", "category", "tool", "cost"] : ["id", "name", "cost"],
-          section === "video" ? rows : rows.map((row) => [row[0] ?? "", row[1] ?? "", row[4] ?? ""])
-        );
-      }
-    });
-  });
-  program.command("workspaces").description("List your workspaces (the active one is bound to your token)").action(async function() {
-    const ctx = buildContext(this);
-    const result = await ctx.client.callTool("list_workspaces");
-    const workspaces = result?.workspaces ?? result ?? [];
-    emit(ctx.out, result, (o) => {
-      table(
-        o,
-        ["id", "name", "role", "active"],
-        workspaces.map((w) => [
-          String(w.id ?? ""),
-          String(w.name ?? ""),
-          String(w.role ?? ""),
-          w.is_active || w.active ? "\u2713" : ""
-        ])
-      );
-    });
-  });
-  const sessions = program.command("sessions").description("AI Studio sessions");
-  sessions.command("list", { isDefault: true }).description("List AI Studio sessions (owned + shared)").option("--project <id>", "filter to a project's sessions").option("--name <fragment>", "filter by name (case-insensitive)").option("--limit <n>", "max rows (default 50)").option("--offset <n>", "pagination offset (default 0)").action(async function() {
-    const ctx = buildContext(this);
-    const opts = this.opts();
-    const result = await ctx.client.callTool(
-      "list_ai_studio_sessions",
-      compact({
-        project_id: opts.project,
-        name: opts.name,
-        limit: opts.limit ? Number(opts.limit) : void 0,
-        offset: opts.offset ? Number(opts.offset) : void 0
-      })
-    );
-    const rows = result?.sessions ?? result ?? [];
-    emit(ctx.out, result, (o) => {
-      if (!Array.isArray(rows)) return;
-      table(
-        o,
-        ["id", "name", "role", "items", "created"],
-        rows.map((s) => [
-          String(s.id ?? s.session_id ?? ""),
-          String(s.name ?? "").slice(0, 40),
-          String(s.role ?? (s.is_owner === false ? "member" : "owner")),
-          `${s.image_count ?? 0}i/${s.video_count ?? 0}v/${s.sound_count ?? 0}s`,
-          String(s.created_at ?? s.createdAt ?? "").slice(0, 19)
-        ])
-      );
-    });
-  });
-  sessions.command("current").description("Show the current scope's automatic AI Studio session").action(async function() {
-    const ctx = buildContext(this);
-    const knownIds = /* @__PURE__ */ new Set();
-    let listed = false;
-    if (ctx.session) {
-      try {
-        for (let offset = 0; offset < 2e3; ) {
-          const page = await ctx.client.callTool(
-            "list_ai_studio_sessions",
-            { limit: 200, offset }
-          );
-          const pageRows = page?.sessions ?? [];
-          for (const row of pageRows) {
-            const id = row?.id ?? row?.session_id;
-            if (typeof id === "string") knownIds.add(id);
-          }
-          if (pageRows.length < 200) break;
-          offset += pageRows.length;
-        }
-        listed = true;
-      } catch {
-        listed = false;
-      }
-    }
-    const info = ctx.session?.describe();
-    const record = info?.record ?? null;
-    const active = Boolean(record) && !info?.expired;
-    const sessionId = active ? info?.sessionId ?? null : null;
-    const created = Boolean(sessionId) && listed && knownIds.has(sessionId);
-    const result = {
-      enabled: Boolean(ctx.session),
-      scope: info?.scope ?? null,
-      active,
-      expired: Boolean(info?.expired),
-      session_id: sessionId,
-      /** False until naming or the first generation creates the row. */
-      session_created: created,
-      url: sessionId && created ? `${ctx.baseUrl}/ai-studio?session=${sessionId}` : null,
-      created_at: active ? record?.createdAt ?? null : null,
-      last_used_at: active ? record?.lastUsedAt ?? null : null,
-      file: info?.file ?? null,
-      note: ctx.session ? active ? created ? "Project-less generations in this scope share this AI Studio session. `videodraft sessions reset` starts a new one; --session <id> pins a specific session." : "Session id reserved for this scope; name it with `videodraft sessions name <title>` or generate the first asset to create it. `videodraft sessions reset` starts a new one; --session <id> pins a specific session." : info?.expired ? "The previous session idled out (12h); the next command starts a new one. --session <id> pins a specific session instead." : "No session yet; the next command creates one. --session <id> pins a specific session instead." : 'Disabled via VIDEODRAFT_NO_SESSION; generations fall back to the shared "Agent (MCP)" session unless --session is passed.'
-    };
-    emit(ctx.out, result, () => {
-      const state = !result.enabled ? "disabled" : result.active ? `${result.session_created ? "active" : "reserved"}  session=${result.session_id ?? "?"}` : result.expired ? "expired" : "none yet";
-      process.stdout.write(
-        `${state}  scope=${result.scope ?? "-"}
-${result.url ? `${result.url}
-` : ""}${result.note}
-`
-      );
-    });
-  });
-  sessions.command("name <name>").description("Name the automatic AI Studio session before first use").action(async function(name) {
-    if (process.env.VIDEODRAFT_SESSION?.trim()) {
-      throw new UsageError(
-        "Cannot name the automatic session while VIDEODRAFT_SESSION is set. Unset it first, or rename the pinned session in AI Studio."
-      );
-    }
-    const ctx = buildContext(this);
-    const result = await ctx.client.callTool(
-      "name_current_ai_studio_session",
-      { name }
-    );
-    emit(ctx.out, result, () => {
-      const session = result?.session ?? result;
-      process.stdout.write(
-        `${String(session?.name ?? name)}  ${String(session?.id ?? result?.session_id ?? "")}
-`
-      );
-    });
-  });
-  sessions.command("reset").description(
-    "Forget this connection session so the next generation starts a fresh AI Studio session (--all: every scope)"
-  ).option("--all", "reset every stored connection session").action(async function() {
-    const ctx = buildContext(this);
-    const opts = this.opts();
-    let removed = 0;
-    let declined = false;
-    if (opts.all) {
-      removed = resetAllConnectionSessions();
-    } else if (ctx.session) {
-      const had = Boolean(ctx.session.describe().record);
-      const ran = ctx.session.reset();
-      removed = had && ran ? 1 : 0;
-      declined = had && !ran;
-    }
-    const result = {
-      reset: removed,
-      declined,
-      scope: opts.all ? "all" : ctx.session?.describe().scope ?? null
-    };
-    emit(ctx.out, result, () => {
-      process.stdout.write(
-        removed > 0 ? `Reset ${removed} connection session${removed === 1 ? "" : "s"}; the next generation starts a new AI Studio session.
-` : declined ? "Could not reset: the session store is locked or unwritable; the session may still be in use.\n" : "Nothing to reset.\n"
-      );
-    });
-  });
-  sessions.command("create <name>").description(
-    "Create an AI Studio session (reuse its id across standalone generations)"
-  ).option("--project <id>", "attach the session to a project").action(async function(name) {
-    const ctx = buildContext(this);
-    const result = await ctx.client.callTool(
-      "create_ai_studio_session",
-      compact({ name, project_id: this.opts().project })
-    );
-    emit(ctx.out, result, (o) => {
-      const id = result?.session?.id ?? result?.session_id ?? result?.id;
-      process.stdout.write(`${id ?? JSON.stringify(result)}
-`);
-    });
-  });
-}
-
-// src/commands/projects.ts
-import { spawn as spawn2 } from "child_process";
-function registerProjectCommands(program) {
-  const projects = program.command("projects").description("List and manage projects");
-  projects.command("list", { isDefault: true }).description("List projects").option("--limit <n>", "max projects (default 50)").option("--offset <n>", "pagination offset").option("--favorites", "only favorited projects").action(async function() {
-    const ctx = buildContext(this);
-    const opts = this.opts();
-    const result = await ctx.client.callTool(
-      "list_projects",
-      compact({
-        limit: opts.limit ? Number(opts.limit) : void 0,
-        offset: opts.offset ? Number(opts.offset) : void 0,
-        favorites_only: opts.favorites || void 0
-      })
-    );
-    const rows = result?.projects ?? [];
-    emit(ctx.out, result, (o) => {
-      table(
-        o,
-        ["id", "title", "status", "modified"],
-        rows.map((p) => [
-          String(p.id ?? ""),
-          String(p.title ?? "Untitled").slice(0, 44),
-          String(p.status ?? ""),
-          String(p.lastModified ?? "").slice(0, 19)
-        ])
-      );
-    });
-  });
-  projects.command("get <project_id>").description("Fetch a project (summary view; --raw for the editable blob)").option("--raw", "return the raw editable JSON blob").action(async function(projectId) {
-    const ctx = buildContext(this);
-    const result = await ctx.client.callTool("get_project", {
-      project_id: projectId,
-      view: this.opts().raw ? "raw" : "summary"
-    });
-    emit(ctx.out, result);
-  });
-  projects.command("delete <project_id>").description("Permanently delete a project (cannot be undone)").option("--yes", "skip the confirmation").action(async function(projectId) {
-    const ctx = buildContext(this);
-    if (!this.opts().yes) {
-      throw new CliError(
-        "Refusing to delete without --yes. Deletion is permanent for every collaborator.",
-        EXIT.USAGE
-      );
-    }
-    const result = await ctx.client.callTool("delete_project", {
-      project_id: projectId
-    });
-    emit(
-      ctx.out,
-      result,
-      (o) => note(o, fmt.green(o, `Deleted project ${projectId}.`))
-    );
-  });
-  projects.command("favorite <project_id>").description("Star or unstar a project").option("--remove", "unstar instead of star").action(async function(projectId) {
-    const ctx = buildContext(this);
-    const favorite = !this.opts().remove;
-    const result = await ctx.client.callTool("set_project_favorite", {
-      project_id: projectId,
-      favorite
-    });
-    emit(
-      ctx.out,
-      result,
-      (o) => note(o, favorite ? "Starred." : "Unstarred.")
-    );
-  });
-  projects.command("open <project_id>").description("Open the project in your browser").action(async function(projectId) {
-    const ctx = buildContext(this);
-    const result = await ctx.client.callTool("get_project", {
-      project_id: projectId,
-      view: "summary"
-    });
-    const url = result?.urls?.storyboard ?? result?.urls?.script ?? `${ctx.baseUrl}/projects/${projectId}`;
-    const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
-    try {
-      const child = spawn2(cmd, [url], {
-        stdio: "ignore",
-        detached: true,
-        shell: process.platform === "win32"
-      });
-      child.on("error", () => {
-      });
-      child.unref();
-    } catch {
-    }
-    emit(ctx.out, { url }, (o) => note(o, url));
-  });
-  const checkpoint = program.command("checkpoint").description("Project version checkpoints");
-  checkpoint.command("create <project_id>").description("Snapshot the project as a new version").option("--name <name>", "version name").option("--description <text>", "version description").action(async function(projectId) {
-    const ctx = buildContext(this);
-    const opts = this.opts();
-    const result = await ctx.client.callTool(
-      "create_project_checkpoint",
-      compact({
-        project_id: projectId,
-        name: opts.name,
-        description: opts.description
-      })
-    );
-    emit(ctx.out, result);
-  });
-  checkpoint.command("list <project_id>").description("List a project's checkpoints").action(async function(projectId) {
-    const ctx = buildContext(this);
-    const result = await ctx.client.callTool("list_project_checkpoints", {
-      project_id: projectId
-    });
-    emit(ctx.out, result);
-  });
-  checkpoint.command("restore <project_id> [version_number]").description(
-    "Restore a project to a saved version (current state is snapshotted first)"
-  ).option(
-    "--checkpoint-id <id>",
-    "restore by checkpoint UUID instead of version number"
-  ).action(async function(projectId, versionNumber) {
-    const ctx = buildContext(this);
-    const opts = this.opts();
-    if (!versionNumber && !opts.checkpointId) {
-      throw new CliError(
-        "Pass a version_number or --checkpoint-id.",
-        EXIT.USAGE
-      );
-    }
-    const result = await ctx.client.callTool(
-      "restore_project_checkpoint",
-      compact({
-        project_id: projectId,
-        version_number: versionNumber ? Number(versionNumber) : void 0,
-        checkpoint_id: opts.checkpointId
-      })
-    );
-    emit(ctx.out, result);
-  });
-}
-
 // src/commands/generate.ts
 import fs9 from "fs";
 import path8 from "path";
@@ -3950,12 +3449,23 @@ var ELEVENLABS_MUSIC_MODELS = [
 ];
 var ELEVENLABS_MUSIC_V1 = "elevenlabs-music-v1";
 var MUSIC_REFERENCE_STRENGTHS = ["low", "medium", "high", "xhigh"];
+var VOICEOVER_MODES = ["standard", "turbo"];
 var UUID_RE3 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 function normalizeGeminiOmniResolutionOption(value) {
   if (typeof value !== "string") return void 0;
   const normalized = value.trim().toLowerCase();
   return normalized === "360p" || normalized === "720p" || normalized === "1080p" || normalized === "4k" ? normalized : void 0;
 }
+function parseVoiceoverMode(value, flag) {
+  if (value === void 0) return void 0;
+  if (!VOICEOVER_MODES.includes(value)) {
+    throw new CliError(
+      `${flag} must be one of: ${VOICEOVER_MODES.join(", ")}.`,
+      EXIT.USAGE
+    );
+  }
+  return value;
+}
 function inferDubMediaType(source, explicit) {
   if (explicit) {
     if (explicit === "audio" || explicit === "video") return explicit;
@@ -4428,10 +3938,23 @@ async function handleAsyncJob(ctx, submitted, options) {
     throw err;
   }
 }
+function parseImageColor(value) {
+  if (!/^#?[0-9a-f]{6}$/i.test(value))
+    throw new CliError(
+      "Colors must be six hexadecimal digits, e.g. #7f3f98.",
+      EXIT.USAGE
+    );
+  const hex = value.replace(/^#/, "");
+  return {
+    r: parseInt(hex.slice(0, 2), 16),
+    g: parseInt(hex.slice(2, 4), 16),
+    b: parseInt(hex.slice(4, 6), 16)
+  };
+}
 function registerGenerateCommands(program) {
   const generate = program.command("generate").description("Generate images, video, audio and 3D assets");
   register3DGenerationCommand(generate);
-  generate.command("image <prompt...>").description("Generate an image (async; waits by default)").option(
+  generate.command("image [prompt...]").description("Generate an image (async; waits by default)").option(
     "--model <id|name>",
     "image model id or display name (default nano-banana-2); run `videodraft models image`"
   ).option("--ar <ratio>", 'aspect ratio, e.g. "16:9"').option("--resolution <res>", 'e.g. "1K", "2K", "4K"').option(
@@ -4440,6 +3963,17 @@ function registerGenerateCommands(program) {
   ).option(
     "--rendering-speed <tier>",
     'Ideogram speed/cost tier, e.g. V4 "Turbo"/"Balanced"/"Quality"'
+  ).option("--temperature <n>", "Nano Banana Pro/2 creativity (0-2)").option(
+    "--google-search-grounding <true|false>",
+    "Nano Banana Pro/2 Google Search grounding"
+  ).option("--horizontal-angle <degrees>", "Qwen horizontal rotation (0-360)").option("--vertical-angle <degrees>", "Qwen elevation (-30 to 90)").option("--zoom <n>", "Qwen zoom (0-10)").option(
+    "--recraft-color <hex>",
+    "Recraft RGB palette color, e.g. #7f3f98 (repeat up to five)",
+    collect,
+    []
+  ).option(
+    "--recraft-background <hex>",
+    "Recraft background color, e.g. #ffffff"
   ).option("--num <n>", "variations of this prompt in one call (1-4)").option(
     "--seed <n>",
     "seed (supported models only, e.g. Flux, Ideogram V4)"
@@ -4465,6 +3999,34 @@ function registerGenerateCommands(program) {
     const ctx = buildContext(this);
     const opts = this.opts();
     const prompt = promptWords.join(" ");
+    const imageOptions = {
+      temperature: optionalRangedNumber(
+        opts.temperature,
+        "--temperature",
+        0,
+        2
+      ),
+      google_search_grounding: optionalBooleanChoice(
+        opts.googleSearchGrounding,
+        "--google-search-grounding"
+      ),
+      horizontal_angle: optionalRangedNumber(
+        opts.horizontalAngle,
+        "--horizontal-angle",
+        0,
+        360
+      ),
+      vertical_angle: optionalRangedNumber(
+        opts.verticalAngle,
+        "--vertical-angle",
+        -30,
+        90
+      ),
+      zoom: optionalRangedNumber(opts.zoom, "--zoom", 0, 10),
+      recraft_colors: opts.recraftColor?.length ? opts.recraftColor.map(parseImageColor) : void 0,
+      recraft_background_color: opts.recraftBackground ? parseImageColor(opts.recraftBackground) : void 0
+    };
+    const imageSeed = optionalSeed(opts.seed);
     if (opts.estimate) {
       await printEstimate(ctx, {
         // Cost lookup needs a concrete model. Keep runtime generation
@@ -4497,6 +4059,7 @@ function registerGenerateCommands(program) {
     const submitted = await ctx.client.callTool(
       "generate_image",
       compact({
+        ...imageOptions,
         prompt,
         model: opts.model,
         aspect_ratio: opts.ar,
@@ -4504,7 +4067,7 @@ function registerGenerateCommands(program) {
         quality: opts.quality,
         rendering_speed: opts.renderingSpeed,
         num_images: opts.num ? Number(opts.num) : void 0,
-        seed: opts.seed ? Number(opts.seed) : void 0,
+        seed: imageSeed,
         reference_images: refs.length > 0 ? refs : void 0,
         video_url: videoRef,
         style: opts.style,
@@ -4527,7 +4090,7 @@ function registerGenerateCommands(program) {
     "video model id (task-aware when omitted; Grok 1.5 supports text, first frame, or 1-7 image refs)"
   ).option("--ar <ratio>", 'aspect ratio, e.g. "16:9", "9:16"').option("--duration <seconds>", "clip duration in seconds").option(
     "--auto-duration",
-    "Wan 3.0 only: provider selects 2-30s; reserves 30s and reconciles unused credits"
+    "Wan 3.0, Seedance 2/2.5, FLUX 3 or Gemini Omni: automatic duration, reserves the model ceiling and reconciles unused credits"
   ).option("--resolution <res>", 'e.g. "360p", "720p", "1080p", "2K", "4K"').option(
     "--quality <tier>",
     'e.g. "mini", "fast", "standard", "quality", "pro"'
@@ -4581,7 +4144,7 @@ function registerGenerateCommands(program) {
     "multi-prompt segment (repeatable; Kling 3.0 / 3.0 Turbo / O3)",
     collect,
     []
-  ).option("--negative <text>", "negative prompt (Kling/Luma; not Wan 3.0)").option("--camera-fixed", "Seedance 1.5 Pro: lock camera motion").option(
+  ).option("--cfg-scale <n>", "Kling 3.0/2.5 Pro prompt adherence (0-1)").option("--negative <text>", "negative prompt (Kling/Luma; not Wan 3.0)").option("--camera-fixed", "Seedance 1.5 Pro: lock camera motion").option(
     "--prompt-expansion <true|false>",
     "Wan 3.0 only: enable or disable prompt expansion (default true)"
   ).option(
@@ -4589,7 +4152,7 @@ function registerGenerateCommands(program) {
     "MiniMax H3 Max only: disabled, balanced (default), or quality"
   ).option(
     "--safety-checker <true|false>",
-    "MiniMax H3 Max only: opt into provider safety checking (off by default)"
+    "MiniMax H3 Max / Happy Horse: opt into provider safety checking (off by default)"
   ).option(
     "--thinking",
     "Wan 3.0 only: enable provider thinking; required with --file-url/--web-url"
@@ -4665,6 +4228,24 @@ function registerGenerateCommands(program) {
       );
     }
     const seed = optionalSeed(opts.seed);
+    const cfgScale = optionalRangedNumber(opts.cfgScale, "--cfg-scale", 0, 1);
+    if (cfgScale !== void 0 && !["kling-3.0", "kling-2.5-pro"].includes(opts.model))
+      throw new CliError(
+        "--cfg-scale requires --model kling-3.0 or kling-2.5-pro.",
+        EXIT.USAGE
+      );
+    if (opts.autoDuration && duration !== void 0)
+      throw new CliError(
+        "--auto-duration and --duration are mutually exclusive.",
+        EXIT.USAGE
+      );
+    const isFlux3Request = ["flux-3", "flux3", "flux_3"].includes(opts.model);
+    const flux3FixedFrameMode = isFlux3Request && (Boolean(opts.startImage && opts.endImage) || (opts.keyframe?.length ?? 0) > 0);
+    if (isFlux3Request && opts.autoDuration && (opts.endImage || (opts.keyframe?.length ?? 0) > 0))
+      throw new CliError(
+        "FLUX 3 --auto-duration supports only text and first-frame generation.",
+        EXIT.USAGE
+      );
     const rawElements = parseKlingElements(opts.element ?? []);
     const voiceIds = opts.voiceId ?? [];
     const segments = parseSegments(opts.segment ?? []);
@@ -4704,7 +4285,16 @@ function registerGenerateCommands(program) {
         EXIT.USAGE
       );
     }
-    const hasWan3OnlyControls = opts.autoDuration === true || promptExpansion !== void 0 || opts.thinking === true || Boolean(opts.fileUrl) || Boolean(opts.webUrl);
+    const hasWan3OnlyControls = opts.autoDuration === true && ![
+      "seedance-2",
+      "seedance2",
+      "seedance-2.5",
+      "seedance25",
+      "flux-3",
+      "flux3",
+      "flux_3",
+      "gemini-omni-1.1-flash"
+    ].includes(opts.model) || promptExpansion !== void 0 || opts.thinking === true || Boolean(opts.fileUrl) || Boolean(opts.webUrl);
     const hasH3MaxOnlyControls = promptExpansionMode !== void 0 || safetyChecker !== void 0;
     const hasGeminiOmniOnlyControls = Boolean(opts.sourceVideo) || Boolean(opts.previousInteractionId) || Boolean(opts.videoTask) || opts.extend === true || referenceVideoDurations.length > 0;
     if (!opts.model && hasGeminiOmniOnlyControls) {
@@ -5068,9 +4658,9 @@ function registerGenerateCommands(program) {
         EXIT.USAGE
       );
     }
-    if (opts.model !== "minimax-h3-max" && hasH3MaxOnlyControls) {
+    if (opts.model !== "minimax-h3-max" && (promptExpansionMode !== void 0 || safetyChecker !== void 0 && opts.model !== "happy-horse")) {
       throw new CliError(
-        "--prompt-expansion-mode and --safety-checker are supported only by --model minimax-h3-max.",
+        "--prompt-expansion-mode requires --model minimax-h3-max; --safety-checker supports minimax-h3-max and happy-horse.",
         EXIT.USAGE
       );
     }
@@ -5256,334 +4846,819 @@ function registerGenerateCommands(program) {
         );
       }
     }
-    if (opts.estimate) {
-      const estimateModel = estimateVideoModel(opts, duration);
-      const refVideoWindow = refVideoSecondsWindow(estimateModel);
-      if (refVideoSeconds !== void 0 && refVideoWindow !== null && refVideoSeconds > refVideoWindow) {
-        throw new CliError(
-          `--ref-video-seconds must be from 0 to ${refVideoWindow} for ${estimateModel}.`,
-          EXIT.USAGE
-        );
-      }
-      const estimateReferenceImageCount = estimateModel === "minimax-h3" ? Array.isArray(opts.ref) ? opts.ref.length : 0 : (
-        // H3 Max prices reference images as pooled tokens, so send the
-        // count only when there is one; a plain text quote stays clean.
-        estimateModel === "minimax-h3-max" ? Array.isArray(opts.ref) && opts.ref.length > 0 ? opts.ref.length : void 0 : estimateModel === "grok-imagine-video-1.5" ? Array.isArray(opts.ref) && opts.ref.length > 0 ? opts.ref.length : opts.startImage ? 1 : 0 : void 0
+    if (opts.estimate) {
+      const estimateModel = estimateVideoModel(opts, duration);
+      const refVideoWindow = refVideoSecondsWindow(estimateModel);
+      if (refVideoSeconds !== void 0 && refVideoWindow !== null && refVideoSeconds > refVideoWindow) {
+        throw new CliError(
+          `--ref-video-seconds must be from 0 to ${refVideoWindow} for ${estimateModel}.`,
+          EXIT.USAGE
+        );
+      }
+      const estimateReferenceImageCount = estimateModel === "minimax-h3" ? Array.isArray(opts.ref) ? opts.ref.length : 0 : (
+        // H3 Max prices reference images as pooled tokens, so send the
+        // count only when there is one; a plain text quote stays clean.
+        estimateModel === "minimax-h3-max" ? Array.isArray(opts.ref) && opts.ref.length > 0 ? opts.ref.length : void 0 : estimateModel === "grok-imagine-video-1.5" ? Array.isArray(opts.ref) && opts.ref.length > 0 ? opts.ref.length : opts.startImage ? 1 : 0 : void 0
+      );
+      const hasRefVideos = Array.isArray(opts.refVideo) && opts.refVideo.length > 0;
+      const estimateReferenceVideoDuration = estimateModel === "minimax-h3" ? hasRefVideos ? refVideoSeconds : 0 : refVideoWindow !== null && hasRefVideos ? refVideoSeconds : void 0;
+      const h3MaxMissingDurationFlags = estimateModel === "minimax-h3-max" ? [
+        hasRefVideos && refVideoSeconds === void 0 ? "--ref-video-seconds" : null,
+        Array.isArray(opts.refAudio) && opts.refAudio.length > 0 && refAudioSeconds === void 0 ? "--ref-audio-seconds" : null
+      ].filter((flag) => flag !== null) : [];
+      const h3MaxHasImageRefs = estimateModel === "minimax-h3-max" && Array.isArray(opts.ref) && opts.ref.length > 0;
+      const h3MaxLowerBoundReason = h3MaxMissingDurationFlags.length > 0 || h3MaxHasImageRefs ? [
+        "minimax-h3-max bills reference media as pooled tokens.",
+        h3MaxMissingDurationFlags.length > 0 ? `Pass ${h3MaxMissingDurationFlags.join(" and ")} for an exact quote.` : null,
+        h3MaxHasImageRefs ? "Reference images are priced on their measured pixel area, so this quote assumes 1024x1024 and the charge may be higher." : null
+      ].filter(Boolean).join(" ") : void 0;
+      const estimateDuration = (segments.length > 0 ? segmentDuration : duration) ?? // The generic FLUX quote assumes text/first-frame auto generation.
+      // Fixed-frame modes instead default to five seconds in the MCP
+      // request builder, and their mode is not sent to get_model_costs.
+      (flux3FixedFrameMode ? 5 : estimateModel === "grok-imagine-video-1.5" ? Array.isArray(opts.ref) && opts.ref.length > 0 ? 8 : 6 : !opts.model && estimateModel === "google-veo3.1" ? Array.isArray(opts.ref) && opts.ref.length > 0 ? 8 : 6 : void 0);
+      await printEstimate(ctx, {
+        model: estimateModel,
+        type: "video",
+        duration: estimateDuration,
+        autoDuration: opts.autoDuration === true,
+        resolution: opts.resolution,
+        quality: opts.quality,
+        audio: opts.audio,
+        referenceImageCount: estimateReferenceImageCount,
+        referenceVideoDurationSeconds: estimateReferenceVideoDuration,
+        referenceAudioDurationSeconds: estimateModel === "minimax-h3-max" && Array.isArray(opts.refAudio) && opts.refAudio.length > 0 ? refAudioSeconds : void 0,
+        // H3 Max bills reference video and audio as pooled tokens, so a
+        // quote that cannot see their durations omits a real surcharge.
+        lowerBoundReason: h3MaxLowerBoundReason,
+        voiceControl: voiceIds.length > 0 || rawElements.some((element) => element.voice_id),
+        allowRealPeople: opts.allowRealPeople
+      });
+      return;
+    }
+    const [
+      refs,
+      refVideos,
+      refAudios,
+      startImage,
+      endImage,
+      sourceVideo,
+      elements
+    ] = await Promise.all([
+      resolveRefs(ctx, opts.ref ?? []),
+      resolveRefs(ctx, opts.refVideo ?? []),
+      resolveRefs(ctx, opts.refAudio ?? []),
+      opts.startImage ? resolveRefs(ctx, [opts.startImage]).then((r) => r[0]) : void 0,
+      opts.endImage ? resolveRefs(ctx, [opts.endImage]).then((r) => r[0]) : void 0,
+      opts.sourceVideo ? resolveRefs(ctx, [opts.sourceVideo]).then((r) => r[0]) : void 0,
+      resolveKlingElements(ctx, rawElements)
+    ]);
+    const parsedKeyframes = parseKeyframes(opts.keyframe ?? []);
+    const keyframes = parsedKeyframes.length > 0 ? await resolveRefs(
+      ctx,
+      parsedKeyframes.map((keyframe) => keyframe.source)
+    ).then(
+      (urls) => parsedKeyframes.map((keyframe, index) => ({
+        image_url: urls[index],
+        time_seconds: keyframe.time_seconds
+      }))
+    ) : [];
+    if (!prompt && segments.length === 0 && !startImage && keyframes.length === 0 && refs.length === 0 && refVideos.length === 0 && refAudios.length === 0 && !sourceVideo && !opts.fileUrl && !opts.webUrl && !opts.previousInteractionId) {
+      throw new CliError(
+        "Provide a prompt, --segment, a frame, or a reference source.",
+        EXIT.USAGE
+      );
+    }
+    capture("cli_generate", {
+      kind: "video",
+      model: opts.model ?? "default",
+      wait: opts.wait !== false
+    });
+    const videoEditModels = /* @__PURE__ */ new Set([
+      "happy-horse-video-edit",
+      "grok-imagine-video-edit"
+    ]);
+    const motionControlModels = /* @__PURE__ */ new Set([
+      "kling-v3-motion-control",
+      "kling-2.6-motion-control"
+    ]);
+    let toolName = "generate_video";
+    let toolArgs;
+    if (videoEditModels.has(opts.model)) {
+      if (refVideos.length !== 1) {
+        throw new CliError(
+          `${opts.model} requires exactly one --ref-video source. You can also use videodraft edit video.`,
+          EXIT.USAGE
+        );
+      }
+      if (startImage || endImage || refAudios.length > 0 || segments.length > 0 || opts.ar || opts.negative || opts.cameraFixed || opts.seed || elements.length > 0 || voiceIds.length > 0) {
+        throw new CliError(
+          `${opts.model} does not support --start-image, --end-image, --ref-audio, --element, --voice-id, --segment, --ar, --negative, --camera-fixed, or --seed in video-edit mode. Use --ref for supported reference images.`,
+          EXIT.USAGE
+        );
+      }
+      toolName = "edit_video";
+      toolArgs = {
+        model: opts.model,
+        prompt: prompt || void 0,
+        video_url: refVideos[0],
+        reference_images: refs.length > 0 ? refs : void 0,
+        resolution: opts.resolution,
+        quality: opts.quality,
+        duration_seconds: duration,
+        preserve_audio: opts.audio,
+        project_id: opts.project,
+        session_id: sessionArg(this, opts),
+        scene_index: opts.scene !== void 0 ? Number(opts.scene) : void 0,
+        shot_index: opts.shot !== void 0 ? Number(opts.shot) : void 0
+      };
+    } else if (motionControlModels.has(opts.model)) {
+      if (!startImage || refVideos.length !== 1) {
+        throw new CliError(
+          `${opts.model} requires --start-image plus exactly one --ref-video motion source. You can also use videodraft edit motion.`,
+          EXIT.USAGE
+        );
+      }
+      if (endImage || refs.length > 0 || refAudios.length > 0 || segments.length > 0 || opts.ar || opts.negative || opts.cameraFixed || opts.seed || opts.resolution || voiceIds.length > 0) {
+        throw new CliError(
+          `${opts.model} does not support --end-image, --ref, --ref-audio, --voice-id, --segment, --ar, --negative, --camera-fixed, --seed, or --resolution in motion-control mode.`,
+          EXIT.USAGE
+        );
+      }
+      if (duration !== void 0) {
+        throw new CliError(
+          `${opts.model} follows the motion video duration and orientation cap; use videodraft edit motion --estimate for a duration-based estimate.`,
+          EXIT.USAGE
+        );
+      }
+      toolName = "generate_motion_control_video";
+      const resolvedElement = elements[0];
+      toolArgs = {
+        model: opts.model,
+        prompt: prompt || void 0,
+        image_url: startImage,
+        motion_video_url: refVideos[0],
+        quality: opts.quality,
+        keep_original_sound: opts.audio,
+        character_orientation: elements.length > 0 ? "video" : void 0,
+        duration_seconds: duration,
+        project_id: opts.project,
+        session_id: sessionArg(this, opts),
+        scene_index: opts.scene !== void 0 ? Number(opts.scene) : void 0,
+        shot_index: opts.shot !== void 0 ? Number(opts.shot) : void 0,
+        element: elements.length === 1 && resolvedElement ? {
+          frontal_image_url: resolvedElement.frontal_image_url,
+          reference_image_urls: resolvedElement.reference_image_urls
+        } : void 0
+      };
+    } else {
+      toolArgs = {
+        prompt: prompt || void 0,
+        model: opts.model,
+        aspect_ratio: opts.ar,
+        duration_seconds: duration,
+        auto_duration: opts.autoDuration ? true : void 0,
+        resolution: opts.resolution,
+        quality: opts.quality,
+        generate_audio: opts.audio,
+        allow_real_people: opts.allowRealPeople,
+        start_image_url: startImage,
+        end_image_url: endImage,
+        reference_images: refs.length > 0 ? refs : void 0,
+        video_url: sourceVideo,
+        reference_videos: refVideos.length > 0 ? refVideos : void 0,
+        reference_video_durations: referenceVideoDurations.length > 0 ? referenceVideoDurations : void 0,
+        reference_audio: refAudios.length > 0 ? refAudios : void 0,
+        file_url: opts.fileUrl,
+        web_url: opts.webUrl,
+        previous_interaction_id: opts.previousInteractionId,
+        video_task: geminiVideoTask,
+        enable_prompt_expansion: promptExpansion,
+        prompt_expansion_mode: promptExpansionMode,
+        enable_safety_checker: safetyChecker,
+        enable_thinking: opts.thinking ? true : void 0,
+        elements: elements.length > 0 ? elements : void 0,
+        voice_ids: voiceIds.length > 0 ? voiceIds.map((voiceId) => voiceId.trim()) : void 0,
+        multi_prompt: segments.length > 0 ? segments : void 0,
+        keyframes: keyframes.length > 0 ? keyframes : void 0,
+        negative_prompt: opts.negative,
+        cfg_scale: cfgScale,
+        camera_fixed: opts.cameraFixed ? true : void 0,
+        seed,
+        project_id: opts.project,
+        session_id: sessionArg(this, opts),
+        scene_index: opts.scene !== void 0 ? Number(opts.scene) : void 0,
+        shot_index: opts.shot !== void 0 ? Number(opts.shot) : void 0
+      };
+    }
+    const submitted = await ctx.client.callTool(toolName, compact(toolArgs));
+    await handleAsyncJob(ctx, submitted, {
+      wait: opts.wait !== false,
+      download: opts.download,
+      label: "Generating video"
+    });
+  });
+  generate.command("audio <prompt...>").description(
+    "Generate or edit audio with ByteDance Seed Audio 1.0 (synchronous)"
+  ).option("--voice <id>", "preset Seed Audio voice or custom cloned voice id").option(
+    "--ref-audio <url|file>",
+    "reference audio for @Audio1..@Audio3 (repeatable; local files uploaded)",
+    collect,
+    []
+  ).option(
+    "--image <url|file>",
+    "reference image (cannot be combined with --ref-audio)"
+  ).option("--format <wav|mp3|pcm|ogg_opus>", "output format (default mp3)").option(
+    "--sample-rate <hz>",
+    "8000 | 16000 | 24000 | 32000 | 44100 | 48000 (default 24000)"
+  ).option("--speed <0.5-2>", "playback speed multiplier (default 1)").option("--volume <0.5-2>", "volume multiplier (default 1)").option("--pitch <-12-12>", "pitch in whole semitones (default 0)").option("--project <id>", "link to a project's AI Studio session").option(
+    "--session <id>",
+    "pin an AI Studio session id (default: the current connection scope; env VIDEODRAFT_SESSION)",
+    process.env.VIDEODRAFT_SESSION
+  ).option(
+    "--idempotency-key <uuid>",
+    "set a stable UUID for recovery after a process interruption"
+  ).option("--download <path>", "download the generated audio file").option(
+    "--estimate",
+    "show 19 credits/minute pricing and the 38-credit maximum reservation"
+  ).action(async function(promptWords) {
+    const ctx = buildContext(this);
+    const opts = this.opts();
+    const prompt = promptWords.join(" ").trim();
+    if (!prompt) {
+      throw new CliError("A Seed Audio prompt is required.", EXIT.USAGE);
+    }
+    if (prompt.length > SEED_AUDIO_PROMPT_MAX_CHARS) {
+      throw new CliError(
+        `Seed Audio prompts must be ${SEED_AUDIO_PROMPT_MAX_CHARS} characters or fewer.`,
+        EXIT.USAGE
       );
-      const hasRefVideos = Array.isArray(opts.refVideo) && opts.refVideo.length > 0;
-      const estimateReferenceVideoDuration = estimateModel === "minimax-h3" ? hasRefVideos ? refVideoSeconds : 0 : refVideoWindow !== null && hasRefVideos ? refVideoSeconds : void 0;
-      const h3MaxMissingDurationFlags = estimateModel === "minimax-h3-max" ? [
-        hasRefVideos && refVideoSeconds === void 0 ? "--ref-video-seconds" : null,
-        Array.isArray(opts.refAudio) && opts.refAudio.length > 0 && refAudioSeconds === void 0 ? "--ref-audio-seconds" : null
-      ].filter((flag) => flag !== null) : [];
-      const h3MaxHasImageRefs = estimateModel === "minimax-h3-max" && Array.isArray(opts.ref) && opts.ref.length > 0;
-      const h3MaxLowerBoundReason = h3MaxMissingDurationFlags.length > 0 || h3MaxHasImageRefs ? [
-        "minimax-h3-max bills reference media as pooled tokens.",
-        h3MaxMissingDurationFlags.length > 0 ? `Pass ${h3MaxMissingDurationFlags.join(" and ")} for an exact quote.` : null,
-        h3MaxHasImageRefs ? "Reference images are priced on their measured pixel area, so this quote assumes 1024x1024 and the charge may be higher." : null
-      ].filter(Boolean).join(" ") : void 0;
-      const estimateDuration = (segments.length > 0 ? segmentDuration : duration) ?? (estimateModel === "grok-imagine-video-1.5" ? Array.isArray(opts.ref) && opts.ref.length > 0 ? 8 : 6 : !opts.model && estimateModel === "google-veo3.1" ? Array.isArray(opts.ref) && opts.ref.length > 0 ? 8 : 6 : void 0);
+    }
+    const rawAudioRefs = opts.refAudio ?? [];
+    if (rawAudioRefs.length > SEED_AUDIO_MAX_REFERENCES) {
+      throw new CliError(
+        `Seed Audio accepts at most ${SEED_AUDIO_MAX_REFERENCES} --ref-audio values.`,
+        EXIT.USAGE
+      );
+    }
+    if (opts.image && rawAudioRefs.length > 0) {
+      throw new CliError(
+        "--image and --ref-audio cannot be used together.",
+        EXIT.USAGE
+      );
+    }
+    const outputFormat = opts.format ?? "mp3";
+    if (!SEED_AUDIO_FORMATS.includes(outputFormat)) {
+      throw new CliError(
+        `--format must be one of: ${SEED_AUDIO_FORMATS.join(", ")}.`,
+        EXIT.USAGE
+      );
+    }
+    const sampleRate = opts.sampleRate ? Number(opts.sampleRate) : 24e3;
+    if (!SEED_AUDIO_SAMPLE_RATES.includes(sampleRate)) {
+      throw new CliError(
+        `--sample-rate must be one of: ${SEED_AUDIO_SAMPLE_RATES.join(", ")}.`,
+        EXIT.USAGE
+      );
+    }
+    const speed = optionalRangedNumber(opts.speed, "--speed", 0.5, 2);
+    const volume = optionalRangedNumber(opts.volume, "--volume", 0.5, 2);
+    const pitch = optionalRangedNumber(opts.pitch, "--pitch", -12, 12, true);
+    const idempotencyKey = opts.idempotencyKey ?? randomUUID4();
+    if (!UUID_RE3.test(idempotencyKey)) {
+      throw new CliError(
+        "--idempotency-key must be a valid UUID.",
+        EXIT.USAGE
+      );
+    }
+    if (opts.estimate) {
       await printEstimate(ctx, {
-        model: estimateModel,
-        type: "video",
-        duration: estimateDuration,
-        autoDuration: opts.autoDuration === true,
-        resolution: opts.resolution,
-        quality: opts.quality,
-        audio: opts.audio,
-        referenceImageCount: estimateReferenceImageCount,
-        referenceVideoDurationSeconds: estimateReferenceVideoDuration,
-        referenceAudioDurationSeconds: estimateModel === "minimax-h3-max" && Array.isArray(opts.refAudio) && opts.refAudio.length > 0 ? refAudioSeconds : void 0,
-        // H3 Max bills reference video and audio as pooled tokens, so a
-        // quote that cannot see their durations omits a real surcharge.
-        lowerBoundReason: h3MaxLowerBoundReason,
-        voiceControl: voiceIds.length > 0 || rawElements.some((element) => element.voice_id),
-        allowRealPeople: opts.allowRealPeople
+        model: "seed-audio-1.0",
+        type: "audio"
       });
       return;
     }
-    const [
-      refs,
-      refVideos,
-      refAudios,
-      startImage,
-      endImage,
-      sourceVideo,
-      elements
-    ] = await Promise.all([
-      resolveRefs(ctx, opts.ref ?? []),
-      resolveRefs(ctx, opts.refVideo ?? []),
-      resolveRefs(ctx, opts.refAudio ?? []),
-      opts.startImage ? resolveRefs(ctx, [opts.startImage]).then((r) => r[0]) : void 0,
-      opts.endImage ? resolveRefs(ctx, [opts.endImage]).then((r) => r[0]) : void 0,
-      opts.sourceVideo ? resolveRefs(ctx, [opts.sourceVideo]).then((r) => r[0]) : void 0,
-      resolveKlingElements(ctx, rawElements)
+    const [audioUrls, imageUrl] = await Promise.all([
+      resolveRefs(ctx, rawAudioRefs),
+      opts.image ? resolveRefs(ctx, [opts.image]).then((urls2) => urls2[0]) : void 0
     ]);
-    const parsedKeyframes = parseKeyframes(opts.keyframe ?? []);
-    const keyframes = parsedKeyframes.length > 0 ? await resolveRefs(
-      ctx,
-      parsedKeyframes.map((keyframe) => keyframe.source)
-    ).then(
-      (urls) => parsedKeyframes.map((keyframe, index) => ({
-        image_url: urls[index],
-        time_seconds: keyframe.time_seconds
-      }))
-    ) : [];
-    if (!prompt && segments.length === 0 && !startImage && keyframes.length === 0 && refs.length === 0 && refVideos.length === 0 && refAudios.length === 0 && !sourceVideo && !opts.fileUrl && !opts.webUrl && !opts.previousInteractionId) {
+    capture("cli_generate", { kind: "audio", model: "seed-audio-1.0" });
+    const toolArgs = compact({
+      prompt,
+      voice: opts.voice,
+      audio_urls: audioUrls.length > 0 ? audioUrls : void 0,
+      image_url: imageUrl,
+      output_format: outputFormat,
+      sample_rate: sampleRate,
+      speed,
+      volume,
+      pitch,
+      project_id: opts.project,
+      session_id: sessionArg(this, opts),
+      idempotency_key: idempotencyKey
+    });
+    let result;
+    try {
+      result = await callAudioWithRetry(
+        () => ctx.client.callTool("generate_audio", toolArgs)
+      );
+    } catch (error) {
+      const hint = isRetryableAudioError(error) ? `Retry this exact request with --idempotency-key ${idempotencyKey}` : void 0;
+      if (error instanceof CliError) {
+        if (hint) error.hint = hint;
+        throw error;
+      }
       throw new CliError(
-        "Provide a prompt, --segment, a frame, or a reference source.",
-        EXIT.USAGE
+        error instanceof Error ? error.message : "Audio generation failed",
+        EXIT.ERROR,
+        hint
       );
     }
-    capture("cli_generate", {
-      kind: "video",
-      model: opts.model ?? "default",
-      wait: opts.wait !== false
-    });
-    const videoEditModels = /* @__PURE__ */ new Set([
-      "happy-horse-video-edit",
-      "grok-imagine-video-edit"
-    ]);
-    const motionControlModels = /* @__PURE__ */ new Set([
-      "kling-v3-motion-control",
-      "kling-2.6-motion-control"
-    ]);
-    let toolName = "generate_video";
-    let toolArgs;
-    if (videoEditModels.has(opts.model)) {
-      if (refVideos.length !== 1) {
+    const urls = extractOutputUrls(result);
+    let downloaded;
+    if (opts.download && urls.length > 0) {
+      downloaded = await downloadOutputs(urls, opts.download, {
+        name: "seed-audio"
+      });
+    }
+    const media = buildMediaDescriptors(urls, "audio");
+    emit(
+      ctx.out,
+      { ...result, downloaded_files: downloaded, output_media: media },
+      (o) => {
+        for (const url of urls) process.stdout.write(`${url}
+`);
+        for (const file of downloaded ?? []) {
+          note(o, fmt.dim(o, savedLine(file)));
+        }
+      }
+    );
+  });
+  generate.command("voiceover <text...>").description(
+    "Generate TTS audio (synchronous, returns an audio URL). ElevenLabs voices run on Eleven v4"
+  ).option(
+    "--voice <id>",
+    "TTS voice ID; accepts raw ElevenLabs IDs or elevenlabs-<id>, including voices outside `videodraft models voices`; must be accessible to the provider account"
+  ).option(
+    "--mode <standard|turbo>",
+    "ElevenLabs voices only: standard (default; Eleven v4, best quality, 10 credits per 1000 chars) | turbo (Eleven v4 Turbo, faster, 5 credits per 1000 chars). Google, OpenAI and cloned custom-* voices ignore it"
+  ).option("--language <bcp47>", 'target language, default "en"').option("--project <id>", "attach to a project").option(
+    "--scene <n>",
+    "0-based scene index; wires the audio onto that scene"
+  ).option(
+    "--session <id>",
+    "pin an AI Studio session id (default: the current connection scope; env VIDEODRAFT_SESSION)",
+    process.env.VIDEODRAFT_SESSION
+  ).option("--download <path>", "download the audio file").action(async function(textWords) {
+    const ctx = buildContext(this);
+    const opts = this.opts();
+    const mode = parseVoiceoverMode(opts.mode, "--mode");
+    capture("cli_generate", { kind: "voiceover" });
+    const result = await ctx.client.callTool(
+      "generate_voiceover",
+      compact({
+        text: textWords.join(" "),
+        voice_id: opts.voice,
+        mode,
+        target_language: opts.language,
+        project_id: opts.project,
+        session_id: sessionArg(this, opts),
+        scene_index: opts.scene !== void 0 ? Number(opts.scene) : void 0
+      })
+    );
+    const urls = extractOutputUrls(result);
+    let downloaded;
+    if (opts.download && urls.length > 0) {
+      downloaded = await downloadOutputs(urls, opts.download, {
+        name: "voiceover"
+      });
+    }
+    const media = buildMediaDescriptors(urls, "audio");
+    emit(
+      ctx.out,
+      { ...result, downloaded_files: downloaded, output_media: media },
+      (o) => {
+        for (const url of urls) process.stdout.write(`${url}
+`);
+        for (const f of downloaded ?? []) note(o, fmt.dim(o, savedLine(f)));
+      }
+    );
+  });
+  generate.command("music [prompt...]").description(
+    "Generate music (Lyria 3.5 for any length, vocals or instrumental; ElevenLabs for exact timing and composition plans)"
+  ).option(
+    "--model <id>",
+    "omit for the server default (lyria-3.5 where the backend supports it) | lyria-3.5 (short or long, 10 credits) | lyria-3-clip-preview (fixed 30s, 4 credits) | lyria-3-pro-preview (legacy) | elevenlabs-music-v2.5 | elevenlabs-music-v1 (elevenlabs-music means v2.5)"
+  ).option(
+    "--length <seconds>",
+    "ElevenLabs prompt mode: length 3-300s (default 30)"
+  ).option(
+    "--instrumental",
+    "ElevenLabs prompt mode: force instrumental (no vocals)"
+  ).option(
+    "--plan <file|json>",
+    'ElevenLabs v2.5: composition plan JSON ({"chunks":[...]}) as a file or inline; replaces the prompt. Local audio_reference paths are uploaded. Picks elevenlabs-music-v2.5 when --model is omitted'
+  ).option(
+    "--section <spec>",
+    'ElevenLabs v2.5: add a plan chunk "<seconds>|<style, style>|<text>" (repeatable; \\n for line breaks; empty seconds = 20, empty text = instrumental), e.g. "20|synthwave,female vocals|[Verse 1]\\nNeon rain". Picks elevenlabs-music-v2.5 when --model is omitted',
+    collect,
+    []
+  ).option(
+    "--ref-audio <url|file>",
+    "ElevenLabs v2.5 plan: style reference audio for the first chunk (local files uploaded)"
+  ).option("--ref-start <ms>", "reference window start in ms (default 0)").option(
+    "--ref-end <ms>",
+    "reference window end in ms (window up to 30000 ms)"
+  ).option(
+    "--ref-strength <level>",
+    "how closely to follow the reference: low | medium | high | xhigh"
+  ).option("--seed <n>", "ElevenLabs v2.5 plan: random seed (0-4294967295)").option(
+    "--format <output_format>",
+    "ElevenLabs output format, e.g. mp3_48000_192 (v2.5 default), mp3_44100_128 (v1 default), opus_48000_128, pcm_44100 (WAV)"
+  ).option(
+    "--idempotency-key <uuid>",
+    "ElevenLabs: stable UUID for recovery after an interruption"
+  ).option(
+    "--ref <url|file>",
+    "reference image to inspire the music (Lyria only; max 10 on Google, 1 with Fal BYOK)",
+    collect,
+    []
+  ).option(
+    "--project <id>",
+    "link the generation to a project's AI Studio session"
+  ).option(
+    "--attach <project_id>",
+    "also set the track as that project's background music"
+  ).option("--volume <n>", "0-100 BGM volume when attaching (default 30)").option(
+    "--bgm-disabled",
+    "when attaching, store the BGM as disabled (enabled:false)"
+  ).option(
+    "--session <id>",
+    "pin an AI Studio session id (default: the current connection scope; env VIDEODRAFT_SESSION)",
+    process.env.VIDEODRAFT_SESSION
+  ).option("--download <path>", "download the audio file").option("--estimate", "show the credit quote and exit without generating").action(async function(promptWords) {
+    const ctx = buildContext(this);
+    const opts = this.opts();
+    const sections = opts.section ?? [];
+    const usesPlan = Boolean(opts.plan) || sections.length > 0;
+    const musicModel = opts.model ?? (usesPlan ? "elevenlabs-music-v2.5" : "lyria-3.5");
+    const usesServerDefault = !opts.model && !usesPlan;
+    const isElevenMusic = ELEVENLABS_MUSIC_MODELS.includes(musicModel);
+    const prompt = (promptWords ?? []).join(" ").trim();
+    const elevenOnlyFlags = [
+      ["--plan", opts.plan],
+      ["--section", sections.length > 0 ? true : void 0],
+      ["--ref-audio", opts.refAudio],
+      ["--seed", opts.seed],
+      ["--format", opts.format],
+      ["--idempotency-key", opts.idempotencyKey]
+    ].filter(([, value]) => value !== void 0 && value !== false);
+    if (!isElevenMusic) {
+      if (!LYRIA_MUSIC_MODELS.includes(musicModel)) {
         throw new CliError(
-          `${opts.model} requires exactly one --ref-video source. You can also use videodraft edit video.`,
+          `Unknown music model "${musicModel}". Use ${[...LYRIA_MUSIC_MODELS, ...ELEVENLABS_MUSIC_MODELS].join(", ")}.`,
           EXIT.USAGE
         );
       }
-      if (startImage || endImage || refAudios.length > 0 || segments.length > 0 || opts.ar || opts.negative || opts.cameraFixed || opts.seed || elements.length > 0 || voiceIds.length > 0) {
+      if (elevenOnlyFlags.length > 0) {
         throw new CliError(
-          `${opts.model} does not support --start-image, --end-image, --ref-audio, --element, --voice-id, --segment, --ar, --negative, --camera-fixed, or --seed in video-edit mode. Use --ref for supported reference images.`,
+          `${elevenOnlyFlags.map(([flag]) => flag).join(", ")} only work with ElevenLabs Music. Add --model elevenlabs-music-v2.5.`,
           EXIT.USAGE
         );
       }
-      toolName = "edit_video";
-      toolArgs = {
-        model: opts.model,
-        prompt: prompt || void 0,
-        video_url: refVideos[0],
-        reference_images: refs.length > 0 ? refs : void 0,
-        resolution: opts.resolution,
-        quality: opts.quality,
-        duration_seconds: duration,
-        preserve_audio: opts.audio,
-        project_id: opts.project,
-        session_id: sessionArg(this, opts),
-        scene_index: opts.scene !== void 0 ? Number(opts.scene) : void 0,
-        shot_index: opts.shot !== void 0 ? Number(opts.shot) : void 0
-      };
-    } else if (motionControlModels.has(opts.model)) {
-      if (!startImage || refVideos.length !== 1) {
+      if ((opts.ref ?? []).length > 10) {
         throw new CliError(
-          `${opts.model} requires --start-image plus exactly one --ref-video motion source. You can also use videodraft edit motion.`,
+          "Lyria accepts at most 10 --ref images on Google, or 1 with Fal BYOK.",
           EXIT.USAGE
         );
       }
-      if (endImage || refs.length > 0 || refAudios.length > 0 || segments.length > 0 || opts.ar || opts.negative || opts.cameraFixed || opts.seed || opts.resolution || voiceIds.length > 0) {
+      if (!prompt && (opts.ref ?? []).length === 0) {
         throw new CliError(
-          `${opts.model} does not support --end-image, --ref, --ref-audio, --voice-id, --segment, --ar, --negative, --camera-fixed, --seed, or --resolution in motion-control mode.`,
+          "A prompt or at least one --ref image is required.",
           EXIT.USAGE
         );
       }
-      if (duration !== void 0) {
+      if (opts.length !== void 0 || opts.instrumental) {
+        note(
+          ctx.out,
+          fmt.dim(
+            ctx.out,
+            "--length and --instrumental only apply to ElevenLabs Music. For Lyria, put duration and instrumental/no-vocals instructions in the prompt; timing is approximate."
+          )
+        );
+      }
+    } else {
+      if (usesPlan && musicModel === ELEVENLABS_MUSIC_V1) {
         throw new CliError(
-          `${opts.model} follows the motion video duration and orientation cap; use videodraft edit motion --estimate for a duration-based estimate.`,
+          "Composition plans need elevenlabs-music-v2.5; v1 only takes a prompt.",
+          EXIT.USAGE
+        );
+      }
+      if (opts.plan && sections.length > 0) {
+        throw new CliError("Use --plan or --section, not both.", EXIT.USAGE);
+      }
+      if (usesPlan && (prompt || opts.length || opts.instrumental)) {
+        throw new CliError(
+          "A composition plan replaces the prompt, --length and --instrumental; its length is the sum of its sections.",
+          EXIT.USAGE
+        );
+      }
+      if (!usesPlan && !prompt) {
+        throw new CliError(
+          "A prompt is required (or pass --plan / --section).",
+          EXIT.USAGE
+        );
+      }
+      if (!usesPlan && (opts.seed !== void 0 || opts.refAudio)) {
+        throw new CliError(
+          "--seed and --ref-audio need a composition plan (--plan or --section).",
+          EXIT.USAGE
+        );
+      }
+      if ((opts.ref ?? []).length > 0) {
+        throw new CliError(
+          "--ref images only work with Lyria. For ElevenLabs, use --ref-audio with a composition plan.",
           EXIT.USAGE
         );
       }
-      toolName = "generate_motion_control_video";
-      const resolvedElement = elements[0];
-      toolArgs = {
-        model: opts.model,
-        prompt: prompt || void 0,
-        image_url: startImage,
-        motion_video_url: refVideos[0],
-        quality: opts.quality,
-        keep_original_sound: opts.audio,
-        character_orientation: elements.length > 0 ? "video" : void 0,
-        duration_seconds: duration,
-        project_id: opts.project,
-        session_id: sessionArg(this, opts),
-        scene_index: opts.scene !== void 0 ? Number(opts.scene) : void 0,
-        shot_index: opts.shot !== void 0 ? Number(opts.shot) : void 0,
-        element: elements.length === 1 && resolvedElement ? {
-          frontal_image_url: resolvedElement.frontal_image_url,
-          reference_image_urls: resolvedElement.reference_image_urls
-        } : void 0
-      };
-    } else {
-      toolArgs = {
-        prompt: prompt || void 0,
-        model: opts.model,
-        aspect_ratio: opts.ar,
-        duration_seconds: duration,
-        auto_duration: opts.autoDuration ? true : void 0,
-        resolution: opts.resolution,
-        quality: opts.quality,
-        generate_audio: opts.audio,
-        allow_real_people: opts.allowRealPeople,
-        start_image_url: startImage,
-        end_image_url: endImage,
-        reference_images: refs.length > 0 ? refs : void 0,
-        video_url: sourceVideo,
-        reference_videos: refVideos.length > 0 ? refVideos : void 0,
-        reference_video_durations: referenceVideoDurations.length > 0 ? referenceVideoDurations : void 0,
-        reference_audio: refAudios.length > 0 ? refAudios : void 0,
-        file_url: opts.fileUrl,
-        web_url: opts.webUrl,
-        previous_interaction_id: opts.previousInteractionId,
-        video_task: geminiVideoTask,
-        enable_prompt_expansion: promptExpansion,
-        prompt_expansion_mode: promptExpansionMode,
-        enable_safety_checker: safetyChecker,
-        enable_thinking: opts.thinking ? true : void 0,
-        elements: elements.length > 0 ? elements : void 0,
-        voice_ids: voiceIds.length > 0 ? voiceIds.map((voiceId) => voiceId.trim()) : void 0,
-        multi_prompt: segments.length > 0 ? segments : void 0,
-        keyframes: keyframes.length > 0 ? keyframes : void 0,
-        negative_prompt: opts.negative,
-        camera_fixed: opts.cameraFixed ? true : void 0,
-        seed,
-        project_id: opts.project,
-        session_id: sessionArg(this, opts),
-        scene_index: opts.scene !== void 0 ? Number(opts.scene) : void 0,
-        shot_index: opts.shot !== void 0 ? Number(opts.shot) : void 0
-      };
-    }
-    const submitted = await ctx.client.callTool(toolName, compact(toolArgs));
-    await handleAsyncJob(ctx, submitted, {
-      wait: opts.wait !== false,
-      download: opts.download,
-      label: "Generating video"
-    });
-  });
-  generate.command("audio <prompt...>").description(
-    "Generate or edit audio with ByteDance Seed Audio 1.0 (synchronous)"
-  ).option("--voice <id>", "preset Seed Audio voice or custom cloned voice id").option(
-    "--ref-audio <url|file>",
-    "reference audio for @Audio1..@Audio3 (repeatable; local files uploaded)",
-    collect,
-    []
-  ).option(
-    "--image <url|file>",
-    "reference image (cannot be combined with --ref-audio)"
-  ).option("--format <wav|mp3|pcm|ogg_opus>", "output format (default mp3)").option(
-    "--sample-rate <hz>",
-    "8000 | 16000 | 24000 | 32000 | 44100 | 48000 (default 24000)"
-  ).option("--speed <0.5-2>", "playback speed multiplier (default 1)").option("--volume <0.5-2>", "volume multiplier (default 1)").option("--pitch <-12-12>", "pitch in whole semitones (default 0)").option("--project <id>", "link to a project's AI Studio session").option(
-    "--session <id>",
-    "pin an AI Studio session id (default: the current connection scope; env VIDEODRAFT_SESSION)",
-    process.env.VIDEODRAFT_SESSION
-  ).option(
-    "--idempotency-key <uuid>",
-    "set a stable UUID for recovery after a process interruption"
-  ).option("--download <path>", "download the generated audio file").option(
-    "--estimate",
-    "show 19 credits/minute pricing and the 38-credit maximum reservation"
-  ).action(async function(promptWords) {
-    const ctx = buildContext(this);
-    const opts = this.opts();
-    const prompt = promptWords.join(" ").trim();
-    if (!prompt) {
-      throw new CliError("A Seed Audio prompt is required.", EXIT.USAGE);
-    }
-    if (prompt.length > SEED_AUDIO_PROMPT_MAX_CHARS) {
-      throw new CliError(
-        `Seed Audio prompts must be ${SEED_AUDIO_PROMPT_MAX_CHARS} characters or fewer.`,
-        EXIT.USAGE
-      );
     }
-    const rawAudioRefs = opts.refAudio ?? [];
-    if (rawAudioRefs.length > SEED_AUDIO_MAX_REFERENCES) {
+    if (!opts.refAudio && (opts.refStart !== void 0 || opts.refEnd !== void 0 || opts.refStrength !== void 0)) {
       throw new CliError(
-        `Seed Audio accepts at most ${SEED_AUDIO_MAX_REFERENCES} --ref-audio values.`,
+        "--ref-start, --ref-end and --ref-strength need --ref-audio.",
         EXIT.USAGE
       );
     }
-    if (opts.image && rawAudioRefs.length > 0) {
+    if (opts.refStrength !== void 0 && !MUSIC_REFERENCE_STRENGTHS.includes(opts.refStrength)) {
       throw new CliError(
-        "--image and --ref-audio cannot be used together.",
+        `--ref-strength must be one of: ${MUSIC_REFERENCE_STRENGTHS.join(", ")}.`,
         EXIT.USAGE
       );
     }
-    const outputFormat = opts.format ?? "mp3";
-    if (!SEED_AUDIO_FORMATS.includes(outputFormat)) {
+    const lengthSeconds = isElevenMusic ? optionalRangedNumber(opts.length, "--length", 3, 300) : void 0;
+    const seed = optionalRangedNumber(
+      opts.seed,
+      "--seed",
+      0,
+      4294967295,
+      true
+    );
+    const refStart = optionalRangedNumber(
+      opts.refStart,
+      "--ref-start",
+      0,
+      Number.MAX_SAFE_INTEGER,
+      true
+    );
+    const refEnd = optionalRangedNumber(
+      opts.refEnd,
+      "--ref-end",
+      1,
+      Number.MAX_SAFE_INTEGER,
+      true
+    );
+    const idempotencyKey = isElevenMusic ? opts.idempotencyKey ?? randomUUID4() : void 0;
+    if (idempotencyKey && !UUID_RE3.test(idempotencyKey)) {
       throw new CliError(
-        `--format must be one of: ${SEED_AUDIO_FORMATS.join(", ")}.`,
+        "--idempotency-key must be a valid UUID.",
         EXIT.USAGE
       );
     }
-    const sampleRate = opts.sampleRate ? Number(opts.sampleRate) : 24e3;
-    if (!SEED_AUDIO_SAMPLE_RATES.includes(sampleRate)) {
-      throw new CliError(
-        `--sample-rate must be one of: ${SEED_AUDIO_SAMPLE_RATES.join(", ")}.`,
-        EXIT.USAGE
-      );
+    let planChunks;
+    let planBaseDir = process.cwd();
+    if (opts.plan) {
+      const loaded = loadMusicPlan(opts.plan);
+      planChunks = loaded.plan.chunks;
+      planBaseDir = loaded.baseDir;
+    } else if (sections.length > 0) {
+      planChunks = parseMusicSections(sections);
     }
-    const speed = optionalRangedNumber(opts.speed, "--speed", 0.5, 2);
-    const volume = optionalRangedNumber(opts.volume, "--volume", 0.5, 2);
-    const pitch = optionalRangedNumber(opts.pitch, "--pitch", -12, 12, true);
-    const idempotencyKey = opts.idempotencyKey ?? randomUUID4();
-    if (!UUID_RE3.test(idempotencyKey)) {
-      throw new CliError(
-        "--idempotency-key must be a valid UUID.",
-        EXIT.USAGE
-      );
+    if (planChunks && opts.refAudio) {
+      const firstChunk = planChunks[0];
+      if (firstChunk.audio_reference) {
+        throw new CliError(
+          "The plan's first chunk already has an audio_reference; drop --ref-audio or edit the plan.",
+          EXIT.USAGE
+        );
+      }
+      planChunks = [
+        {
+          ...firstChunk,
+          audio_reference: compact({
+            // A --ref-audio path is relative to where the command runs, not
+            // to the plan file, so pin it before the plan's base dir applies.
+            audio_url: URI_SCHEME.test(opts.refAudio) ? opts.refAudio : path8.resolve(opts.refAudio),
+            start_ms: refStart,
+            end_ms: refEnd,
+            strength: opts.refStrength
+          })
+        },
+        ...planChunks.slice(1)
+      ];
     }
     if (opts.estimate) {
+      const planSeconds = planChunks ? musicPlanSeconds(planChunks) : void 0;
       await printEstimate(ctx, {
-        model: "seed-audio-1.0",
-        type: "audio"
+        // Quote the model the server will actually default to.
+        model: usesServerDefault ? await serverDefaultMusicModel(ctx) : musicModel,
+        type: "audio",
+        duration: isElevenMusic ? planSeconds ?? lengthSeconds : void 0
       });
       return;
     }
-    const [audioUrls, imageUrl] = await Promise.all([
-      resolveRefs(ctx, rawAudioRefs),
-      opts.image ? resolveRefs(ctx, [opts.image]).then((urls2) => urls2[0]) : void 0
-    ]);
-    capture("cli_generate", { kind: "audio", model: "seed-audio-1.0" });
+    const refs = isElevenMusic ? [] : await resolveRefs(ctx, opts.ref ?? []);
+    const compositionPlan = planChunks ? {
+      chunks: await resolveMusicPlanReferences(
+        ctx,
+        planChunks,
+        planBaseDir
+      )
+    } : void 0;
+    capture("cli_generate", {
+      kind: "music",
+      model: usesServerDefault ? "server-default" : musicModel,
+      mode: compositionPlan ? "composition_plan" : "prompt"
+    });
     const toolArgs = compact({
-      prompt,
-      voice: opts.voice,
-      audio_urls: audioUrls.length > 0 ? audioUrls : void 0,
-      image_url: imageUrl,
-      output_format: outputFormat,
-      sample_rate: sampleRate,
-      speed,
-      volume,
-      pitch,
+      prompt: prompt || void 0,
+      model: usesServerDefault ? void 0 : musicModel,
+      length_seconds: lengthSeconds,
+      force_instrumental: isElevenMusic && opts.instrumental ? true : void 0,
+      composition_plan: compositionPlan,
+      seed,
+      output_format: opts.format,
+      idempotency_key: idempotencyKey,
+      image_urls: refs.length > 0 ? refs : void 0,
       project_id: opts.project,
-      session_id: sessionArg(this, opts),
-      idempotency_key: idempotencyKey
+      attach_to_project_id: opts.attach,
+      volume: opts.volume ? Number(opts.volume) : void 0,
+      enabled: opts.bgmDisabled ? false : void 0,
+      session_id: sessionArg(this, opts)
     });
     let result;
-    try {
-      result = await callAudioWithRetry(
-        () => ctx.client.callTool("generate_audio", toolArgs)
-      );
-    } catch (error) {
-      const hint = isRetryableAudioError(error) ? `Retry this exact request with --idempotency-key ${idempotencyKey}` : void 0;
-      if (error instanceof CliError) {
-        if (hint) error.hint = hint;
-        throw error;
+    if (isElevenMusic) {
+      try {
+        result = await callAudioWithRetry(
+          () => ctx.client.callTool("generate_music", toolArgs)
+        );
+      } catch (error) {
+        const hint = isRetryableAudioError(error) ? `Retry this exact request with --idempotency-key ${idempotencyKey}` : void 0;
+        if (error instanceof CliError) {
+          if (hint) error.hint = hint;
+          throw error;
+        }
+        throw new CliError(
+          error instanceof Error ? error.message : "Music generation failed",
+          EXIT.ERROR,
+          hint
+        );
       }
-      throw new CliError(
-        error instanceof Error ? error.message : "Audio generation failed",
-        EXIT.ERROR,
-        hint
+    } else {
+      result = await ctx.client.callTool("generate_music", toolArgs);
+    }
+    const urls = extractOutputUrls(result);
+    let downloaded;
+    if (opts.download && urls.length > 0) {
+      downloaded = await downloadOutputs(urls, opts.download, {
+        name: "music"
+      });
+    }
+    const media = buildMediaDescriptors(urls, "music");
+    emit(
+      ctx.out,
+      { ...result, downloaded_files: downloaded, output_media: media },
+      (o) => {
+        for (const url of urls) process.stdout.write(`${url}
+`);
+        for (const f of downloaded ?? []) note(o, fmt.dim(o, savedLine(f)));
+      }
+    );
+  });
+  generate.command("sound-effect <prompt...>").description("Generate a sound effect (ElevenLabs Sound Effects)").option("--duration <seconds>", "length 0.5\u201322s (default 5)").option("--influence <0-1>", "prompt influence (default 0.3)").option("--project <id>", "link to a project's AI Studio session").option(
+    "--session <id>",
+    "pin an AI Studio session id (default: the current connection scope; env VIDEODRAFT_SESSION)",
+    process.env.VIDEODRAFT_SESSION
+  ).option("--download <path>", "download the audio file").action(async function(promptWords) {
+    const ctx = buildContext(this);
+    const opts = this.opts();
+    capture("cli_generate", { kind: "sound_effect" });
+    const result = await ctx.client.callTool(
+      "generate_sound_effect",
+      compact({
+        prompt: promptWords.join(" "),
+        duration_seconds: opts.duration ? Number(opts.duration) : void 0,
+        prompt_influence: opts.influence ? Number(opts.influence) : void 0,
+        project_id: opts.project,
+        session_id: sessionArg(this, opts)
+      })
+    );
+    const urls = extractOutputUrls(result);
+    let downloaded;
+    if (opts.download && urls.length > 0) {
+      downloaded = await downloadOutputs(urls, opts.download, {
+        name: "sound-effect"
+      });
+    }
+    const media = buildMediaDescriptors(urls, "audio");
+    emit(
+      ctx.out,
+      { ...result, downloaded_files: downloaded, output_media: media },
+      (o) => {
+        for (const url of urls) process.stdout.write(`${url}
+`);
+        for (const f of downloaded ?? []) note(o, fmt.dim(o, savedLine(f)));
+      }
+    );
+  });
+  generate.command("dialogue").description(
+    "Generate multi-speaker dialogue (ElevenLabs Text-to-Dialogue). Repeat --line."
+  ).option(
+    "--line <voiceId:text>",
+    'a dialogue line as "voiceId:text" (repeatable); accepts raw ElevenLabs IDs or elevenlabs-<id>, including voices outside the catalog; must be accessible to the provider account',
+    collect,
+    []
+  ).option("--stability <0|0.5|1>", "voice stability").option("--language <iso>", "ISO 639-1 language code").option("--project <id>", "link to a project's AI Studio session").option(
+    "--session <id>",
+    "pin an AI Studio session id (default: the current connection scope; env VIDEODRAFT_SESSION)",
+    process.env.VIDEODRAFT_SESSION
+  ).option("--download <path>", "download the audio file").action(async function() {
+    const ctx = buildContext(this);
+    const opts = this.opts();
+    const lines = opts.line.map((raw) => {
+      const i = raw.indexOf(":");
+      if (i < 0) {
+        throw new Error(`--line must be "voiceId:text" (got "${raw}")`);
+      }
+      return {
+        voice_id: raw.slice(0, i).trim(),
+        text: raw.slice(i + 1).trim()
+      };
+    });
+    if (lines.length === 0)
+      throw new Error("at least one --line is required");
+    capture("cli_generate", { kind: "dialogue" });
+    const result = await ctx.client.callTool(
+      "generate_dialogue",
+      compact({
+        lines,
+        stability: opts.stability !== void 0 ? Number(opts.stability) : void 0,
+        language_code: opts.language,
+        project_id: opts.project,
+        session_id: sessionArg(this, opts)
+      })
+    );
+    const urls = extractOutputUrls(result);
+    let downloaded;
+    if (opts.download && urls.length > 0) {
+      downloaded = await downloadOutputs(urls, opts.download, {
+        name: "dialogue"
+      });
+    }
+    const media = buildMediaDescriptors(urls, "audio");
+    emit(
+      ctx.out,
+      { ...result, downloaded_files: downloaded, output_media: media },
+      (o) => {
+        for (const url of urls) process.stdout.write(`${url}
+`);
+        for (const f of downloaded ?? []) note(o, fmt.dim(o, savedLine(f)));
+      }
+    );
+  });
+  generate.command("voice-changer <audio>").description("Restyle speech into another ElevenLabs voice (Voice Changer)").option(
+    "--voice <id>",
+    "target ElevenLabs voice ID, raw or elevenlabs-<id>; catalog membership is not required, but provider account access is (default Brittney, or an account voice with ElevenLabs BYOK)"
+  ).option(
+    "--duration <seconds>",
+    "length of the source audio in seconds (required, max 300)"
+  ).option("--remove-noise", "remove background noise from the input").option("--project <id>", "link to a project's AI Studio session").option(
+    "--session <id>",
+    "pin an AI Studio session id (default: the current connection scope; env VIDEODRAFT_SESSION)",
+    process.env.VIDEODRAFT_SESSION
+  ).option("--download <path>", "download the audio file").action(async function(source) {
+    const ctx = buildContext(this);
+    const opts = this.opts();
+    if (!opts.duration) {
+      throw new Error(
+        "--duration <seconds> is required (length of the source audio)"
       );
     }
+    const [audioUrl] = await resolveRefs(ctx, [source]);
+    capture("cli_generate", { kind: "voice_changer" });
+    const result = await ctx.client.callTool(
+      "change_voice",
+      compact({
+        audio_url: audioUrl,
+        voice_id: opts.voice,
+        duration_seconds: Number(opts.duration),
+        remove_background_noise: opts.removeNoise ? true : void 0,
+        project_id: opts.project,
+        session_id: sessionArg(this, opts)
+      })
+    );
     const urls = extractOutputUrls(result);
     let downloaded;
     if (opts.download && urls.length > 0) {
       downloaded = await downloadOutputs(urls, opts.download, {
-        name: "seed-audio"
+        name: "voice-changed"
       });
     }
     const media = buildMediaDescriptors(urls, "audio");
@@ -5593,45 +5668,58 @@ function registerGenerateCommands(program) {
       (o) => {
         for (const url of urls) process.stdout.write(`${url}
 `);
-        for (const file of downloaded ?? []) {
-          note(o, fmt.dim(o, savedLine(file)));
-        }
+        for (const f of downloaded ?? []) note(o, fmt.dim(o, savedLine(f)));
       }
     );
   });
-  generate.command("voiceover <text...>").description("Generate TTS audio (synchronous \u2014 returns an audio URL)").option(
-    "--voice <id>",
-    "TTS voice ID; accepts raw ElevenLabs IDs or elevenlabs-<id>, including voices outside `videodraft models voices`; must be accessible to the provider account"
-  ).option("--language <bcp47>", 'target language, default "en"').option("--project <id>", "attach to a project").option(
-    "--scene <n>",
-    "0-based scene index; wires the audio onto that scene"
+  generate.command("dub <media>").description(
+    "Dub a video/audio file into another language (ElevenLabs Dubbing)"
+  ).option(
+    "--to <iso>",
+    "target language ISO 639-1 code, e.g. es or te (required)"
   ).option(
+    "--from <iso>",
+    "source language ISO 639-1 code (auto-detected if omitted)"
+  ).option("--type <audio|video>", "source media type override").option(
+    "--duration <seconds>",
+    "length of the source media in seconds (required, max 300)"
+  ).option("--speakers <n>", "number of speakers (auto-detected if omitted)").option("--project <id>", "link to a project's AI Studio session").option(
     "--session <id>",
     "pin an AI Studio session id (default: the current connection scope; env VIDEODRAFT_SESSION)",
     process.env.VIDEODRAFT_SESSION
-  ).option("--download <path>", "download the audio file").action(async function(textWords) {
+  ).option("--download <path>", "download the dubbed file").action(async function(source) {
     const ctx = buildContext(this);
     const opts = this.opts();
-    capture("cli_generate", { kind: "voiceover" });
+    if (!opts.to) throw new Error("--to <iso> (target language) is required");
+    if (!opts.duration) {
+      throw new Error(
+        "--duration <seconds> is required (length of the source media)"
+      );
+    }
+    const mediaType = inferDubMediaType(source, opts.type);
+    const [mediaUrl] = await resolveRefs(ctx, [source]);
+    capture("cli_generate", { kind: "dub" });
     const result = await ctx.client.callTool(
-      "generate_voiceover",
+      "dub_media",
       compact({
-        text: textWords.join(" "),
-        voice_id: opts.voice,
-        target_language: opts.language,
+        video_url: mediaType === "video" ? mediaUrl : void 0,
+        audio_url: mediaType === "audio" ? mediaUrl : void 0,
+        target_lang: opts.to,
+        source_lang: opts.from,
+        num_speakers: opts.speakers ? Number(opts.speakers) : void 0,
+        duration_seconds: Number(opts.duration),
         project_id: opts.project,
-        session_id: sessionArg(this, opts),
-        scene_index: opts.scene !== void 0 ? Number(opts.scene) : void 0
+        session_id: sessionArg(this, opts)
       })
     );
     const urls = extractOutputUrls(result);
     let downloaded;
     if (opts.download && urls.length > 0) {
       downloaded = await downloadOutputs(urls, opts.download, {
-        name: "voiceover"
+        name: "dubbed"
       });
     }
-    const media = buildMediaDescriptors(urls, "audio");
+    const media = buildMediaDescriptors(urls, mediaType);
     emit(
       ctx.out,
       { ...result, downloaded_files: downloaded, output_media: media },
@@ -5642,681 +5730,737 @@ function registerGenerateCommands(program) {
       }
     );
   });
-  generate.command("music [prompt...]").description(
-    "Generate music (Lyria 3.5 for any length, vocals or instrumental; ElevenLabs for exact timing and composition plans)"
-  ).option(
-    "--model <id>",
-    "omit for the server default (lyria-3.5 where the backend supports it) | lyria-3.5 (short or long, 10 credits) | lyria-3-clip-preview (fixed 30s, 4 credits) | lyria-3-pro-preview (legacy) | elevenlabs-music-v2.5 | elevenlabs-music-v1 (elevenlabs-music means v2.5)"
-  ).option(
-    "--length <seconds>",
-    "ElevenLabs prompt mode: length 3-300s (default 30)"
-  ).option(
-    "--instrumental",
-    "ElevenLabs prompt mode: force instrumental (no vocals)"
-  ).option(
-    "--plan <file|json>",
-    'ElevenLabs v2.5: composition plan JSON ({"chunks":[...]}) as a file or inline; replaces the prompt. Local audio_reference paths are uploaded. Picks elevenlabs-music-v2.5 when --model is omitted'
-  ).option(
-    "--section <spec>",
-    'ElevenLabs v2.5: add a plan chunk "<seconds>|<style, style>|<text>" (repeatable; \\n for line breaks; empty seconds = 20, empty text = instrumental), e.g. "20|synthwave,female vocals|[Verse 1]\\nNeon rain". Picks elevenlabs-music-v2.5 when --model is omitted',
-    collect,
-    []
-  ).option(
-    "--ref-audio <url|file>",
-    "ElevenLabs v2.5 plan: style reference audio for the first chunk (local files uploaded)"
-  ).option("--ref-start <ms>", "reference window start in ms (default 0)").option(
-    "--ref-end <ms>",
-    "reference window end in ms (window up to 30000 ms)"
-  ).option(
-    "--ref-strength <level>",
-    "how closely to follow the reference: low | medium | high | xhigh"
-  ).option("--seed <n>", "ElevenLabs v2.5 plan: random seed (0-4294967295)").option(
-    "--format <output_format>",
-    "ElevenLabs output format, e.g. mp3_48000_192 (v2.5 default), mp3_44100_128 (v1 default), opus_48000_128, pcm_44100 (WAV)"
-  ).option(
-    "--idempotency-key <uuid>",
-    "ElevenLabs: stable UUID for recovery after an interruption"
+  const upscale = program.command("upscale").description("Upscale / enhance images and videos (Topaz)");
+  const numOpt = (v) => v === void 0 || v === null || v === "" ? void 0 : Number(v);
+  upscale.command("image <url|file>").description(
+    "Enhance or upscale an existing image with Topaz (waits by default)"
+  ).option("--scale <factor>", '"1x" | "2x" | "4x" (default 2x)').option(
+    "--mode <mode>",
+    "generative (default; Wonder 3.5, best for AI images) | precision (faithful, cheapest; real photos) | creative (Bloom, artistic)"
   ).option(
-    "--ref <url|file>",
-    "reference image to inspire the music (Lyria only; max 10 on Google, 1 with Fal BYOK)",
-    collect,
-    []
+    "--model <name>",
+    'Topaz model inside the mode, e.g. "High Fidelity V3", "Wonder 3.5", "Redefine", "Bloom 2" (see: videodraft models image --json)'
+  ).option("--format <jpeg|png>", "output format (default jpeg)").option("--no-face-enhance", "disable Topaz face recovery").option("--face-strength <0-1>", "face recovery strength (default 0.8)").option("--sharpen <0-1>", "extra sharpening (precision/generative)").option("--denoise <0-1>", "noise reduction (precision/generative)").option(
+    "--fix-compression <0-1>",
+    "compression-artifact repair (precision)"
   ).option(
-    "--project <id>",
-    "link the generation to a project's AI Studio session"
+    "--prompt <text>",
+    "guide detail (generative Redefine / creative Bloom)"
+  ).option("--creativity <n>", "generative 1-6 / creative 1-9").option("--texture <1-5>", "texture amount (generative Redefine)").option(
+    "--width <px>",
+    "source width hint (server must verify dimensions; max source 50MB)"
   ).option(
-    "--attach <project_id>",
-    "also set the track as that project's background music"
-  ).option("--volume <n>", "0-100 BGM volume when attaching (default 30)").option(
-    "--bgm-disabled",
-    "when attaching, store the BGM as disabled (enabled:false)"
+    "--height <px>",
+    "source height hint (server must verify dimensions; max source 50MB)"
   ).option(
     "--session <id>",
     "pin an AI Studio session id (default: the current connection scope; env VIDEODRAFT_SESSION)",
     process.env.VIDEODRAFT_SESSION
-  ).option("--download <path>", "download the audio file").option("--estimate", "show the credit quote and exit without generating").action(async function(promptWords) {
+  ).option("--download <path>", "download the result").option(
+    "--no-wait",
+    "return a job ID immediately when the server queues the upscale"
+  ).action(async function(source) {
     const ctx = buildContext(this);
     const opts = this.opts();
-    const sections = opts.section ?? [];
-    const usesPlan = Boolean(opts.plan) || sections.length > 0;
-    const musicModel = opts.model ?? (usesPlan ? "elevenlabs-music-v2.5" : "lyria-3.5");
-    const usesServerDefault = !opts.model && !usesPlan;
-    const isElevenMusic = ELEVENLABS_MUSIC_MODELS.includes(musicModel);
-    const prompt = (promptWords ?? []).join(" ").trim();
-    const elevenOnlyFlags = [
-      ["--plan", opts.plan],
-      ["--section", sections.length > 0 ? true : void 0],
-      ["--ref-audio", opts.refAudio],
-      ["--seed", opts.seed],
-      ["--format", opts.format],
-      ["--idempotency-key", opts.idempotencyKey]
-    ].filter(([, value]) => value !== void 0 && value !== false);
-    if (!isElevenMusic) {
-      if (!LYRIA_MUSIC_MODELS.includes(musicModel)) {
-        throw new CliError(
-          `Unknown music model "${musicModel}". Use ${[...LYRIA_MUSIC_MODELS, ...ELEVENLABS_MUSIC_MODELS].join(", ")}.`,
-          EXIT.USAGE
-        );
-      }
-      if (elevenOnlyFlags.length > 0) {
-        throw new CliError(
-          `${elevenOnlyFlags.map(([flag]) => flag).join(", ")} only work with ElevenLabs Music. Add --model elevenlabs-music-v2.5.`,
-          EXIT.USAGE
-        );
-      }
-      if ((opts.ref ?? []).length > 10) {
-        throw new CliError(
-          "Lyria accepts at most 10 --ref images on Google, or 1 with Fal BYOK.",
-          EXIT.USAGE
-        );
-      }
-      if (!prompt && (opts.ref ?? []).length === 0) {
-        throw new CliError(
-          "A prompt or at least one --ref image is required.",
-          EXIT.USAGE
-        );
-      }
-      if (opts.length !== void 0 || opts.instrumental) {
-        note(
-          ctx.out,
-          fmt.dim(
-            ctx.out,
-            "--length and --instrumental only apply to ElevenLabs Music. For Lyria, put duration and instrumental/no-vocals instructions in the prompt; timing is approximate."
-          )
-        );
-      }
-    } else {
-      if (usesPlan && musicModel === ELEVENLABS_MUSIC_V1) {
-        throw new CliError(
-          "Composition plans need elevenlabs-music-v2.5; v1 only takes a prompt.",
-          EXIT.USAGE
-        );
-      }
-      if (opts.plan && sections.length > 0) {
-        throw new CliError("Use --plan or --section, not both.", EXIT.USAGE);
-      }
-      if (usesPlan && (prompt || opts.length || opts.instrumental)) {
-        throw new CliError(
-          "A composition plan replaces the prompt, --length and --instrumental; its length is the sum of its sections.",
-          EXIT.USAGE
-        );
-      }
-      if (!usesPlan && !prompt) {
-        throw new CliError(
-          "A prompt is required (or pass --plan / --section).",
-          EXIT.USAGE
-        );
-      }
-      if (!usesPlan && (opts.seed !== void 0 || opts.refAudio)) {
-        throw new CliError(
-          "--seed and --ref-audio need a composition plan (--plan or --section).",
-          EXIT.USAGE
-        );
-      }
-      if ((opts.ref ?? []).length > 0) {
-        throw new CliError(
-          "--ref images only work with Lyria. For ElevenLabs, use --ref-audio with a composition plan.",
-          EXIT.USAGE
-        );
-      }
-    }
-    if (!opts.refAudio && (opts.refStart !== void 0 || opts.refEnd !== void 0 || opts.refStrength !== void 0)) {
-      throw new CliError(
-        "--ref-start, --ref-end and --ref-strength need --ref-audio.",
-        EXIT.USAGE
-      );
-    }
-    if (opts.refStrength !== void 0 && !MUSIC_REFERENCE_STRENGTHS.includes(opts.refStrength)) {
-      throw new CliError(
-        `--ref-strength must be one of: ${MUSIC_REFERENCE_STRENGTHS.join(", ")}.`,
-        EXIT.USAGE
-      );
-    }
-    const lengthSeconds = isElevenMusic ? optionalRangedNumber(opts.length, "--length", 3, 300) : void 0;
-    const seed = optionalRangedNumber(
-      opts.seed,
-      "--seed",
-      0,
-      4294967295,
-      true
-    );
-    const refStart = optionalRangedNumber(
-      opts.refStart,
-      "--ref-start",
-      0,
-      Number.MAX_SAFE_INTEGER,
-      true
-    );
-    const refEnd = optionalRangedNumber(
-      opts.refEnd,
-      "--ref-end",
-      1,
-      Number.MAX_SAFE_INTEGER,
-      true
+    const [url] = await resolveRefs(ctx, [source]);
+    capture("cli_upscale", {
+      kind: "image",
+      mode: opts.mode ?? "generative"
+    });
+    const result = await ctx.client.callTool(
+      "upscale_image",
+      compact({
+        image_url: url,
+        scale: opts.scale,
+        mode: opts.mode,
+        model: opts.model,
+        output_format: opts.format,
+        face_enhancement: opts.faceEnhance === false ? false : void 0,
+        face_enhancement_strength: numOpt(opts.faceStrength),
+        sharpen: numOpt(opts.sharpen),
+        denoise: numOpt(opts.denoise),
+        fix_compression: numOpt(opts.fixCompression),
+        prompt: opts.prompt,
+        creativity: numOpt(opts.creativity),
+        texture: numOpt(opts.texture),
+        image_width: numOpt(opts.width),
+        image_height: numOpt(opts.height),
+        session_id: sessionArg(this, opts)
+      })
     );
-    const idempotencyKey = isElevenMusic ? opts.idempotencyKey ?? randomUUID4() : void 0;
-    if (idempotencyKey && !UUID_RE3.test(idempotencyKey)) {
-      throw new CliError(
-        "--idempotency-key must be a valid UUID.",
-        EXIT.USAGE
-      );
-    }
-    let planChunks;
-    let planBaseDir = process.cwd();
-    if (opts.plan) {
-      const loaded = loadMusicPlan(opts.plan);
-      planChunks = loaded.plan.chunks;
-      planBaseDir = loaded.baseDir;
-    } else if (sections.length > 0) {
-      planChunks = parseMusicSections(sections);
-    }
-    if (planChunks && opts.refAudio) {
-      const firstChunk = planChunks[0];
-      if (firstChunk.audio_reference) {
-        throw new CliError(
-          "The plan's first chunk already has an audio_reference; drop --ref-audio or edit the plan.",
-          EXIT.USAGE
-        );
-      }
-      planChunks = [
-        {
-          ...firstChunk,
-          audio_reference: compact({
-            // A --ref-audio path is relative to where the command runs, not
-            // to the plan file, so pin it before the plan's base dir applies.
-            audio_url: URI_SCHEME.test(opts.refAudio) ? opts.refAudio : path8.resolve(opts.refAudio),
-            start_ms: refStart,
-            end_ms: refEnd,
-            strength: opts.refStrength
-          })
-        },
-        ...planChunks.slice(1)
-      ];
-    }
-    if (opts.estimate) {
-      const planSeconds = planChunks ? musicPlanSeconds(planChunks) : void 0;
-      await printEstimate(ctx, {
-        // Quote the model the server will actually default to.
-        model: usesServerDefault ? await serverDefaultMusicModel(ctx) : musicModel,
-        type: "audio",
-        duration: isElevenMusic ? planSeconds ?? lengthSeconds : void 0
+    if (result?.job_id || result?.jobId) {
+      await handleAsyncJob(ctx, result, {
+        wait: opts.wait !== false,
+        download: opts.download,
+        label: "Upscaling image"
       });
       return;
     }
-    const refs = isElevenMusic ? [] : await resolveRefs(ctx, opts.ref ?? []);
-    const compositionPlan = planChunks ? {
-      chunks: await resolveMusicPlanReferences(
-        ctx,
-        planChunks,
-        planBaseDir
-      )
-    } : void 0;
-    capture("cli_generate", {
-      kind: "music",
-      model: usesServerDefault ? "server-default" : musicModel,
-      mode: compositionPlan ? "composition_plan" : "prompt"
-    });
-    const toolArgs = compact({
-      prompt: prompt || void 0,
-      model: usesServerDefault ? void 0 : musicModel,
-      length_seconds: lengthSeconds,
-      force_instrumental: isElevenMusic && opts.instrumental ? true : void 0,
-      composition_plan: compositionPlan,
-      seed,
-      output_format: opts.format,
-      idempotency_key: idempotencyKey,
-      image_urls: refs.length > 0 ? refs : void 0,
-      project_id: opts.project,
-      attach_to_project_id: opts.attach,
-      volume: opts.volume ? Number(opts.volume) : void 0,
-      enabled: opts.bgmDisabled ? false : void 0,
-      session_id: sessionArg(this, opts)
-    });
-    let result;
-    if (isElevenMusic) {
-      try {
-        result = await callAudioWithRetry(
-          () => ctx.client.callTool("generate_music", toolArgs)
-        );
-      } catch (error) {
-        const hint = isRetryableAudioError(error) ? `Retry this exact request with --idempotency-key ${idempotencyKey}` : void 0;
-        if (error instanceof CliError) {
-          if (hint) error.hint = hint;
-          throw error;
-        }
-        throw new CliError(
-          error instanceof Error ? error.message : "Music generation failed",
-          EXIT.ERROR,
-          hint
-        );
-      }
-    } else {
-      result = await ctx.client.callTool("generate_music", toolArgs);
-    }
     const urls = extractOutputUrls(result);
     let downloaded;
     if (opts.download && urls.length > 0) {
       downloaded = await downloadOutputs(urls, opts.download, {
-        name: "music"
+        name: "upscaled"
       });
     }
-    const media = buildMediaDescriptors(urls, "music");
+    const media = buildMediaDescriptors(urls, "image");
     emit(
       ctx.out,
       { ...result, downloaded_files: downloaded, output_media: media },
       (o) => {
-        for (const url of urls) process.stdout.write(`${url}
+        for (const u of urls) process.stdout.write(`${u}
 `);
         for (const f of downloaded ?? []) note(o, fmt.dim(o, savedLine(f)));
       }
     );
   });
-  generate.command("sound-effect <prompt...>").description("Generate a sound effect (ElevenLabs Sound Effects)").option("--duration <seconds>", "length 0.5\u201322s (default 5)").option("--influence <0-1>", "prompt influence (default 0.3)").option("--project <id>", "link to a project's AI Studio session").option(
-    "--session <id>",
-    "pin an AI Studio session id (default: the current connection scope; env VIDEODRAFT_SESSION)",
-    process.env.VIDEODRAFT_SESSION
-  ).option("--download <path>", "download the audio file").action(async function(promptWords) {
+  upscale.command("video <url|file>").description(
+    "Enhance or upscale an existing video with Topaz (async; waits by default)"
+  ).option(
+    "--resolution <720p|1080p|4k>",
+    "output preset by short edge (preferred over --scale)"
+  ).option(
+    "--scale <factor>",
+    '"1x" | "2x" | "4x" (default 2x when no --resolution)'
+  ).option(
+    "--mode <mode>",
+    "generative (default; Starlight Precise 2.6, best for AI clips) | precision (Proteus, 6x cheaper; real footage) | creative (Astra 2)"
+  ).option(
+    "--model <name>",
+    'Topaz model inside the mode, e.g. "Proteus", "Gaia 2", "Starlight Precise 2.6", "Starlight Fast 2" (see: videodraft models video --category upscale --json)'
+  ).option("--fps <n>", "deliver at this frame rate (24-120; 60 doubles cost)").option("--prompt <text>", "creative (Astra 2) only").option("--creativity <0-1>", "creative (Astra 2) only").option("--realism <0-1>", "creative (Astra 2) only").option("--sharp <0-1>", "creative (Astra 2) only").option("--softness <1-5>", "generative (Starlight Precise 2.6) only").option("--compression <0-1>", "precision only").option("--noise <0-1>", "precision only").option("--halo <0-1>", "precision only").option("--grain <0-0.1>", "precision only").option("--recover-detail <0-1>", "precision only").option(
+    "--session <id>",
+    "pin an AI Studio session id (default: the current connection scope; env VIDEODRAFT_SESSION)",
+    process.env.VIDEODRAFT_SESSION
+  ).option(
+    "--duration <seconds>",
+    "source duration hint (compatibility only; server must probe MP4/MOV up to 100MB)"
+  ).option(
+    "--width <px>",
+    "source width hint (server measurement is required)"
+  ).option(
+    "--height <px>",
+    "source height hint (server measurement is required)"
+  ).option(
+    "--source-fps <n>",
+    "source frame rate hint (compatibility only; server measurement controls billing)"
+  ).option("--download <path>", "download the result").option("--no-wait", "submit and return the job id immediately").action(async function(source) {
+    const ctx = buildContext(this);
+    const opts = this.opts();
+    const [url] = await resolveRefs(ctx, [source]);
+    capture("cli_upscale", {
+      kind: "video",
+      mode: opts.mode ?? "generative"
+    });
+    const submitted = await ctx.client.callTool(
+      "upscale_video",
+      compact({
+        video_url: url,
+        scale: opts.scale,
+        target_resolution: opts.resolution?.toLowerCase(),
+        mode: opts.mode,
+        model: opts.model,
+        target_fps: numOpt(opts.fps),
+        prompt: opts.prompt,
+        creativity: numOpt(opts.creativity),
+        realism: numOpt(opts.realism),
+        sharp: numOpt(opts.sharp),
+        softness: numOpt(opts.softness),
+        compression: numOpt(opts.compression),
+        noise: numOpt(opts.noise),
+        halo: numOpt(opts.halo),
+        grain: numOpt(opts.grain),
+        recover_detail: numOpt(opts.recoverDetail),
+        session_id: sessionArg(this, opts),
+        duration_seconds: numOpt(opts.duration),
+        video_width: numOpt(opts.width),
+        video_height: numOpt(opts.height),
+        source_fps: numOpt(opts.sourceFps)
+      })
+    );
+    await handleAsyncJob(ctx, submitted, {
+      wait: opts.wait !== false,
+      download: opts.download,
+      label: "Upscaling video"
+    });
+  });
+  program.command("interpolate <url|file>").description(
+    "Raise a video's frame rate or make slow motion with Topaz (async; waits by default)"
+  ).option(
+    "--model <Apollo|Chronos|Aion>",
+    "interpolation model (default Apollo)"
+  ).option("--fps <n>", "target frame rate 24-120 (default 60)").option("--slowdown <1-8>", "slow-motion factor (default 1)").option(
+    "--session <id>",
+    "pin an AI Studio session id (default: the current connection scope; env VIDEODRAFT_SESSION)",
+    process.env.VIDEODRAFT_SESSION
+  ).option(
+    "--duration <seconds>",
+    "source duration hint (compatibility only; server must probe MP4/MOV up to 100MB)"
+  ).option(
+    "--width <px>",
+    "source width hint (server measurement is required)"
+  ).option(
+    "--height <px>",
+    "source height hint (server measurement is required)"
+  ).option(
+    "--source-fps <n>",
+    "source frame rate hint (compatibility only; server measurement controls billing)"
+  ).option("--download <path>", "download the result").option("--no-wait", "submit and return the job id immediately").action(async function(source) {
+    const ctx = buildContext(this);
+    const opts = this.opts();
+    const [url] = await resolveRefs(ctx, [source]);
+    capture("cli_interpolate", { model: opts.model ?? "Apollo" });
+    const submitted = await ctx.client.callTool(
+      "interpolate_video",
+      compact({
+        video_url: url,
+        model: opts.model,
+        target_fps: numOpt(opts.fps),
+        slowdown_factor: numOpt(opts.slowdown),
+        session_id: sessionArg(this, opts),
+        duration_seconds: numOpt(opts.duration),
+        video_width: numOpt(opts.width),
+        video_height: numOpt(opts.height),
+        source_fps: numOpt(opts.sourceFps)
+      })
+    );
+    await handleAsyncJob(ctx, submitted, {
+      wait: opts.wait !== false,
+      download: opts.download,
+      label: "Interpolating video"
+    });
+  });
+}
+
+// src/commands/account.ts
+var VOICEOVER_COST_MODELS = ["voiceover", "tts", "speech", "text-to-speech"];
+var CLONED_VOICEOVER_COST_MODELS = [
+  "voiceover-cloned",
+  "cloned-voice",
+  "custom-voice"
+];
+var TURBO_VOICEOVER_COST_MODELS = ["voiceover-turbo", "tts-turbo"];
+function voiceoverCostModelId(model, mode) {
+  if (!model) return void 0;
+  const cloned = CLONED_VOICEOVER_COST_MODELS.includes(model);
+  const turbo = TURBO_VOICEOVER_COST_MODELS.includes(model);
+  if (!cloned && !turbo && !VOICEOVER_COST_MODELS.includes(model)) {
+    return void 0;
+  }
+  const voiceMode = parseVoiceoverMode(mode, "--mode for a voiceover estimate");
+  if (cloned && voiceMode === "turbo") {
+    throw new UsageError(
+      `Cloned custom-* voices have no Turbo mode, so ${model} cannot take --mode turbo.`,
+      'Drop --mode for the cloned rate, or run "costs voiceover --mode turbo" for ElevenLabs Turbo.'
+    );
+  }
+  if (turbo && voiceMode === "standard") {
+    throw new UsageError(
+      `${model} already quotes Turbo, so it cannot take --mode standard.`,
+      'Run "costs voiceover" for the standard rate.'
+    );
+  }
+  return voiceMode === "turbo" && !turbo ? "voiceover-turbo" : model;
+}
+function registerAccountCommands(program) {
+  program.command("credits").description("Show your credit balance").action(async function() {
+    const ctx = buildContext(this);
+    const balance = await ctx.client.callTool("get_credits_balance");
+    emit(ctx.out, balance, (o) => {
+      kv(o, [
+        ["Plan", balance?.planId],
+        ["Available credits", balance?.availableCredits],
+        ["Monthly allowance", balance?.totalCreditsMonthly],
+        ["Used this month", balance?.monthlyCreditsUsed],
+        ["Bonus credits", balance?.bonusCredits],
+        ["Bonus expiry", balance?.bonusCreditsExpiry],
+        ["Last monthly reset", balance?.lastMonthlyReset],
+        ["Next monthly reset", balance?.nextMonthlyReset]
+      ]);
+    });
+  });
+  program.command("costs [model]").description(
+    "Show credit costs. Pass a model id, or an image display name, plus settings for an exact estimate"
+  ).option("--type <type>", "image | video | audio").option("--duration <seconds>", "video/audio duration in seconds").option(
+    "--length <seconds>",
+    "ElevenLabs Music output length in seconds (for a composition plan, the sum of its sections)"
+  ).option(
+    "--chars <n>",
+    'character count (ElevenLabs Dialogue, or voiceover TTS via model id "voiceover", "voiceover-cloned" or "voiceover-turbo")'
+  ).option("--resolution <res>", 'e.g. "720p", "1080p", "1K", "2K"').option("--quality <tier>", 'e.g. "standard", "pro", "fast"').option("--ar <ratio>", "image aspect ratio for accurate credit quotes").option(
+    "--rendering-speed <tier>",
+    'image speed/cost tier, e.g. Ideogram V4 "Turbo"/"Balanced"/"Quality"'
+  ).option("--audio", "include native model audio in the estimate").option("--no-audio", "exclude native model audio").option(
+    "--voice-control",
+    "Kling element voice_id pricing (V3 Standard/Pro only; O3/4K are unavailable)"
+  ).option(
+    "--allow-real-people",
+    "Seedance 2.x: estimate the higher tier-specific Fal rate (the default, matching AI Studio)"
+  ).option(
+    "--no-allow-real-people",
+    "Seedance 2.x: estimate the lower Byteplus-only rate"
+  ).option(
+    "--ref-images <n>",
+    "input/reference image count for MiniMax H3, MiniMax H3 Max, or Grok 1.5"
+  ).option(
+    "--ref-video-seconds <seconds>",
+    "MiniMax H3 / H3 Max combined reference-video duration"
+  ).option("--num <n>", "image batch size").option(
+    "--width <px>",
+    "Topaz: source width (with --height gives an exact quote)"
+  ).option("--height <px>", "Topaz: source height").option(
+    "--source-fps <n>",
+    "Topaz video upscale: source frame rate (>30 bills the 60fps rate)"
+  ).option("--scale <factor>", 'Topaz: "1x" | "2x" | "4x" or a factor 1-4').option("--fps <n>", "Topaz: delivered / target frame rate").option(
+    "--mode <mode>",
+    "Topaz upscale mode: generative | precision | creative. For voiceover, the ElevenLabs TTS mode: standard (Eleven v4, 10 credits per 1000 chars) | turbo (Eleven v4 Turbo, 5 credits per 1000 chars)"
+  ).option(
+    "--topaz-model <name>",
+    'Topaz model inside the mode, or "Apollo" | "Chronos" | "Aion" for interpolation'
+  ).option("--slowdown <1-8>", "Topaz interpolate: slow-motion factor").action(async function(model) {
     const ctx = buildContext(this);
     const opts = this.opts();
-    capture("cli_generate", { kind: "sound_effect" });
+    const voiceoverModelId = voiceoverCostModelId(model, opts.mode);
     const result = await ctx.client.callTool(
-      "generate_sound_effect",
+      "get_model_costs",
       compact({
-        prompt: promptWords.join(" "),
+        model_id: voiceoverModelId ?? model,
+        type: opts.type,
         duration_seconds: opts.duration ? Number(opts.duration) : void 0,
-        prompt_influence: opts.influence ? Number(opts.influence) : void 0,
-        project_id: opts.project,
-        session_id: sessionArg(this, opts)
+        length_seconds: opts.length ? Number(opts.length) : void 0,
+        characters: opts.chars ? Number(opts.chars) : void 0,
+        resolution: opts.resolution,
+        quality: opts.quality,
+        aspect_ratio: opts.ar,
+        rendering_speed: opts.renderingSpeed,
+        generate_audio: opts.audio,
+        voice_control: opts.voiceControl,
+        allow_real_people: opts.allowRealPeople,
+        reference_image_count: opts.refImages ? Number(opts.refImages) : void 0,
+        reference_video_duration_seconds: opts.refVideoSeconds ? Number(opts.refVideoSeconds) : void 0,
+        num_images: opts.num ? Number(opts.num) : void 0,
+        source_width: opts.width ? Number(opts.width) : void 0,
+        source_height: opts.height ? Number(opts.height) : void 0,
+        source_fps: opts.sourceFps ? Number(opts.sourceFps) : void 0,
+        scale: opts.scale,
+        target_resolution: opts.resolution && /^(720p|1080p|4k)$/i.test(opts.resolution) ? opts.resolution.toLowerCase() : void 0,
+        target_fps: opts.fps ? Number(opts.fps) : void 0,
+        // A voiceover's --mode is already folded into its model id.
+        mode: voiceoverModelId ? void 0 : opts.mode,
+        topaz_model: opts.topazModel,
+        slowdown_factor: opts.slowdown ? Number(opts.slowdown) : void 0
       })
     );
-    const urls = extractOutputUrls(result);
-    let downloaded;
-    if (opts.download && urls.length > 0) {
-      downloaded = await downloadOutputs(urls, opts.download, {
-        name: "sound-effect"
-      });
-    }
-    const media = buildMediaDescriptors(urls, "audio");
-    emit(
-      ctx.out,
-      { ...result, downloaded_files: downloaded, output_media: media },
-      (o) => {
-        for (const url of urls) process.stdout.write(`${url}
-`);
-        for (const f of downloaded ?? []) note(o, fmt.dim(o, savedLine(f)));
-      }
-    );
+    emit(ctx.out, result);
   });
-  generate.command("dialogue").description(
-    "Generate multi-speaker dialogue (ElevenLabs Text-to-Dialogue). Repeat --line."
+  program.command("models [kind]").description(
+    "List available models: image | video | audio | 3d | voices | styles (default: image + video + audio)"
   ).option(
-    "--line <voiceId:text>",
-    'a dialogue line as "voiceId:text" (repeatable); accepts raw ElevenLabs IDs or elevenlabs-<id>, including voices outside the catalog; must be accessible to the provider account',
-    collect,
-    []
-  ).option("--stability <0|0.5|1>", "voice stability").option("--language <iso>", "ISO 639-1 language code").option("--project <id>", "link to a project's AI Studio session").option(
-    "--session <id>",
-    "pin an AI Studio session id (default: the current connection scope; env VIDEODRAFT_SESSION)",
-    process.env.VIDEODRAFT_SESSION
-  ).option("--download <path>", "download the audio file").action(async function() {
+    "--category <name>",
+    "video only: generation | video_edit | motion_control | avatar_lipsync | upscale"
+  ).action(async function(kind) {
     const ctx = buildContext(this);
     const opts = this.opts();
-    const lines = opts.line.map((raw) => {
-      const i = raw.indexOf(":");
-      if (i < 0) {
-        throw new Error(`--line must be "voiceId:text" (got "${raw}")`);
-      }
-      return {
-        voice_id: raw.slice(0, i).trim(),
-        text: raw.slice(i + 1).trim()
-      };
-    });
-    if (lines.length === 0)
-      throw new Error("at least one --line is required");
-    capture("cli_generate", { kind: "dialogue" });
-    const result = await ctx.client.callTool(
-      "generate_dialogue",
-      compact({
-        lines,
-        stability: opts.stability !== void 0 ? Number(opts.stability) : void 0,
-        language_code: opts.language,
-        project_id: opts.project,
-        session_id: sessionArg(this, opts)
-      })
-    );
-    const urls = extractOutputUrls(result);
-    let downloaded;
-    if (opts.download && urls.length > 0) {
-      downloaded = await downloadOutputs(urls, opts.download, {
-        name: "dialogue"
-      });
+    const wanted = kind ?? "all";
+    if (!["all", "image", "video", "audio", "3d", "voices", "styles"].includes(
+      wanted
+    )) {
+      throw new UsageError(
+        `Unknown model kind "${wanted}". Use image, video, audio, 3d, voices, or styles.`
+      );
     }
-    const media = buildMediaDescriptors(urls, "audio");
-    emit(
-      ctx.out,
-      { ...result, downloaded_files: downloaded, output_media: media },
-      (o) => {
-        for (const url of urls) process.stdout.write(`${url}
+    const videoCategories = /* @__PURE__ */ new Set([
+      "generation",
+      "video_edit",
+      "motion_control",
+      "avatar_lipsync",
+      "upscale"
+    ]);
+    if (opts.category && !videoCategories.has(opts.category)) {
+      throw new UsageError(
+        `Unknown video category "${opts.category}". Use generation, video_edit, motion_control, avatar_lipsync, or upscale.`
+      );
+    }
+    if (opts.category && wanted !== "video" && wanted !== "all") {
+      throw new UsageError(
+        "--category is only valid for the video model catalog."
+      );
+    }
+    const result = {};
+    if (wanted === "image" || wanted === "all") {
+      result.image = await ctx.client.callTool("list_available_image_models");
+    }
+    if (wanted === "video" || wanted === "all") {
+      const video = await ctx.client.callTool(
+        "list_available_video_models"
+      );
+      result.video = opts.category ? {
+        ...video,
+        // A card may belong to more than one category — gemini-omni-1.1-flash
+        // is both the generation default and the preferred video_edit
+        // model — and declares that in `categories`. Match either field so
+        // dual-category cards surface under both.
+        models: (video?.models ?? []).filter(
+          (model) => Array.isArray(model.categories) ? model.categories.includes(opts.category) : model.category === opts.category
+        ),
+        selected_category: opts.category
+      } : video;
+    }
+    if (wanted === "audio" || wanted === "all") {
+      result.audio = await ctx.client.callTool("list_available_audio_models");
+    }
+    if (wanted === "3d") {
+      result["3d"] = await ctx.client.callTool("get_3d_models");
+    }
+    if (wanted === "voices") {
+      result.voices = await ctx.client.callTool("list_available_voices");
+    }
+    if (wanted === "styles") {
+      result.styles = await ctx.client.callTool("list_available_styles");
+    }
+    emit(ctx.out, result, (o) => {
+      for (const [section, payload] of Object.entries(result)) {
+        const models = Array.isArray(payload) ? payload : payload?.models ?? payload?.voices ?? payload?.styles ?? [];
+        process.stdout.write(`
+${section.toUpperCase()}
 `);
-        for (const f of downloaded ?? []) note(o, fmt.dim(o, savedLine(f)));
+        if (!Array.isArray(models) || models.length === 0) {
+          process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
+          continue;
+        }
+        if (section === "3d") {
+          table(
+            o,
+            ["model", "input", "default credits", "Fal endpoint"],
+            models.flatMap(
+              (model) => (model.inputs ?? []).map((input) => [
+                String(model.id ?? ""),
+                String(input.input_mode ?? ""),
+                String(input.default_credits ?? ""),
+                String(input.endpoint_id ?? "")
+              ])
+            )
+          );
+          const rig = payload?.rigging;
+          if (rig)
+            note(
+              o,
+              `Humanoid rigging: ${rig.credits} credits; preset animation adds ${rig.animation_addon_credits} credits.`
+            );
+          note(
+            o,
+            "Use --json for exact options, defaults, input limits, and pricing notes. Use generate 3d --estimate for your selected recipe and BYOK status."
+          );
+          continue;
+        }
+        const rows = models.map((m) => [
+          String(m.id ?? m.model_id ?? m.voice_id ?? ""),
+          String(m.name ?? "").slice(0, 40),
+          String(m.category ?? ""),
+          String(m.tool ?? ""),
+          String(m.credit_cost ?? m.cost ?? m.pricing?.summary ?? "")
+        ]);
+        table(
+          o,
+          section === "video" ? ["id", "name", "category", "tool", "cost"] : ["id", "name", "cost"],
+          section === "video" ? rows : rows.map((row) => [row[0] ?? "", row[1] ?? "", row[4] ?? ""])
+        );
       }
-    );
+    });
+  });
+  program.command("workspaces").description("List your workspaces (the active one is bound to your token)").action(async function() {
+    const ctx = buildContext(this);
+    const result = await ctx.client.callTool("list_workspaces");
+    const workspaces = result?.workspaces ?? result ?? [];
+    emit(ctx.out, result, (o) => {
+      table(
+        o,
+        ["id", "name", "role", "active"],
+        workspaces.map((w) => [
+          String(w.id ?? ""),
+          String(w.name ?? ""),
+          String(w.role ?? ""),
+          w.is_active || w.active ? "\u2713" : ""
+        ])
+      );
+    });
   });
-  generate.command("voice-changer <audio>").description("Restyle speech into another ElevenLabs voice (Voice Changer)").option(
-    "--voice <id>",
-    "target ElevenLabs voice ID, raw or elevenlabs-<id>; catalog membership is not required, but provider account access is (default Brittney, or an account voice with ElevenLabs BYOK)"
-  ).option(
-    "--duration <seconds>",
-    "length of the source audio in seconds (required, max 300)"
-  ).option("--remove-noise", "remove background noise from the input").option("--project <id>", "link to a project's AI Studio session").option(
-    "--session <id>",
-    "pin an AI Studio session id (default: the current connection scope; env VIDEODRAFT_SESSION)",
-    process.env.VIDEODRAFT_SESSION
-  ).option("--download <path>", "download the audio file").action(async function(source) {
+  const sessions = program.command("sessions").description("AI Studio sessions");
+  sessions.command("list", { isDefault: true }).description("List AI Studio sessions (owned + shared)").option("--project <id>", "filter to a project's sessions").option("--name <fragment>", "filter by name (case-insensitive)").option("--limit <n>", "max rows (default 50)").option("--offset <n>", "pagination offset (default 0)").action(async function() {
     const ctx = buildContext(this);
     const opts = this.opts();
-    if (!opts.duration) {
-      throw new Error(
-        "--duration <seconds> is required (length of the source audio)"
-      );
-    }
-    const [audioUrl] = await resolveRefs(ctx, [source]);
-    capture("cli_generate", { kind: "voice_changer" });
     const result = await ctx.client.callTool(
-      "change_voice",
+      "list_ai_studio_sessions",
       compact({
-        audio_url: audioUrl,
-        voice_id: opts.voice,
-        duration_seconds: Number(opts.duration),
-        remove_background_noise: opts.removeNoise ? true : void 0,
         project_id: opts.project,
-        session_id: sessionArg(this, opts)
+        name: opts.name,
+        limit: opts.limit ? Number(opts.limit) : void 0,
+        offset: opts.offset ? Number(opts.offset) : void 0
       })
     );
-    const urls = extractOutputUrls(result);
-    let downloaded;
-    if (opts.download && urls.length > 0) {
-      downloaded = await downloadOutputs(urls, opts.download, {
-        name: "voice-changed"
-      });
-    }
-    const media = buildMediaDescriptors(urls, "audio");
-    emit(
-      ctx.out,
-      { ...result, downloaded_files: downloaded, output_media: media },
-      (o) => {
-        for (const url of urls) process.stdout.write(`${url}
-`);
-        for (const f of downloaded ?? []) note(o, fmt.dim(o, savedLine(f)));
+    const rows = result?.sessions ?? result ?? [];
+    emit(ctx.out, result, (o) => {
+      if (!Array.isArray(rows)) return;
+      table(
+        o,
+        ["id", "name", "role", "items", "created"],
+        rows.map((s) => [
+          String(s.id ?? s.session_id ?? ""),
+          String(s.name ?? "").slice(0, 40),
+          String(s.role ?? (s.is_owner === false ? "member" : "owner")),
+          `${s.image_count ?? 0}i/${s.video_count ?? 0}v/${s.sound_count ?? 0}s`,
+          String(s.created_at ?? s.createdAt ?? "").slice(0, 19)
+        ])
+      );
+    });
+  });
+  sessions.command("current").description("Show the current scope's automatic AI Studio session").action(async function() {
+    const ctx = buildContext(this);
+    const knownIds = /* @__PURE__ */ new Set();
+    let listed = false;
+    if (ctx.session) {
+      try {
+        for (let offset = 0; offset < 2e3; ) {
+          const page = await ctx.client.callTool(
+            "list_ai_studio_sessions",
+            { limit: 200, offset }
+          );
+          const pageRows = page?.sessions ?? [];
+          for (const row of pageRows) {
+            const id = row?.id ?? row?.session_id;
+            if (typeof id === "string") knownIds.add(id);
+          }
+          if (pageRows.length < 200) break;
+          offset += pageRows.length;
+        }
+        listed = true;
+      } catch {
+        listed = false;
       }
+    }
+    const info = ctx.session?.describe();
+    const record = info?.record ?? null;
+    const active = Boolean(record) && !info?.expired;
+    const sessionId = active ? info?.sessionId ?? null : null;
+    const created = Boolean(sessionId) && listed && knownIds.has(sessionId);
+    const result = {
+      enabled: Boolean(ctx.session),
+      scope: info?.scope ?? null,
+      active,
+      expired: Boolean(info?.expired),
+      session_id: sessionId,
+      /** False until naming or the first generation creates the row. */
+      session_created: created,
+      url: sessionId && created ? `${ctx.baseUrl}/ai-studio?session=${sessionId}` : null,
+      created_at: active ? record?.createdAt ?? null : null,
+      last_used_at: active ? record?.lastUsedAt ?? null : null,
+      file: info?.file ?? null,
+      note: ctx.session ? active ? created ? "Project-less generations in this scope share this AI Studio session. `videodraft sessions reset` starts a new one; --session <id> pins a specific session." : "Session id reserved for this scope; name it with `videodraft sessions name <title>` or generate the first asset to create it. `videodraft sessions reset` starts a new one; --session <id> pins a specific session." : info?.expired ? "The previous session idled out (12h); the next command starts a new one. --session <id> pins a specific session instead." : "No session yet; the next command creates one. --session <id> pins a specific session instead." : 'Disabled via VIDEODRAFT_NO_SESSION; generations fall back to the shared "Agent (MCP)" session unless --session is passed.'
+    };
+    emit(ctx.out, result, () => {
+      const state = !result.enabled ? "disabled" : result.active ? `${result.session_created ? "active" : "reserved"}  session=${result.session_id ?? "?"}` : result.expired ? "expired" : "none yet";
+      process.stdout.write(
+        `${state}  scope=${result.scope ?? "-"}
+${result.url ? `${result.url}
+` : ""}${result.note}
+`
+      );
+    });
+  });
+  sessions.command("name <name>").description("Name the automatic AI Studio session before first use").action(async function(name) {
+    if (process.env.VIDEODRAFT_SESSION?.trim()) {
+      throw new UsageError(
+        "Cannot name the automatic session while VIDEODRAFT_SESSION is set. Unset it first, or rename the pinned session in AI Studio."
+      );
+    }
+    const ctx = buildContext(this);
+    const result = await ctx.client.callTool(
+      "name_current_ai_studio_session",
+      { name }
     );
+    emit(ctx.out, result, () => {
+      const session = result?.session ?? result;
+      process.stdout.write(
+        `${String(session?.name ?? name)}  ${String(session?.id ?? result?.session_id ?? "")}
+`
+      );
+    });
   });
-  generate.command("dub <media>").description(
-    "Dub a video/audio file into another language (ElevenLabs Dubbing)"
-  ).option(
-    "--to <iso>",
-    "target language ISO 639-1 code, e.g. es or te (required)"
-  ).option(
-    "--from <iso>",
-    "source language ISO 639-1 code (auto-detected if omitted)"
-  ).option("--type <audio|video>", "source media type override").option(
-    "--duration <seconds>",
-    "length of the source media in seconds (required, max 300)"
-  ).option("--speakers <n>", "number of speakers (auto-detected if omitted)").option("--project <id>", "link to a project's AI Studio session").option(
-    "--session <id>",
-    "pin an AI Studio session id (default: the current connection scope; env VIDEODRAFT_SESSION)",
-    process.env.VIDEODRAFT_SESSION
-  ).option("--download <path>", "download the dubbed file").action(async function(source) {
+  sessions.command("reset").description(
+    "Forget this connection session so the next generation starts a fresh AI Studio session (--all: every scope)"
+  ).option("--all", "reset every stored connection session").action(async function() {
     const ctx = buildContext(this);
     const opts = this.opts();
-    if (!opts.to) throw new Error("--to <iso> (target language) is required");
-    if (!opts.duration) {
-      throw new Error(
-        "--duration <seconds> is required (length of the source media)"
-      );
+    let removed = 0;
+    let declined = false;
+    if (opts.all) {
+      removed = resetAllConnectionSessions();
+    } else if (ctx.session) {
+      const had = Boolean(ctx.session.describe().record);
+      const ran = ctx.session.reset();
+      removed = had && ran ? 1 : 0;
+      declined = had && !ran;
     }
-    const mediaType = inferDubMediaType(source, opts.type);
-    const [mediaUrl] = await resolveRefs(ctx, [source]);
-    capture("cli_generate", { kind: "dub" });
+    const result = {
+      reset: removed,
+      declined,
+      scope: opts.all ? "all" : ctx.session?.describe().scope ?? null
+    };
+    emit(ctx.out, result, () => {
+      process.stdout.write(
+        removed > 0 ? `Reset ${removed} connection session${removed === 1 ? "" : "s"}; the next generation starts a new AI Studio session.
+` : declined ? "Could not reset: the session store is locked or unwritable; the session may still be in use.\n" : "Nothing to reset.\n"
+      );
+    });
+  });
+  sessions.command("create <name>").description(
+    "Create an AI Studio session (reuse its id across standalone generations)"
+  ).option("--project <id>", "attach the session to a project").action(async function(name) {
+    const ctx = buildContext(this);
     const result = await ctx.client.callTool(
-      "dub_media",
-      compact({
-        video_url: mediaType === "video" ? mediaUrl : void 0,
-        audio_url: mediaType === "audio" ? mediaUrl : void 0,
-        target_lang: opts.to,
-        source_lang: opts.from,
-        num_speakers: opts.speakers ? Number(opts.speakers) : void 0,
-        duration_seconds: Number(opts.duration),
-        project_id: opts.project,
-        session_id: sessionArg(this, opts)
-      })
+      "create_ai_studio_session",
+      compact({ name, project_id: this.opts().project })
     );
-    const urls = extractOutputUrls(result);
-    let downloaded;
-    if (opts.download && urls.length > 0) {
-      downloaded = await downloadOutputs(urls, opts.download, {
-        name: "dubbed"
-      });
-    }
-    const media = buildMediaDescriptors(urls, mediaType);
-    emit(
-      ctx.out,
-      { ...result, downloaded_files: downloaded, output_media: media },
-      (o) => {
-        for (const url of urls) process.stdout.write(`${url}
+    emit(ctx.out, result, (o) => {
+      const id = result?.session?.id ?? result?.session_id ?? result?.id;
+      process.stdout.write(`${id ?? JSON.stringify(result)}
 `);
-        for (const f of downloaded ?? []) note(o, fmt.dim(o, savedLine(f)));
-      }
-    );
+    });
   });
-  const upscale = program.command("upscale").description("Upscale / enhance images and videos (Topaz)");
-  const numOpt = (v) => v === void 0 || v === null || v === "" ? void 0 : Number(v);
-  upscale.command("image <url|file>").description(
-    "Enhance or upscale an existing image with Topaz (synchronous)"
-  ).option("--scale <factor>", '"1x" | "2x" | "4x" (default 2x)').option(
-    "--mode <mode>",
-    "generative (default; Wonder 3.5, best for AI images) | precision (faithful, cheapest; real photos) | creative (Bloom, artistic)"
-  ).option(
-    "--model <name>",
-    'Topaz model inside the mode, e.g. "High Fidelity V3", "Wonder 3.5", "Redefine", "Bloom 2" (see: videodraft models image --json)'
-  ).option("--format <jpeg|png>", "output format (default jpeg)").option("--no-face-enhance", "disable Topaz face recovery").option("--face-strength <0-1>", "face recovery strength (default 0.8)").option("--sharpen <0-1>", "extra sharpening (precision/generative)").option("--denoise <0-1>", "noise reduction (precision/generative)").option(
-    "--fix-compression <0-1>",
-    "compression-artifact repair (precision)"
-  ).option(
-    "--prompt <text>",
-    "guide detail (generative Redefine / creative Bloom)"
-  ).option("--creativity <n>", "generative 1-6 / creative 1-9").option("--texture <1-5>", "texture amount (generative Redefine)").option(
-    "--width <px>",
-    "source width hint (server must verify dimensions; max source 50MB)"
-  ).option(
-    "--height <px>",
-    "source height hint (server must verify dimensions; max source 50MB)"
-  ).option(
-    "--session <id>",
-    "pin an AI Studio session id (default: the current connection scope; env VIDEODRAFT_SESSION)",
-    process.env.VIDEODRAFT_SESSION
-  ).option("--download <path>", "download the result").action(async function(source) {
+}
+
+// src/commands/projects.ts
+import { spawn as spawn2 } from "child_process";
+function registerProjectCommands(program) {
+  const projects = program.command("projects").description("List and manage projects");
+  projects.command("list", { isDefault: true }).description("List projects").option("--limit <n>", "max projects (default 50)").option("--offset <n>", "pagination offset").option("--favorites", "only favorited projects").action(async function() {
     const ctx = buildContext(this);
     const opts = this.opts();
-    const [url] = await resolveRefs(ctx, [source]);
-    capture("cli_upscale", {
-      kind: "image",
-      mode: opts.mode ?? "generative"
-    });
     const result = await ctx.client.callTool(
-      "upscale_image",
+      "list_projects",
       compact({
-        image_url: url,
-        scale: opts.scale,
-        mode: opts.mode,
-        model: opts.model,
-        output_format: opts.format,
-        face_enhancement: opts.faceEnhance === false ? false : void 0,
-        face_enhancement_strength: numOpt(opts.faceStrength),
-        sharpen: numOpt(opts.sharpen),
-        denoise: numOpt(opts.denoise),
-        fix_compression: numOpt(opts.fixCompression),
-        prompt: opts.prompt,
-        creativity: numOpt(opts.creativity),
-        texture: numOpt(opts.texture),
-        image_width: numOpt(opts.width),
-        image_height: numOpt(opts.height),
-        session_id: sessionArg(this, opts)
+        limit: opts.limit ? Number(opts.limit) : void 0,
+        offset: opts.offset ? Number(opts.offset) : void 0,
+        favorites_only: opts.favorites || void 0
       })
     );
-    const urls = extractOutputUrls(result);
-    let downloaded;
-    if (opts.download && urls.length > 0) {
-      downloaded = await downloadOutputs(urls, opts.download, {
-        name: "upscaled"
-      });
+    const rows = result?.projects ?? [];
+    emit(ctx.out, result, (o) => {
+      table(
+        o,
+        ["id", "title", "status", "modified"],
+        rows.map((p) => [
+          String(p.id ?? ""),
+          String(p.title ?? "Untitled").slice(0, 44),
+          String(p.status ?? ""),
+          String(p.lastModified ?? "").slice(0, 19)
+        ])
+      );
+    });
+  });
+  projects.command("get <project_id>").description("Fetch a project (summary view; --raw for the editable blob)").option("--raw", "return the raw editable JSON blob").action(async function(projectId) {
+    const ctx = buildContext(this);
+    const result = await ctx.client.callTool("get_project", {
+      project_id: projectId,
+      view: this.opts().raw ? "raw" : "summary"
+    });
+    emit(ctx.out, result);
+  });
+  projects.command("delete <project_id>").description("Permanently delete a project (cannot be undone)").option("--yes", "skip the confirmation").action(async function(projectId) {
+    const ctx = buildContext(this);
+    if (!this.opts().yes) {
+      throw new CliError(
+        "Refusing to delete without --yes. Deletion is permanent for every collaborator.",
+        EXIT.USAGE
+      );
     }
-    const media = buildMediaDescriptors(urls, "image");
+    const result = await ctx.client.callTool("delete_project", {
+      project_id: projectId
+    });
     emit(
       ctx.out,
-      { ...result, downloaded_files: downloaded, output_media: media },
-      (o) => {
-        for (const u of urls) process.stdout.write(`${u}
-`);
-        for (const f of downloaded ?? []) note(o, fmt.dim(o, savedLine(f)));
-      }
+      result,
+      (o) => note(o, fmt.green(o, `Deleted project ${projectId}.`))
     );
   });
-  upscale.command("video <url|file>").description(
-    "Enhance or upscale an existing video with Topaz (async; waits by default)"
-  ).option(
-    "--resolution <720p|1080p|4k>",
-    "output preset by short edge (preferred over --scale)"
-  ).option(
-    "--scale <factor>",
-    '"1x" | "2x" | "4x" (default 2x when no --resolution)'
-  ).option(
-    "--mode <mode>",
-    "generative (default; Starlight Precise 2.6, best for AI clips) | precision (Proteus, 6x cheaper; real footage) | creative (Astra 2)"
-  ).option(
-    "--model <name>",
-    'Topaz model inside the mode, e.g. "Proteus", "Gaia 2", "Starlight Precise 2.6", "Starlight Fast 2" (see: videodraft models video --category upscale --json)'
-  ).option("--fps <n>", "deliver at this frame rate (24-120; 60 doubles cost)").option("--prompt <text>", "creative (Astra 2) only").option("--creativity <0-1>", "creative (Astra 2) only").option("--realism <0-1>", "creative (Astra 2) only").option("--sharp <0-1>", "creative (Astra 2) only").option("--softness <1-5>", "generative (Starlight Precise 2.6) only").option("--compression <0-1>", "precision only").option("--noise <0-1>", "precision only").option("--halo <0-1>", "precision only").option("--grain <0-0.1>", "precision only").option("--recover-detail <0-1>", "precision only").option(
-    "--session <id>",
-    "pin an AI Studio session id (default: the current connection scope; env VIDEODRAFT_SESSION)",
-    process.env.VIDEODRAFT_SESSION
-  ).option(
-    "--duration <seconds>",
-    "source duration hint (compatibility only; server must probe MP4/MOV up to 100MB)"
-  ).option(
-    "--width <px>",
-    "source width hint (server measurement is required)"
-  ).option(
-    "--height <px>",
-    "source height hint (server measurement is required)"
-  ).option(
-    "--source-fps <n>",
-    "source frame rate hint (compatibility only; server measurement controls billing)"
-  ).option("--download <path>", "download the result").option("--no-wait", "submit and return the job id immediately").action(async function(source) {
+  projects.command("favorite <project_id>").description("Star or unstar a project").option("--remove", "unstar instead of star").action(async function(projectId) {
     const ctx = buildContext(this);
-    const opts = this.opts();
-    const [url] = await resolveRefs(ctx, [source]);
-    capture("cli_upscale", {
-      kind: "video",
-      mode: opts.mode ?? "generative"
+    const favorite = !this.opts().remove;
+    const result = await ctx.client.callTool("set_project_favorite", {
+      project_id: projectId,
+      favorite
     });
-    const submitted = await ctx.client.callTool(
-      "upscale_video",
+    emit(
+      ctx.out,
+      result,
+      (o) => note(o, favorite ? "Starred." : "Unstarred.")
+    );
+  });
+  projects.command("open <project_id>").description("Open the project in your browser").action(async function(projectId) {
+    const ctx = buildContext(this);
+    const result = await ctx.client.callTool("get_project", {
+      project_id: projectId,
+      view: "summary"
+    });
+    const url = result?.urls?.storyboard ?? result?.urls?.script ?? `${ctx.baseUrl}/projects/${projectId}`;
+    const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+    try {
+      const child = spawn2(cmd, [url], {
+        stdio: "ignore",
+        detached: true,
+        shell: process.platform === "win32"
+      });
+      child.on("error", () => {
+      });
+      child.unref();
+    } catch {
+    }
+    emit(ctx.out, { url }, (o) => note(o, url));
+  });
+  const checkpoint = program.command("checkpoint").description("Project version checkpoints");
+  checkpoint.command("create <project_id>").description("Snapshot the project as a new version").option("--name <name>", "version name").option("--description <text>", "version description").action(async function(projectId) {
+    const ctx = buildContext(this);
+    const opts = this.opts();
+    const result = await ctx.client.callTool(
+      "create_project_checkpoint",
       compact({
-        video_url: url,
-        scale: opts.scale,
-        target_resolution: opts.resolution?.toLowerCase(),
-        mode: opts.mode,
-        model: opts.model,
-        target_fps: numOpt(opts.fps),
-        prompt: opts.prompt,
-        creativity: numOpt(opts.creativity),
-        realism: numOpt(opts.realism),
-        sharp: numOpt(opts.sharp),
-        softness: numOpt(opts.softness),
-        compression: numOpt(opts.compression),
-        noise: numOpt(opts.noise),
-        halo: numOpt(opts.halo),
-        grain: numOpt(opts.grain),
-        recover_detail: numOpt(opts.recoverDetail),
-        session_id: sessionArg(this, opts),
-        duration_seconds: numOpt(opts.duration),
-        video_width: numOpt(opts.width),
-        video_height: numOpt(opts.height),
-        source_fps: numOpt(opts.sourceFps)
+        project_id: projectId,
+        name: opts.name,
+        description: opts.description
       })
     );
-    await handleAsyncJob(ctx, submitted, {
-      wait: opts.wait !== false,
-      download: opts.download,
-      label: "Upscaling video"
+    emit(ctx.out, result);
+  });
+  checkpoint.command("list <project_id>").description("List a project's checkpoints").action(async function(projectId) {
+    const ctx = buildContext(this);
+    const result = await ctx.client.callTool("list_project_checkpoints", {
+      project_id: projectId
     });
+    emit(ctx.out, result);
   });
-  program.command("interpolate <url|file>").description(
-    "Raise a video's frame rate or make slow motion with Topaz (async; waits by default)"
-  ).option(
-    "--model <Apollo|Chronos|Aion>",
-    "interpolation model (default Apollo)"
-  ).option("--fps <n>", "target frame rate 24-120 (default 60)").option("--slowdown <1-8>", "slow-motion factor (default 1)").option(
-    "--session <id>",
-    "pin an AI Studio session id (default: the current connection scope; env VIDEODRAFT_SESSION)",
-    process.env.VIDEODRAFT_SESSION
-  ).option(
-    "--duration <seconds>",
-    "source duration hint (compatibility only; server must probe MP4/MOV up to 100MB)"
-  ).option(
-    "--width <px>",
-    "source width hint (server measurement is required)"
-  ).option(
-    "--height <px>",
-    "source height hint (server measurement is required)"
+  checkpoint.command("restore <project_id> [version_number]").description(
+    "Restore a project to a saved version (current state is snapshotted first)"
   ).option(
-    "--source-fps <n>",
-    "source frame rate hint (compatibility only; server measurement controls billing)"
-  ).option("--download <path>", "download the result").option("--no-wait", "submit and return the job id immediately").action(async function(source) {
+    "--checkpoint-id <id>",
+    "restore by checkpoint UUID instead of version number"
+  ).action(async function(projectId, versionNumber) {
     const ctx = buildContext(this);
     const opts = this.opts();
-    const [url] = await resolveRefs(ctx, [source]);
-    capture("cli_interpolate", { model: opts.model ?? "Apollo" });
-    const submitted = await ctx.client.callTool(
-      "interpolate_video",
+    if (!versionNumber && !opts.checkpointId) {
+      throw new CliError(
+        "Pass a version_number or --checkpoint-id.",
+        EXIT.USAGE
+      );
+    }
+    const result = await ctx.client.callTool(
+      "restore_project_checkpoint",
       compact({
-        video_url: url,
-        model: opts.model,
-        target_fps: numOpt(opts.fps),
-        slowdown_factor: numOpt(opts.slowdown),
-        session_id: sessionArg(this, opts),
-        duration_seconds: numOpt(opts.duration),
-        video_width: numOpt(opts.width),
-        video_height: numOpt(opts.height),
-        source_fps: numOpt(opts.sourceFps)
+        project_id: projectId,
+        version_number: versionNumber ? Number(versionNumber) : void 0,
+        checkpoint_id: opts.checkpointId
       })
     );
-    await handleAsyncJob(ctx, submitted, {
-      wait: opts.wait !== false,
-      download: opts.download,
-      label: "Interpolating video"
-    });
+    emit(ctx.out, result);
   });
 }
 
@@ -6524,9 +6668,13 @@ function registerPipelineCommands(program) {
   ).option("--no-voiceover", "skip per-scene voiceovers + captions").option("--no-video-prompts", "skip advisory per-shot motion prompts").option(
     "--shot-duration <seconds>",
     "per-shot clip length for silent/no-voiceover scenes (default 3)"
-  ).option("--voice <id>", "TTS voice id for voiceovers").option("--language <bcp47>", "voiceover + caption language").option("--captions", "force burn captions").option("--no-captions", "force no captions (default follows voiceover)").action(async function(projectId) {
+  ).option("--voice <id>", "TTS voice id for voiceovers").option(
+    "--voice-mode <standard|turbo>",
+    "ElevenLabs narration voices only: standard (default; Eleven v4, 10 credits per 1000 chars) | turbo (Eleven v4 Turbo, faster, 5 credits per 1000 chars)"
+  ).option("--language <bcp47>", "voiceover + caption language").option("--captions", "force burn captions").option("--no-captions", "force no captions (default follows voiceover)").action(async function(projectId) {
     const ctx = buildContext(this);
     const opts = this.opts();
+    const voiceMode = parseVoiceoverMode(opts.voiceMode, "--voice-mode");
     const captionsSrc = this.getOptionValueSource("captions");
     capture("cli_produce", { mode: opts.mode ?? "animatic" });
     const spin = spinner(
@@ -6547,6 +6695,7 @@ function registerPipelineCommands(program) {
           generate_video_prompts: opts.videoPrompts === false ? false : void 0,
           shot_duration: opts.shotDuration ? Number(opts.shotDuration) : void 0,
           voice_id: opts.voice,
+          voice_mode: voiceMode,
           language: opts.language,
           show_captions: captionsSrc === "cli" ? opts.captions : void 0
         })
@@ -7607,8 +7756,8 @@ function bundledSkillDir() {
   );
 }
 function bundledSkillFiles() {
-  if ('{"SKILL.md":"---\\nname: videodraft\\ndescription: Create and edit AI videos, images, 3D meshes, Seed Audio, voiceovers, music, sound effects, dialogue, dubbing, storyboards, avatar videos, media upscales, and product/ad videos with VideoDraft. Use whenever the user mentions VideoDraft; asks to generate a video, image, 3D asset, audio asset, ad, explainer, storyboard, avatar, upscale, or batch/CI workflow; wants to download a video from YouTube, Instagram, TikTok, X or another site; or wants to assemble, cut, caption, mix, lay out, inspect, or export a native VideoDraft Editor timeline. Covers the cloud `videodraft` CLI/MCP and local headless `videodraft_editor` MCP. When the editor MCP is exposed, prefer it for production, timeline assembly, and export; use cloud production/export only when explicitly requested or the editor is unavailable.\\n---\\n\\n# VideoDraft\\n\\nVideoDraft is an AI video creation platform where asset generation is the priority lane:\\n\\n- **Asset generation**: standalone images, video clips, Seed Audio, voiceovers, music, sound effects, dialogue, voice-changed audio, dubbed media, upscales, and image descriptions. This is the fastest and most important lane. Treat these as complete deliverables when the user asks for assets.\\n- **Asset I/O**: upload local files, download outputs, auto-upload local references, and save generated media where the user can see it.\\n- **3D assets**: standalone Meshy 7 and Tripo H3.1 meshes, multi-view generation, complete artifact downloads, and Meshy humanoid rigging through MCP/CLI. Read [references/3d.md](references/3d.md), or `videodraft skills show 3d`. These assets have their own saved library and do not require an AI Studio session or web viewer.\\n- **Native editing**: local `.vdproject` timelines, cuts, layouts, captions, effects, audio, and exports through the headless VideoDraft Editor. Inside VideoDraft ADE, this is the default production and export lane whenever `videodraft_editor` is available.\\n- **Hosted project production**: idea \u2192 script \u2192 storyboard \u2192 hosted production timeline \u2192 exported MP4. Use the early stages for scripts, storyboards, and generated assets when useful. Treat hosted production and export as a fallback when the native editor is unavailable, or as an explicit destination when the user asks for an editable web project or hosted workflow.\\n\\n## How to connect\\n\\nCloud generation has two equivalent surfaces (same backend, credits, and hosted projects). Native timeline editing is a separate local surface:\\n\\n1. **CLI** (preferred when you have a shell): run `videodraft` if it\'s on PATH; otherwise `npx -y videodraft@latest` runs it with no install (needs Node \u226520; the `-y` skips npx\'s install prompt so it runs non-interactively; the package is fetched on first use and cached). For heavy use, `npm install -g videodraft`. If there\'s no Node/shell here but the MCP connector below is available, use that instead; if neither works, tell the user how to install (https://videodraft.ai/cli).\\n   - Auth \u2014 pick by context, don\'t guess:\\n     \u2022 INTERACTIVE (a human is in the session, e.g. Claude Code / Codex): on exit code 3 (\\"not authenticated\\"), tell the user to run `videodraft login` in their terminal \u2014 it opens their browser for a one-click VideoDraft sign-in (OAuth), no key to copy. Wait for them to confirm it succeeded, then retry the command. This is the preferred path when the user is present.\\n     \u2022 HEADLESS / CI (no browser): set `VIDEODRAFT_API_KEY=vd_mcp_...` (a token the user mints at https://app.videodraft.ai/mcp-keys).\\n     \u2022 SECURITY: never ask the user to paste a `vd_mcp_...` token into the chat \u2014 use browser `login` or the env var so the token never lands in the transcript.\\n   - Every command accepts `--json` (parse this, don\'t scrape text). Exit codes: 0 ok, 1 error, 2 usage, 3 auth (see Auth above), 4 insufficient credits (\u2192 tell the user, don\'t retry).\\n   - Tool discovery: start with `videodraft tools list` for the grouped catalog, then narrow with `videodraft tools list --lane assets`, `--lane asset_io`, `--lane project_data`, or `--lane production`.\\n   - Asset lane: `videodraft generate ...`, `videodraft edit video|motion`, `videodraft avatar ...`, `videodraft upscale ...`, `videodraft interpolate ...`, `videodraft upload`, and `videodraft download`.\\n   - Full API access: `videodraft tools schema <name>`, `videodraft call <tool> --args \'<json>\'`.\\n2. **MCP connector**: if VideoDraft MCP tools (e.g. `generate_storyboard_from_idea`) are available, call them directly \u2014 the CLI\'s curated commands map 1:1 onto these tools.\\n3. **Native editor MCP** (`videodraft_editor`): prefer this for project production, timeline assembly, cutting, layouts, transitions, captions, audio placement, and final export. Inside VideoDraft ADE on a supported Mac, Claude, Codex, OpenCode and Grok receive it automatically in both Code and VideoDraft modes. It runs headlessly, so an Open Editor click is not required. Start with `project_manage` (`operation: \\"project\\"`, action `list`, `open`, or `create`); standalone asset generation remains in the cloud CLI or MCP.\\n\\nSend native editor edits serially, batching everything a request needs into one `edit_apply` recipe. Pass the latest `context` when a person may be editing at the same time, so a stale write is refused. See [references/editor.md](references/editor.md) for project selection, media import, timing units, edit recipes, verification, export, and the `videodraft-editor` terminal bridge.\\n\\nIf you are reading this skill through `videodraft skills show skill`, run `videodraft skills show editor` before native editor work to load that reference.\\n\\n**VideoDraft ADE routing rule:** the presence of `videodraft_editor` means the native editor is ready, even when no editor window is visible. Use cloud tools to generate or source assets and, when helpful, scripts or storyboards. Do not call hosted `produce_project` / `videodraft produce` or `export_video` / `videodraft export` by default. Import the assets into the native project, assemble there, and export with native `delivery_manage` `submit`. Use hosted production/export only when the user explicitly asks for the web workflow or the native editor tools are unavailable. Do not silently fall back to hosted production after a native tool error.\\n\\n## First decision: asset, hosted project, or native edit?\\n\\n- **One standalone asset** (image, clip, voiceover, music track, sound effect, dialogue track, voice-changed file, dubbed media file, upscale, or description): generate it directly. Do NOT create a project.\\n  - `videodraft generate image \\"a red fox in snow, cinematic\\" --ar 16:9 --download ./out/`\\n  - `videodraft generate video \\"slow dolly over a misty lake\\" --model gemini-omni-1.1-flash --duration 6 --download ./out/`\\n- **Any final video, production timeline, existing footage, local `.vdproject`, or hands-on edit**: use `videodraft_editor` when available. List or open the intended local project, or create a native project for a new production. The editor can work without showing its UI.\\n- **A small set of related assets**: still stay in the asset lane. They are grouped automatically (see [AI Studio sessions](#ai-studio-sessions)); give the current group one useful task-specific name with `videodraft sessions name \\"<name>\\"`. Switch to a project only when the deliverable matches the project criteria below or the user asks to attach the assets to one.\\n- **A generated multi-scene video / ad / explainer**: when the editor is available, use hosted tools only for any needed script, storyboard, shot planning, or generated assets; stop before hosted production, import the assets, and build/export the native timeline. A hosted project is optional unless the user wants the web project or its storyboard workflow.\\n- **A hosted web project or hosted export**: use the hosted pipeline only when the user explicitly asks for it or the native editor is unavailable.\\n- **Just a script** (no video asked for): A script-only request creates a script-stage project but stops at the script. Use `videodraft create \\"...\\" --script-only`; do not build a storyboard the user didn\'t ask for.\\n- **Iterating on existing work**: identify the surface first. Use `project_manage` `project` with `action: \\"list\\"` for native projects and `videodraft projects list` only for hosted work. Never create a replacement project just to change an existing one.\\n\\n## Choose the model from the task\\n\\nIf the user names a model, use it when compatible. If it cannot handle the request, explain why and recommend alternatives instead of silently switching. Otherwise inspect the inputs, duration, audio, quality, speed, and cost, check the live catalog, and pass an explicit model.\\n\\n### Seedance 2.x real-person rule\\n\\nSeedance 2.0 and 2.5 allow real people by default, the same as AI Studio:\\n\\n- The default is true. Generation tries Byteplus first and can fall back to Fal, which allows real-person likenesses, so a person in the prompt, a start frame, end frame, reference image, or reference video does not hard-fail. The request is charged at Fal\'s higher tier-specific rate even if Byteplus serves it.\\n- Turn it off for the cheapest run, only when the user wants that and nothing in the job is a real identifiable person (text-only requests, non-people, anime, clearly synthetic or stylized characters). For MCP use `allow_real_people: false`. For the CLI use `--no-allow-real-people`. That pins the job to the lower-priced Byteplus path, and a Byteplus likeness-policy refusal does not fall back to Fal. Pass the same value to `get_model_costs` or `videodraft costs` so the estimate matches the charge.\\n- If a request made with the option off fails with code `SEEDANCE_REAL_PERSON_OPT_IN_REQUIRED`, estimate the higher rate, follow the user\'s spend-confirmation preference, and retry exactly once with the option on. The structured recovery fields are `retryable: true`, `retry_with: { allow_real_people: true }`, `cli_flag: \\"--allow-real-people\\"`, and `retry_policy: \\"once\\"`. CLI `--json` submit errors expose them under `details`; `status` and `wait` include them on the failed job result. Do not treat an unrelated moderation or provider error as that signal.\\n- Do not loop when the option was on. Byteplus can accept a task and reject its generated output later. VideoDraft refunds that failed generation, but the late asynchronous failure cannot be rerouted to Fal. Rephrase the prompt or use different references before trying again.\\n- For hosted AI Production, the same default applies to every Seedance scene segment: `produce_project` with `mode: \\"full_video\\"` and `videodraft produce <project> --mode full_video` allow real people unless you pass `allow_real_people: false` or `--no-allow-real-people`. If an earlier run with the option off partially submitted and returns the opt-in code, rerun that same project once with an explicit `allow_real_people: true` / `--allow-real-people`. The server reconciles asynchronous results first, preserves running/completed jobs, and resubmits only failed scene-video placeholders carrying the exact opt-in signal. Keep the native-first VideoDraft ADE routing rule above: hosted full-video production is still explicit/fallback-only when the local editor is available.\\n\\n**How to pick a model. Follow this order every time:**\\n\\n1. The user named a model: use it, never substitute.\\n2. Otherwise pick a **Tier 1** model.\\n3. Use a **Tier 2** model only when no Tier 1 model supports the request, and say why. Never pick Tier 2 on your own for price, speed, novelty or variety.\\n\\nTier 1: images `nano-banana-2`, `nano-banana-pro`, `nano-banana-2-lite`, `gpt-image-2.5-flare`, `gpt-image-2.5-sunburst`, and `recraft-v4` for vector/SVG only; videos `gemini-omni-1.1-flash`, `seedance-2.5`, `seedance-2`, `kling-3.0`, `kling-o3`, `minimax-h3-max`; video edits `gemini-omni-1.1-flash`; talking-head portraits `veed-fabric`, `minimax-h3-max-lipsync`; motion transfer `kling-v3-motion-control`; audio ElevenLabs for speech tools, Lyria 3.5 for music at any length.\\n\\nTier 2 is every other catalog model (`wan-3.0`, `flux-3`, `minimax-h3`, `kling-v3-turbo`, `kling-2.6-pro`, `grok-imagine-video-1.5`, `happy-horse`, Veo 3.1, Sora, Seedream, Grok Imagine images, FLUX images, `sync-lipsync-2` and the rest). All of them stay available by name. Real Tier 2-only jobs: document or web-page references (`wan-3.0`), keyframes pinned to timestamps (`flux-3`), re-syncing existing footage (`sync-lipsync-2`).\\n\\nEvery `videodraft models image|video|audio --json` entry carries `tier` (1 or 2), and the top-level `recommended` array is Tier 1, best first. That catalog beats this page when they disagree.\\n\\n**Speech in video:** write the dialogue in the video prompt. `gemini-omni-1.1-flash`, `seedance-2.5`, `seedance-2`, `kling-3.0` and `kling-o3` speak it natively. For a specific voice add a Seedance reference audio clip (`--ref-audio`) or a Kling bound voice. Do not plan silent video + TTS + lip-sync. Lip-sync tools are only for a portrait presenter talking to camera, or for re-syncing footage that already exists. Off-screen narration and voiceover are unaffected: keep using `generate voiceover` for those.\\n\\n**Images:**\\n\\n- `nano-banana-2`: general default, editing, consistency, and references.\\n- `nano-banana-pro`: maximum quality. `nano-banana-2-lite`: fast, inexpensive drafts.\\n- `gpt-image-2.5-flare`: replaces the GPT Image 2 recommendation for posters, logos, signs, title cards, readable text and composition. Use `gpt-image-2.5-sunburst` for extra precision/detail. Both use the same basic options as GPT Image 2: references (up to 16), aspect ratio, 1K/2K/4K resolution, image count (1-4), and quality. Quality adds xhigh/max; auto is charged at the max tier. Other model recommendations are unchanged; explicit `gpt-image-2` requests still use GPT Image 2.\\n\\n**Videos:**\\n\\n- `gemini-omni-1.1-flash`: general default for 3-10s generation, image-to-video, uploaded source edits up to 10s, and silent or voiceover-backed shots (audio is always on, so describe quiet ambience with no speech and mute or mix it on the timeline; only a file with no audio track at all needs `kling-3.0`, `kling-o3` or Seedance with `--no-audio`). It supports first and last frames, up to 10 total image inputs, up to 3 creative reference videos of at most 3 seconds each on `--video-task generate` ONLY, uploaded-video extension, and continuation of an earlier generation through `--previous-interaction-id`. Output is 360p/720p/1080p/4K at 3/10/15/30 cr/s with audio always on. Use `--source-video` for the uploaded edit/extension source; extension sources must be 1-30s. Edit and extend accept EXACTLY ONE input video, so `--ref-video` cannot accompany `--source-video` or `--previous-interaction-id`; only `--ref` images can. One `--ref-video` with no separate source remains a legacy source edit. A previous interaction defaults to conversational edit; add `--video-task extend` or `--extend` with an explicit 3-10s duration to append at the end. A continuation resolves to the prior turn\'s output and is submitted as an ordinary source, so the same limits apply to it: at most 30s to extend, at most 10s to edit. 40 seconds total is reachable, but only by extending from a source of 30s or less, so a ladder dead-ends once it passes 30s. New dialogue can only be added when the SOURCE video is silent; adding speech on top of a source that already contains speech is refused with \\"the model is currently unable to process speech edits\\". The server safely measures creative-reference durations, or you can repeat `--ref-video-duration` when a host blocks metadata probing. Fal BYOK supports its currently callable v1.1 generation and basic-edit endpoints at zero VideoDraft credits, but Fal does not expose continuation/extension or mixed source-edit references as callable endpoints and VideoDraft must never fall back to paid Google.\\n- `grok-imagine-video-1.5` (Tier 2): 1-15s text, first-frame, or 1-7 reference-image generation with native audio. Text/first-frame modes support 480p, 720p, and 1080p; reference mode supports 480p/720p. Cite references as `<IMAGE_0>` through `<IMAGE_6>`. It has no last frame, seed, negative prompt, quality tier, reference video, or reference audio.\\n- `minimax-h3` (Tier 2): 480p/768p/2K/4K (5/6/13/16 cr/s, 768p default), native stereo audio, and 5-15s text, first/last-frame, or mixed-reference generation. Reference mode accepts up to 9 images, 3 videos, and 3 audio clips, with at most 12 files total. Cite them as `Image 1`, `Video 1`, and `Audio 1` in array order.\\n- `minimax-h3-max`: 480p/768p pricing (5/8 cr/s, 768p default), native audio, and 5-15s text, first/last-frame, or mixed-reference generation. Reference mode accepts up to 9 images, 3 videos, and 3 audio clips, with at most 12 files total, cited as `Image 1`, `Video 1`, and `Audio 1` in array order. It supports a reproducibility seed and `disabled` / `balanced` / `quality` prompt expansion.\\n- `wan-3.0` (Tier 2): unified 2-30s text, first/last-frame, or ordered mixed-reference generation at 480p/720p/1080p (7/14/28 cr/s), with optional native audio. Reference mode accepts up to 10 images, 5 videos, and 5 audio clips, at most 20 media files total; video and audio each total at most 15 seconds. `--auto-duration` reserves 30 seconds and reconciles to the provider-reported output length. Document/web references use `--file-url` or `--web-url` and require `--thinking`.\\n- `flux-3` (Tier 2): Black Forest Labs FLUX 3. 5-20s at 720p/1080p with 24fps native audio, from a prompt, a first frame, first + last frames, or up to 10 keyframes pinned to specific moments (`--keyframe shot.png@2.5`, repeatable). `--quality draft` renders the same shot at 720p for roughly a third of the cost. Auto duration is text/first-frame only.\\n- `seedance-2`: 11-15s, video/audio/mixed references, wider ratios, selectable audio, or first/last frames. `mini` is the economical default; move to `standard` when the user asks for high quality, when a Mini result is not good enough, or for 1080p/4K; `fast` for speed.\\n- `seedance-2.5`: 4-30s single takes and up to 50 references (30 image, 10 video, 10 audio). Same modes as 2.0, one quality tier, 480p/720p/1080p. Reach for it when a shot must run past 15s or carry more references than 2.0 allows.\\n- `kling-o3`: reference images plus structured image/video elements, first/last frames, multi-prompt, audio control, or 4K. O3 allows 7 combined image references and image-backed elements, reduced to 4 combined items when a video-backed element is present. `kling-3.0`: image-to-video can use structured image/video elements and bind a custom Kling voice ID to either element form. Tier 2, by name: `kling-v3-turbo` (fast polished 3-15s with first frame, multi-prompt, and audio, but no elements) and Kling 2.6 Pro (top-level voice IDs cited as `<<<voice_1>>>` and `<<<voice_2>>>`).\\n- Existing-video edits use `videodraft edit video`, not generic generation. `gemini-omni-1.1-flash` is the preferred edit model and is chosen automatically when you omit `--model`: source up to 10s, up to 10 reference images, 360p/720p/1080p/4K with audio. Creative `--ref-video` inputs are NOT accepted on an edit, because an edit takes exactly one input video; use `generate video --video-task generate` to guide a new clip with video references instead. Omitting `--model` on a longer or unmeasurable source spends nothing and prints a priced menu (what each model edits, what it drops, what it costs) so you can put the choice to the user. **Truncation:** only Gemini refuses an over-length source. Happy Horse silently edits just the first 15s, Kling O3 the first 10s, and Grok the first 8s. The command warns you when that will happen; always relay it to the user. Gemini regenerates the audio track, so use Happy Horse or Kling O3 with `--preserve-audio` when the source audio must survive. Choose Grok for the cheapest prompt-only edit, Happy Horse for up to 5 image references, or Kling O3 for controlled reference-image edits.\\n- To edit a source longer than 10s without losing its tail, cut it into <=10s pieces in the native editor, edit each with Gemini, and reassemble. VideoDraft has no server-side split/concat, so this path needs `videodraft_editor`.\\n- Kling O3 also has a reference-generation mode. Use `videodraft generate video --model kling-o3-video-ref-edit` with exactly one `--ref-video` to generate a new guided clip; use `videodraft edit video` when changing the source itself. For new mixed-reference generation use Seedance 2 / 2.5.\\n- Motion transfer uses `videodraft edit motion` with Kling V3 by default, or Kling 2.6 when explicitly requested or lower cost matters. It requires a subject image and a motion-reference video.\\n- Veo 3.1, Sora, Grok, Happy Horse and the other Tier 2 video models: only when explicitly requested or when no Tier 1 model fits.\\n\\n**Audio and utilities:**\\n\\n- Use Seed Audio 1.0 for open-ended text-to-audio, speech/music/sound synthesis, voice conditioning, or prompt-driven editing with up to three audio references or one image. Use `videodraft generate audio`. Reference clips are `@Audio1`, `@Audio2`, and `@Audio3` in array order. There is no duration input. Output is up to two minutes and settles at 19 credits per actual minute, with up to 38 credits reserved during generation. The CLI automatically retries transient responses with one operation key. To recover after the CLI process itself is interrupted, set `--idempotency-key <uuid>` on the original command and reuse it.\\n- Prefer ElevenLabs for voiceover, dialogue, voice changing, dubbing, and sound effects. Honor an explicitly selected supported TTS voice/provider. Use `lyria-3.5` for all music, short or long (up to ~3 minutes, 10 credits flat), with vocals/lyrics or instrumental arrangements. When `--model` is omitted the CLI sends no model and the server default applies, which is `lyria-3.5` wherever the backend supports it. If the server answers that `lyria-3.5` is an unknown model, that backend predates it: rerun without `--model` (the server default then applies), or use `lyria-3-pro-preview` for a track longer than 30 seconds. Ask for the length in the prompt. Keep `lyria-3-clip-preview` (fixed ~30s, 4 credits) and `lyria-3-pro-preview` (8 credits) for explicit requests. For Lyria, put desired length, lyrics and \\"instrumental only, no vocals\\" in the prompt; `--length` and `--instrumental` are ElevenLabs-only. Use ElevenLabs Music for exact timing, composition plans, or a style reference track. Lyria allows 10 reference images on Google, 1 on Fal BYOK; Fal 3.5 prompts are limited to 5000 characters. BYOK uses zero VideoDraft credits. ElevenLabs Music means `elevenlabs-music-v2.5` (`elevenlabs-music` is an alias for it); use `elevenlabs-music-v1` only when the user asks for v1 by name.\\n- For ElevenLabs voiceover, dialogue, and voice changing, accept a supplied raw voice ID (16-64 alphanumeric characters) or `elevenlabs-<id>`. The voice catalog is for discovery, not an allowlist. Do not reject or substitute a supplied ID because it is absent from `videodraft models voices` / `list_available_voices`. Use `--voice <id>` for voiceover and voice changing, or repeat `--line \\"<id>:Text\\"` for dialogue; for example, `--voice kPzsL2i3teMYv0FxEYQ6` and `--line \\"elevenlabs-kPzsL2i3teMYv0FxEYQ6:Hello.\\"` use the same voice. The voice must be accessible to the provider account used for generation. Private or cloned voices may require the user\'s connected ElevenLabs key. Kling video-control IDs and MiniMax `custom-*` IDs are separate voice systems.\\n- A character who needs to TALK:\\n  - **Speaking inside a scene**, or any ordinary clip with dialogue: `generate video` with the line in the prompt, in quotes, with who says it and how. `gemini-omni-1.1-flash`, `seedance-2.5`, `seedance-2`, `kling-3.0` and `kling-o3` all voice it natively. For a specific voice use a Seedance `--ref-audio` clip or a Kling voice bound per element. This is the default path; do not generate speech separately and lip-sync it on.\\n  - **Talking to camera from a portrait** (presenter, spokesperson, explainer): the avatar lane, and VEED Fabric is preferred. Use managed `avatar create` then `avatar render` for a reusable avatar record with bundled speech, `avatar fabric` for a one-off portrait plus text or existing audio, and `avatar h3-lipsync` for a short (5-14.8s) portrait clip from existing audio at up to 2K. Not for in-scene shots: Fabric animates a portrait facing the lens, so a cinematic request comes back as a head-on talking headshot.\\n  - **Footage that already exists plus replacement audio** (re-dub, translation): `avatar lipsync`. This is the only job for Sync Labs unless the user names it.\\n- Enhancement: use Topaz image/video upscaling only when the content is already correct. Use image 1x for cleanup, 2x by default, 4x when justified; use video 2x by default. Edit or regenerate creative errors.\\n\\nSee [references/models.md](references/models.md) for the detailed routing table and exact capability limits.\\n\\n## Prefer references when continuity matters\\n\\nPure text-to-image or text-to-video is fine for a generic one-off asset. When a specific character, product, location, style, composition, or brand identity must survive generation, use references instead of hoping the prompt recreates it.\\n\\n- If the user supplies reference media, preserve and pass it. Never reduce the request to text alone.\\n- When continuity matters, generate/select a strong still first with the selected image model (`nano-banana-2` by default), wait for its URL, then animate it as a start frame/reference. Confirm the combined image and video cost.\\n- When using a hosted storyboard stage for multiple shots, use `videodraft shots <project_id> --model <selected-image-model> --grid`, then animate the decoded shots. Preserve explicit models. In VideoDraft ADE, import the resulting assets into the native editor instead of continuing into hosted production. A requested non-Seedance video model must use manual per-shot generation instead of Seedance full-video mode.\\n\\n## Cost and credits\\n\\nDo not call `videodraft credits` before routine generations. Paid endpoints validate and deduct atomically; if the balance is insufficient, the request is rejected before the provider job starts (CLI exit code 4). Check the balance only when the user asks, gives a credit budget, or a large workflow needs budget planning.\\n\\nFor expensive work, estimate with `--estimate` or `videodraft costs`, state the selected model/settings/cost, and get a go-ahead. This matters most for shot-image batches, long or high-resolution video, AI Production, and paid audio batches. Honor the user\'s confirmation preference for the session.\\n\\nKling voice creation costs 1 VideoDraft credit on the platform Fal account and 0 credits with Fal BYOK. Preview it with `videodraft kling-voices create <sample> --name <name> --estimate`; the estimate does not create a voice or require consent confirmation. Actual creation requires `--confirm-consent`.\\n\\nMiniMax H3 costs 5 / 6 / 13 / 16 credits per output second at 480p / 768p / 2K / 4K (768p by default). In reference mode the first 5 images are included and each additional image costs 8 credits. Reference video and reference audio are NOT billed.\\n\\nMiniMax H3 Max costs 5 credits per output second at 480p and 8 credits per second at 768p (default), plus pooled reference tokens in reference mode: the first 4,096 are free and every 1,000 after that costs 2 credits, where an image is `(width x height) / 1024` tokens, a reference video is 2,886 tokens per second at 480p or 7,459 at 768p, and reference audio is about 2,121 per second. Use `--prompt-expansion-mode disabled|balanced|quality`; balanced is the default. Fal\'s provider safety checker is OFF by default and is not exposed in the app \u2014 only pass `--safety-checker true` if the user explicitly asks for it.\\n\\nWan 3.0 costs 7 / 14 / 28 credits per output second at 480p / 720p / 1080p. Auto duration reserves the 30-second maximum and refunds the unused reserve after the provider reports the actual whole-second output length. Fal BYOK runs on the connected user key and charges zero VideoDraft credits.\\n\\nGrok Imagine Video 1.5 costs 8 credits per output second at 480p, 14 at 720p, or 25 at 1080p, plus 1 credit for each first-frame or reference image. Native audio is always generated.\\n\\n`videodraft models image|video` lists the live image and video catalogs with supported inputs. Video entries are grouped as `generation`, `video_edit`, `motion_control`, `avatar_lipsync`, and `upscale`, and each reports the exact tool. Use `videodraft models video --category video_edit` to narrow the list. `videodraft models audio` lists Seed Audio, Google Lyria, and ElevenLabs audio/media tools, while `videodraft models voices` helps discover TTS voices. Consult them for capabilities; a supplied ElevenLabs voice ID does not need to appear in the voice catalog.\\n\\n## Async jobs\\n\\nImage/video generation is asynchronous: commands submit a job and **wait by default**, printing output URLs (and saving files with `--download`). Large downloaded images also get a downscaled copy in `previews/` next to them (the `preview` field / \\"inspect via preview\\" line in the output) \u2014 **look at the preview, deliver the original**; viewing full-resolution images bloats the chat permanently. In scripts/CI prefer explicit control:\\n\\n```bash\\nJOB=$(videodraft generate image \\"...\\" --no-wait --json | jq -r .job_id)\\nvideodraft wait \\"$JOB\\" --download \\"./outputs/{job_id}_{index}.{ext}\\" --json\\n```\\n\\nFor MANY jobs: submit each with `--no-wait`, collect ALL with one command \u2014 `videodraft wait <id1> <id2> ...` polls every job from one process with one batched request per tick. Do NOT spawn parallel `wait`/`generate --wait` processes for a batch.\\n\\nIf a wait times out, the job is still running server-side \u2014 `videodraft status <job_id>` later. Never re-submit just because a wait timed out (that double-spends credits).\\n\\nFor completed Wan 3.0 jobs, MCP `check_generation_status` and CLI `status`/`wait --json` include `outputMetadata` with Fal\'s returned `seed`, `duration`, and `actual_prompt` when present.\\n\\n## AI Studio sessions\\n\\nStandalone image/video/audio generations are filed into an AI Studio session in the web app. 3D assets use `assets 3d list/get` separately. You do not have to create an AI Studio session:\\n\\n- **MCP hosts** (Claude Code, claude.ai, Codex, VideoDraft ADE): on 2025-era MCP the server mints an `Mcp-Session-Id` on `initialize`; your host echoes it, and this conversation\'s generations land in their own session. On stateless MCP (2026-07-28) hosts that send a conversation id (ChatGPT) get the same. Otherwise `name_current_ai_studio_session` returns `pass_session_id: true` with a `session_id`: pass that `session_id` to every later standalone generation in the conversation. Tool results echo the session as `ai_studio_session_id`.\\n- **CLI**: the same handshake runs once per (profile, server, working directory) and is cached for 12 idle hours, so everything generated from one directory shares one session. `videodraft sessions current` shows it; `videodraft sessions reset` starts a new one.\\n- Project generations (`--project <id>` / `project_id`) always go to that project\'s session.\\n\\nOnce you understand the creative task, name the current automatic session before the first standalone generation:\\n\\n```bash\\nvideodraft sessions name \\"Purple Seal Rescue Short\\"\\n```\\n\\nChoose a concise, specific 3-6 word title for the intended work. Do not copy the client name, date, or exact chat title. Name it once: the operation creates the session with that title. If generation, a user, or an earlier agent created the session first, its existing name is preserved.\\n\\nApart from the `pass_session_id: true` case above, pass `--session <id>` / `session_id` only to **continue earlier work** or create an explicit separate group:\\n\\n```bash\\nSESSION=$(videodraft sessions create \\"Fox brand explorations\\" --json | jq -r \'.session.id\')\\nvideodraft generate image \\"a red fox in snow, cinematic\\" --session \\"$SESSION\\"\\nvideodraft generations --session \\"$SESSION\\"          # what is in it\\nvideodraft sessions list --name fox                  # find it again later\\n```\\n\\n`VIDEODRAFT_SESSION=<id>` sets the default for every command (ignored when `--project` is given). While it is set, `sessions name` refuses to run because that command names the current automatic connection session, not the pinned override; unset it first or rename the pinned session in AI Studio. `VIDEODRAFT_SESSION_SCOPE=<label>` groups several directories into one connection session; `VIDEODRAFT_CLIENT_NAME=<host>` labels the fallback placeholder used when generation creates the session before `sessions name`; `VIDEODRAFT_NO_SESSION=1` disables the handshake. Generations that reach the server with no session at all fall back to the account-wide \\"Agent (MCP)\\" session; if you see work landing there, pass `--session` explicitly.\\n\\n## Generation history\\n\\nPast work is queryable \u2014 reuse a previous setup instead of guessing. `videodraft generations` lists recent generations; scope with `--session <id>` or `--project <id>` (includes collaborators\' rows in shared scopes; pass one, project wins), and filter with `--type`, `--model`, `--favorites`. `--full --json` returns each row\'s exact parameters (aspect ratio, resolution, duration, references) \u2014 the human table stays compact, so pair `--full` with `--json`. `videodraft generation <id>` prints one generation\'s complete recipe (prompt, input image, parameters, outputs); `--favorite` / `--unfavorite` stars it. `videodraft sessions list` shows AI Studio sessions (owned + shared) with `--name` search \u2014 take a session id from there to read its history.\\n\\n## Free stock footage and photos\\n\\nPexels and Pixabay are wired in through `search_stock_media` / `import_stock_media` (`videodraft stock search \\"<query>\\"`, `videodraft stock import <ref>`). Both libraries are free, watermark-free and cost **zero credits**, so use stock for b-roll, establishing shots, backgrounds and ordinary real-world footage, and spend credits on the shots that must be specific: the product, the character, the scripted action.\\n\\n```bash\\nvideodraft stock search \\"city skyline night\\" --min-duration 5 --orientation landscape\\nURL=$(videodraft stock import pexels:video:35379336 --quality hd --json | jq -r .url)\\n```\\n\\n- Always two steps. A search result\'s `preview_url` is a thumbnail for judging the shot; never place it on a timeline, attach it to a shot or send it to a model. `import_stock_media` copies the file onto the VideoDraft CDN and returns the URL every other surface accepts, including the native editor\'s `library_manage` import.\\n- `--quality hd` (default) caps video at 1080p; `4k` caps at 2160p, `best` takes the largest the provider has, `sd` suits rough cuts. Stills ignore quality and import at full size. Use `--orientation portrait` for 9:16, and `--min-resolution 1920` to drop anything below HD on its long edge.\\n- Photos come from Pexels. Pixabay contributes video only, because its full-size image host refuses server-side downloads.\\n- Credit the creator and link the provider page when you show results or deliver the finished work; both come back on every result. Skip clips that imply a person or brand endorses the product, and avoid recognisable logos in ads.\\n- Search and import are rate limited per user (30 searches and 15 imports a minute) and searches are cached for 24h, so a burst of searches while planning a montage is fine. Bulk downloading a stock library is prohibited by both providers. A note saying Pixabay was skipped means its provider budget for that minute is spent; the Pexels results still stand.\\n\\n## Downloading from YouTube, Instagram, TikTok and other sites\\n\\nVideoDraft ships no downloader. When the user asks to pull a video from YouTube, Instagram, TikTok, X, LinkedIn or anywhere else, `yt-dlp` on the user\'s own machine does the work. Check for it with `command -v yt-dlp` before promising anything.\\n\\n**Present:** pin the format. On its defaults yt-dlp takes the best stream, usually VP9 or AV1 in WebM, which the native editor\'s import rejects (mp4, mov and m4v only). This returns one pre-muxed H.264 + AAC MP4 and needs no ffmpeg:\\n\\n```bash\\nyt-dlp -f \\"b[ext=mp4]\\" -o \\"media/%(title)s.%(ext)s\\" \\"<url>\\"\\n```\\n\\n**Missing:** say so in one line, then offer `brew install yt-dlp` only where `brew` exists, and only after asking. With no Homebrew, say the tool is unavailable and stop.\\n\\n- Never install Homebrew, never `sudo`, never write to `/usr/local/bin` or `/opt`, never pipe a script into a shell.\\n- `ffmpeg` is optional, matters only above 720p, and the selector above never needs it.\\n- Auth-gated content needs `--cookies-from-browser`; raise it only after a download fails on auth.\\n- Fetch only what was asked for, never a channel, playlist or back catalogue.\\n\\n## Local files and reference images\\n\\nReference inputs must be public URLs. The CLI uploads local files automatically wherever a URL is expected (`--ref photo.jpg`, `--start-image frame.png`), or explicitly:\\n\\n```bash\\nURL=$(videodraft upload ./product.png --json | jq -r .url)\\n```\\n\\nNever silently drop a reference you couldn\'t upload \u2014 stop and tell the user. Never upload a user\'s file to a third-party host.\\n\\nWhen the user attaches media for a native production, import actual footage into the editor by default. For hosted generation/storyboarding, classify each item before acting: a recurring **visual asset** (character/product/location/style), actual **footage to place as shots**, or **inspiration only**. See [references/pipeline.md](references/pipeline.md) for the hosted role mapping.\\n\\n## Showing media to the user\\n\\nGenerated media is **not** displayed in the chat automatically \u2014 you decide what to show. To preview an asset inline, save it locally (use `--download` so it lands under `media/`) and reference its **local path** as a Markdown link with a **leading `./`**:\\n\\n```\\n[ferrari shot](./media/ferrari_01.png)     \u2190 image card\\n[the clip](./media/clip.mp4)               \u2190 video player\\n[voiceover](./media/vo.mp3)                \u2190 audio player\\n```\\n\\nPut the Markdown link **in your message text** \u2014 video and audio embed exactly like images. Do **not** use `SendUserFile` (or other file-send tools) to display media: that renders inside a collapsible tool card and gets buried in the tool list. The Markdown link in your prose is what produces the inline card.\\n\\nUse the path you saved to: a **workspace-relative** path (`./media/clip.mp4`, or `./<any-folder>/clip.mp4` \u2014 any folder in the workspace works), or the **absolute** path for a file outside the workspace (e.g. `/Users/you/Desktop/clip.mp4` or another workspace\'s path). Both render. Show the finished results worth showing (and only those \u2014 not every intermediate job). A bare CDN URL or a JSON dump of output URLs does **not** render; the local-path Markdown link is what produces an inline card.\\n\\n## Native-first VideoDraft ADE pipeline (idea \u2192 MP4)\\n\\nWhen `videodraft_editor` is present:\\n\\n1. Generate or source the script, storyboard, shot images, clips, voiceovers, music, and other assets through the cloud CLI/MCP as needed.\\n2. Call native `project_manage` (`project`, action `open` or `create`) to open or create the `.vdproject`.\\n3. Call native `library_manage` `import`, wait for imports to become ready, then assemble and refine the timeline with `edit_apply` recipes.\\n4. Call native `delivery_manage` `submit` and use its `jobs` operation for progress and results.\\n\\nDo not run the hosted production or export steps in this path unless the user explicitly asks for a web production.\\n\\n## Hosted fallback pipeline (idea \u2192 MP4)\\n\\nUse this only when there is NO native editor at all, or the user explicitly requests the hosted web\\nworkflow. The native surface is not only the injected `videodraft_editor` MCP: a `videodraft-editor`\\nexecutable on PATH is the same editor reached through its terminal bridge, and\\n[references/editor.md](references/editor.md) covers driving it that way. Treating a missing MCP as\\n\\"no editor\\" sends sessions that have the binary into hosted production for no reason.\\n\\n```bash\\nvideodraft create \\"<idea>\\" --ar 9:16            # project: script \u2192 visual assets \u2192 storyboard\\nvideodraft shots <project_id> --grid --estimate # cost preview, confirm with user\\nvideodraft shots <project_id> --grid            # batch shot images (waits, writes onto shot cards)\\nvideodraft produce <project_id>                 # voiceovers + captions + production timeline\\nvideodraft export <project_id> --download final.mp4\\n```\\n\\nOptional between produce and export: per-shot motion clips (`videodraft generate video ... --project <id>` then place it with `videodraft attach <project> --scene N --shot M --media <url|file> --type video --duration <s>`), music (`videodraft generate music \\"...\\" --attach <project_id>`), and standalone audio assets (`generate audio`, `generate sound-effect`, `generate dialogue`, `generate voice-changer`, `generate dub`). Details, per-step tools and editing rules: [references/pipeline.md](references/pipeline.md).\\n\\n## Avatar and talking-head videos (both surfaces)\\n\\nAvatar generation is cloud-only \u2014 the native editor has no avatar or lipsync tools \u2014 so this applies whether or not `videodraft_editor` is present. Generate the avatar in the cloud; in VideoDraft ADE, import the rendered clip and cut it on the native timeline like any other footage.\\n\\nAvatar/talking-head videos use dedicated commands. For a reusable managed avatar, obtain or generate a clear portrait \u2192 `videodraft avatar script` when needed \u2192 `videodraft avatar create` \u2192 `videodraft avatar render --resolution 720p`. For a one-off portrait, use `videodraft avatar fabric <portrait> --text \\"...\\"` or `--audio <file>`, or `videodraft avatar h3-lipsync <portrait> --audio <file>` for a short high-resolution clip from existing audio. For an existing video plus replacement audio, use `videodraft avatar lipsync <video> --audio <file>`. Managed script/creation is bundled/free; direct Fabric, H3 Max Lip Sync, Sync, the managed Fabric render, and optional portrait generation/upscaling are paid. Confirm expensive steps first.\\n\\n## Working with hosted project data\\n\\nA hosted project is one JSON blob (script, storyboard scenes, shot cards, visual assets, production timeline). To inspect: `videodraft projects get <id>`. To edit: fetch `--raw`, modify, then `videodraft call update_project` \u2014 objects deep-merge, **arrays replace wholesale** (send the complete `storyboard.scenes` array to change one scene). Snapshot first with `videodraft checkpoint create <id>` before risky edits. Schema reference: `videodraft call get_project_schema`. This does not replace native editor tools when `videodraft_editor` is available for the production itself.\\n\\n## More\\n\\n- [references/pipeline.md](references/pipeline.md) \u2014 hosted fallback data model and production workflow\\n- [references/editor.md](references/editor.md) \u2014 native headless editor routing, project selection, import, timeline edits, verification, and export\\n- [references/models.md](references/models.md) \u2014 choosing image/video models, pricing patterns, voices and styles\\n- [references/examples.md](references/examples.md) \u2014 recipes: batch product videos from a CSV, talking-head from a script, changelog video in CI\\n","references/3d.md":"# Standalone 3D assets through MCP and CLI\\n\\nUse this lane for downloadable meshes, textured 3D models, and humanoid rigging. These are independent of AI Studio sessions and do not require a storyboard or web viewer. Never create a project just to generate a mesh. Native editor media import does not establish support for GLB/FBX assets; use external 3D software unless the live editor schema explicitly supports them.\\n\\n## Discover and quote\\n\\n```bash\\nvideodraft models 3d --json\\nvideodraft generate 3d \\"a worn brass telescope\\" --model meshy-7 --estimate\\nvideodraft generate 3d --model tripo-h3.1 --ref ./reference.png --options @options.json --estimate\\nvideodraft rig 3d --estimate\\n```\\n\\nMCP tools: `get_3d_models`, `estimate_3d`, `generate_3d`, `rig_3d`, `check_generation_status`, `list_3d_assets`, `get_3d_asset`, `create_3d_upload`, and `finalize_3d_upload`.\\n\\nThe generator catalog is deliberately limited to `meshy-7` and `tripo-h3.1`. Both expose text/image/multi-image modes; use the live schemas for option availability, view order, limits, topology, texture/PBR, and pose controls. Do not invent common provider option names. Server defaults prioritize quality. Rigging is a separate Meshy operation for compatible textured humanoid GLBs; it is not an arbitrary creature or facial rig service.\\n\\nEvery option is accessible through `--options` JSON (`@path.json` supported), plus repeatable `--option key=value` overrides. Values parse as JSON when valid. Options and explicit input mode affect pricing, so obtain a fresh quote for the exact recipe. Estimates perform no file upload or provider generation. VideoDraft bills whole credits at 100 credits per dollar using the server\'s rounding rules. BYOK costs zero VideoDraft credits and runs on the connected user Fal key. Do not infer the user\'s Fal-account charges from a zero VideoDraft-credit quote.\\n\\n## Generate and retrieve\\n\\n```bash\\nvideodraft generate 3d \\"a worn brass telescope\\" --model meshy-7 --download --json\\nvideodraft generate 3d --model meshy-7 --ref ./hero.png --no-wait --json\\nvideodraft generate 3d --model tripo-h3.1 --input-mode multi_image --ref ./front.png --ref ./left.png --ref ./back.png --ref ./right.png --no-wait --json\\nvideodraft status JOB_ID --json\\nvideodraft wait JOB_ID --download --json\\nvideodraft assets 3d list --status completed --json\\nvideodraft assets 3d get ASSET_ID --download ./media/3d --json\\nvideodraft rig 3d --asset ASSET_ID --download --json\\nvideodraft rig 3d ./textured-humanoid.glb --download --json\\n```\\n\\nLocal image references upload automatically. Local rigging inputs must be self-contained `.glb` files and upload via the dedicated 3D route. Input mode is inferred from reference count unless `--input-mode text|image|multi_image` is supplied. A text prompt requires no images; image mode requires exactly one and no geometry prompt. Meshy multi-image accepts 1-4 views, and Tripo accepts 2-4 in front, left, back, right order. Use Meshy\'s `texture_prompt` option when texturing guidance is needed with image inputs. Do not mix unrelated images as if they were views of the same object.\\n\\nGeneration and rigging wait by default. `--no-wait` returns a persisted job that continues server-side. For many jobs use one `wait ID1 ID2 ... --download`; do not run parallel polling processes. Recover timeout with the same job ID, not another paid generation.\\n\\nSubmission returns a `request_id` UUID. A same-request retry must use `--request-id UUID` and the original arguments. The CLI journals resolved uploads in its private config directory so retries reuse the same remote files. Changed inputs under that UUID are rejected. Submission errors include the UUID in JSON `details.request_id` where available. Never retry a failed request with a new UUID until the prior job status is known.\\n\\n## Complete artifact packages\\n\\n`--download` defaults to `media/3d/<asset_id>/`. A user directory is respected and receives a per-asset folder. `{job_id}` and `{asset_id}` directory templates are accepted. Do not pass a `.glb` filename or a media `{index}.{ext}` template: a 3D result can contain multiple formats and texture/material dependencies.\\n\\nDownloads preserve every returned artifact. The manifest records provider URLs, source filenames, local paths, role, content type, and actual downloaded sizes. glTF/OBJ/MTL references are rewritten to saved dependency paths; binary GLB/FBX and provider ZIPs are retained as returned. Supplied dependency aliases become local copies at the paths needed by original FBX files. Unsafe or colliding aliases produce warnings. Existing packages are never overwritten. A successful package has `manifest.json`; read its `complete` field and `warnings`, plus CLI `package_warnings`. Do not claim a package with unresolved dependencies is ready for offline use.\\n\\nMachine results use `type: \\"model3d\\"` with `output_files` for files and `output_media` only for ordinary preview media. Texture maps and models are not image/video gallery entries. Show a supplied preview via a local image Markdown link and deliver the original mesh/package files. Do not imply an interactive 3D viewer exists in AI Studio or VideoDraft ADE.\\n","references/editor.md":"# Native VideoDraft Editor reference\\n\\nUse this reference when the user wants to assemble, cut, caption, mix, lay out, inspect, or export a local VideoDraft Editor project. The native editor is deterministic and local. Cloud generation remains in the `videodraft` CLI or hosted MCP.\\n\\n## VideoDraft ADE preference rule\\n\\nWhen `videodraft_editor` tools are exposed, treat the native editor as available and make it the default surface for production, timeline assembly, and final export. It is headless by design, so a hidden window or an untouched Open Editor button does not justify using hosted production instead.\\n\\nUse cloud tools for asset generation and optional script/storyboard work, then import the results. Do not call hosted `produce_project` / `videodraft produce` or `export_video` / `videodraft export` unless the user explicitly requests an editable web production or the native editor tools are unavailable. If a native tool call fails after the editor was available, report or recover that native failure rather than silently switching surfaces.\\n\\n## Choose the correct surface\\n\\n- `videodraft` and the hosted VideoDraft MCP generate assets and can manage hosted web projects. They use the user\'s VideoDraft account and credits. In VideoDraft ADE, use them mainly as the source of generated media and optional storyboards for the native production.\\n- `videodraft_editor` edits local `.vdproject` packages. It has no generation, account, model, or credit tools.\\n- Inside VideoDraft ADE on a supported Mac, the editor MCP is injected automatically for Claude, Codex, OpenCode and Grok in both Code and VideoDraft modes. It starts headlessly before the chat opens. The user does not need to click Open Editor, and closing or hiding the editor window does not stop headless editing.\\n- Outside that environment, use the editor only if `videodraft_editor` MCP tools are already exposed or the `videodraft-editor` executable is on PATH. Do not confuse the public `videodraft` cloud CLI with the separate native editor executable.\\n\\nPrefer the direct MCP tools when they are available. The terminal bridge is useful for scripts, diagnostics, or an agent session where the MCP was not injected.\\n\\n## Which editor tools you have\\n\\nCurrent editors expose eight workflow tools: `project_manage`, `edit_snapshot`, `edit_apply`, `edit_undo`, `library_manage`, `inspect`, `speech_apply`, and `delivery_manage`. Use them whenever `edit_apply` is available. Everything below describes them.\\n\\nEarlier editors expose a different set of tools. If `edit_apply` is not in your catalog, follow the live tool descriptions; the working rules below still apply.\\n\\nThe live tool descriptions and schemas are authoritative. When they differ from this reference, follow them.\\n\\nService tools (`project_manage`, `library_manage`, `inspect`, `speech_apply`, `delivery_manage`) take `operation` and `parameters`, plus an optional `context` (see [Keep a reliable editing model](#keep-a-reliable-editing-model)):\\n\\n```json\\n{\\"operation\\": \\"import\\", \\"parameters\\": {\\"source\\": {\\"path\\": \\"/Users/me/clips\\"}}}\\n```\\n\\n### Parameters at a glance\\n\\nEach operation\'s schema has the full list. These are the fields that matter most, and the ones most often confused:\\n\\n| Tool and operation | Key `parameters` |\\n| --- | --- |\\n| `project_manage` `project` | `action` (`list`, `open`, `create`, `close`); `id`, `name` or `path` to open; `name`, `fps`, `aspectRatio`, `quality` to create |\\n| `edit_snapshot` (no `parameters`) | `includeLibrary`, a `startFrame`/`endFrame` window, `offset`/`limit` paging, `context` for later pages |\\n| `edit_apply` (no `parameters`) | `actions`; optional `context`, `requestId`, `previewOnly` |\\n| `library_manage` `import` | `source` with one of `path`, `url`, `bytes` + `mimeType`, or `matte`; optional `name`, `folder`. A `.srt` or `.vtt` file becomes captions |\\n| `library_manage` `list` | `ids` to poll imports, `pending`, `folder` |\\n| `inspect` `timeline` | a `startFrame`/`endFrame` window; there is no clip filter |\\n| `inspect` `frame` | `startFrame` for one frame; add `endFrame` and `maxFrames` to sample a range |\\n| `inspect` `media` | `mediaRef` (a library asset, not a file path), `startSeconds`/`endSeconds` in source seconds, `wordTimestamps`, `overview` |\\n| `inspect` `transcript` | a `startFrame`/`endFrame` window, `granularity` (`words` or `segments`), `clipId` |\\n| `inspect` `color` | `clipId` with `atFrame`, or `mediaRef`; optional `reference` |\\n| `speech_apply` `words` | `words`: transcript word indices, each one index or a `[first, last]` pair; or `matches`: exact words to remove everywhere; `pacing` |\\n| `speech_apply` `silence` | none |\\n| `speech_apply` `captions` | caption `style`, `position` and look fields; it finds the speech itself. `style` `plain` (sentences without a preset) takes `positionY` or `transform.centerY`, not `position` or `punctuation` |\\n| `delivery_manage` `submit` | `mode`, `codec`, `resolution`, `outputPath` (its folder must already exist); `captionGroupId` and `wordTiming` for `srt` and `vtt`; `check: false` skips a video\'s export check |\\n| `delivery_manage` `jobs` | `action` `list` (every job with its progress, warnings, output path and check findings; with a `jobId`, that job with all its findings), `cancel` with a `jobId`, or `dismiss` with a `jobId` and optional `findingIds` |\\n\\n`previewOnly` exists only on `edit_apply`. Service operations apply immediately.\\n\\n### `edit_apply` actions at a glance\\n\\nEvery action puts its fields beside `kind`, for example `{\\"kind\\": \\"adjust\\", \\"clipId\\": \\"c1\\", \\"speed\\": 2}`. `remove`, `adjust`, `replace`, `transition`, `mask`, `text`, `grade` and `effects` take `clipId` for one clip or `clipIds` for several; `animate`, `extract`, and the rows of `move` and `split` take a single `clipId`. Advanced actions cannot take `as`, but their clip ids accept `@name`. The one exception is `transition`, whose own `kind` field names the style, so its fields go inside `parameters`: `{\\"kind\\": \\"transition\\", \\"parameters\\": {\\"clipId\\": \\"c2\\", \\"kind\\": \\"dipToBlack\\"}}`. These `actions` place a clip, warm it and add a vignette:\\n\\n```json\\n[{\\"kind\\": \\"place\\", \\"assetId\\": \\"\u2026\\", \\"atFrame\\": 0, \\"as\\": \\"shot\\"},\\n {\\"kind\\": \\"grade\\", \\"clipId\\": \\"@shot\\", \\"adjustments\\": {\\"temperature\\": 7500}},\\n {\\"kind\\": \\"effects\\", \\"clipId\\": \\"@shot\\", \\"effects\\": [{\\"type\\": \\"finish.vignette\\", \\"params\\": {\\"strength\\": 35}}]}]\\n```\\n\\n| Advanced `kind` | Key fields |\\n| --- | --- |\\n| `place_batch` | `entries: [{mediaRef, startFrame, endFrame or source, trackIndex}]`, not the concise `assetId`, `atFrame`, `durationFrames`; leave `trackIndex` off every entry for a new track |\\n| `insert_batch` | `trackIndex`, `atFrame`, `entries: [{mediaRef, durationFrames or source}]`; later clips move right |\\n| `move` | `moves: [{clipId, toFrame, toTrack}]` |\\n| `remove` | `clipId` or `clipIds`; leaves a gap |\\n| `split` | `splits: [{clipId, atFrame}]`, or `trackIndex` with `frames` |\\n| `extract` | `trackIndex` with `ranges: [[start, end]]` in frames, or `clipId` with `ranges` and `units` (`frames`, or source `seconds`); closes the gap |\\n| `adjust` | `clipId` or `clipIds` plus any of `durationFrames`, `trimStartFrame`, `trimEndFrame`, `speed`, `speedCurve` (`{preset}`, or `{points: [{t, rate}]}` with `t` from 0 to 1 along the source), `preservesPitch`, `volume`, `opacity`, `transform` (`centerX`, `centerY`, `width`, `height`, `flipHorizontal`, `flipVertical`), `blendMode` |\\n| `animate` | `clipId`, `property` (`volume`, `opacity`, `rotation`, `position`, `scale`, `crop`), `keyframes: [[frame, ...values]]` with frames counted from the clip\'s start; `position` is the top-left corner |\\n| `arrange` | `layout`, `slots: [{slot, clipIds or mediaRef, anchor}]`, `fit` (`fill` or `fit`); `mediaRef` slots also need `endFrame` |\\n| `transition` (fields inside `parameters`) | `clipId` or `clipIds` (the clip after each cut), `kind` (`crossDissolve`, `dipToBlack`, `dipToWhite`, `blurDissolve`, `push`, `linearWipe`, `whipPan`, `crossZoom`, or `none` to remove), `durationFrames`, `params` (`direction` 0 to 3 for left, right, up, down; `feather`; `blur`; `intensity`) |\\n| `mask` | `clipId` or `clipIds`, `shape` (`rectangle`, `ellipse`, `none`), `centerX`, `centerY`, `width`, `height` (0 to 1 of the clip\'s own frame), `feather`, `strength`, `inverted` |\\n| `replace` | `clipId` or `clipIds`, `mediaRef` (a library asset of the same kind), `trim` (`keep`, the default, or `reset`), `linkedAudio` (`follow`, the default, or `keep`) |\\n| `tracks` | `reorder: [{trackId, to}]`, `set: [{trackId, muted, hidden, syncLocked}]`, `remove: [{trackId}]`; there is no add, since placing without a track makes one |\\n| `titles` | `entries: [{startFrame, endFrame, content}]`, optionally with `trackIndex` (on every entry or none), `style`, `animation`, `transform` and typography (`fontName`, `fontSize`, `color`) |\\n| `text` | `clipId`, `clipIds` or `captionGroupId`, with `content`, `style`, `position`, `animation` or typography |\\n| `grade` | `clipId` or `clipIds`, `adjustments`, `wheels`, `curves`, `hueCurves`, `lut`, `reset` |\\n| `effects` | `clipId` or `clipIds`, `effects: [{type, params, enabled}]`, `remove: [type]` |\\n\\n- `grade`: `adjustments` holds `exposure` (EV, -4 to 4), `temperature` (kelvin, 1800 to 15000, 6500 neutral, higher is warmer), `tint` (-150 magenta to 150 green); `contrast`, `highlights`, `shadows`, `whites`, `blacks`, `vibrance` and `saturation` are signed percents (-100 to 100, 0 neutral), not factors like 1.2. `wheels`: `shadows`, `midtones`, `highlights`, each `{hue, strength, brightness}`. `curves`: `luma`, `red`, `green`, `blue` as `[x, y]` points from 0 to 1. `hueCurves`: `targets: [{hue, rotate, saturation, lightness}]`. `lut`: `{path, mix}`, with the `storedPath` from `prepare_look`. Out-of-range values are refused.\\n- Effect `type` ids and their knobs, which go inside `params` and run 0 to 100 unless noted. Defaults leave the picture unchanged, so send the knob you want to see:\\n  - `finish.vignette`: `strength` and `curvature` (-100 to 100; positive `strength` darkens the edges), `size`, `falloff`\\n  - `finish.grain`: `strength`, `grainSize` (0.5 to 6 px); `finish.glow`: `strength`, `haloRadius` (px), `cutoff`, `halation`\\n  - `defocus.gaussian`: `blurRadius` (px); `defocus.motion`: `streakLength` (px), `streakAngle` (-180 to 180 degrees)\\n  - `texture.clarity`: `localContrast`, `hazeRemoval` (-100 to 100); `texture.sharpen`: `strength` (0 to 200); `texture.denoise`: `strength`\\n  - `matte.chroma`: `screenHue` (0 to 360 degrees, 120 is green), `range`, `edgeSoftness`, `spillSuppression`\\n- `arrange` layouts and their slots (fill every slot): `fullscreen` (`stage`); `split` (`left`, `right`); `stack` (`top`, `bottom`); `corner_top_left`, `corner_top_right`, `corner_bottom_left`, `corner_bottom_right` (`stage`, `corner`); `quad` (`top_left`, `top_right`, `bottom_left`, `bottom_right`); `side_panel` (`stage`, `panel`); `thirds` (`left`, `middle`, `right`). The layout picks the corner; `anchor` only biases the crop.\\n- `trackIndex` and `toTrack` are an existing track\'s `order` from `edit_snapshot` (0 draws on top), counted at that point in the recipe: a track an earlier action adds shifts them. `tracks` takes `trackId` handles instead.\\n\\n## Start with the intended project\\n\\nAn MCP session can begin without a project selected. Project selection belongs to the session, not to whichever editor window happens to be frontmost.\\n\\n1. If the user named an existing project but its identity is unclear, call `project_manage` with `operation: \\"project\\"` and `parameters.action: \\"list\\"`.\\n2. Open the exact project with `action: \\"open\\"` and the returned `id`, an unambiguous `name`, or the `.vdproject` `path`.\\n3. Create only when the user wants a new local edit. `action: \\"create\\"` accepts optional `name`, `fps`, `aspectRatio`, and `quality`.\\n4. Treat `isActive` as this session\'s target and `isVisible` as the project shown in the UI. Headless editing only needs the session target.\\n5. Use `action: \\"close\\"` only when closing is part of the task. It saves first and never deletes the project. Afterwards other calls answer `no_project` until you open or create a project again.\\n\\nOther `project_manage` operations: `create_timeline` and `select_timeline` for additional timelines, and `configure` for project settings (a frame-rate change applies to every timeline).\\n\\nDo not substitute a hosted project ID for a native project. A hosted project can supply scripts, storyboards, and generated media, but the native edit is a separate `.vdproject` package.\\n\\n## Keep a reliable editing model\\n\\n- Opening or creating a project, and creating or selecting a timeline, returns `data.snapshot` (the `edit_snapshot` view with the library: format, tracks, clips and assets) and a `context`, so you can edit right away. Call `edit_snapshot` only after an out-of-band user edit, to page a long timeline with `offset` and `limit`, or for handles you lack.\\n- `context` (`epoch`, `timelineId`, `revision`) is optional on every write except `edit_undo` and `project_manage` `project`, which take none. Without it, a write applies to the current state. With it, the editor refuses the write if the project changed since that context, which is what you want when a person may be editing at the same time. Every reply returns a fresh `context`. After `context_expired` (a reopen or restart), take a new snapshot.\\n- Timeline positions and durations are frames at `format.fps`. `sourceSeconds` values are seconds in the source file. Pass values as returned; do not multiply or divide by fps yourself.\\n- IDs are short handles. Pass them back exactly as returned; do not derive them from UUIDs. Tracks keep stable handles; indexes can change.\\n- When the user says \\"this clip\\", \\"these captions\\", or \\"here\\", take a fresh `edit_snapshot` (a one-frame window is enough). Its `selection` names what they selected in the project\'s window, in the snapshot\'s handles: `clipIds`, `captionGroupIds`, a `gap`, the marked `range`, and library `mediaIds`; no `selection` means nothing is selected. `currentFrame` is the playhead. `visible: false` means the user is not looking at this project.\\n- Send writes serially. Parallel writes against one project race each other\'s context.\\n- A refused call answers `status: \\"rejected\\"`: nothing changed, so fix what the message names and send it again. A service write that answers `failed` may have applied before a save or connection failed; inspect before repeating it.\\n- Use `inspect` for detail and verification: `timeline` for exact clip and track properties, `frame` for rendered frames of the composited result, `media` before describing source content, `color` for scopes, and `transcript` to locate spoken words.\\n- Volume values, including volume keyframes, are linear from `0` to `1`.\\n\\n## Edit with recipes\\n\\n`edit_apply` takes an ordered list of `actions`, plus an optional `context` and `requestId`. The editor validates the whole recipe before changing anything, then applies it as one undo step. If any action fails, nothing changes and the error names the action. An applied reply lists the resulting `clips` (position, length, source window, text); use it to confirm the edit instead of re-reading.\\n\\n- Concise actions: `place` (an `assetId` at `atFrame`, optionally on a `trackId`, with `durationFrames` or `sourceSeconds`, `mode` `overwrite` or `insert`), `trim` (a `clipId` to a `sourceSeconds` window), and `title` (`text` at `atFrame` for `durationFrames`, optional `look` and `motion`). Name an action with `as` and address its clip in later actions as `@name`.\\n- Advanced actions put their fields beside `kind` too: `place_batch`, `insert_batch`, `move`, `remove`, `split`, `extract`, `adjust`, `animate`, `arrange`, `transition` (fields inside `parameters`), `mask`, `replace`, `tracks`, `titles`, `text`, `grade`, and `effects`. Their field help lists every supported effect, grading control, mask, layout, speed curve, and caption control.\\n- Use `arrange` for split screens, picture-in-picture, grids, and canvas placement, and `tracks` to fix stacking. Do not synthesize layouts from generic transforms or keyframes.\\n- Use `replace` to swap a clip\'s media and keep its timing, effects, keyframes, and links, for example a re-render of the same shot. `trim: \\"keep\\"` holds the clip\'s source offsets; `trim: \\"reset\\"` plays the new media from its first frame and keeps linked audio in sync.\\n- Put every edit a request needs into one recipe: placing, trimming, titling, grading and effects together are one call and one undo step. Use `previewOnly: true` to validate a large or risky recipe without editing.\\n- Send a `requestId` when a retry must not edit twice: repeating the identical request with the same `requestId` returns the original receipt, even after a dropped connection. Without one, a repeated request applies again. Use a new `requestId` for a different edit.\\n- `applied_unsaved` means the edit applied but saving failed. If you sent your own `requestId`, repeat the identical request to retry the save, not the edit. Without one, do not resend: a repeat would apply the edit again.\\n- `edit_undo` reverses this connection\'s latest edit while it is still the top undo step. It never undoes the user\'s own edits. Take a new snapshot afterward.\\n\\nEdits are undoable. Do not ask for confirmation before each ordinary edit. Ask one focused question only when the user\'s creative direction is materially ambiguous.\\n\\n## Bring generated or local media into the editor\\n\\nFor b-roll and establishing shots, search free stock first (`videodraft stock search \\"<query>\\"`), import the pick with `videodraft stock import <ref>`, and feed the returned CDN URL to `library_manage` `import` as `source.url`. It costs no credits.\\n\\nOtherwise use cloud generation for new assets, save or download the outputs, then call `library_manage` with `operation: \\"import\\"`:\\n\\n- `source.path`: absolute local file or directory. A directory imports recursively and preserves its folder structure.\\n- `source.url`: HTTPS asset URL. Set `mimeType` when a signed URL has no usable extension.\\n- `source.bytes`: small base64 media with a required `mimeType`.\\n- `source.matte`: generated solid-color image.\\n\\nReadiness differs by source, and so does the poll that detects it:\\n\\n- **URL and single-file path** imports return `status: \\"downloading\\"` with one `mediaRef`. Poll `library_manage` `list` with `parameters.ids: [mediaRef]` until `generationStatus` is absent.\\n- **Directory** imports also return `status: \\"downloading\\"` with one placeholder `mediaRef` for the batch. Poll it the same way; the folder\'s assets appear when `generationStatus` clears. (`pending: true` remains a fallback that lists every unresolved import.)\\n- **Inline bytes and matte** imports finish inline and come back `status: \\"ready\\"`; no polling is needed.\\n\\nAn import\'s `mediaRef` is the `assetId` that recipe actions take. Never place a pending asset on the timeline. `generationStatus` is the signal: `preparing`, `generating`, `downloading`, and `rendering` mean keep polling, absent means usable, and **`failed` is terminal**. Report it or retry the import explicitly; never poll on. Do not treat \\"not downloading\\" as ready.\\n\\nA `.srt` or `.vtt` caption file (by `path`, `url`, or `bytes` with `mimeType` `application/x-subrip`, `text/srt`, or `text/vtt`) is not added to the library. Its captions go onto a new caption track at the times the file gives, as one undo step, and the reply names the new `captionGroupId` to restyle with a `text` action.\\n\\nFor a batch of local outputs, download them into one workspace directory and import that directory once when practical. This is safer and faster than racing many import calls.\\n\\nTo apply a LUT, first store it with `library_manage` `prepare_look` (`parameters.path` to a `.cube` file), then use the returned `storedPath` in a `grade` action.\\n\\n## Speech edits\\n\\n`speech_apply` runs speech work as separate operations, not recipe actions: `words` removes transcript words, `silence` trims dead air, and `captions` generates styled captions. Read a fresh transcript with `inspect` `transcript` after any speech edit, because word positions change.\\n\\n## Service operations and timeouts\\n\\n`project_manage`, `library_manage`, `speech_apply`, and `delivery_manage` writes have no retry receipts. After a timeout, inspect the outcome (a snapshot, a library `list`, or delivery `jobs`) before repeating a write. A failed service write may have applied an edit before saving failed, so read its `data` and the current state.\\n\\n## Edit and verify\\n\\nA dependable sequence:\\n\\n1. `project_manage` to select or create the local project; its reply carries the snapshot.\\n2. `inspect` `media` when content selection matters.\\n3. One `edit_apply` recipe with every clip, track, layout, text, audio, color, and effect change the request needs; `speech_apply` for word cuts, silence, and captions.\\n4. Check the reply\'s `clips`; use `inspect` `frame` only when visual composition or layer order matters.\\n5. `edit_undo` if the result is wrong and the next recipe would not cleanly correct it.\\n\\n## Export\\n\\nCall `delivery_manage` with `operation: \\"submit\\"`. Submission is not completion: it returns a job, destination, and `started` or `queued` status.\\n\\n- Use `mode: \\"video\\"` for H.264, H.265, or ProRes.\\n- Use `mode: \\"xml\\"` (XMEML) for Premiere Pro **and DaVinci Resolve**. Resolve reads XMEML natively. Use `fcpxml` only for Final Cut Pro; sending Resolve an FCPXML produces a package it cannot open cleanly.\\n- Use `mode: \\"videodraft\\"` for a self-contained project package.\\n- Use `mode: \\"srt\\"` or `mode: \\"vtt\\"` for a subtitle file of the captions: words and timing only, without styling. `captionGroupId` picks a caption group; `wordTiming: true` adds each word\'s start to a `vtt`.\\n- Omit `outputPath` unless the user named a destination; the default is `~/Downloads`. The editor does not create folders, so a named destination\'s folder must already exist.\\n- Use `operation: \\"jobs\\"` with `parameters.action` `list` to follow progress, warnings, and results. Cancel only when the user asks or the just-queued settings were wrong. Do not infer that an export is stuck from elapsed time alone.\\n- A finished video export is then checked in the background for black picture, gaps, sound that drops out or clips, and missing media. `list` shows each job\'s `findingCount` and its first three findings; `list` with that `jobId` returns every finding. Findings are warnings on a completed export: tell the user what was found and where, rather than treating the export as failed.\\n\\n## Terminal bridge\\n\\nVideoDraft desktop terminals expose `videodraft-editor`, which controls the same process and tools:\\n\\n```bash\\nvideodraft-editor status\\nvideodraft-editor list-tools\\nvideodraft-editor tool project_manage --json \'{\\"operation\\":\\"project\\",\\"parameters\\":{\\"action\\":\\"list\\"}}\'\\nvideodraft-editor tool edit_snapshot --project \\"/path/to/My Video.vdproject\\" --json \'{\\"includeLibrary\\":true}\'\\nvideodraft-editor show\\nvideodraft-editor hide\\n```\\n\\nEach `videodraft-editor` invocation is a separate connection, so a project opened by one call is NOT remembered by the next. Pass `--project <path>` on every `tool` call that operates on a project; without it, a follow-up call answers `no_project` (no project is open for this session) even though the open succeeded. For the same reason, `edit_undo` has nothing to undo from the terminal: it only reverses an edit made on its own connection.\\n\\nControl and tool commands auto-start a headless editor if none is running. `show` only reveals the already-running UI. Use `videodraft-editor tool <name> --json -` to read a JSON object from stdin when shell quoting would be fragile. Never read, copy, or expose the editor\'s rotating local authentication secret.\\n","references/examples.md":"# Recipes\\n\\nWorking patterns for common asks. All assume auth (`videodraft login` once, or `VIDEODRAFT_API_KEY` in the environment) and use `--json` for parsing.\\n\\nInside VideoDraft ADE, if a native editor is available, use these recipes for asset generation and\\noptional script/storyboard stages. Hand the results to the editor for production and export ONLY\\nwhen the deliverable the user asked for is a composed production. A standalone output \u2014 the batch\\nproduct clips in recipe 1, the upscale in recipe 7 \u2014 is finished when it is generated; importing it\\ninto a project and exporting a timeline builds an edit nobody asked for. Recipes below that call `videodraft produce` or `videodraft export` are hosted fallbacks only. Do not choose them over the available native editor unless the user explicitly asks for the hosted web workflow.\\n\\n## 1. Batch product videos from a CSV\\n\\nOne 9:16 product clip per row of `products.csv` (`name,image_url,tagline`):\\n\\n```bash\\n#!/usr/bin/env bash\\nset -euo pipefail\\nmkdir -p outputs\\n\\nwhile IFS=, read -r name image tagline; do\\n  job=$(videodraft generate video \\\\\\n    \\"Premium product shot of ${name}: ${tagline}. Slow orbit, studio lighting.\\" \\\\\\n    --model gemini-omni-1.1-flash --ar 9:16 --duration 6 \\\\\\n    --start-image \\"$image\\" \\\\\\n    --no-wait --json | jq -r .job_id)\\n  echo \\"$name,$job\\" >> outputs/jobs.csv\\ndone < <(tail -n +2 products.csv)\\n\\n# Collect ALL results with ONE process (batched polling \u2014 one request per tick)\\nvideodraft wait $(cut -d, -f2 outputs/jobs.csv) \\\\\\n  --download \\"outputs/{job_id}_{index}.{ext}\\" --json > outputs/results.json\\n# map job ids back to product names via outputs/jobs.csv\\n```\\n\\nSubmit-then-collect parallelizes server-side generation; the single multi-id `wait` keeps it to one local process and one batched poll request per tick no matter how many jobs. Gemini Omni 1.1 Flash is selected because these are six-second first-frame product clips. Estimate first: `videodraft costs gemini-omni-1.1-flash --type video --duration 6 --resolution 720p --audio` \xD7 rows, and confirm with the user.\\n\\nExtend an uploaded clip or conversationally edit an official Google interaction with Gemini Omni 1.1 Flash:\\n\\nEach extension appends 3-10 seconds at the end. Edit and extend accept EXACTLY ONE input video, so `--ref-video` cannot accompany `--source-video` or `--previous-interaction-id`; only `--ref` images can. New dialogue is allowed only when the source video is silent, so a chain of spoken beats must carry its speech in the first turn. A continuation is submitted as the prior turn\'s output, so 40 seconds total is reachable only by extending from a source of 30s or less, and a ladder dead-ends past 30s.\\n\\n```bash\\n# Uploaded-video extension. Reference IMAGES are fine here; reference videos are not.\\nvideodraft generate video --model gemini-omni-1.1-flash \\\\\\n  --source-video ./ending.mp4 --ref ./wardrobe.png \\\\\\n  --extend --duration 6 --resolution 1080p \\\\\\n  --download ./media/extended.mp4\\n\\n# Conversational edit from the interaction_id of an earlier generation. Add --extend to lengthen instead.\\nvideodraft generate video --model gemini-omni-1.1-flash \\\\\\n  --previous-interaction-id \\"$INTERACTION_ID\\" \\\\\\n  --resolution 720p \\\\\\n  --download ./media/continued.mp4\\n```\\n\\nFal BYOK supports the currently callable Gemini Omni 1.1 generation and basic source-edit endpoints at zero VideoDraft credits. Its published callable v1.1 endpoints do not expose continuation, extension, or separate creative references on a source edit. Do not infer a Fal route or retry on paid Google while Fal BYOK is active.\\n\\n## 2. Hosted full marketing video from one idea (fallback)\\n\\n```bash\\nvideodraft create \\"30-second launch video for Solace, a sleep-tracking ring. Calm, premium, dark palette.\\" \\\\\\n  --ar 9:16 --style cinematic --json > project.json\\nPROJECT=$(jq -r .project_id project.json)\\n\\nvideodraft shots \\"$PROJECT\\" --grid --estimate          # show the user the cost; get a go-ahead\\nvideodraft shots \\"$PROJECT\\" --grid\\nvideodraft produce \\"$PROJECT\\"\\nvideodraft generate music \\"minimal ambient, warm pads, 60 BPM\\" --attach \\"$PROJECT\\"\\nvideodraft generate audio \\"Extend @Audio1 into a 20-second transition\\" --ref-audio ./intro.wav --format wav --download ./transition.wav\\nvideodraft export \\"$PROJECT\\" --download solace-launch.mp4\\n```\\n\\nUse this complete hosted path only when the user requested a web project or the native editor is unavailable. Otherwise stop after the storyboard/assets, import them into the native `.vdproject`, and export with `delivery_manage`. The hosted project stays editable at the URL in `project.json` (`.urls`).\\n\\n## 3. Talking-head (avatar) video\\n\\nWhen the user has no portrait, generate a clear front-facing avatar image first. Skip this step when they supplied one or an existing character should be reused.\\n\\n```bash\\nvideodraft generate image \\\\\\n  \\"Front-facing head-and-shoulders portrait of a friendly coffee expert, direct eye contact, natural expression, clean studio background\\" \\\\\\n  --model nano-banana-2 --ar 9:16 --download ./media/avatar.png\\n\\nSCRIPT=$(videodraft avatar script \\"why our espresso subscription saves you money\\" --style ad-style --json | jq -r .script)\\nAVATAR=$(videodraft avatar create ./media/avatar.png --script \\"$SCRIPT\\" --voice elevenlabs-kPzsL2i3teMYv0FxEYQ6 --ar 9:16 --json | jq -r .avatar_video_id)\\nvideodraft avatar render \\"$AVATAR\\" --resolution 720p   # VEED Fabric paid step; confirm cost first (~20 credits/sec)\\n```\\n\\n`avatar script` and `avatar create` (including speech) are bundled/free. In this example only the optional portrait generation and Fabric render spend credits.\\n\\nIf the portrait is low resolution, enhance it before `avatar create`:\\n\\n```bash\\nvideodraft upscale image ./founder-small.jpg --scale 2x --download ./media/founder-upscaled.png\\n```\\n\\nFor a one-off portrait animation without creating a managed avatar record:\\n\\n```bash\\nvideodraft avatar fabric ./founder.jpg \\\\\\n  --text \\"Welcome to the weekly product update.\\" \\\\\\n  --voice-description \\"warm, confident American presenter\\" \\\\\\n  --resolution 720p --download ./media/presenter.mp4\\n```\\n\\nFor a short, sharp clip from speech or a song the user already has (5-14.8s of audio is used):\\n\\n```bash\\nvideodraft avatar h3-lipsync ./singer.png --audio ./chorus.mp3 \\\\\\n  --resolution 1080P --audio-duration 12 --estimate\\nvideodraft avatar h3-lipsync ./singer.png --audio ./chorus.mp3 \\\\\\n  --resolution 1080P --download ./media/singer-lipsync.mp4\\n```\\n\\nWhen the user already has both the video and replacement speech:\\n\\n```bash\\nvideodraft avatar lipsync ./presenter.mp4 \\\\\\n  --audio ./localized-voiceover.mp3 \\\\\\n  --sync-mode loop --download ./media/presenter-localized.mp4\\n```\\n\\nEdit an existing video with a dedicated edit model:\\n\\n```bash\\nvideodraft models video --category video_edit\\nvideodraft edit video ./product-demo.mp4 \\\\\\n  \\"Preserve the product but follow the reference camera rhythm\\" \\\\\\n  --model gemini-omni-1.1-flash --ref-video ./camera-rhythm.mp4 \\\\\\n  --ref-video-duration 2.5 --resolution 1080p \\\\\\n  --download ./media/product-demo-reframed.mp4\\n\\nvideodraft edit video ./product-demo.mp4 \\\\\\n  \\"Turn the room into a warm evening scene while preserving the product and camera motion\\" \\\\\\n  --model kling-o3-video-ref-edit --ref ./evening-style.jpg \\\\\\n  --preserve-audio --download ./media/product-demo-evening.mp4\\n```\\n\\nTransfer motion from a reference clip onto a character image:\\n\\n```bash\\nvideodraft edit motion ./character.png \\\\\\n  \\"Apply the dancer\'s movement to this character while preserving identity\\" \\\\\\n  --motion-video ./dance-reference.mp4 \\\\\\n  --model kling-v3-motion-control --quality pro \\\\\\n  --download ./media/character-dance.mp4\\n```\\n\\n## 4. Hosted changelog video in CI\\n\\nIn a GitHub Action with `VIDEODRAFT_API_KEY` set as a secret:\\n\\n```bash\\nNOTES=$(git log --oneline v1.2.0..HEAD | head -20)\\nvideodraft create \\"Weekly product update video. Energetic, 20 seconds. Changes: ${NOTES}\\" --ar 16:9 --json > p.json\\nPROJECT=$(jq -r .project_id p.json)\\nvideodraft shots \\"$PROJECT\\" && videodraft produce \\"$PROJECT\\"\\nvideodraft export \\"$PROJECT\\" --download changelog.mp4 --wait-timeout 30m\\n```\\n\\n## 5. Variations and picking a winner\\n\\n```bash\\nvideodraft generate image \\"logo concept: minimalist fox, geometric\\" --num 4 --download \\"./concepts/{job_id}_{index}.{ext}\\" --json\\n# Show all 4 to the user; regenerate the chosen one at higher res:\\nvideodraft generate image \\"<same prompt>\\" --model nano-banana-pro --resolution 4K\\n```\\n\\n## 6. Reaching tools without a curated command\\n\\n```bash\\nvideodraft tools list --json | jq -r \'.[].name\'\\nvideodraft tools schema attach_media_to_shot --json\\nvideodraft call attach_media_to_shot --args \'{\\"project_id\\":\\"...\\",\\"scene_index\\":0,\\"shot_index\\":1,\\"media_url\\":\\"https://...\\",\\"media_type\\":\\"video\\",\\"duration_seconds\\":6}\'\\n```\\n\\nAnything the hosted VideoDraft MCP exposes, including character studio, product studio, and hosted project data, is reachable this way even before it gets a curated command. Native `.vdproject` editing uses the separate `videodraft_editor` MCP described in SKILL.md.\\n\\n## 7. Enhance an existing asset without changing it\\n\\n```bash\\n# Light image cleanup, no enlargement\\nvideodraft upscale image ./poster.png --scale 1x --download ./media/poster-enhanced.png\\n\\n# General image and video enlargement\\nvideodraft upscale image ./frame.png --scale 2x --download ./media/frame-2x.png\\nvideodraft upscale video ./clip.mp4 --resolution 1080p --download ./media/clip-1080p.mp4\\n\\n# Rebuild detail in a tiny/blurry source (generative), or reimagine it (creative)\\nvideodraft upscale image ./tiny.jpg --scale 4x --mode generative --model \\"Wonder 3.5\\" --download ./media/tiny-4x.png\\nvideodraft upscale video ./ai-clip.mp4 --resolution 4k --mode generative --download ./media/ai-clip-4k.mp4\\n\\n# Smoother motion or slow motion (resolution unchanged)\\nvideodraft interpolate ./clip.mp4 --fps 60 --download ./media/clip-60fps.mp4\\nvideodraft interpolate ./clip.mp4 --model Chronos --slowdown 4 --download ./media/clip-slowmo.mp4\\n```\\n\\nUse these when the content is correct and only quality or resolution needs improvement. If the poster text, composition, subject, or motion is wrong, edit or regenerate instead.\\n","references/models.md":"# Choosing models (and predicting cost)\\n\\nAlways consult the live catalog instead of memorizing this page \u2014 models change weekly:\\n\\n```bash\\nvideodraft models image --json     # every image model + inputs (aspect ratios, resolutions, max refs)\\nvideodraft models video --json     # every video model + inputs + per-second pricing metadata\\nvideodraft models audio --json     # standalone audio/media models + pricing inputs\\nvideodraft models voices --json    # TTS voices\\nvideodraft models styles --json    # visual style presets\\n```\\n\\n## Task-based model selection\\n\\nFollow this order every time:\\n\\n1. The user named a model: use it, never substitute.\\n2. Otherwise pick a **Tier 1** model from the task\'s inputs, duration, audio, quality, speed, and cost, and pass it explicitly instead of relying on a blind platform fallback.\\n3. Use a **Tier 2** model only when no Tier 1 model supports the request, and say why. Never pick Tier 2 on your own for price, speed, novelty or variety.\\n\\nTier 1 is the rows marked **T1** below. Every other catalog model is Tier 2 and stays available by name. The catalogs carry this themselves: every `videodraft models image|video|audio --json` entry has `tier` (1 or 2) plus `recommended` / `recommended_for`, and the top-level `recommended` array is Tier 1, best first. Trust the catalog over this page when they disagree.\\n\\n### Images\\n\\n| Need                                                                                       | Choose                   | Why                                                               |\\n| ------------------------------------------------------------------------------------------ | ------------------------ | ----------------------------------------------------------------- |\\n| T1: Most generation, editing, character consistency, or reference work                     | `nano-banana-2`          | Best general default; 1K/2K/4K and up to 14 reference images      |\\n| T1: Highest-quality complex generation or reasoning                                        | `nano-banana-pro`        | Premium Nano Banana quality and reasoning                         |\\n| T1: Fast, inexpensive drafts and iteration                                                 | `nano-banana-2-lite`     | Fastest/cheapest Nano Banana option; 1K only, up to 14 references |\\n| T1: Posters, title cards, signs, logos, or any image with important readable text          | `gpt-image-2.5-flare`    | Fast OpenAI option; 16 references, 1K/2K/4K and PNG output        |\\n| T1: Complex multi-image composition, precise editing, or a strong alternate interpretation | `gpt-image-2.5-sunburst` | More fidelity/detail; 16 references, quality through max          |\\n| T1: Vector / SVG output (logos, icons, illustrations that must scale)                      | `recraft-v4`             | Recraft V4.1 text-to-vector; SVG only, no reference images        |\\n| T2: By name, or an explicitly requested xAI look                                           | `grok-imagine`           | 2 cr flat (3 with a reference); 1 reference image                 |\\n| T2: xAI at 2K or with a quality tier, up to 3 edit references                              | `grok-imagine-2.0`       | 1K 4 (low) / 6 (medium), 2K 6 / 8, +1 cr per reference image      |\\n\\nGPT Image 2.5 has two IDs: `gpt-image-2.5-flare` replaces the former GPT Image 2 recommendation; `gpt-image-2.5-sunburst` is the precision/detail alternative. Other model recommendations are unchanged. Explicit `gpt-image-2` selections continue to use the previous model.\\n\\nUse the same basic image controls as GPT Image 2: `--ref`, `--ar`, `--resolution 1K|2K|4K`, `--quality`, and `--num 1..4`. GPT Image 2.5 quality supports auto/low/medium/high/xhigh/max. Auto is priced at Max. Generation runs directly on OpenAI, or exclusively on the user\'s Fal key when active.\\n\\n```bash\\nvideodraft generate image \'A blue glass bird\' --model gpt-image-2.5-flare --ar 1:1 --resolution 2K --quality high --estimate\\nvideodraft generate image \'A blue glass bird\' --model gpt-image-2.5-flare --ar 1:1 --resolution 2K --quality high --num 2\\n```\\n\\n`videodraft shots` forwards resolution and quality for both normal and grid generation. Estimates use the project\'s model and aspect when omitted; grid canvas costs may differ from ordinary shot costs. Use `videodraft costs --model <id> --ar <ratio> --resolution <tier> --quality <tier>` for a specific per-image quote.\\n\\n### Videos\\n\\n| Need                                                                                                           | Choose                   | Important limits                                                                                                                                                                                                                                               |\\n| -------------------------------------------------------------------------------------------------------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\\n| T1: Most generation, first/last-frame, mixed-reference, source-edit, or extension requests                     | `gemini-omni-1.1-flash`  | 3-10s output; 360p/720p/1080p/4K at 3/10/15/30 cr/s; audio always; up to 10 image inputs, and 3 reference videos <=3s on generate only; edit source <=10s; continuation or 3-10s extension of a 1-30s source, 40s total reachable only by extending from <=30s |\\n| T2: Grok 1.5 text, first-frame, or 1-7 image-reference clips with native audio and optional 1080p              | `grok-imagine-video-1.5` | 1-15s; 480p/720p/1080p for text/first-frame; references are 480p/720p only; no last frame                                                                                                                                                                      |\\n| T2: Document or webpage reference generation; by name otherwise                                                | `wan-3.0`                | 2-30s or auto; 480p/720p/1080p at 7/14/28 cr/s; 10 image, 5 video, 5 audio refs, 20 media files total; document/web refs require thinking                                                                                                                      |\\n| T2: 480p/768p/2K/4K with native stereo audio, first/last frames, or mixed image/video/audio references         | `minimax-h3`             | 5-15s; 5/6/13/16 cr/s by resolution; up to 9 image, 3 video, 3 audio refs, 12 files total; first 5 reference images free then 8 cr each; reference video/audio each total <=15s                                                                                |\\n| T1: Text, first/last-frame, or mixed-reference video with native audio and stronger prompt adherence           | `minimax-h3-max`         | 5-15s; 5/8 cr/s at 480p/768p plus pooled reference tokens; up to 9 image, 3 video, 3 audio refs, 12 files total; seed and disabled/balanced/quality prompt expansion; provider safety checker off by default                                                   |\\n| T2: Images pinned to specific moments (keyframes); by name otherwise                                           | `flux-3`                 | 5-20s (auto for text/first-frame only); 720p/1080p; up to 10 keyframes; `--quality draft` is 720p-only at ~1/3 the cost                                                                                                                                        |\\n| T1: Video/audio references, mixed reference media, broad aspect ratios, frame-mode first+last frame, or 11-15s | `seedance-2`             | 4-15s or auto; up to 9 image, 3 video, and 3 audio refs; audio toggle; Mini/Fast are 480p/720p only                                                                                                                                                            |\\n| T1: Single takes past 15s, or more references than Seedance 2.0 allows                                         | `seedance-2.5`           | 4-30s or auto; up to 30 image, 10 video, and 10 audio refs (50 files total); one quality tier; 480p/720p/1080p                                                                                                                                                 |\\n| T2: Fast polished 3-15s video with first frame, multi-prompt, and native audio                                 | `kling-v3-turbo`         | Audio always on; Pro default; no end frame, reference-media mode, or elements                                                                                                                                                                                  |\\n| T1: Cinematic 3-15s with reference images, image/video elements, first+last frame, audio, or 4K                | `kling-o3`               | 7 combined image refs/elements, reduced to 4 with a video element; Standard/Pro/4K                                                                                                                                                                             |\\n| T1: Kling 3-15s image-to-video with first+last frame, image/video elements, multi-prompt, audio, or 4K         | `kling-3.0`              | Elements require a start image; image or video elements can bind voice_id; Standard/Pro/4K                                                                                                                                                                     |\\n| T2: User explicitly requests Veo, or the selected workflow specifically needs Veo                              | `google-veo3.1`          | Good fallback, but not the preferred general model                                                                                                                                                                                                             |\\n\\nRouting rules:\\n\\n- Inexpensive pass or draft at 480p/768p with native audio: use MiniMax H3 Max (5/8 cr/s plus reference tokens).\\n- Grok 1.5 reference mode accepts 1-7 images only. Address them in array order as `<IMAGE_0>` through `<IMAGE_6>`. Do not combine reference images with `--start-image`, `--end-image`, `--ref-video`, or `--ref-audio`.\\n- Grok 1.5 first-frame mode accepts one `--start-image`, derives the output aspect ratio from that image, and does not support `--end-image`. Text and first-frame modes support 480p, 720p, or 1080p. Reference mode supports 480p or 720p.\\n- Grok 1.5 always generates native audio. Do not pass `--no-audio`, `--seed`, `--negative`, or `--quality`.\\n- Around 11-15 seconds with native audio: use Seedance, Kling 3.0 / O3, or MiniMax H3 Max, not Gemini. Past 15 seconds: Seedance 2.5.\\n- Dialogue: write the line in the prompt, in quotes, with who says it and how. `gemini-omni-1.1-flash`, `seedance-2.5`, `seedance-2`, `kling-3.0` and `kling-o3` speak it natively; add `--ref-audio` on Seedance or a bound Kling voice for a specific voice. Do not generate speech separately and lip-sync it on.\\n- One existing source video that should be edited: use `videodraft edit video`, which auto-selects Gemini Omni 1.1 Flash for a source up to 10s. Generic `generate video --ref-video` retains source-edit behavior when `--video-task` is omitted, but the dedicated edit command is clearer.\\n- Video supplied as a creative reference: Gemini Omni 1.1 Flash accepts up to 3 videos of at most 3 seconds each, including mixed image and video input. Creative video references are accepted on `--video-task generate` ONLY: edit and extend take exactly one input video, so `--ref-video` cannot accompany `--source-video` or `--previous-interaction-id`. Use Seedance 2.5 for more or longer video/audio references, or Seedance 2.0 when quality-tier control matters.\\n- First and last frame control: every Tier 1 video model supports it (Gemini Omni 1.1 Flash, Seedance, Kling O3, Kling 3.0, MiniMax H3 Max). For Gemini, every start/end frame counts toward the 10-image total, leaving up to 9 references with a start frame or 8 with both frames.\\n- Extension with a 1-30s uploaded source uses Gemini Omni 1.1 Flash plus `--source-video` and `--video-task extend` (or `--extend`). Pass an explicit 3-10s output duration; the model appends it at the end, up to 40 seconds total. Creative `--ref-video` clips CANNOT accompany the source: edit and extend take exactly one input video. New dialogue is allowed only when the source video is silent; adding speech on top of a source that already has speech is refused with \\"the model is currently unable to process speech edits\\". Continuation uses `--previous-interaction-id <id>` and defaults to a conversational edit; `--video-task extend` lengthens it. A continuation is submitted as the prior turn\'s output video, so it obeys the same source limits (<=30s to extend, <=10s to edit) and the same silent-source dialogue rule. 40s total is reachable only by extending from a source of 30s or less, so a ladder dead-ends past 30s. Fal returns interaction IDs, but its currently published callable v1.1 endpoints do not expose continuation/extension or mixed source-edit references; never infer a route or silently fall back to paid Google.\\n- Wan 3.0 reference mode and frame mode are separate. It accepts 10 images, 5 videos, and 5 audio clips, at most 20 media files total. Video and audio each total at most 15 seconds. `--file-url` and `--web-url` require `--thinking`. `--auto-duration` cannot be combined with `--duration`.\\n- MiniMax H3 and H3 Max reference mode and first-plus-last-frame mode are separate. Audio cannot be the only reference. Address references as `Image 1`, `Video 1`, and `Audio 1` in array order.\\n- Seedance reference mode and first-plus-last-frame mode are separate. Do not promise reference video/audio plus a last frame in one generation.\\n- Multi-prompt sequencing: use Kling 3.0 Turbo, Kling O3, or Kling 3.0.\\n- Kling 3.0 image-to-video and Kling O3 reference-to-video accept repeatable structured `--element` JSON. Each element is image-backed (`frontal_image_url` plus 1-3 `reference_image_urls`) or video-backed (`video_url`). Either form may include `voice_id`. Keep the voice ID inside the same element so the association is preserved. Reference them as `@Element1`, `@Element2`. Kling V3 Turbo rejects elements.\\n- Kling 2.6 Pro image-to-video accepts one or two repeatable `--voice-id` values. Cite them as `<<<voice_1>>>` and `<<<voice_2>>>` in the prompt. Voice control costs 17 cr/s. Use `videodraft kling-voices list|create|delete` to manage the separate Kling video-control voice library. Creating a voice requires a clean 5-30 second, up-to-50MB single-speaker `.mp3`, `.wav`, `.mp4`, or `.mov` sample plus `--confirm-consent`. Creation costs 1 VideoDraft credit on the platform Fal account and 0 credits with Fal BYOK; use the create command\'s `--estimate` flag to check without creating.\\n- Kling V3 voice control costs 16 cr/s for Standard and 20 cr/s for Pro.\\n- Seedance quality: `mini` for the lowest cost, `fast` for speed, `standard` for maximum quality and for 1080p/4K. Seedance 2.5 has a single tier and ignores `--quality`.\\n- Longer than 15 seconds, or more than 9 image / 3 video / 3 audio references: use Seedance 2.5. It reaches 30s and 30/10/10 references (50 files total) at 480p/720p/1080p, but has no 4K.\\n- Seedance 2.x allows real people by default, the same as AI Studio: Byteplus first, a submit-time Fal fallback, and Fal\'s higher tier-specific rate. Turn it off with MCP `allow_real_people: false` or CLI `--no-allow-real-people` for the lower Byteplus-only rate, only when the user wants the cheapest run and nothing in the job is a real identifiable person (text-only requests, non-people, anime, clearly synthetic or stylized characters).\\n- If a Seedance request made with the option off fails with `SEEDANCE_REAL_PERSON_OPT_IN_REQUIRED`, estimate the higher rate, follow the user\'s spend policy, and retry once with the option on. The response also carries `retry_with: { allow_real_people: true }`, `cli_flag: \\"--allow-real-people\\"`, and `retry_policy: \\"once\\"`. If the option was already on, do not repeat the same request. Byteplus may accept a task and reject the output later. VideoDraft refunds that failed generation, but it cannot reroute the asynchronous failure to Fal. Rephrase or change the references instead.\\n\\n### Video edit and motion-control categories\\n\\nUse `videodraft models video --category video_edit` for existing-video transforms and `--category motion_control` for motion transfer.\\n\\n| Need                                       | Command/model                                                                | Important limits                                                                                                                                          |\\n| ------------------------------------------ | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |\\n| Most edits of a source up to 10s (DEFAULT) | `videodraft edit video <video> \\"...\\"` (auto-selects `gemini-omni-1.1-flash`) | Source <=10s or it REFUSES; up to 10 image refs and 3 creative video refs <=3s each; 360p/720p/1080p/4K; audio always regenerated (no `--preserve-audio`) |\\n| Cheapest simple prompt edit                | `videodraft edit video <video> \\"...\\" --model grok-imagine-video-edit`        | No image refs; source silently truncated to 8s; auto/480p/720p                                                                                            |\\n| Edit with several image references         | `--model happy-horse-video-edit --ref ...`                                   | Up to 5 refs; 720p/1080p; source silently truncated to 15s; highest rate (28-56 cr/s)                                                                     |\\n| Controlled Kling edit                      | `--model kling-o3-video-ref-edit --ref ...`                                  | Up to 4 refs; Standard/Pro; source silently clamped to 3-10s                                                                                              |\\n| Transfer reference motion to an image      | `videodraft edit motion <image> [direction] --motion-video <video>`          | Prompt/direction is optional; Kling V3 default; optional one image-only `--element`; element requires video orientation                                   |\\n\\nIf the user explicitly names one of these models, preserve it. The CLI uploads local source videos and reference images automatically. Editing returns an async job and waits by default.\\n\\n**Omit `--model` and the SERVER chooses**, because only it can measure the source. It picks `gemini-omni-1.1-flash` for any source up to 10s. When that is not safe (source longer than 10s, unmeasurable duration, `--preserve-audio`, more than 10 refs, or Fal BYOK with refs) it spends nothing and returns a priced menu: per model, the seconds it would edit, the seconds it would drop, and the credit cost. The CLI prints that table and exits 2. Show it to the user, then re-run with `--model`.\\n\\n**Truncation is the trap here.** Only Gemini refuses a source it cannot fully consume. Every other edit model accepts a 30s clip and returns an edit of its first 8-15 seconds with no error. `videodraft edit video` now warns when this will happen and the tool response carries `source.truncated` / `source.dropped_seconds`; relay it to the user rather than letting them discover it in the output.\\n\\nTo edit a longer source without losing its tail, cut it into <=10s pieces with `videodraft_editor`, edit each with Gemini, then reassemble and export there. VideoDraft has no server-side split/concat, so this needs the native editor.\\n\\nKling O3 is also exposed for reference generation. `videodraft generate video --model kling-o3-video-ref-edit` requires exactly one `--ref-video` and generates a new reference-guided clip. Wan 3.0 handles new text, frame, and mixed-reference generation, but is not an existing-source edit model.\\n\\n### Reference-first video workflow\\n\\n- Prefer a start frame or reference image whenever a specific character, product, location, style, composition, or brand identity must stay recognizable.\\n- If the user gives a reference, pass it. Never silently replace it with a text description.\\n- If no reference exists and continuity matters, generate a still first with the user\'s explicitly requested compatible image model, otherwise use Nano Banana 2. Wait for the image URL, then animate it with the selected video model. Confirm the combined image plus video cost before starting.\\n- For multi-shot scenes, generate shot images with `videodraft shots <project_id> --model <selected-image-model> --grid`. Preserve an explicitly requested compatible image model; otherwise use `nano-banana-2`. The grid establishes the scene and characters together, then decodes into individual shot images.\\n- Animate the decoded shot images as per-shot start frames or references. Do not independently text-generate each video clip when the shots need to match.\\n- Pure text-to-video remains appropriate for generic one-off footage where no subject, composition, or continuity needs to be preserved.\\n\\n### Audio\\n\\n- **Seed Audio 1.0**: use `videodraft generate audio` for open-ended speech, sound, music, or prompt-driven audio editing. It accepts up to three audio references or one image. Address audio references as `@Audio1`, `@Audio2`, and `@Audio3`. Preset and custom cloned voice IDs are supported. Output is up to 120 seconds. There is no requested-duration input. The CLI automatically retries transient responses with one idempotency key. To recover after the CLI process itself is interrupted, set `--idempotency-key <uuid>` on the original command and reuse it.\\n- **Voiceover/TTS**: prefer ElevenLabs. Brittney is the platform default voice; under ElevenLabs BYOK, use a compatible voice from the user\'s account. Honor another supported voice/provider when the user explicitly selects it.\\n- **Dialogue, voice changing, and dubbing**: ElevenLabs only.\\n- **Sound effects**: ElevenLabs Sound Effects only.\\n- **Music**: use `lyria-3.5` for all music, short or long (up to ~3 minutes), with vocals/lyrics or instrumental music. When `--model` is omitted the CLI sends no model and the server default applies, which is `lyria-3.5` wherever the backend supports it. If the server answers that `lyria-3.5` is an unknown model, that backend predates it: rerun without `--model` (the server default then applies), or use `lyria-3-pro-preview` for a track longer than 30 seconds. `lyria-3-clip-preview` (fixed ~30s) and `lyria-3-pro-preview` remain available for explicit requests. Lyria length and structure are prompt-guided, not exact; for an instrumental, include \\"instrumental only, no vocals\\" in the prompt. `--length` and `--instrumental` only apply to ElevenLabs. Use `elevenlabs-music-v2.5` when a specified 3-300 second length, composition plan, or style reference track matters. Lyria references: up to 10 images on Google, 1 on Fal BYOK; 3.5 Fal prompts are 1-5000 characters (an image-only request gets a neutral prompt). `elevenlabs-music` is an alias for v2.5. Use `elevenlabs-music-v1` only when the user asks for v1 by name; it takes a prompt, `--length` and `--instrumental` only.\\n- **ElevenLabs Music v2.5 inputs**: either a prompt (`--length`, `--instrumental`) or a composition plan, never both. A plan is 1-30 sections of 3-120 seconds each, up to 300 seconds in total, and `--plan`/`--section` pick v2.5 when `--model` is omitted. Empty section parts default to 20 seconds and an instrumental part. Build one with repeatable `--section \\"<seconds>|<style, style>|<text>\\"` (use `\\\\n` for line breaks) or pass `--plan plan.json` with `{\\"chunks\\":[{\\"text\\",\\"duration_ms\\",\\"positive_styles\\",\\"negative_styles\\",\\"context_adherence\\",\\"audio_reference\\"}]}`. Section text is an optional `[Section name]`, lyric lines, and `{inline directions}`. Put 6-7 specific English styles on the first section; it sets the genre. `--ref-audio <url|file>` adds a style reference clip to the first section (window up to 30 seconds via `--ref-start`/`--ref-end` in ms, `--ref-strength low|medium|high|xhigh`); local files are uploaded, including relative `audio_reference.audio_url` paths in a plan file. `--seed` works only with a plan. `--format` picks the output (`mp3_48000_192` default on v2.5; `pcm_*`, `ulaw_8000` and `alaw_8000` arrive as stereo WAV files). Style references don\'t run on the user\'s own ElevenLabs key; with that key connected, drop the reference or ask the user to turn the key off. The CLI retries transient responses with one idempotency key; set `--idempotency-key <uuid>` to recover after an interruption.\\n- Voice Changer and Dubbing require the source media duration and currently accept source media up to 300 seconds.\\n\\n**User-supplied ElevenLabs voice IDs:** voiceover, dialogue, and voice changing accept raw IDs (16-64 alphanumeric characters) or `elevenlabs-<id>`. `videodraft models voices` / MCP `list_available_voices` is for discovery, not an allowlist. Pass a supplied ID directly even when it is absent from the catalog; do not reject it or substitute a catalog voice. The voice must be accessible to the provider account used for generation. Private or cloned voices may require the user\'s connected ElevenLabs key. A failed voice listing does not prove that a supplied ID cannot generate; a connected key with generation access may still work. If the provider rejects generation access, report that error rather than silently changing the voice.\\n\\nUse `--voice <id>` for voiceover and voice changing, and repeat `--line \\"<id>:Text\\"` for dialogue. These examples show both ID forms; replace the sample IDs with the user\'s supplied IDs:\\n\\n```bash\\nvideodraft generate voiceover \\"Hello there.\\" --voice kPzsL2i3teMYv0FxEYQ6 --download ./media/voiceover.mp3\\nvideodraft generate dialogue --line \\"kPzsL2i3teMYv0FxEYQ6:Hello.\\" --line \\"elevenlabs-kmSVBPu7loj4ayNinwWM:Welcome back.\\" --download ./media/dialogue.mp3\\nvideodraft generate voice-changer ./media/source.wav --voice elevenlabs-kPzsL2i3teMYv0FxEYQ6 --duration 12 --download ./media/changed-voice.mp3\\n```\\n\\nFor MCP, use `generate_voiceover.voice_id`, `generate_dialogue.lines[].voice_id`, or `change_voice.voice_id` with either form. ElevenLabs IDs are separate from Kling video-control voice IDs and MiniMax `custom-*` cloned-voice IDs. Do not convert IDs from those systems into ElevenLabs IDs.\\n\\n### Avatar / talking head\\n\\n**First decide the framing, not just \\"someone talks\\".** This lane animates a PORTRAIT facing the lens. A character delivering a line inside a real scene, with blocking, framing or camera movement, belongs to `generate video` instead: write the dialogue in the prompt and `gemini-omni-1.1-flash`, `seedance-2.5`, `seedance-2`, `kling-3.0` or `kling-o3` voices it natively (add a Seedance `--ref-audio` clip or a Kling voice bound per element for a specific voice). That is the default for any talking character; never plan silent video + TTS + lip-sync. Sending a cinematic shot to Fabric returns a head-on talking headshot, not the shot that was asked for. `videodraft models video --json` lists these under `recommended.in_scene_dialogue`.\\n\\nFor a presenter, spokesperson or explainer speaking to camera, VEED Fabric is the preferred model. Choose the dedicated path from the media the user already has:\\n\\n| Starting media                             | Command                                                                   | Use                                                        |\\n| ------------------------------------------ | ------------------------------------------------------------------------- | ---------------------------------------------------------- |\\n| Portrait + script, reusable avatar record  | `videodraft avatar create <portrait> --script \\"...\\"` then `avatar render` | Managed avatar flow with bundled speech preparation        |\\n| Portrait + text                            | `videodraft avatar fabric <portrait> --text \\"...\\"`                        | One-off direct VEED Fabric text mode                       |\\n| Portrait + existing audio                  | `videodraft avatar fabric <portrait> --audio <audio>`                     | One-off direct VEED Fabric audio lip sync                  |\\n| Portrait + existing audio, short and sharp | `videodraft avatar h3-lipsync <portrait> --audio <audio>`                 | MiniMax H3 Max Lip Sync, 5-14.8s at up to 2K               |\\n| Existing video + existing audio            | `videodraft avatar lipsync <video> --audio <audio>`                       | Sync Labs Lipsync 2 (Tier 2): re-dub existing footage only |\\n\\nThe managed renderer is VEED Fabric Fast (`veed/fabric-1.0/fast`). Direct Fabric, MiniMax H3 Max Lip Sync, and Sync Labs are paid AI Studio generations and return async job IDs.\\n\\n1. Obtain the avatar image. Prefer the user\'s supplied portrait or an existing character. If none exists, use the user\'s explicitly requested compatible image model, otherwise generate a front-facing head-and-shoulders portrait with `nano-banana-2`, direct eye contact, a natural expression, and a clean background. Match the intended video aspect ratio when practical.\\n2. If the portrait is visibly soft or too small, run Topaz image enhancement/upscaling before animation.\\n3. Generate a script only if needed: `videodraft avatar script \\"<idea>\\"`.\\n4. Create the avatar record and speech: `videodraft avatar create <portrait-url-or-file> --script \\"...\\" --voice <id> --ar 9:16`. Prefer ElevenLabs when unspecified, but honor another explicitly selected supported voice/provider.\\n5. Render with VEED Fabric: `videodraft avatar render <avatar_video_id> --resolution 720p`.\\n\\nThe portrait is passed as the avatar\'s character image, not as a generic video\'s start frame. Prefer rendering directly at 720p. Use 480p only when the user prioritizes lower cost. Avatar script generation and `avatar create` (including speech) are bundled/free. Confirm the Fabric render cost, plus portrait generation or upscaling when needed.\\n\\nDirect Fabric text/audio, H3 Max Lip Sync, and Sync Labs do not use the managed avatar record. The CLI uploads local portrait, video, and audio files automatically. `avatar fabric --speed fast` applies only to audio mode. `avatar h3-lipsync` takes no prompt: pick `--resolution 480P|768P|1080P|2K` (default 768P), an optional `--seed`, `--no-transcription` to sync without transcribing the audio (transcription is on by default), and `--safety-checker` only when the user asks for Fal\'s checker. The portrait\'s width / height must be 0.4-2.5, and audio shorter than 5 seconds is refused before any charge. Sync costs 5 credits per verified audio second; under Fal BYOK, `sync_mode` remains available but `temperature` and `active_speaker` are ignored by the provider.\\n\\n### Upscaling / enhancement\\n\\n- **Images**: Topaz via `videodraft upscale image <url-or-file> --scale 1x|2x|4x [--mode precision|generative|creative] [--model <name>]`. Modes: `generative` (default; Wonder 3.5, Topaz\'s recommended model for AI-generated images; `Redefine` takes `--prompt`, `--creativity 1-6`, `--texture 1-5`), `precision` (faithful and cheapest; Standard V2, High Fidelity V3, Low Resolution V2, CGI, Text Refine; use for clean real photos), `creative` (Bloom 2; artistic, `--prompt`, `--creativity 1-9`). Extra knobs: `--no-face-enhance`, `--face-strength`, `--sharpen`, `--denoise`, `--fix-compression`, `--format png`. Use 1x for light enhancement without enlargement, 2x as the general default, and 4x only when the source quality and target size justify it. The server must verify dimensions from a readable image of at most 50 MB; `--width` and `--height` are compatibility hints and cannot bypass a failed probe. The result is synchronous. Cost: 8 credits per started 24 MP of output in precision, per 8 MP (Wonder 3/3.5) or 4 MP in generative, per 2 MP in creative.\\n- **Videos**: Topaz via `videodraft upscale video <url-or-file> --resolution 720p|1080p|4k` (preferred) or `--scale 2x`, plus `--mode precision|generative|creative` and `--model <name>`. `generative` (default; Starlight Precise 2.6, Topaz\'s recommended model for AI-generated footage; Starlight Fast 2 at half price) costs 12 credits/s up to 1080p and 26 at 4K. `precision` (Proteus, Proteus Natural, Iris, Gaia 2 for animation, Rhea, Theia, Artemis, Dione) is 6x cheaper at 1 / 2 / 6 credits per second for 720p / 1080p / 4K output; use it for real footage or when cost matters. `creative` (Astra 2, `--prompt`, `--creativity`, `--realism`, `--sharp`) always renders 4K at 50 credits/s. `--fps 60` delivers 60fps on the same pass; any output above 30fps (including a 50/60fps source) doubles every rate; the server must verify duration, dimensions, and frame rate from an MP4/MOV source of at most 100 MB. `--duration`, `--width`, `--height`, and `--source-fps` are compatibility hints and cannot override billing or bypass a failed probe. The same source-verification requirement applies to frame interpolation. `--scale` also accepts intermediate factors such as `1.5x`. Max source length 5 minutes. The job is asynchronous; the CLI waits by default, while MCP callers poll `check_generation_status`. MCP video input must be VideoDraft-hosted, so upload local or external sources first.\\n- **Frame interpolation / slow motion**: `videodraft interpolate <url-or-file> --fps 60 [--model Apollo|Chronos|Aion] [--slowdown 1-8]` (MCP `interpolate_video`). Resolution is unchanged. Apollo (default) for smooth general conversion, Chronos for natural slow motion, Aion for extreme slow motion. Apollo/Chronos cost 3 credits per output second up to 1080p (6 at 4K); Aion 5 / 17. These rates cover targets up to 60fps; above 60fps multiply by target FPS / 60 (120fps doubles the rate). Output seconds = source seconds \xD7 slowdown. The final charge rounds up to a whole credit.\\n- Use upscaling to preserve the image/video while improving detail, resolution, or cleanup. It cannot fix the wrong subject, misspelled text, bad framing, unwanted objects, broken continuity, or incorrect motion. Use an edit or regeneration for those problems. Keep `generative` for AI-generated sources; switch to `precision` for clean real photos/footage or a cheap pass, and `creative` only when the user wants an artistic reinterpretation.\\n- For a new Fabric avatar, render directly at 720p instead of rendering at 480p and then upscaling. Upscale the source portrait first only when the portrait itself is low quality.\\n\\n## Capability gotchas\\n\\n- Each model\'s `inputs` block is authoritative: supported `aspect_ratios`, `resolutions`, `quality_options`, `start_frame`/`end_frame`, `max_reference_images/videos/audio`, `multi_prompt`, `audio_toggle`. Passing an unsupported input fails with a clear error \u2014 check first, don\'t trial-and-error paid calls.\\n- Most video models support only 16:9 / 9:16 / 1:1. A 3:4 request hard-fails on most.\\n- `--seed` reproduces a specific output on models that support it (e.g. Flux, Ideogram V4). GPT Image 2.5 rejects any explicit seed; older models may ignore unsupported seeds. You do not need a seed for variation \u2014 `--num` already varies.\\n- `--rendering-speed` applies to Ideogram (V3: `Default`/`Turbo`/`Quality`; V4: `Turbo`/`Balanced`/`Quality`) and affects image cost \u2014 pass it to `videodraft costs ... --rendering-speed <tier>` for an accurate estimate. Always trust `videodraft models image --json` over this list; new models and tiers appear there the moment the platform ships them, with no CLI update.\\n- `seedream-v5-pro` supports unified text-to-image and reference-image editing with up to 10 image references. Use `--resolution 1K` for 7 credits/image or `--resolution 2K` for 14 credits/image.\\n- Reference inputs: `--ref <img>` (images, including up to 10 total for Gemini Omni 1.1 Flash and Wan 3.0, and 7 for Grok 1.5), `--source-video <v>` (Gemini uploaded edit/extension source), `--ref-video <v>` (up to 3 creative videos <=3s each for Gemini Omni 1.1 Flash; also Wan 3.0, MiniMax H3, MiniMax H3 Max, and Seedance 2), `--ref-audio <a>` (Wan 3.0, MiniMax H3, MiniMax H3 Max, Seedance 2), and `--element \'<json>\'` or `--element @elements.json` for Kling V3/O3. For an exact Seedance 2.x reference-video `--estimate`, add `--ref-video-seconds <combined-seconds>`; Seedance bills input seconds alongside output. Wan 3.0 and MiniMax H3 do not bill input reference seconds; MiniMax H3 Max bills them as pooled reference tokens. The CLI uploads local media references and every structured element without flattening the source/reference roles. `--segment \\"<prompt>:<seconds>\\"` (repeatable) drives Kling 3.0, Kling 3.0 Turbo, and O3 multi-prompt generation. Use 1-6 segments of 1-15 whole seconds each, with 3-15 seconds total. `generate image --video-ref` is the nano-banana-2 video reference.\\n- The top-level prompt is OPTIONAL for Gemini Omni 1.1 Flash media-input or continuation calls, Wan 3.0 frame/reference modes, `generate video` with multi-prompt models, and Kling 3.0 Turbo (`--model kling-v3-turbo`) image-to-video. Text-only Gemini and Wan calls still require a prompt unless their live schema says otherwise.\\n- Hosted AI Production fallback: `videodraft produce <project> --mode full_video` generates one Seedance 2 video per scene, with real people allowed by default at the higher Fal-tier rate on every submitted scene segment; add `--no-allow-real-people` for the lower Byteplus-only rate when no scene shows a real identifiable person. The MCP equivalent is `produce_project` with `mode: \\"full_video\\"` (and `allow_real_people: false` to opt out). If a partial opted-out run returns `SEEDANCE_REAL_PERSON_OPT_IN_REQUIRED`, rerun the same project once with an explicit `--allow-real-people` after cost confirmation. The server reconciles asynchronous results first, preserves running/completed jobs, and retries only failed placeholders carrying that exact code. Poll with `videodraft generations`, then `videodraft finalize <project>` swaps them into the hosted timeline before `export`. In VideoDraft ADE, do not choose this path while `videodraft_editor` is available unless the user explicitly requests hosted production. Generate or download the scene assets, import them, and assemble/export with the native editor instead. If the user explicitly requests another compatible video model for a hosted production, do not use this fixed Seedance path; generate the project shots manually with the requested model and attach them to the hosted timeline.\\n\\n## Cost model\\n\\n- Images: per image (\xD7 `--num`). Matrix-priced models (GPT-Image, Nano Banana Pro, Seedream v5 Pro) vary by resolution/quality.\\n- Video: usually credits/second \xD7 duration; rate depends on model + resolution + quality + native audio on/off.\\n- Gemini Omni 1.1 Flash: 3 / 10 / 15 / 30 credits per output second at 360p / 720p / 1080p / 4K (720p default). Extend appends an explicit 3-10 seconds to a 1-30s source, whether uploaded or resolved from a prior interaction; 40 seconds total is reachable only while the source stays at or under 30s. Fal BYOK generation and basic source edits cost zero VideoDraft credits; continuation, extension, and separate creative references on a source edit are unavailable under Fal BYOK.\\n- MiniMax H3: 5 / 6 / 13 / 16 credits per output second at 480p / 768p / 2K / 4K (768p default). The first 5 reference images are included, then 8 credits for each additional image. Reference video and reference audio are NOT billed.\\n- MiniMax H3 Max: 5 credits per output second at 480p or 8 credits per second at 768p (default), plus pooled reference tokens. The first 4,096 reference tokens are free and each additional 1,000 costs 2 credits. An image is `(width x height) / 1024` tokens (a 1024x1024 reference is 1,024, so four of them are free); a reference video is 2,886 tokens per second at 480p or 7,459 at 768p; reference audio is about 2,121 per second. Pass `--ref-audio-seconds` for an exact estimate with audio references. The server measures each reference image, so a quote that assumes 1024x1024 is a floor.\\n- Wan 3.0: 7 / 14 / 28 credits per output second at 480p / 720p / 1080p. Auto duration reserves 30 seconds and reconciles unused credits from the provider-reported output duration. Fal BYOK charges zero VideoDraft credits.\\n- Grok Imagine Video 1.5: 8 credits/output second at 480p, 14 at 720p, or 25 at 1080p, plus 1 credit for each first-frame or reference image. Native generated audio is part of every output.\\n- Kling voice control: 17 credits/output second for Kling 2.6 Pro, 16 at Kling V3 Standard, and 20 at Kling V3 Pro.\\n- Shot-image batches: one image per shot (+1 grid image per scene in `--grid` mode) \u2014 the largest single spend in the pipeline.\\n- VEED Fabric avatar renders: ~10 credits/sec at 480p, ~20/sec at 720p. Avatar creation and its speech are bundled/free; only optional portrait generation/upscaling adds cost before the render.\\n- Direct VEED Fabric: text or normal audio is 8 credits/sec at 480p and 15/sec at 720p; fast audio is 10/sec at 480p and 20/sec at 720p.\\n- MiniMax H3 Max Lip Sync: 5 / 8 / 16 / 32 credits per output second at 480P / 768P (default) / 1080P / 2K. The video runs as long as the audio (at least 5s; only the first 14.8s is used), billed on the server-measured length rounded up, so at most 15 seconds. Use MP3, WAV, M4A (AAC), or AAC audio; other formats run only on the user\'s own Fal key.\\n- Sync Labs Lipsync 2: 5 credits per verified audio second.\\n- Voiceover TTS: 10 credits per 1000 characters for standard voices, 30 per 1000 for cloned `custom-*` voices (min 1, pro-rated); applies to standalone voiceovers AND per-scene narration during `produce`. Silent tracks are free. Voice cloning itself is a flat 150 credits per clone.\\n- Lyria music: flat per track, 4 credits (Clip) / 10 credits (3.5) / 8 credits (legacy Pro). Fal BYOK uses zero VideoDraft credits.\\n- Seed Audio 1.0: 19 credits per actual output minute, prorated and rounded up to a whole credit. VideoDraft reserves the 120-second maximum of 38 credits and refunds the unused portion after generation. Fal BYOK is free.\\n- ElevenLabs audio: sound effects are per second, dialogue is per character, music/voice-changer/dubbing are per started minute. ElevenLabs Music v2.5 and v1 both cost 60 credits per started output minute; estimate a composition plan with its total length. Voice changer and dubbing reject source media above 300s in the current synchronous flow.\\n- Seedance 2.0 / 2.5 real people: allowed by default, which keeps Byteplus first, permits a submit-time Fal fallback, and prices at Fal\'s rate for that tier: 2.0 Mini 8/16 cr/s, Fast 11/25, Standard 14/31/69/156, 2.5 23/48/114 for 480p/720p/1080p. `--no-allow-real-people` uses the Byteplus-priced path instead (2.0 Mini 4/8, Fast 6/13, Standard 7/16/38/78, 2.5 11/24/57); Byteplus refuses real-person likenesses, so a likeness-policy failure then does not fall back. The gap is roughly 2x but not exactly: the Seedance 2.0 1080p pair is 38/69, or about 1.82x. If Byteplus accepts the task and later rejects the generated output, VideoDraft refunds the failure but does not resubmit it to Fal. Turn the option off only for the cheapest run when nothing in the job is a real identifiable person.\\n- Grok Imagine images: `grok-imagine` is a flat 2 cr (3 with a reference). `grok-imagine-2.0` is a separate, newer model priced by resolution and quality: 1K 4 (low) / 6 (medium), 2K 6 / 8, plus 1 cr per reference image (up to 3). v1 is NOT superseded \u2014 pick it when cost matters more than 2K.\\n- xAI bills refused requests, so failed Grok generations are not refunded.\\n- Upscales: priced by output size, mode, and (video) duration/fps; see the Upscaling section above.\\n\\nQuote before spending:\\n\\n```bash\\nvideodraft costs gemini-omni-1.1-flash --type video --duration 8 --resolution 720p --audio\\nvideodraft costs topaz-upscale-video --type video --duration 10 --width 1920 --height 1080 --resolution 4k --mode generative\\nvideodraft costs topaz-upscale --type image --width 2048 --height 2048 --scale 2x\\nvideodraft costs topaz-interpolate-video --type video --duration 10 --width 1920 --height 1080 --fps 60 --topaz-model Apollo\\nvideodraft costs minimax-h3 --type video --duration 10 --resolution 2K --ref-images 7\\nvideodraft costs minimax-h3-max --type video --duration 10 --resolution 768p --ref-images 2\\nvideodraft costs grok-imagine-video-1.5 --type video --duration 8 --resolution 720p --ref-images 4\\nvideodraft costs seedance-2 --type video --duration 15 --resolution 720p --quality standard --audio\\nvideodraft costs grok-imagine-2.0 --type image --resolution 2K --quality medium --num 2\\nvideodraft costs seedance-2 --type video --duration 15 --resolution 720p --quality standard --audio --no-allow-real-people # lower Byteplus-only rate\\nvideodraft costs elevenlabs-dubbing --type audio --duration 60\\nvideodraft costs seed-audio-1.0 --type audio --duration 60 # scenario only; model controls actual length\\nvideodraft costs elevenlabs-dialogue --type audio --chars 350\\nvideodraft costs voiceover --type audio --chars 800    # TTS: 10 cr / 1000 chars\\nvideodraft generate video \\"...\\" --model gemini-omni-1.1-flash --estimate # same quote, inline\\nvideodraft generate video \\"...\\" --model minimax-h3-max --duration 8 --resolution 768p --prompt-expansion-mode balanced\\n```\\n","references/pipeline.md":"# VideoDraft pipeline reference\\n\\nEverything here describes the hosted fallback pipeline through the CLI (`videodraft <command>` / `videodraft call <tool>`) or hosted MCP connector (tool names in backticks). When the local `videodraft_editor` MCP is available, do not use hosted production or export by default. Use hosted tools only for asset generation and optional script/storyboard stages, then import the results and finish with the native editor reference linked from SKILL.md. Continue through `produce_project` and `export_video` only when the user explicitly requests a hosted web production or the native editor is unavailable.\\n\\nUse direct asset tools for standalone images, clips, audio, upscales, and descriptions. Use a hosted project when the user explicitly wants the editable web project, when a hosted storyboard stage is useful, or when the native editor is unavailable. Script-only uses a script-stage project and stops at the script. In VideoDraft ADE with editor tools present, stop before hosted production, import the generated assets, and build/export the native project.\\n\\n## Stages and their tools\\n\\n| Stage                                    | CLI                                                                         | Underlying tool                             |\\n| ---------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------- |\\n| Idea \u2192 full storyboard project           | `videodraft create \\"<idea>\\"`                                                | `generate_storyboard_from_idea`             |\\n| Idea \u2192 script only (stop there)          | `videodraft create \\"<idea>\\" --script-only`                                  | `generate_script_from_idea`                 |\\n| Footage IS the video                     | `videodraft call generate_storyboard_from_media`                            | `generate_storyboard_from_media`            |\\n| Batch shot images                        | `videodraft shots <project>`                                                | `generate_shot_images`                      |\\n| One shot image                           | `videodraft generate image --project <id> --scene N --shot M`               | `generate_image`                            |\\n| Produce (voiceover, captions, timeline)  | `videodraft produce <project>`                                              | `produce_project`                           |\\n| Seedance full-video production           | `videodraft produce <project> --mode full_video`                            | `produce_project` with `mode: \\"full_video\\"` |\\n| Per-shot motion prompts                  | `videodraft video-prompts <project>`                                        | `generate_video_prompts`                    |\\n| Motion clip for a shot                   | `videodraft generate video --project <id>`                                  | `generate_video`                            |\\n| Attach a finished clip to the timeline   | `videodraft attach <project> --scene N --shot M --media <url> --type video` | `attach_media_to_shot`                      |\\n| Find free b-roll (no credits)            | `videodraft stock search \\"<query>\\"`                                         | `search_stock_media`                        |\\n| Copy stock media onto the CDN            | `videodraft stock import <ref>`                                             | `import_stock_media`                        |\\n| Background music                         | `videodraft generate music --attach <project>`                              | `generate_music` / `set_background_music`   |\\n| Song with vocals, lyrics or sections     | `videodraft generate music --model elevenlabs-music-v2.5 --section \\"...\\"`   | `generate_music` with `composition_plan`    |\\n| General or reference-driven audio        | `videodraft generate audio \\"...\\"`                                           | `generate_audio`                            |\\n| Sound effect                             | `videodraft generate sound-effect \\"...\\"`                                    | `generate_sound_effect`                     |\\n| Dialogue audio                           | `videodraft generate dialogue --line \\"voice:text\\"`                          | `generate_dialogue`                         |\\n| Voice changer                            | `videodraft generate voice-changer <audio>`                                 | `change_voice`                              |\\n| Dubbing                                  | `videodraft generate dub <audio_or_video>`                                  | `dub_media`                                 |\\n| Scene voiceover                          | `videodraft generate voiceover --project <id> --scene N`                    | `generate_voiceover`                        |\\n| Avatar script                            | `videodraft avatar script \\"<idea>\\"`                                         | `generate_avatar_script`                    |\\n| Avatar + speech                          | `videodraft avatar create <portrait> --script \\"...\\"`                        | `create_avatar_video`                       |\\n| Talking-head render                      | `videodraft avatar render <avatar_video_id>`                                | `render_avatar_video` + `get_avatar_video`  |\\n| Direct portrait + text/audio             | `videodraft avatar fabric <portrait> --text \\"...\\"` or `--audio <file>`      | `generate_veed_fabric_video`                |\\n| Short portrait clip from audio, up to 2K | `videodraft avatar h3-lipsync <portrait> --audio <file>`                    | `generate_minimax_h3_lipsync_video`         |\\n| Existing video + replacement audio       | `videodraft avatar lipsync <video> --audio <file>`                          | `generate_sync_lipsync_video`               |\\n| Existing-video AI edit                   | `videodraft edit video <video> \\"<change>\\" --model <video-edit-model>`       | `edit_video`                                |\\n| Motion transfer                          | `videodraft edit motion <image> [direction] --motion-video <video>`         | `generate_motion_control_video`             |\\n| Image enhancement/upscale                | `videodraft upscale image <image>`                                          | `upscale_image`                             |\\n| Video enhancement/upscale                | `videodraft upscale video <video>`                                          | `upscale_video`                             |\\n| Frame rate / slow motion                 | `videodraft interpolate <video> --fps 60 [--slowdown 4]`                    | `interpolate_video`                         |\\n| Final MP4                                | `videodraft export <project>`                                               | `export_video` + `check_export_status`      |\\n\\n## Rules that prevent broken results\\n\\n- **The storyboard is generated FROM the script**, never from the raw idea. `videodraft create` runs the whole chain correctly. Don\'t call `generate_storyboard_scenes` with a raw idea as the \\"script\\".\\n- **Visual consistency**: never generate a storyboard shot in isolation. Shot prompts carry `[[asset:Name]]` / `[[shot:X-Y]]` tags that `generate_shot_images` resolves against the project\'s visual assets and prior shots. When generating a single shot whose prompt has no tags, pass `--ref` images yourself (the project\'s visual assets and/or the previous shot\'s image; `projects get` exposes both). For scenes with multiple shots or recurring characters, prefer `videodraft shots <project> --model <selected-image-model> --grid`: preserve an explicitly requested compatible image model, otherwise use `nano-banana-2`. It creates one coherent scene grid, then decodes it into individual shot images.\\n- **Reference-first video**: when identity, styling, or composition matters, do not generate each motion clip from text alone. Generate or select the shot still first, then pass the decoded shot image as `--start-image` or `--ref` to the selected video model. AI Production already composes scene grids and sends them to Seedance as references. If the user explicitly requests another compatible video model, bypass fixed Seedance full-video mode and generate the per-shot clips with the requested model, using the individual decoded shot images as anchors.\\n- **Seedance full-video real people**: hosted `full_video` allows real people by default, which applies Fal-tier pricing to every submitted segment and permits the Byteplus-to-Fal fallback. For the lower Byteplus-only rate when no scene grid shows a real identifiable person (non-people, anime, clearly synthetic or stylized characters), use `videodraft produce <project> --mode full_video --no-allow-real-people`, or MCP `produce_project` with `mode: \\"full_video\\", allow_real_people: false`. If a partial opted-out run returns `SEEDANCE_REAL_PERSON_OPT_IN_REQUIRED`, re-estimate, follow the user\'s spend-confirmation preference, and rerun the same project once with an explicit `--allow-real-people` / `allow_real_people: true`. The server reconciles asynchronous results first, preserves running/completed jobs, and retries only failed placeholders carrying that exact code. Do not loop when it was already on. VideoDraft refunds a Byteplus task rejected after asynchronous acceptance, but cannot reroute it; rephrase or change the scene references instead.\\n- **Hold off generating shot images while the user is still iterating** on storyboard structure.\\n- **produce \u2192 export ordering**: `export` requires a produced project where every production scene has timeline media. If `produce` returns `generating_shot_images`, poll the job ids it returns, then re-run produce.\\n- **Do not attach motion clips before production exists**: run `produce` successfully first, then attach finished motion clips to the production timeline. Attaching before `production_data` exists cannot place them in the final timeline.\\n- **Generated motion clips do not auto-attach**: after `generate video` completes, attach the clip with `attach_media_to_shot` (`media_type:\\"video\\"`, include `duration_seconds`) \u2014 it replaces the production timeline clip while keeping the storyboard still.\\n- **Talking heads use dedicated avatar tools**: do not use `generate video`. Use managed `avatar create` and `avatar render` for reusable avatars, direct `avatar fabric` for a portrait plus text/audio, `avatar h3-lipsync` for a short (5-14.8s) portrait clip from existing audio at up to 2K, and `avatar lipsync` for an existing video plus replacement audio. Reuse a supplied person image or generate a clear front-facing portrait with the explicitly requested compatible image model, otherwise Nano Banana 2. Managed avatar creation and speech are bundled/free; direct Fabric, H3 Max Lip Sync, Sync, and render are paid.\\n- **Existing-video edits use their own category**: call `edit_video` or `videodraft edit video` with a `video_edit` model when transforming the source itself. Kling O3 also has a reference-generation mode that creates a new guided clip. Wan 3.0 is a text/frame/reference generation model, not a source-video editor. Motion transfer similarly uses `generate_motion_control_video` or `videodraft edit motion` with a `motion_control` model.\\n- **Upscaling preserves rather than redesigns**: use Topaz when resolution, detail, or cleanup is the problem (generative mode by default: Wonder 3.5 / Starlight Precise 2.6, Topaz\'s pick for AI sources; precision for real photos/footage or the cheapest pass; creative only for an artistic reinterpretation; `interpolate` for frame rate or slow motion). Regenerate or edit when the subject, text, framing, continuity, or motion is wrong. Upscale a low-quality avatar portrait before Fabric; do not render a new avatar at 480p just to upscale the result.\\n- **Timeouts on the one-shot create**: if `create` times out at the transport layer, the project was still created server-side \u2014 `videodraft projects list`, take the most recent, and resume with its id. Don\'t start a duplicate.\\n\\n## User-attached media: classify roles first\\n\\nFor EACH attached file decide:\\n\\n- **visual_asset** \u2014 recurring reference (character / product / location / style). Upload, then pass in `visual_assets` of `generate_storyboard_from_idea` (via `videodraft call`), or add to an existing project with `add_visual_assets`. Type must be one of `character | object | location | style | custom` with a short name + concrete description.\\n- **shot** \u2014 the media IS footage for the video. Whole video = footage \u2192 `generate_storyboard_from_media`. Idea + footage \u2192 `generate_storyboard_from_idea` with `shot_media`. Existing storyboard \u2192 `attach_media_to_shots`.\\n- **reference** \u2014 inspiration only \u2192 fold a description into the idea/instructions; don\'t place it as a shot or asset.\\n\\nAmbiguous (e.g. a person holding a product)? Ask the user.\\n\\nUploads persist in the media library \u2014 recall later with `videodraft media list`.\\n\\n## Editing project data safely\\n\\n1. `videodraft call get_project_schema` \u2014 read the structure once per session.\\n2. `videodraft projects get <id> --raw` \u2014 the exact editable blob.\\n3. Modify; then `videodraft call update_project --stdin` with `{\\"project_id\\": \\"...\\", \\"data\\": {...}}`.\\n   - Objects deep-merge key-by-key; **arrays replace wholesale** \u2014 send the complete array you\'re changing (e.g. all of `storyboard.scenes`).\\n   - Scene shot arrays (`image_prompt` / `shot_types` / `shot_actions` / `search_prompt` / `preview_media`) are auto-aligned; fix-ups come back as warnings.\\n4. Snapshot before risky edits: `videodraft checkpoint create <id> --name \\"before re-script\\"`. Restore with `videodraft checkpoint restore <id> <version>`.\\n\\n## AI Studio sessions (standalone generations)\\n\\nProject generations group automatically, and standalone work is grouped per conversation (MCP) or per working directory (CLI) by the connection session \u2014 see the \\"AI Studio sessions\\" section of SKILL.md. Once the task is clear, give that automatic session a concise 3-6 word title before the first generation:\\n\\n```bash\\nvideodraft sessions name \\"Fox Brand Explorations\\"\\nvideodraft generate image \\"...\\"\\n```\\n\\nNaming creates the session with that title. If generation, a user, or an earlier agent created it first, the existing name is preserved. The command refuses to run while `VIDEODRAFT_SESSION` is set, because that override would send later generations to a different session. Use `sessions create` plus `--session` only to continue or deliberately create a separate group.\\n"}') {
-    return JSON.parse('{"SKILL.md":"---\\nname: videodraft\\ndescription: Create and edit AI videos, images, 3D meshes, Seed Audio, voiceovers, music, sound effects, dialogue, dubbing, storyboards, avatar videos, media upscales, and product/ad videos with VideoDraft. Use whenever the user mentions VideoDraft; asks to generate a video, image, 3D asset, audio asset, ad, explainer, storyboard, avatar, upscale, or batch/CI workflow; wants to download a video from YouTube, Instagram, TikTok, X or another site; or wants to assemble, cut, caption, mix, lay out, inspect, or export a native VideoDraft Editor timeline. Covers the cloud `videodraft` CLI/MCP and local headless `videodraft_editor` MCP. When the editor MCP is exposed, prefer it for production, timeline assembly, and export; use cloud production/export only when explicitly requested or the editor is unavailable.\\n---\\n\\n# VideoDraft\\n\\nVideoDraft is an AI video creation platform where asset generation is the priority lane:\\n\\n- **Asset generation**: standalone images, video clips, Seed Audio, voiceovers, music, sound effects, dialogue, voice-changed audio, dubbed media, upscales, and image descriptions. This is the fastest and most important lane. Treat these as complete deliverables when the user asks for assets.\\n- **Asset I/O**: upload local files, download outputs, auto-upload local references, and save generated media where the user can see it.\\n- **3D assets**: standalone Meshy 7 and Tripo H3.1 meshes, multi-view generation, complete artifact downloads, and Meshy humanoid rigging through MCP/CLI. Read [references/3d.md](references/3d.md), or `videodraft skills show 3d`. These assets have their own saved library and do not require an AI Studio session or web viewer.\\n- **Native editing**: local `.vdproject` timelines, cuts, layouts, captions, effects, audio, and exports through the headless VideoDraft Editor. Inside VideoDraft ADE, this is the default production and export lane whenever `videodraft_editor` is available.\\n- **Hosted project production**: idea \u2192 script \u2192 storyboard \u2192 hosted production timeline \u2192 exported MP4. Use the early stages for scripts, storyboards, and generated assets when useful. Treat hosted production and export as a fallback when the native editor is unavailable, or as an explicit destination when the user asks for an editable web project or hosted workflow.\\n\\n## How to connect\\n\\nCloud generation has two equivalent surfaces (same backend, credits, and hosted projects). Native timeline editing is a separate local surface:\\n\\n1. **CLI** (preferred when you have a shell): run `videodraft` if it\'s on PATH; otherwise `npx -y videodraft@latest` runs it with no install (needs Node \u226520; the `-y` skips npx\'s install prompt so it runs non-interactively; the package is fetched on first use and cached). For heavy use, `npm install -g videodraft`. If there\'s no Node/shell here but the MCP connector below is available, use that instead; if neither works, tell the user how to install (https://videodraft.ai/cli).\\n   - Auth \u2014 pick by context, don\'t guess:\\n     \u2022 INTERACTIVE (a human is in the session, e.g. Claude Code / Codex): on exit code 3 (\\"not authenticated\\"), tell the user to run `videodraft login` in their terminal \u2014 it opens their browser for a one-click VideoDraft sign-in (OAuth), no key to copy. Wait for them to confirm it succeeded, then retry the command. This is the preferred path when the user is present.\\n     \u2022 HEADLESS / CI (no browser): set `VIDEODRAFT_API_KEY=vd_mcp_...` (a token the user mints at https://app.videodraft.ai/mcp-keys).\\n     \u2022 SECURITY: never ask the user to paste a `vd_mcp_...` token into the chat \u2014 use browser `login` or the env var so the token never lands in the transcript.\\n   - Every command accepts `--json` (parse this, don\'t scrape text). Exit codes: 0 ok, 1 error, 2 usage, 3 auth (see Auth above), 4 insufficient credits (\u2192 tell the user, don\'t retry).\\n   - Tool discovery: start with `videodraft tools list` for the grouped catalog, then narrow with `videodraft tools list --lane assets`, `--lane asset_io`, `--lane project_data`, or `--lane production`.\\n   - Asset lane: `videodraft generate ...`, `videodraft edit video|motion`, `videodraft avatar ...`, `videodraft upscale ...`, `videodraft interpolate ...`, `videodraft upload`, and `videodraft download`.\\n   - Full API access: `videodraft tools schema <name>`, `videodraft call <tool> --args \'<json>\'`.\\n2. **MCP connector**: if VideoDraft MCP tools (e.g. `generate_storyboard_from_idea`) are available, call them directly \u2014 the CLI\'s curated commands map 1:1 onto these tools.\\n3. **Native editor MCP** (`videodraft_editor`): prefer this for project production, timeline assembly, cutting, layouts, transitions, captions, audio placement, and final export. Inside VideoDraft ADE on a supported Mac, Claude, Codex, OpenCode and Grok receive it automatically in both Code and VideoDraft modes. It runs headlessly, so an Open Editor click is not required. Start with `project_manage` (`operation: \\"project\\"`, action `list`, `open`, or `create`); standalone asset generation remains in the cloud CLI or MCP.\\n\\nSend native editor edits serially, batching everything a request needs into one `edit_apply` recipe. Pass the latest `context` when a person may be editing at the same time, so a stale write is refused. See [references/editor.md](references/editor.md) for project selection, media import, timing units, edit recipes, verification, export, and the `videodraft-editor` terminal bridge.\\n\\nIf you are reading this skill through `videodraft skills show skill`, run `videodraft skills show editor` before native editor work to load that reference.\\n\\n**VideoDraft ADE routing rule:** the presence of `videodraft_editor` means the native editor is ready, even when no editor window is visible. Use cloud tools to generate or source assets and, when helpful, scripts or storyboards. Do not call hosted `produce_project` / `videodraft produce` or `export_video` / `videodraft export` by default. Import the assets into the native project, assemble there, and export with native `delivery_manage` `submit`. Use hosted production/export only when the user explicitly asks for the web workflow or the native editor tools are unavailable. Do not silently fall back to hosted production after a native tool error.\\n\\n## First decision: asset, hosted project, or native edit?\\n\\n- **One standalone asset** (image, clip, voiceover, music track, sound effect, dialogue track, voice-changed file, dubbed media file, upscale, or description): generate it directly. Do NOT create a project.\\n  - `videodraft generate image \\"a red fox in snow, cinematic\\" --ar 16:9 --download ./out/`\\n  - `videodraft generate video \\"slow dolly over a misty lake\\" --model gemini-omni-1.1-flash --duration 6 --download ./out/`\\n- **Any final video, production timeline, existing footage, local `.vdproject`, or hands-on edit**: use `videodraft_editor` when available. List or open the intended local project, or create a native project for a new production. The editor can work without showing its UI.\\n- **A small set of related assets**: still stay in the asset lane. They are grouped automatically (see [AI Studio sessions](#ai-studio-sessions)); give the current group one useful task-specific name with `videodraft sessions name \\"<name>\\"`. Switch to a project only when the deliverable matches the project criteria below or the user asks to attach the assets to one.\\n- **A generated multi-scene video / ad / explainer**: when the editor is available, use hosted tools only for any needed script, storyboard, shot planning, or generated assets; stop before hosted production, import the assets, and build/export the native timeline. A hosted project is optional unless the user wants the web project or its storyboard workflow.\\n- **A hosted web project or hosted export**: use the hosted pipeline only when the user explicitly asks for it or the native editor is unavailable.\\n- **Just a script** (no video asked for): A script-only request creates a script-stage project but stops at the script. Use `videodraft create \\"...\\" --script-only`; do not build a storyboard the user didn\'t ask for.\\n- **Iterating on existing work**: identify the surface first. Use `project_manage` `project` with `action: \\"list\\"` for native projects and `videodraft projects list` only for hosted work. Never create a replacement project just to change an existing one.\\n\\n## Choose the model from the task\\n\\nIf the user names a model, use it when compatible. If it cannot handle the request, explain why and recommend alternatives instead of silently switching. Otherwise inspect the inputs, duration, audio, quality, speed, and cost, check the live catalog, and pass an explicit model.\\n\\n### Seedance 2.x real-person rule\\n\\nSeedance 2.0 and 2.5 allow real people by default, the same as AI Studio:\\n\\n- The default is true. Generation tries Byteplus first and can fall back to Fal, which allows real-person likenesses, so a person in the prompt, a start frame, end frame, reference image, or reference video does not hard-fail. The request is charged at Fal\'s higher tier-specific rate even if Byteplus serves it.\\n- Turn it off for the cheapest run, only when the user wants that and nothing in the job is a real identifiable person (text-only requests, non-people, anime, clearly synthetic or stylized characters). For MCP use `allow_real_people: false`. For the CLI use `--no-allow-real-people`. That pins the job to the lower-priced Byteplus path, and a Byteplus likeness-policy refusal does not fall back to Fal. Pass the same value to `get_model_costs` or `videodraft costs` so the estimate matches the charge.\\n- If a request made with the option off fails with code `SEEDANCE_REAL_PERSON_OPT_IN_REQUIRED`, estimate the higher rate, follow the user\'s spend-confirmation preference, and retry exactly once with the option on. The structured recovery fields are `retryable: true`, `retry_with: { allow_real_people: true }`, `cli_flag: \\"--allow-real-people\\"`, and `retry_policy: \\"once\\"`. CLI `--json` submit errors expose them under `details`; `status` and `wait` include them on the failed job result. Do not treat an unrelated moderation or provider error as that signal.\\n- Do not loop when the option was on. Byteplus can accept a task and reject its generated output later. VideoDraft refunds that failed generation, but the late asynchronous failure cannot be rerouted to Fal. Rephrase the prompt or use different references before trying again.\\n- For hosted AI Production, the same default applies to every Seedance scene segment: `produce_project` with `mode: \\"full_video\\"` and `videodraft produce <project> --mode full_video` allow real people unless you pass `allow_real_people: false` or `--no-allow-real-people`. If an earlier run with the option off partially submitted and returns the opt-in code, rerun that same project once with an explicit `allow_real_people: true` / `--allow-real-people`. The server reconciles asynchronous results first, preserves running/completed jobs, and resubmits only failed scene-video placeholders carrying the exact opt-in signal. Keep the native-first VideoDraft ADE routing rule above: hosted full-video production is still explicit/fallback-only when the local editor is available.\\n\\n**How to pick a model. Follow this order every time:**\\n\\n1. The user named a model: use it, never substitute.\\n2. Otherwise pick a **Tier 1** model.\\n3. Use a **Tier 2** model only when no Tier 1 model supports the request, and say why. Never pick Tier 2 on your own for price, speed, novelty or variety.\\n\\nTier 1: images `nano-banana-2`, `nano-banana-pro`, `nano-banana-2-lite`, `gpt-image-2.5-flare`, `gpt-image-2.5-sunburst`, and `recraft-v4` for vector/SVG only; videos `gemini-omni-1.1-flash`, `seedance-2.5`, `seedance-2`, `kling-3.0`, `kling-o3`, `minimax-h3-max`; video edits `gemini-omni-1.1-flash`; talking-head portraits `veed-fabric`, `minimax-h3-max-lipsync`; motion transfer `kling-v3-motion-control`; audio ElevenLabs for speech tools, Lyria 3.5 for music at any length.\\n\\nTier 2 is every other catalog model (`wan-3.0`, `flux-3`, `minimax-h3`, `kling-v3-turbo`, `kling-2.6-pro`, `grok-imagine-video-1.5`, `happy-horse`, Veo 3.1, Sora, Seedream, Grok Imagine images, FLUX images, `sync-lipsync-2` and the rest). All of them stay available by name. Real Tier 2-only jobs: document or web-page references (`wan-3.0`), keyframes pinned to timestamps (`flux-3`), re-syncing existing footage (`sync-lipsync-2`).\\n\\nEvery `videodraft models image|video|audio --json` entry carries `tier` (1 or 2), and the top-level `recommended` array is Tier 1, best first. That catalog beats this page when they disagree.\\n\\n**Speech in video:** write the dialogue in the video prompt. `gemini-omni-1.1-flash`, `seedance-2.5`, `seedance-2`, `kling-3.0` and `kling-o3` speak it natively. For a specific voice add a Seedance reference audio clip (`--ref-audio`) or a Kling bound voice. Do not plan silent video + TTS + lip-sync. Lip-sync tools are only for a portrait presenter talking to camera, or for re-syncing footage that already exists. Off-screen narration and voiceover are unaffected: keep using `generate voiceover` for those.\\n\\n**Images:**\\n\\n- `nano-banana-2`: general default, editing, consistency, and references.\\n- `nano-banana-pro`: maximum quality. `nano-banana-2-lite`: fast, inexpensive drafts.\\n- `gpt-image-2.5-flare`: replaces the GPT Image 2 recommendation for posters, logos, signs, title cards, readable text and composition. Use `gpt-image-2.5-sunburst` for extra precision/detail. Both use the same basic options as GPT Image 2: references (up to 16), aspect ratio, 1K/2K/4K resolution, image count (1-4), and quality. Quality adds xhigh/max; auto is charged at the max tier. Other model recommendations are unchanged; explicit `gpt-image-2` requests still use GPT Image 2.\\n\\n**Videos:**\\n\\n- `gemini-omni-1.1-flash`: general default for 3-10s generation, image-to-video, uploaded source edits up to 10s, and silent or voiceover-backed shots (audio is always on, so describe quiet ambience with no speech and mute or mix it on the timeline; only a file with no audio track at all needs `kling-3.0`, `kling-o3` or Seedance with `--no-audio`). It supports first and last frames, up to 10 total image inputs, up to 3 creative reference videos of at most 3 seconds each on `--video-task generate` ONLY, uploaded-video extension, and continuation of an earlier generation through `--previous-interaction-id`. Output is 360p/720p/1080p/4K at 3/10/15/30 cr/s with audio always on. Use `--source-video` for the uploaded edit/extension source; extension sources must be 1-30s. Edit and extend accept EXACTLY ONE input video, so `--ref-video` cannot accompany `--source-video` or `--previous-interaction-id`; only `--ref` images can. One `--ref-video` with no separate source remains a legacy source edit. A previous interaction defaults to conversational edit; add `--video-task extend` or `--extend` with an explicit 3-10s duration to append at the end. A continuation resolves to the prior turn\'s output and is submitted as an ordinary source, so the same limits apply to it: at most 30s to extend, at most 10s to edit. 40 seconds total is reachable, but only by extending from a source of 30s or less, so a ladder dead-ends once it passes 30s. New dialogue can only be added when the SOURCE video is silent; adding speech on top of a source that already contains speech is refused with \\"the model is currently unable to process speech edits\\". The server safely measures creative-reference durations, or you can repeat `--ref-video-duration` when a host blocks metadata probing. Fal BYOK supports its currently callable v1.1 generation and basic-edit endpoints at zero VideoDraft credits, but Fal does not expose continuation/extension or mixed source-edit references as callable endpoints and VideoDraft must never fall back to paid Google.\\n- `grok-imagine-video-1.5` (Tier 2): 1-15s text, first-frame, or 1-7 reference-image generation with native audio. Text/first-frame modes support 480p, 720p, and 1080p; reference mode supports 480p/720p. Cite references as `<IMAGE_0>` through `<IMAGE_6>`. It has no last frame, seed, negative prompt, quality tier, reference video, or reference audio.\\n- `minimax-h3` (Tier 2): 480p/768p/2K/4K (5/6/13/16 cr/s, 768p default), native stereo audio, and 5-15s text, first/last-frame, or mixed-reference generation. Reference mode accepts up to 9 images, 3 videos, and 3 audio clips, with at most 12 files total. Cite them as `Image 1`, `Video 1`, and `Audio 1` in array order.\\n- `minimax-h3-max`: 480p/768p pricing (5/8 cr/s, 768p default), native audio, and 5-15s text, first/last-frame, or mixed-reference generation. Reference mode accepts up to 9 images, 3 videos, and 3 audio clips, with at most 12 files total, cited as `Image 1`, `Video 1`, and `Audio 1` in array order. It supports a reproducibility seed and `disabled` / `balanced` / `quality` prompt expansion.\\n- `wan-3.0` (Tier 2): unified 2-30s text, first/last-frame, or ordered mixed-reference generation at 480p/720p/1080p (7/14/28 cr/s), with optional native audio. Reference mode accepts up to 10 images, 5 videos, and 5 audio clips, at most 20 media files total; video and audio each total at most 15 seconds. `--auto-duration` reserves 30 seconds and reconciles to the provider-reported output length. Document/web references use `--file-url` or `--web-url` and require `--thinking`.\\n- `flux-3` (Tier 2): Black Forest Labs FLUX 3. 5-20s at 720p/1080p with 24fps native audio, from a prompt, a first frame, first + last frames, or up to 10 keyframes pinned to specific moments (`--keyframe shot.png@2.5`, repeatable). `--quality draft` renders the same shot at 720p for roughly a third of the cost. Auto duration is text/first-frame only.\\n- `seedance-2`: 11-15s, video/audio/mixed references, wider ratios, selectable audio, or first/last frames. `mini` is the economical default; move to `standard` when the user asks for high quality, when a Mini result is not good enough, or for 1080p/4K; `fast` for speed.\\n- `seedance-2.5`: 4-30s single takes and up to 50 references (30 image, 10 video, 10 audio). Same modes as 2.0, one quality tier, 480p/720p/1080p. Reach for it when a shot must run past 15s or carry more references than 2.0 allows.\\n- `kling-o3`: reference images plus structured image/video elements, first/last frames, multi-prompt, audio control, or 4K. O3 allows 7 combined image references and image-backed elements, reduced to 4 combined items when a video-backed element is present. `kling-3.0`: image-to-video can use structured image/video elements and bind a custom Kling voice ID to either element form. Tier 2, by name: `kling-v3-turbo` (fast polished 3-15s with first frame, multi-prompt, and audio, but no elements) and Kling 2.6 Pro (top-level voice IDs cited as `<<<voice_1>>>` and `<<<voice_2>>>`).\\n- Existing-video edits use `videodraft edit video`, not generic generation. `gemini-omni-1.1-flash` is the preferred edit model and is chosen automatically when you omit `--model`: source up to 10s, up to 10 reference images, 360p/720p/1080p/4K with audio. Creative `--ref-video` inputs are NOT accepted on an edit, because an edit takes exactly one input video; use `generate video --video-task generate` to guide a new clip with video references instead. Omitting `--model` on a longer or unmeasurable source spends nothing and prints a priced menu (what each model edits, what it drops, what it costs) so you can put the choice to the user. **Truncation:** only Gemini refuses an over-length source. Happy Horse silently edits just the first 15s, Kling O3 the first 10s, and Grok the first 8s. The command warns you when that will happen; always relay it to the user. Gemini regenerates the audio track, so use Happy Horse or Kling O3 with `--preserve-audio` when the source audio must survive. Choose Grok for the cheapest prompt-only edit, Happy Horse for up to 5 image references, or Kling O3 for controlled reference-image edits.\\n- To edit a source longer than 10s without losing its tail, cut it into <=10s pieces in the native editor, edit each with Gemini, and reassemble. VideoDraft has no server-side split/concat, so this path needs `videodraft_editor`.\\n- Kling O3 also has a reference-generation mode. Use `videodraft generate video --model kling-o3-video-ref-edit` with exactly one `--ref-video` to generate a new guided clip; use `videodraft edit video` when changing the source itself. For new mixed-reference generation use Seedance 2 / 2.5.\\n- Motion transfer uses `videodraft edit motion` with Kling V3 by default, or Kling 2.6 when explicitly requested or lower cost matters. It requires a subject image and a motion-reference video.\\n- Veo 3.1, Sora, Grok, Happy Horse and the other Tier 2 video models: only when explicitly requested or when no Tier 1 model fits.\\n\\n**Audio and utilities:**\\n\\n- Use Seed Audio 1.0 for open-ended text-to-audio, speech/music/sound synthesis, voice conditioning, or prompt-driven editing with up to three audio references or one image. Use `videodraft generate audio`. Reference clips are `@Audio1`, `@Audio2`, and `@Audio3` in array order. There is no duration input. Output is up to two minutes and settles at 19 credits per actual minute, with up to 38 credits reserved during generation. The CLI automatically retries transient responses with one operation key. To recover after the CLI process itself is interrupted, set `--idempotency-key <uuid>` on the original command and reuse it.\\n- Prefer ElevenLabs for voiceover, dialogue, voice changing, dubbing, and sound effects. Honor an explicitly selected supported TTS voice/provider. Use `lyria-3.5` for all music, short or long (up to ~3 minutes, 10 credits flat), with vocals/lyrics or instrumental arrangements. When `--model` is omitted the CLI sends no model and the server default applies, which is `lyria-3.5` wherever the backend supports it. If the server answers that `lyria-3.5` is an unknown model, that backend predates it: rerun without `--model` (the server default then applies), or use `lyria-3-pro-preview` for a track longer than 30 seconds. Ask for the length in the prompt. Keep `lyria-3-clip-preview` (fixed ~30s, 4 credits) and `lyria-3-pro-preview` (8 credits) for explicit requests. For Lyria, put desired length, lyrics and \\"instrumental only, no vocals\\" in the prompt; `--length` and `--instrumental` are ElevenLabs-only. Use ElevenLabs Music for exact timing, composition plans, or a style reference track. Lyria allows 10 reference images on Google, 1 on Fal BYOK; Fal 3.5 prompts are limited to 5000 characters. BYOK uses zero VideoDraft credits. ElevenLabs Music means `elevenlabs-music-v2.5` (`elevenlabs-music` is an alias for it); use `elevenlabs-music-v1` only when the user asks for v1 by name.\\n- For ElevenLabs voiceover, dialogue, and voice changing, accept a supplied raw voice ID (16-64 alphanumeric characters) or `elevenlabs-<id>`. The voice catalog is for discovery, not an allowlist. Do not reject or substitute a supplied ID because it is absent from `videodraft models voices` / `list_available_voices`. Use `--voice <id>` for voiceover and voice changing, or repeat `--line \\"<id>:Text\\"` for dialogue; for example, `--voice kPzsL2i3teMYv0FxEYQ6` and `--line \\"elevenlabs-kPzsL2i3teMYv0FxEYQ6:Hello.\\"` use the same voice. The voice must be accessible to the provider account used for generation. Private or cloned voices may require the user\'s connected ElevenLabs key. Kling video-control IDs and MiniMax `custom-*` IDs are separate voice systems.\\n- A character who needs to TALK:\\n  - **Speaking inside a scene**, or any ordinary clip with dialogue: `generate video` with the line in the prompt, in quotes, with who says it and how. `gemini-omni-1.1-flash`, `seedance-2.5`, `seedance-2`, `kling-3.0` and `kling-o3` all voice it natively. For a specific voice use a Seedance `--ref-audio` clip or a Kling voice bound per element. This is the default path; do not generate speech separately and lip-sync it on.\\n  - **Talking to camera from a portrait** (presenter, spokesperson, explainer): the avatar lane, and VEED Fabric is preferred. Use managed `avatar create` then `avatar render` for a reusable avatar record with bundled speech, `avatar fabric` for a one-off portrait plus text or existing audio, and `avatar h3-lipsync` for a short (5-14.8s) portrait clip from existing audio at up to 2K. Not for in-scene shots: Fabric animates a portrait facing the lens, so a cinematic request comes back as a head-on talking headshot.\\n  - **Footage that already exists plus replacement audio** (re-dub, translation): `avatar lipsync`. This is the only job for Sync Labs unless the user names it.\\n- Enhancement: use Topaz image/video upscaling only when the content is already correct. Use image 1x for cleanup, 2x by default, 4x when justified; use video 2x by default. Edit or regenerate creative errors.\\n\\nSee [references/models.md](references/models.md) for the detailed routing table and exact capability limits.\\n\\n## Prefer references when continuity matters\\n\\nPure text-to-image or text-to-video is fine for a generic one-off asset. When a specific character, product, location, style, composition, or brand identity must survive generation, use references instead of hoping the prompt recreates it.\\n\\n- If the user supplies reference media, preserve and pass it. Never reduce the request to text alone.\\n- When continuity matters, generate/select a strong still first with the selected image model (`nano-banana-2` by default), wait for its URL, then animate it as a start frame/reference. Confirm the combined image and video cost.\\n- When using a hosted storyboard stage for multiple shots, use `videodraft shots <project_id> --model <selected-image-model> --grid`, then animate the decoded shots. Preserve explicit models. In VideoDraft ADE, import the resulting assets into the native editor instead of continuing into hosted production. A requested non-Seedance video model must use manual per-shot generation instead of Seedance full-video mode.\\n\\n## Cost and credits\\n\\nDo not call `videodraft credits` before routine generations. Paid endpoints validate and deduct atomically; if the balance is insufficient, the request is rejected before the provider job starts (CLI exit code 4). Check the balance only when the user asks, gives a credit budget, or a large workflow needs budget planning.\\n\\nFor expensive work, estimate with `--estimate` or `videodraft costs`, state the selected model/settings/cost, and get a go-ahead. This matters most for shot-image batches, long or high-resolution video, AI Production, and paid audio batches. Honor the user\'s confirmation preference for the session.\\n\\nKling voice creation costs 1 VideoDraft credit on the platform Fal account and 0 credits with Fal BYOK. Preview it with `videodraft kling-voices create <sample> --name <name> --estimate`; the estimate does not create a voice or require consent confirmation. Actual creation requires `--confirm-consent`.\\n\\nMiniMax H3 costs 5 / 6 / 13 / 16 credits per output second at 480p / 768p / 2K / 4K (768p by default). In reference mode the first 5 images are included and each additional image costs 8 credits. Reference video and reference audio are NOT billed.\\n\\nMiniMax H3 Max costs 5 credits per output second at 480p and 8 credits per second at 768p (default), plus pooled reference tokens in reference mode: the first 4,096 are free and every 1,000 after that costs 2 credits, where an image is `(width x height) / 1024` tokens, a reference video is 2,886 tokens per second at 480p or 7,459 at 768p, and reference audio is about 2,121 per second. Use `--prompt-expansion-mode disabled|balanced|quality`; balanced is the default. Fal\'s provider safety checker is OFF by default and is not exposed in the app \u2014 only pass `--safety-checker true` if the user explicitly asks for it.\\n\\nWan 3.0 costs 7 / 14 / 28 credits per output second at 480p / 720p / 1080p. Auto duration reserves the 30-second maximum and refunds the unused reserve after the provider reports the actual whole-second output length. Fal BYOK runs on the connected user key and charges zero VideoDraft credits.\\n\\nGrok Imagine Video 1.5 costs 8 credits per output second at 480p, 14 at 720p, or 25 at 1080p, plus 1 credit for each first-frame or reference image. Native audio is always generated.\\n\\n`videodraft models image|video` lists the live image and video catalogs with supported inputs. Video entries are grouped as `generation`, `video_edit`, `motion_control`, `avatar_lipsync`, and `upscale`, and each reports the exact tool. Use `videodraft models video --category video_edit` to narrow the list. `videodraft models audio` lists Seed Audio, Google Lyria, and ElevenLabs audio/media tools, while `videodraft models voices` helps discover TTS voices. Consult them for capabilities; a supplied ElevenLabs voice ID does not need to appear in the voice catalog.\\n\\n## Async jobs\\n\\nImage/video generation is asynchronous: commands submit a job and **wait by default**, printing output URLs (and saving files with `--download`). Large downloaded images also get a downscaled copy in `previews/` next to them (the `preview` field / \\"inspect via preview\\" line in the output) \u2014 **look at the preview, deliver the original**; viewing full-resolution images bloats the chat permanently. In scripts/CI prefer explicit control:\\n\\n```bash\\nJOB=$(videodraft generate image \\"...\\" --no-wait --json | jq -r .job_id)\\nvideodraft wait \\"$JOB\\" --download \\"./outputs/{job_id}_{index}.{ext}\\" --json\\n```\\n\\nFor MANY jobs: submit each with `--no-wait`, collect ALL with one command \u2014 `videodraft wait <id1> <id2> ...` polls every job from one process with one batched request per tick. Do NOT spawn parallel `wait`/`generate --wait` processes for a batch.\\n\\nIf a wait times out, the job is still running server-side \u2014 `videodraft status <job_id>` later. Never re-submit just because a wait timed out (that double-spends credits).\\n\\nFor completed Wan 3.0 jobs, MCP `check_generation_status` and CLI `status`/`wait --json` include `outputMetadata` with Fal\'s returned `seed`, `duration`, and `actual_prompt` when present.\\n\\n## AI Studio sessions\\n\\nStandalone image/video/audio generations are filed into an AI Studio session in the web app. 3D assets use `assets 3d list/get` separately. You do not have to create an AI Studio session:\\n\\n- **MCP hosts** (Claude Code, claude.ai, Codex, VideoDraft ADE): on 2025-era MCP the server mints an `Mcp-Session-Id` on `initialize`; your host echoes it, and this conversation\'s generations land in their own session. On stateless MCP (2026-07-28) hosts that send a conversation id (ChatGPT) get the same. Otherwise `name_current_ai_studio_session` returns `pass_session_id: true` with a `session_id`: pass that `session_id` to every later standalone generation in the conversation. Tool results echo the session as `ai_studio_session_id`.\\n- **CLI**: the same handshake runs once per (profile, server, working directory) and is cached for 12 idle hours, so everything generated from one directory shares one session. `videodraft sessions current` shows it; `videodraft sessions reset` starts a new one.\\n- Project generations (`--project <id>` / `project_id`) always go to that project\'s session.\\n\\nOnce you understand the creative task, name the current automatic session before the first standalone generation:\\n\\n```bash\\nvideodraft sessions name \\"Purple Seal Rescue Short\\"\\n```\\n\\nChoose a concise, specific 3-6 word title for the intended work. Do not copy the client name, date, or exact chat title. Name it once: the operation creates the session with that title. If generation, a user, or an earlier agent created the session first, its existing name is preserved.\\n\\nApart from the `pass_session_id: true` case above, pass `--session <id>` / `session_id` only to **continue earlier work** or create an explicit separate group:\\n\\n```bash\\nSESSION=$(videodraft sessions create \\"Fox brand explorations\\" --json | jq -r \'.session.id\')\\nvideodraft generate image \\"a red fox in snow, cinematic\\" --session \\"$SESSION\\"\\nvideodraft generations --session \\"$SESSION\\"          # what is in it\\nvideodraft sessions list --name fox                  # find it again later\\n```\\n\\n`VIDEODRAFT_SESSION=<id>` sets the default for every command (ignored when `--project` is given). While it is set, `sessions name` refuses to run because that command names the current automatic connection session, not the pinned override; unset it first or rename the pinned session in AI Studio. `VIDEODRAFT_SESSION_SCOPE=<label>` groups several directories into one connection session; `VIDEODRAFT_CLIENT_NAME=<host>` labels the fallback placeholder used when generation creates the session before `sessions name`; `VIDEODRAFT_NO_SESSION=1` disables the handshake. Generations that reach the server with no session at all fall back to the account-wide \\"Agent (MCP)\\" session; if you see work landing there, pass `--session` explicitly.\\n\\n## Generation history\\n\\nPast work is queryable \u2014 reuse a previous setup instead of guessing. `videodraft generations` lists recent generations; scope with `--session <id>` or `--project <id>` (includes collaborators\' rows in shared scopes; pass one, project wins), and filter with `--type`, `--model`, `--favorites`. `--full --json` returns each row\'s exact parameters (aspect ratio, resolution, duration, references) \u2014 the human table stays compact, so pair `--full` with `--json`. `videodraft generation <id>` prints one generation\'s complete recipe (prompt, input image, parameters, outputs); `--favorite` / `--unfavorite` stars it. `videodraft sessions list` shows AI Studio sessions (owned + shared) with `--name` search \u2014 take a session id from there to read its history.\\n\\n## Free stock footage and photos\\n\\nPexels and Pixabay are wired in through `search_stock_media` / `import_stock_media` (`videodraft stock search \\"<query>\\"`, `videodraft stock import <ref>`). Both libraries are free, watermark-free and cost **zero credits**, so use stock for b-roll, establishing shots, backgrounds and ordinary real-world footage, and spend credits on the shots that must be specific: the product, the character, the scripted action.\\n\\n```bash\\nvideodraft stock search \\"city skyline night\\" --min-duration 5 --orientation landscape\\nURL=$(videodraft stock import pexels:video:35379336 --quality hd --json | jq -r .url)\\n```\\n\\n- Always two steps. A search result\'s `preview_url` is a thumbnail for judging the shot; never place it on a timeline, attach it to a shot or send it to a model. `import_stock_media` copies the file onto the VideoDraft CDN and returns the URL every other surface accepts, including the native editor\'s `library_manage` import.\\n- `--quality hd` (default) caps video at 1080p; `4k` caps at 2160p, `best` takes the largest the provider has, `sd` suits rough cuts. Stills ignore quality and import at full size. Use `--orientation portrait` for 9:16, and `--min-resolution 1920` to drop anything below HD on its long edge.\\n- Photos come from Pexels. Pixabay contributes video only, because its full-size image host refuses server-side downloads.\\n- Credit the creator and link the provider page when you show results or deliver the finished work; both come back on every result. Skip clips that imply a person or brand endorses the product, and avoid recognisable logos in ads.\\n- Search and import are rate limited per user (30 searches and 15 imports a minute) and searches are cached for 24h, so a burst of searches while planning a montage is fine. Bulk downloading a stock library is prohibited by both providers. A note saying Pixabay was skipped means its provider budget for that minute is spent; the Pexels results still stand.\\n\\n## Downloading from YouTube, Instagram, TikTok and other sites\\n\\nVideoDraft ships no downloader. When the user asks to pull a video from YouTube, Instagram, TikTok, X, LinkedIn or anywhere else, `yt-dlp` on the user\'s own machine does the work. Check for it with `command -v yt-dlp` before promising anything.\\n\\n**Present:** pin the format. On its defaults yt-dlp takes the best stream, usually VP9 or AV1 in WebM, which the native editor\'s import rejects (mp4, mov and m4v only). This returns one pre-muxed H.264 + AAC MP4 and needs no ffmpeg:\\n\\n```bash\\nyt-dlp -f \\"b[ext=mp4]\\" -o \\"media/%(title)s.%(ext)s\\" \\"<url>\\"\\n```\\n\\n**Missing:** say so in one line, then offer `brew install yt-dlp` only where `brew` exists, and only after asking. With no Homebrew, say the tool is unavailable and stop.\\n\\n- Never install Homebrew, never `sudo`, never write to `/usr/local/bin` or `/opt`, never pipe a script into a shell.\\n- `ffmpeg` is optional, matters only above 720p, and the selector above never needs it.\\n- Auth-gated content needs `--cookies-from-browser`; raise it only after a download fails on auth.\\n- Fetch only what was asked for, never a channel, playlist or back catalogue.\\n\\n## Local files and reference images\\n\\nReference inputs must be public URLs. The CLI uploads local files automatically wherever a URL is expected (`--ref photo.jpg`, `--start-image frame.png`), or explicitly:\\n\\n```bash\\nURL=$(videodraft upload ./product.png --json | jq -r .url)\\n```\\n\\nNever silently drop a reference you couldn\'t upload \u2014 stop and tell the user. Never upload a user\'s file to a third-party host.\\n\\nWhen the user attaches media for a native production, import actual footage into the editor by default. For hosted generation/storyboarding, classify each item before acting: a recurring **visual asset** (character/product/location/style), actual **footage to place as shots**, or **inspiration only**. See [references/pipeline.md](references/pipeline.md) for the hosted role mapping.\\n\\n## Showing media to the user\\n\\nGenerated media is **not** displayed in the chat automatically \u2014 you decide what to show. To preview an asset inline, save it locally (use `--download` so it lands under `media/`) and reference its **local path** as a Markdown link with a **leading `./`**:\\n\\n```\\n[ferrari shot](./media/ferrari_01.png)     \u2190 image card\\n[the clip](./media/clip.mp4)               \u2190 video player\\n[voiceover](./media/vo.mp3)                \u2190 audio player\\n```\\n\\nPut the Markdown link **in your message text** \u2014 video and audio embed exactly like images. Do **not** use `SendUserFile` (or other file-send tools) to display media: that renders inside a collapsible tool card and gets buried in the tool list. The Markdown link in your prose is what produces the inline card.\\n\\nUse the path you saved to: a **workspace-relative** path (`./media/clip.mp4`, or `./<any-folder>/clip.mp4` \u2014 any folder in the workspace works), or the **absolute** path for a file outside the workspace (e.g. `/Users/you/Desktop/clip.mp4` or another workspace\'s path). Both render. Show the finished results worth showing (and only those \u2014 not every intermediate job). A bare CDN URL or a JSON dump of output URLs does **not** render; the local-path Markdown link is what produces an inline card.\\n\\n## Native-first VideoDraft ADE pipeline (idea \u2192 MP4)\\n\\nWhen `videodraft_editor` is present:\\n\\n1. Generate or source the script, storyboard, shot images, clips, voiceovers, music, and other assets through the cloud CLI/MCP as needed.\\n2. Call native `project_manage` (`project`, action `open` or `create`) to open or create the `.vdproject`.\\n3. Call native `library_manage` `import`, wait for imports to become ready, then assemble and refine the timeline with `edit_apply` recipes.\\n4. Call native `delivery_manage` `submit` and use its `jobs` operation for progress and results.\\n\\nDo not run the hosted production or export steps in this path unless the user explicitly asks for a web production.\\n\\n## Hosted fallback pipeline (idea \u2192 MP4)\\n\\nUse this only when there is NO native editor at all, or the user explicitly requests the hosted web\\nworkflow. The native surface is not only the injected `videodraft_editor` MCP: a `videodraft-editor`\\nexecutable on PATH is the same editor reached through its terminal bridge, and\\n[references/editor.md](references/editor.md) covers driving it that way. Treating a missing MCP as\\n\\"no editor\\" sends sessions that have the binary into hosted production for no reason.\\n\\n```bash\\nvideodraft create \\"<idea>\\" --ar 9:16            # project: script \u2192 visual assets \u2192 storyboard\\nvideodraft shots <project_id> --grid --estimate # cost preview, confirm with user\\nvideodraft shots <project_id> --grid            # batch shot images (waits, writes onto shot cards)\\nvideodraft produce <project_id>                 # voiceovers + captions + production timeline\\nvideodraft export <project_id> --download final.mp4\\n```\\n\\nOptional between produce and export: per-shot motion clips (`videodraft generate video ... --project <id>` then place it with `videodraft attach <project> --scene N --shot M --media <url|file> --type video --duration <s>`), music (`videodraft generate music \\"...\\" --attach <project_id>`), and standalone audio assets (`generate audio`, `generate sound-effect`, `generate dialogue`, `generate voice-changer`, `generate dub`). Details, per-step tools and editing rules: [references/pipeline.md](references/pipeline.md).\\n\\n## Avatar and talking-head videos (both surfaces)\\n\\nAvatar generation is cloud-only \u2014 the native editor has no avatar or lipsync tools \u2014 so this applies whether or not `videodraft_editor` is present. Generate the avatar in the cloud; in VideoDraft ADE, import the rendered clip and cut it on the native timeline like any other footage.\\n\\nAvatar/talking-head videos use dedicated commands. For a reusable managed avatar, obtain or generate a clear portrait \u2192 `videodraft avatar script` when needed \u2192 `videodraft avatar create` \u2192 `videodraft avatar render --resolution 720p`. For a one-off portrait, use `videodraft avatar fabric <portrait> --text \\"...\\"` or `--audio <file>`, or `videodraft avatar h3-lipsync <portrait> --audio <file>` for a short high-resolution clip from existing audio. For an existing video plus replacement audio, use `videodraft avatar lipsync <video> --audio <file>`. Managed script/creation is bundled/free; direct Fabric, H3 Max Lip Sync, Sync, the managed Fabric render, and optional portrait generation/upscaling are paid. Confirm expensive steps first.\\n\\n## Working with hosted project data\\n\\nA hosted project is one JSON blob (script, storyboard scenes, shot cards, visual assets, production timeline). To inspect: `videodraft projects get <id>`. To edit: fetch `--raw`, modify, then `videodraft call update_project` \u2014 objects deep-merge, **arrays replace wholesale** (send the complete `storyboard.scenes` array to change one scene). Snapshot first with `videodraft checkpoint create <id>` before risky edits. Schema reference: `videodraft call get_project_schema`. This does not replace native editor tools when `videodraft_editor` is available for the production itself.\\n\\n## More\\n\\n- [references/pipeline.md](references/pipeline.md) \u2014 hosted fallback data model and production workflow\\n- [references/editor.md](references/editor.md) \u2014 native headless editor routing, project selection, import, timeline edits, verification, and export\\n- [references/models.md](references/models.md) \u2014 choosing image/video models, pricing patterns, voices and styles\\n- [references/examples.md](references/examples.md) \u2014 recipes: batch product videos from a CSV, talking-head from a script, changelog video in CI\\n","references/3d.md":"# Standalone 3D assets through MCP and CLI\\n\\nUse this lane for downloadable meshes, textured 3D models, and humanoid rigging. These are independent of AI Studio sessions and do not require a storyboard or web viewer. Never create a project just to generate a mesh. Native editor media import does not establish support for GLB/FBX assets; use external 3D software unless the live editor schema explicitly supports them.\\n\\n## Discover and quote\\n\\n```bash\\nvideodraft models 3d --json\\nvideodraft generate 3d \\"a worn brass telescope\\" --model meshy-7 --estimate\\nvideodraft generate 3d --model tripo-h3.1 --ref ./reference.png --options @options.json --estimate\\nvideodraft rig 3d --estimate\\n```\\n\\nMCP tools: `get_3d_models`, `estimate_3d`, `generate_3d`, `rig_3d`, `check_generation_status`, `list_3d_assets`, `get_3d_asset`, `create_3d_upload`, and `finalize_3d_upload`.\\n\\nThe generator catalog is deliberately limited to `meshy-7` and `tripo-h3.1`. Both expose text/image/multi-image modes; use the live schemas for option availability, view order, limits, topology, texture/PBR, and pose controls. Do not invent common provider option names. Server defaults prioritize quality. Rigging is a separate Meshy operation for compatible textured humanoid GLBs; it is not an arbitrary creature or facial rig service.\\n\\nEvery option is accessible through `--options` JSON (`@path.json` supported), plus repeatable `--option key=value` overrides. Values parse as JSON when valid. Options and explicit input mode affect pricing, so obtain a fresh quote for the exact recipe. Estimates perform no file upload or provider generation. VideoDraft bills whole credits at 100 credits per dollar using the server\'s rounding rules. BYOK costs zero VideoDraft credits and runs on the connected user Fal key. Do not infer the user\'s Fal-account charges from a zero VideoDraft-credit quote.\\n\\n## Generate and retrieve\\n\\n```bash\\nvideodraft generate 3d \\"a worn brass telescope\\" --model meshy-7 --download --json\\nvideodraft generate 3d --model meshy-7 --ref ./hero.png --no-wait --json\\nvideodraft generate 3d --model tripo-h3.1 --input-mode multi_image --ref ./front.png --ref ./left.png --ref ./back.png --ref ./right.png --no-wait --json\\nvideodraft status JOB_ID --json\\nvideodraft wait JOB_ID --download --json\\nvideodraft assets 3d list --status completed --json\\nvideodraft assets 3d get ASSET_ID --download ./media/3d --json\\nvideodraft rig 3d --asset ASSET_ID --download --json\\nvideodraft rig 3d ./textured-humanoid.glb --download --json\\n```\\n\\nLocal image references upload automatically. Local rigging inputs must be self-contained `.glb` files and upload via the dedicated 3D route. Input mode is inferred from reference count unless `--input-mode text|image|multi_image` is supplied. A text prompt requires no images; image mode requires exactly one and no geometry prompt. Meshy multi-image accepts 1-4 views, and Tripo accepts 2-4 in front, left, back, right order. Use Meshy\'s `texture_prompt` option when texturing guidance is needed with image inputs. Do not mix unrelated images as if they were views of the same object.\\n\\nGeneration and rigging wait by default. `--no-wait` returns a persisted job that continues server-side. For many jobs use one `wait ID1 ID2 ... --download`; do not run parallel polling processes. Recover timeout with the same job ID, not another paid generation.\\n\\nSubmission returns a `request_id` UUID. A same-request retry must use `--request-id UUID` and the original arguments. The CLI journals resolved uploads in its private config directory so retries reuse the same remote files. Changed inputs under that UUID are rejected. Submission errors include the UUID in JSON `details.request_id` where available. Never retry a failed request with a new UUID until the prior job status is known.\\n\\n## Complete artifact packages\\n\\n`--download` defaults to `media/3d/<asset_id>/`. A user directory is respected and receives a per-asset folder. `{job_id}` and `{asset_id}` directory templates are accepted. Do not pass a `.glb` filename or a media `{index}.{ext}` template: a 3D result can contain multiple formats and texture/material dependencies.\\n\\nDownloads preserve every returned artifact. The manifest records provider URLs, source filenames, local paths, role, content type, and actual downloaded sizes. glTF/OBJ/MTL references are rewritten to saved dependency paths; binary GLB/FBX and provider ZIPs are retained as returned. Supplied dependency aliases become local copies at the paths needed by original FBX files. Unsafe or colliding aliases produce warnings. Existing packages are never overwritten. A successful package has `manifest.json`; read its `complete` field and `warnings`, plus CLI `package_warnings`. Do not claim a package with unresolved dependencies is ready for offline use.\\n\\nMachine results use `type: \\"model3d\\"` with `output_files` for files and `output_media` only for ordinary preview media. Texture maps and models are not image/video gallery entries. Show a supplied preview via a local image Markdown link and deliver the original mesh/package files. Do not imply an interactive 3D viewer exists in AI Studio or VideoDraft ADE.\\n","references/editor.md":"# Native VideoDraft Editor reference\\n\\nUse this reference when the user wants to assemble, cut, caption, mix, lay out, inspect, or export a local VideoDraft Editor project. The native editor is deterministic and local. Cloud generation remains in the `videodraft` CLI or hosted MCP.\\n\\n## VideoDraft ADE preference rule\\n\\nWhen `videodraft_editor` tools are exposed, treat the native editor as available and make it the default surface for production, timeline assembly, and final export. It is headless by design, so a hidden window or an untouched Open Editor button does not justify using hosted production instead.\\n\\nUse cloud tools for asset generation and optional script/storyboard work, then import the results. Do not call hosted `produce_project` / `videodraft produce` or `export_video` / `videodraft export` unless the user explicitly requests an editable web production or the native editor tools are unavailable. If a native tool call fails after the editor was available, report or recover that native failure rather than silently switching surfaces.\\n\\n## Choose the correct surface\\n\\n- `videodraft` and the hosted VideoDraft MCP generate assets and can manage hosted web projects. They use the user\'s VideoDraft account and credits. In VideoDraft ADE, use them mainly as the source of generated media and optional storyboards for the native production.\\n- `videodraft_editor` edits local `.vdproject` packages. It has no generation, account, model, or credit tools.\\n- Inside VideoDraft ADE on a supported Mac, the editor MCP is injected automatically for Claude, Codex, OpenCode and Grok in both Code and VideoDraft modes. It starts headlessly before the chat opens. The user does not need to click Open Editor, and closing or hiding the editor window does not stop headless editing.\\n- Outside that environment, use the editor only if `videodraft_editor` MCP tools are already exposed or the `videodraft-editor` executable is on PATH. Do not confuse the public `videodraft` cloud CLI with the separate native editor executable.\\n\\nPrefer the direct MCP tools when they are available. The terminal bridge is useful for scripts, diagnostics, or an agent session where the MCP was not injected.\\n\\n## Which editor tools you have\\n\\nCurrent editors expose eight workflow tools: `project_manage`, `edit_snapshot`, `edit_apply`, `edit_undo`, `library_manage`, `inspect`, `speech_apply`, and `delivery_manage`. Use them whenever `edit_apply` is available. Everything below describes them.\\n\\nEarlier editors expose a different set of tools. If `edit_apply` is not in your catalog, follow the live tool descriptions; the working rules below still apply.\\n\\nThe live tool descriptions and schemas are authoritative. When they differ from this reference, follow them.\\n\\nService tools (`project_manage`, `library_manage`, `inspect`, `speech_apply`, `delivery_manage`) take `operation` and `parameters`, plus an optional `context` (see [Keep a reliable editing model](#keep-a-reliable-editing-model)):\\n\\n```json\\n{\\"operation\\": \\"import\\", \\"parameters\\": {\\"source\\": {\\"path\\": \\"/Users/me/clips\\"}}}\\n```\\n\\n### Parameters at a glance\\n\\nEach operation\'s schema has the full list. These are the fields that matter most, and the ones most often confused:\\n\\n| Tool and operation | Key `parameters` |\\n| --- | --- |\\n| `project_manage` `project` | `action` (`list`, `open`, `create`, `close`); `id`, `name` or `path` to open; `name`, `fps`, `aspectRatio`, `quality` to create |\\n| `edit_snapshot` (no `parameters`) | `includeLibrary`, a `startFrame`/`endFrame` window, `offset`/`limit` paging, `context` for later pages |\\n| `edit_apply` (no `parameters`) | `actions`; optional `context`, `requestId`, `previewOnly` |\\n| `library_manage` `import` | `source` with one of `path`, `url`, `bytes` + `mimeType`, or `matte`; optional `name`, `folder`. A `.srt` or `.vtt` file becomes captions |\\n| `library_manage` `list` | `ids` to poll imports, `pending`, `folder` |\\n| `inspect` `timeline` | a `startFrame`/`endFrame` window; there is no clip filter |\\n| `inspect` `frame` | `startFrame` for one frame; add `endFrame` and `maxFrames` to sample a range |\\n| `inspect` `media` | `mediaRef` (a library asset, not a file path), `startSeconds`/`endSeconds` in source seconds, `wordTimestamps`, `overview` |\\n| `inspect` `transcript` | a `startFrame`/`endFrame` window, `granularity` (`words` or `segments`), `clipId` |\\n| `inspect` `color` | `clipId` with `atFrame`, or `mediaRef`; optional `reference` |\\n| `speech_apply` `words` | `words`: transcript word indices, each one index or a `[first, last]` pair; or `matches`: exact words to remove everywhere; `pacing` |\\n| `speech_apply` `silence` | none |\\n| `speech_apply` `captions` | caption `style`, `position` and look fields; it finds the speech itself. `style` `plain` (sentences without a preset) takes `positionY` or `transform.centerY`, not `position` or `punctuation` |\\n| `delivery_manage` `submit` | `mode`, `codec`, `resolution`, `outputPath` (its folder must already exist); `captionGroupId` and `wordTiming` for `srt` and `vtt`; `check: false` skips a video\'s export check |\\n| `delivery_manage` `jobs` | `action` `list` (every job with its progress, warnings, output path and check findings; with a `jobId`, that job with all its findings), `cancel` with a `jobId`, or `dismiss` with a `jobId` and optional `findingIds` |\\n\\n`previewOnly` exists only on `edit_apply`. Service operations apply immediately.\\n\\n### `edit_apply` actions at a glance\\n\\nEvery action puts its fields beside `kind`, for example `{\\"kind\\": \\"adjust\\", \\"clipId\\": \\"c1\\", \\"speed\\": 2}`. `remove`, `adjust`, `replace`, `transition`, `mask`, `text`, `grade` and `effects` take `clipId` for one clip or `clipIds` for several; `animate`, `extract`, and the rows of `move` and `split` take a single `clipId`. Advanced actions cannot take `as`, but their clip ids accept `@name`. The one exception is `transition`, whose own `kind` field names the style, so its fields go inside `parameters`: `{\\"kind\\": \\"transition\\", \\"parameters\\": {\\"clipId\\": \\"c2\\", \\"kind\\": \\"dipToBlack\\"}}`. These `actions` place a clip, warm it and add a vignette:\\n\\n```json\\n[{\\"kind\\": \\"place\\", \\"assetId\\": \\"\u2026\\", \\"atFrame\\": 0, \\"as\\": \\"shot\\"},\\n {\\"kind\\": \\"grade\\", \\"clipId\\": \\"@shot\\", \\"adjustments\\": {\\"temperature\\": 7500}},\\n {\\"kind\\": \\"effects\\", \\"clipId\\": \\"@shot\\", \\"effects\\": [{\\"type\\": \\"finish.vignette\\", \\"params\\": {\\"strength\\": 35}}]}]\\n```\\n\\n| Advanced `kind` | Key fields |\\n| --- | --- |\\n| `place_batch` | `entries: [{mediaRef, startFrame, endFrame or source, trackIndex}]`, not the concise `assetId`, `atFrame`, `durationFrames`; leave `trackIndex` off every entry for a new track |\\n| `insert_batch` | `trackIndex`, `atFrame`, `entries: [{mediaRef, durationFrames or source}]`; later clips move right |\\n| `move` | `moves: [{clipId, toFrame, toTrack}]` |\\n| `remove` | `clipId` or `clipIds`; leaves a gap |\\n| `split` | `splits: [{clipId, atFrame}]`, or `trackIndex` with `frames` |\\n| `extract` | `trackIndex` with `ranges: [[start, end]]` in frames, or `clipId` with `ranges` and `units` (`frames`, or source `seconds`); closes the gap |\\n| `adjust` | `clipId` or `clipIds` plus any of `durationFrames`, `trimStartFrame`, `trimEndFrame`, `speed`, `speedCurve` (`{preset}`, or `{points: [{t, rate}]}` with `t` from 0 to 1 along the source), `preservesPitch`, `volume`, `opacity`, `transform` (`centerX`, `centerY`, `width`, `height`, `flipHorizontal`, `flipVertical`), `blendMode` |\\n| `animate` | `clipId`, `property` (`volume`, `opacity`, `rotation`, `position`, `scale`, `crop`), `keyframes: [[frame, ...values]]` with frames counted from the clip\'s start; `position` is the top-left corner |\\n| `arrange` | `layout`, `slots: [{slot, clipIds or mediaRef, anchor}]`, `fit` (`fill` or `fit`); `mediaRef` slots also need `endFrame` |\\n| `transition` (fields inside `parameters`) | `clipId` or `clipIds` (the clip after each cut), `kind` (`crossDissolve`, `dipToBlack`, `dipToWhite`, `blurDissolve`, `push`, `linearWipe`, `whipPan`, `crossZoom`, or `none` to remove), `durationFrames`, `params` (`direction` 0 to 3 for left, right, up, down; `feather`; `blur`; `intensity`) |\\n| `mask` | `clipId` or `clipIds`, `shape` (`rectangle`, `ellipse`, `none`), `centerX`, `centerY`, `width`, `height` (0 to 1 of the clip\'s own frame), `feather`, `strength`, `inverted` |\\n| `replace` | `clipId` or `clipIds`, `mediaRef` (a library asset of the same kind), `trim` (`keep`, the default, or `reset`), `linkedAudio` (`follow`, the default, or `keep`) |\\n| `tracks` | `reorder: [{trackId, to}]`, `set: [{trackId, muted, hidden, syncLocked}]`, `remove: [{trackId}]`; there is no add, since placing without a track makes one |\\n| `titles` | `entries: [{startFrame, endFrame, content}]`, optionally with `trackIndex` (on every entry or none), `style`, `animation`, `transform` and typography (`fontName`, `fontSize`, `color`) |\\n| `text` | `clipId`, `clipIds` or `captionGroupId`, with `content`, `style`, `position`, `animation` or typography |\\n| `grade` | `clipId` or `clipIds`, `adjustments`, `wheels`, `curves`, `hueCurves`, `lut`, `reset` |\\n| `effects` | `clipId` or `clipIds`, `effects: [{type, params, enabled}]`, `remove: [type]` |\\n\\n- `grade`: `adjustments` holds `exposure` (EV, -4 to 4), `temperature` (kelvin, 1800 to 15000, 6500 neutral, higher is warmer), `tint` (-150 magenta to 150 green); `contrast`, `highlights`, `shadows`, `whites`, `blacks`, `vibrance` and `saturation` are signed percents (-100 to 100, 0 neutral), not factors like 1.2. `wheels`: `shadows`, `midtones`, `highlights`, each `{hue, strength, brightness}`. `curves`: `luma`, `red`, `green`, `blue` as `[x, y]` points from 0 to 1. `hueCurves`: `targets: [{hue, rotate, saturation, lightness}]`. `lut`: `{path, mix}`, with the `storedPath` from `prepare_look`. Out-of-range values are refused.\\n- Effect `type` ids and their knobs, which go inside `params` and run 0 to 100 unless noted. Defaults leave the picture unchanged, so send the knob you want to see:\\n  - `finish.vignette`: `strength` and `curvature` (-100 to 100; positive `strength` darkens the edges), `size`, `falloff`\\n  - `finish.grain`: `strength`, `grainSize` (0.5 to 6 px); `finish.glow`: `strength`, `haloRadius` (px), `cutoff`, `halation`\\n  - `defocus.gaussian`: `blurRadius` (px); `defocus.motion`: `streakLength` (px), `streakAngle` (-180 to 180 degrees)\\n  - `texture.clarity`: `localContrast`, `hazeRemoval` (-100 to 100); `texture.sharpen`: `strength` (0 to 200); `texture.denoise`: `strength`\\n  - `matte.chroma`: `screenHue` (0 to 360 degrees, 120 is green), `range`, `edgeSoftness`, `spillSuppression`\\n- `arrange` layouts and their slots (fill every slot): `fullscreen` (`stage`); `split` (`left`, `right`); `stack` (`top`, `bottom`); `corner_top_left`, `corner_top_right`, `corner_bottom_left`, `corner_bottom_right` (`stage`, `corner`); `quad` (`top_left`, `top_right`, `bottom_left`, `bottom_right`); `side_panel` (`stage`, `panel`); `thirds` (`left`, `middle`, `right`). The layout picks the corner; `anchor` only biases the crop.\\n- `trackIndex` and `toTrack` are an existing track\'s `order` from `edit_snapshot` (0 draws on top), counted at that point in the recipe: a track an earlier action adds shifts them. `tracks` takes `trackId` handles instead.\\n\\n## Start with the intended project\\n\\nAn MCP session can begin without a project selected. Project selection belongs to the session, not to whichever editor window happens to be frontmost.\\n\\n1. If the user named an existing project but its identity is unclear, call `project_manage` with `operation: \\"project\\"` and `parameters.action: \\"list\\"`.\\n2. Open the exact project with `action: \\"open\\"` and the returned `id`, an unambiguous `name`, or the `.vdproject` `path`.\\n3. Create only when the user wants a new local edit. `action: \\"create\\"` accepts optional `name`, `fps`, `aspectRatio`, and `quality`.\\n4. Treat `isActive` as this session\'s target and `isVisible` as the project shown in the UI. Headless editing only needs the session target.\\n5. Use `action: \\"close\\"` only when closing is part of the task. It saves first and never deletes the project. Afterwards other calls answer `no_project` until you open or create a project again.\\n\\nOther `project_manage` operations: `create_timeline` and `select_timeline` for additional timelines, and `configure` for project settings (a frame-rate change applies to every timeline).\\n\\nDo not substitute a hosted project ID for a native project. A hosted project can supply scripts, storyboards, and generated media, but the native edit is a separate `.vdproject` package.\\n\\n## Keep a reliable editing model\\n\\n- Opening or creating a project, and creating or selecting a timeline, returns `data.snapshot` (the `edit_snapshot` view with the library: format, tracks, clips and assets) and a `context`, so you can edit right away. Call `edit_snapshot` only after an out-of-band user edit, to page a long timeline with `offset` and `limit`, or for handles you lack.\\n- `context` (`epoch`, `timelineId`, `revision`) is optional on every write except `edit_undo` and `project_manage` `project`, which take none. Without it, a write applies to the current state. With it, the editor refuses the write if the project changed since that context, which is what you want when a person may be editing at the same time. Every reply returns a fresh `context`. After `context_expired` (a reopen or restart), take a new snapshot.\\n- Timeline positions and durations are frames at `format.fps`. `sourceSeconds` values are seconds in the source file. Pass values as returned; do not multiply or divide by fps yourself.\\n- IDs are short handles. Pass them back exactly as returned; do not derive them from UUIDs. Tracks keep stable handles; indexes can change.\\n- When the user says \\"this clip\\", \\"these captions\\", or \\"here\\", take a fresh `edit_snapshot` (a one-frame window is enough). Its `selection` names what they selected in the project\'s window, in the snapshot\'s handles: `clipIds`, `captionGroupIds`, a `gap`, the marked `range`, and library `mediaIds`; no `selection` means nothing is selected. `currentFrame` is the playhead. `visible: false` means the user is not looking at this project.\\n- Send writes serially. Parallel writes against one project race each other\'s context.\\n- A refused call answers `status: \\"rejected\\"`: nothing changed, so fix what the message names and send it again. A service write that answers `failed` may have applied before a save or connection failed; inspect before repeating it.\\n- Use `inspect` for detail and verification: `timeline` for exact clip and track properties, `frame` for rendered frames of the composited result, `media` before describing source content, `color` for scopes, and `transcript` to locate spoken words.\\n- Volume values, including volume keyframes, are linear from `0` to `1`.\\n\\n## Edit with recipes\\n\\n`edit_apply` takes an ordered list of `actions`, plus an optional `context` and `requestId`. The editor validates the whole recipe before changing anything, then applies it as one undo step. If any action fails, nothing changes and the error names the action. An applied reply lists the resulting `clips` (position, length, source window, text); use it to confirm the edit instead of re-reading.\\n\\n- Concise actions: `place` (an `assetId` at `atFrame`, optionally on a `trackId`, with `durationFrames` or `sourceSeconds`, `mode` `overwrite` or `insert`), `trim` (a `clipId` to a `sourceSeconds` window), and `title` (`text` at `atFrame` for `durationFrames`, optional `look` and `motion`). Name an action with `as` and address its clip in later actions as `@name`.\\n- Advanced actions put their fields beside `kind` too: `place_batch`, `insert_batch`, `move`, `remove`, `split`, `extract`, `adjust`, `animate`, `arrange`, `transition` (fields inside `parameters`), `mask`, `replace`, `tracks`, `titles`, `text`, `grade`, and `effects`. Their field help lists every supported effect, grading control, mask, layout, speed curve, and caption control.\\n- Use `arrange` for split screens, picture-in-picture, grids, and canvas placement, and `tracks` to fix stacking. Do not synthesize layouts from generic transforms or keyframes.\\n- Use `replace` to swap a clip\'s media and keep its timing, effects, keyframes, and links, for example a re-render of the same shot. `trim: \\"keep\\"` holds the clip\'s source offsets; `trim: \\"reset\\"` plays the new media from its first frame and keeps linked audio in sync.\\n- Put every edit a request needs into one recipe: placing, trimming, titling, grading and effects together are one call and one undo step. Use `previewOnly: true` to validate a large or risky recipe without editing.\\n- Send a `requestId` when a retry must not edit twice: repeating the identical request with the same `requestId` returns the original receipt, even after a dropped connection. Without one, a repeated request applies again. Use a new `requestId` for a different edit.\\n- `applied_unsaved` means the edit applied but saving failed. If you sent your own `requestId`, repeat the identical request to retry the save, not the edit. Without one, do not resend: a repeat would apply the edit again.\\n- `edit_undo` reverses this connection\'s latest edit while it is still the top undo step. It never undoes the user\'s own edits. Take a new snapshot afterward.\\n\\nEdits are undoable. Do not ask for confirmation before each ordinary edit. Ask one focused question only when the user\'s creative direction is materially ambiguous.\\n\\n## Bring generated or local media into the editor\\n\\nFor b-roll and establishing shots, search free stock first (`videodraft stock search \\"<query>\\"`), import the pick with `videodraft stock import <ref>`, and feed the returned CDN URL to `library_manage` `import` as `source.url`. It costs no credits.\\n\\nOtherwise use cloud generation for new assets, save or download the outputs, then call `library_manage` with `operation: \\"import\\"`:\\n\\n- `source.path`: absolute local file or directory. A directory imports recursively and preserves its folder structure.\\n- `source.url`: HTTPS asset URL. Set `mimeType` when a signed URL has no usable extension.\\n- `source.bytes`: small base64 media with a required `mimeType`.\\n- `source.matte`: generated solid-color image.\\n\\nReadiness differs by source, and so does the poll that detects it:\\n\\n- **URL and single-file path** imports return `status: \\"downloading\\"` with one `mediaRef`. Poll `library_manage` `list` with `parameters.ids: [mediaRef]` until `generationStatus` is absent.\\n- **Directory** imports also return `status: \\"downloading\\"` with one placeholder `mediaRef` for the batch. Poll it the same way; the folder\'s assets appear when `generationStatus` clears. (`pending: true` remains a fallback that lists every unresolved import.)\\n- **Inline bytes and matte** imports finish inline and come back `status: \\"ready\\"`; no polling is needed.\\n\\nAn import\'s `mediaRef` is the `assetId` that recipe actions take. Never place a pending asset on the timeline. `generationStatus` is the signal: `preparing`, `generating`, `downloading`, and `rendering` mean keep polling, absent means usable, and **`failed` is terminal**. Report it or retry the import explicitly; never poll on. Do not treat \\"not downloading\\" as ready.\\n\\nA `.srt` or `.vtt` caption file (by `path`, `url`, or `bytes` with `mimeType` `application/x-subrip`, `text/srt`, or `text/vtt`) is not added to the library. Its captions go onto a new caption track at the times the file gives, as one undo step, and the reply names the new `captionGroupId` to restyle with a `text` action.\\n\\nFor a batch of local outputs, download them into one workspace directory and import that directory once when practical. This is safer and faster than racing many import calls.\\n\\nTo apply a LUT, first store it with `library_manage` `prepare_look` (`parameters.path` to a `.cube` file), then use the returned `storedPath` in a `grade` action.\\n\\n## Speech edits\\n\\n`speech_apply` runs speech work as separate operations, not recipe actions: `words` removes transcript words, `silence` trims dead air, and `captions` generates styled captions. Read a fresh transcript with `inspect` `transcript` after any speech edit, because word positions change.\\n\\n## Service operations and timeouts\\n\\n`project_manage`, `library_manage`, `speech_apply`, and `delivery_manage` writes have no retry receipts. After a timeout, inspect the outcome (a snapshot, a library `list`, or delivery `jobs`) before repeating a write. A failed service write may have applied an edit before saving failed, so read its `data` and the current state.\\n\\n## Edit and verify\\n\\nA dependable sequence:\\n\\n1. `project_manage` to select or create the local project; its reply carries the snapshot.\\n2. `inspect` `media` when content selection matters.\\n3. One `edit_apply` recipe with every clip, track, layout, text, audio, color, and effect change the request needs; `speech_apply` for word cuts, silence, and captions.\\n4. Check the reply\'s `clips`; use `inspect` `frame` only when visual composition or layer order matters.\\n5. `edit_undo` if the result is wrong and the next recipe would not cleanly correct it.\\n\\n## Export\\n\\nCall `delivery_manage` with `operation: \\"submit\\"`. Submission is not completion: it returns a job, destination, and `started` or `queued` status.\\n\\n- Use `mode: \\"video\\"` for H.264, H.265, or ProRes.\\n- Use `mode: \\"xml\\"` (XMEML) for Premiere Pro **and DaVinci Resolve**. Resolve reads XMEML natively. Use `fcpxml` only for Final Cut Pro; sending Resolve an FCPXML produces a package it cannot open cleanly.\\n- Use `mode: \\"videodraft\\"` for a self-contained project package.\\n- Use `mode: \\"srt\\"` or `mode: \\"vtt\\"` for a subtitle file of the captions: words and timing only, without styling. `captionGroupId` picks a caption group; `wordTiming: true` adds each word\'s start to a `vtt`.\\n- Omit `outputPath` unless the user named a destination; the default is `~/Downloads`. The editor does not create folders, so a named destination\'s folder must already exist.\\n- Use `operation: \\"jobs\\"` with `parameters.action` `list` to follow progress, warnings, and results. Cancel only when the user asks or the just-queued settings were wrong. Do not infer that an export is stuck from elapsed time alone.\\n- A finished video export is then checked in the background for black picture, gaps, sound that drops out or clips, and missing media. `list` shows each job\'s `findingCount` and its first three findings; `list` with that `jobId` returns every finding. Findings are warnings on a completed export: tell the user what was found and where, rather than treating the export as failed.\\n\\n## Terminal bridge\\n\\nVideoDraft desktop terminals expose `videodraft-editor`, which controls the same process and tools:\\n\\n```bash\\nvideodraft-editor status\\nvideodraft-editor list-tools\\nvideodraft-editor tool project_manage --json \'{\\"operation\\":\\"project\\",\\"parameters\\":{\\"action\\":\\"list\\"}}\'\\nvideodraft-editor tool edit_snapshot --project \\"/path/to/My Video.vdproject\\" --json \'{\\"includeLibrary\\":true}\'\\nvideodraft-editor show\\nvideodraft-editor hide\\n```\\n\\nEach `videodraft-editor` invocation is a separate connection, so a project opened by one call is NOT remembered by the next. Pass `--project <path>` on every `tool` call that operates on a project; without it, a follow-up call answers `no_project` (no project is open for this session) even though the open succeeded. For the same reason, `edit_undo` has nothing to undo from the terminal: it only reverses an edit made on its own connection.\\n\\nControl and tool commands auto-start a headless editor if none is running. `show` only reveals the already-running UI. Use `videodraft-editor tool <name> --json -` to read a JSON object from stdin when shell quoting would be fragile. Never read, copy, or expose the editor\'s rotating local authentication secret.\\n","references/examples.md":"# Recipes\\n\\nWorking patterns for common asks. All assume auth (`videodraft login` once, or `VIDEODRAFT_API_KEY` in the environment) and use `--json` for parsing.\\n\\nInside VideoDraft ADE, if a native editor is available, use these recipes for asset generation and\\noptional script/storyboard stages. Hand the results to the editor for production and export ONLY\\nwhen the deliverable the user asked for is a composed production. A standalone output \u2014 the batch\\nproduct clips in recipe 1, the upscale in recipe 7 \u2014 is finished when it is generated; importing it\\ninto a project and exporting a timeline builds an edit nobody asked for. Recipes below that call `videodraft produce` or `videodraft export` are hosted fallbacks only. Do not choose them over the available native editor unless the user explicitly asks for the hosted web workflow.\\n\\n## 1. Batch product videos from a CSV\\n\\nOne 9:16 product clip per row of `products.csv` (`name,image_url,tagline`):\\n\\n```bash\\n#!/usr/bin/env bash\\nset -euo pipefail\\nmkdir -p outputs\\n\\nwhile IFS=, read -r name image tagline; do\\n  job=$(videodraft generate video \\\\\\n    \\"Premium product shot of ${name}: ${tagline}. Slow orbit, studio lighting.\\" \\\\\\n    --model gemini-omni-1.1-flash --ar 9:16 --duration 6 \\\\\\n    --start-image \\"$image\\" \\\\\\n    --no-wait --json | jq -r .job_id)\\n  echo \\"$name,$job\\" >> outputs/jobs.csv\\ndone < <(tail -n +2 products.csv)\\n\\n# Collect ALL results with ONE process (batched polling \u2014 one request per tick)\\nvideodraft wait $(cut -d, -f2 outputs/jobs.csv) \\\\\\n  --download \\"outputs/{job_id}_{index}.{ext}\\" --json > outputs/results.json\\n# map job ids back to product names via outputs/jobs.csv\\n```\\n\\nSubmit-then-collect parallelizes server-side generation; the single multi-id `wait` keeps it to one local process and one batched poll request per tick no matter how many jobs. Gemini Omni 1.1 Flash is selected because these are six-second first-frame product clips. Estimate first: `videodraft costs gemini-omni-1.1-flash --type video --duration 6 --resolution 720p --audio` \xD7 rows, and confirm with the user.\\n\\nExtend an uploaded clip or conversationally edit an official Google interaction with Gemini Omni 1.1 Flash:\\n\\nEach extension appends 3-10 seconds at the end. Edit and extend accept EXACTLY ONE input video, so `--ref-video` cannot accompany `--source-video` or `--previous-interaction-id`; only `--ref` images can. New dialogue is allowed only when the source video is silent, so a chain of spoken beats must carry its speech in the first turn. A continuation is submitted as the prior turn\'s output, so 40 seconds total is reachable only by extending from a source of 30s or less, and a ladder dead-ends past 30s.\\n\\n```bash\\n# Uploaded-video extension. Reference IMAGES are fine here; reference videos are not.\\nvideodraft generate video --model gemini-omni-1.1-flash \\\\\\n  --source-video ./ending.mp4 --ref ./wardrobe.png \\\\\\n  --extend --duration 6 --resolution 1080p \\\\\\n  --download ./media/extended.mp4\\n\\n# Conversational edit from the interaction_id of an earlier generation. Add --extend to lengthen instead.\\nvideodraft generate video --model gemini-omni-1.1-flash \\\\\\n  --previous-interaction-id \\"$INTERACTION_ID\\" \\\\\\n  --resolution 720p \\\\\\n  --download ./media/continued.mp4\\n```\\n\\nFal BYOK supports the currently callable Gemini Omni 1.1 generation and basic source-edit endpoints at zero VideoDraft credits. Its published callable v1.1 endpoints do not expose continuation, extension, or separate creative references on a source edit. Do not infer a Fal route or retry on paid Google while Fal BYOK is active.\\n\\n## 2. Hosted full marketing video from one idea (fallback)\\n\\n```bash\\nvideodraft create \\"30-second launch video for Solace, a sleep-tracking ring. Calm, premium, dark palette.\\" \\\\\\n  --ar 9:16 --style cinematic --json > project.json\\nPROJECT=$(jq -r .project_id project.json)\\n\\nvideodraft shots \\"$PROJECT\\" --grid --estimate          # show the user the cost; get a go-ahead\\nvideodraft shots \\"$PROJECT\\" --grid\\nvideodraft produce \\"$PROJECT\\"\\nvideodraft generate music \\"minimal ambient, warm pads, 60 BPM\\" --attach \\"$PROJECT\\"\\nvideodraft generate audio \\"Extend @Audio1 into a 20-second transition\\" --ref-audio ./intro.wav --format wav --download ./transition.wav\\nvideodraft export \\"$PROJECT\\" --download solace-launch.mp4\\n```\\n\\nUse this complete hosted path only when the user requested a web project or the native editor is unavailable. Otherwise stop after the storyboard/assets, import them into the native `.vdproject`, and export with `delivery_manage`. The hosted project stays editable at the URL in `project.json` (`.urls`).\\n\\n## 3. Talking-head (avatar) video\\n\\nWhen the user has no portrait, generate a clear front-facing avatar image first. Skip this step when they supplied one or an existing character should be reused.\\n\\n```bash\\nvideodraft generate image \\\\\\n  \\"Front-facing head-and-shoulders portrait of a friendly coffee expert, direct eye contact, natural expression, clean studio background\\" \\\\\\n  --model nano-banana-2 --ar 9:16 --download ./media/avatar.png\\n\\nSCRIPT=$(videodraft avatar script \\"why our espresso subscription saves you money\\" --style ad-style --json | jq -r .script)\\nAVATAR=$(videodraft avatar create ./media/avatar.png --script \\"$SCRIPT\\" --voice elevenlabs-kPzsL2i3teMYv0FxEYQ6 --ar 9:16 --json | jq -r .avatar_video_id)\\nvideodraft avatar render \\"$AVATAR\\" --resolution 720p   # VEED Fabric paid step; confirm cost first (~20 credits/sec)\\n```\\n\\n`avatar script` and `avatar create` (including speech) are bundled/free. In this example only the optional portrait generation and Fabric render spend credits.\\n\\nIf the portrait is low resolution, enhance it before `avatar create`:\\n\\n```bash\\nvideodraft upscale image ./founder-small.jpg --scale 2x --download ./media/founder-upscaled.png\\n```\\n\\nFor a one-off portrait animation without creating a managed avatar record:\\n\\n```bash\\nvideodraft avatar fabric ./founder.jpg \\\\\\n  --text \\"Welcome to the weekly product update.\\" \\\\\\n  --voice-description \\"warm, confident American presenter\\" \\\\\\n  --resolution 720p --download ./media/presenter.mp4\\n```\\n\\nFor a short, sharp clip from speech or a song the user already has (5-14.8s of audio is used):\\n\\n```bash\\nvideodraft avatar h3-lipsync ./singer.png --audio ./chorus.mp3 \\\\\\n  --resolution 1080P --audio-duration 12 --estimate\\nvideodraft avatar h3-lipsync ./singer.png --audio ./chorus.mp3 \\\\\\n  --resolution 1080P --download ./media/singer-lipsync.mp4\\n```\\n\\nWhen the user already has both the video and replacement speech:\\n\\n```bash\\nvideodraft avatar lipsync ./presenter.mp4 \\\\\\n  --audio ./localized-voiceover.mp3 \\\\\\n  --sync-mode loop --download ./media/presenter-localized.mp4\\n```\\n\\nEdit an existing video with a dedicated edit model:\\n\\n```bash\\nvideodraft models video --category video_edit\\nvideodraft edit video ./product-demo.mp4 \\\\\\n  \\"Preserve the product but follow the reference camera rhythm\\" \\\\\\n  --model gemini-omni-1.1-flash --ref-video ./camera-rhythm.mp4 \\\\\\n  --ref-video-duration 2.5 --resolution 1080p \\\\\\n  --download ./media/product-demo-reframed.mp4\\n\\nvideodraft edit video ./product-demo.mp4 \\\\\\n  \\"Turn the room into a warm evening scene while preserving the product and camera motion\\" \\\\\\n  --model kling-o3-video-ref-edit --ref ./evening-style.jpg \\\\\\n  --preserve-audio --download ./media/product-demo-evening.mp4\\n```\\n\\nTransfer motion from a reference clip onto a character image:\\n\\n```bash\\nvideodraft edit motion ./character.png \\\\\\n  \\"Apply the dancer\'s movement to this character while preserving identity\\" \\\\\\n  --motion-video ./dance-reference.mp4 \\\\\\n  --model kling-v3-motion-control --quality pro \\\\\\n  --download ./media/character-dance.mp4\\n```\\n\\n## 4. Hosted changelog video in CI\\n\\nIn a GitHub Action with `VIDEODRAFT_API_KEY` set as a secret:\\n\\n```bash\\nNOTES=$(git log --oneline v1.2.0..HEAD | head -20)\\nvideodraft create \\"Weekly product update video. Energetic, 20 seconds. Changes: ${NOTES}\\" --ar 16:9 --json > p.json\\nPROJECT=$(jq -r .project_id p.json)\\nvideodraft shots \\"$PROJECT\\" && videodraft produce \\"$PROJECT\\"\\nvideodraft export \\"$PROJECT\\" --download changelog.mp4 --wait-timeout 30m\\n```\\n\\n## 5. Variations and picking a winner\\n\\n```bash\\nvideodraft generate image \\"logo concept: minimalist fox, geometric\\" --num 4 --download \\"./concepts/{job_id}_{index}.{ext}\\" --json\\n# Show all 4 to the user; regenerate the chosen one at higher res:\\nvideodraft generate image \\"<same prompt>\\" --model nano-banana-pro --resolution 4K\\n```\\n\\n## 6. Reaching tools without a curated command\\n\\n```bash\\nvideodraft tools list --json | jq -r \'.[].name\'\\nvideodraft tools schema attach_media_to_shot --json\\nvideodraft call attach_media_to_shot --args \'{\\"project_id\\":\\"...\\",\\"scene_index\\":0,\\"shot_index\\":1,\\"media_url\\":\\"https://...\\",\\"media_type\\":\\"video\\",\\"duration_seconds\\":6}\'\\n```\\n\\nAnything the hosted VideoDraft MCP exposes, including character studio, product studio, and hosted project data, is reachable this way even before it gets a curated command. Native `.vdproject` editing uses the separate `videodraft_editor` MCP described in SKILL.md.\\n\\n## 7. Enhance an existing asset without changing it\\n\\n```bash\\n# Light image cleanup, no enlargement\\nvideodraft upscale image ./poster.png --scale 1x --download ./media/poster-enhanced.png\\n\\n# General image and video enlargement\\nvideodraft upscale image ./frame.png --scale 2x --download ./media/frame-2x.png\\nvideodraft upscale video ./clip.mp4 --resolution 1080p --download ./media/clip-1080p.mp4\\n\\n# Rebuild detail in a tiny/blurry source (generative), or reimagine it (creative)\\nvideodraft upscale image ./tiny.jpg --scale 4x --mode generative --model \\"Wonder 3.5\\" --download ./media/tiny-4x.png\\nvideodraft upscale video ./ai-clip.mp4 --resolution 4k --mode generative --download ./media/ai-clip-4k.mp4\\n\\n# Smoother motion or slow motion (resolution unchanged)\\nvideodraft interpolate ./clip.mp4 --fps 60 --download ./media/clip-60fps.mp4\\nvideodraft interpolate ./clip.mp4 --model Chronos --slowdown 4 --download ./media/clip-slowmo.mp4\\n```\\n\\nUse these when the content is correct and only quality or resolution needs improvement. If the poster text, composition, subject, or motion is wrong, edit or regenerate instead.\\n","references/models.md":"# Choosing models (and predicting cost)\\n\\nAlways consult the live catalog instead of memorizing this page \u2014 models change weekly:\\n\\n```bash\\nvideodraft models image --json     # every image model + inputs (aspect ratios, resolutions, max refs)\\nvideodraft models video --json     # every video model + inputs + per-second pricing metadata\\nvideodraft models audio --json     # standalone audio/media models + pricing inputs\\nvideodraft models voices --json    # TTS voices\\nvideodraft models styles --json    # visual style presets\\n```\\n\\n## Task-based model selection\\n\\nFollow this order every time:\\n\\n1. The user named a model: use it, never substitute.\\n2. Otherwise pick a **Tier 1** model from the task\'s inputs, duration, audio, quality, speed, and cost, and pass it explicitly instead of relying on a blind platform fallback.\\n3. Use a **Tier 2** model only when no Tier 1 model supports the request, and say why. Never pick Tier 2 on your own for price, speed, novelty or variety.\\n\\nTier 1 is the rows marked **T1** below. Every other catalog model is Tier 2 and stays available by name. The catalogs carry this themselves: every `videodraft models image|video|audio --json` entry has `tier` (1 or 2) plus `recommended` / `recommended_for`, and the top-level `recommended` array is Tier 1, best first. Trust the catalog over this page when they disagree.\\n\\n### Images\\n\\n| Need                                                                                       | Choose                   | Why                                                               |\\n| ------------------------------------------------------------------------------------------ | ------------------------ | ----------------------------------------------------------------- |\\n| T1: Most generation, editing, character consistency, or reference work                     | `nano-banana-2`          | Best general default; 1K/2K/4K and up to 14 reference images      |\\n| T1: Highest-quality complex generation or reasoning                                        | `nano-banana-pro`        | Premium Nano Banana quality and reasoning                         |\\n| T1: Fast, inexpensive drafts and iteration                                                 | `nano-banana-2-lite`     | Fastest/cheapest Nano Banana option; 1K only, up to 14 references |\\n| T1: Posters, title cards, signs, logos, or any image with important readable text          | `gpt-image-2.5-flare`    | Fast OpenAI option; 16 references, 1K/2K/4K and PNG output        |\\n| T1: Complex multi-image composition, precise editing, or a strong alternate interpretation | `gpt-image-2.5-sunburst` | More fidelity/detail; 16 references, quality through max          |\\n| T1: Vector / SVG output (logos, icons, illustrations that must scale)                      | `recraft-v4`             | Recraft V4.1 text-to-vector; SVG only, no reference images        |\\n| T2: By name, or an explicitly requested xAI look                                           | `grok-imagine`           | 2 cr flat (3 with a reference); 1 reference image                 |\\n| T2: xAI at 2K or with a quality tier, up to 3 edit references                              | `grok-imagine-2.0`       | 1K 4 (low) / 6 (medium), 2K 6 / 8, +1 cr per reference image      |\\n\\nGPT Image 2.5 has two IDs: `gpt-image-2.5-flare` replaces the former GPT Image 2 recommendation; `gpt-image-2.5-sunburst` is the precision/detail alternative. Other model recommendations are unchanged. Explicit `gpt-image-2` selections continue to use the previous model.\\n\\nUse the same basic image controls as GPT Image 2: `--ref`, `--ar`, `--resolution 1K|2K|4K`, `--quality`, and `--num 1..4`. GPT Image 2.5 quality supports auto/low/medium/high/xhigh/max. Auto is priced at Max. Generation runs directly on OpenAI, or exclusively on the user\'s Fal key when active.\\n\\n```bash\\nvideodraft generate image \'A blue glass bird\' --model gpt-image-2.5-flare --ar 1:1 --resolution 2K --quality high --estimate\\nvideodraft generate image \'A blue glass bird\' --model gpt-image-2.5-flare --ar 1:1 --resolution 2K --quality high --num 2\\n```\\n\\n`videodraft shots` forwards resolution and quality for both normal and grid generation. Estimates use the project\'s model and aspect when omitted; grid canvas costs may differ from ordinary shot costs. Use `videodraft costs --model <id> --ar <ratio> --resolution <tier> --quality <tier>` for a specific per-image quote.\\n\\n### Videos\\n\\n| Need                                                                                                           | Choose                   | Important limits                                                                                                                                                                                                                                               |\\n| -------------------------------------------------------------------------------------------------------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\\n| T1: Most generation, first/last-frame, mixed-reference, source-edit, or extension requests                     | `gemini-omni-1.1-flash`  | 3-10s output; 360p/720p/1080p/4K at 3/10/15/30 cr/s; audio always; up to 10 image inputs, and 3 reference videos <=3s on generate only; edit source <=10s; continuation or 3-10s extension of a 1-30s source, 40s total reachable only by extending from <=30s |\\n| T2: Grok 1.5 text, first-frame, or 1-7 image-reference clips with native audio and optional 1080p              | `grok-imagine-video-1.5` | 1-15s; 480p/720p/1080p for text/first-frame; references are 480p/720p only; no last frame                                                                                                                                                                      |\\n| T2: Document or webpage reference generation; by name otherwise                                                | `wan-3.0`                | 2-30s or auto; 480p/720p/1080p at 7/14/28 cr/s; 10 image, 5 video, 5 audio refs, 20 media files total; document/web refs require thinking                                                                                                                      |\\n| T2: 480p/768p/2K/4K with native stereo audio, first/last frames, or mixed image/video/audio references         | `minimax-h3`             | 5-15s; 5/6/13/16 cr/s by resolution; up to 9 image, 3 video, 3 audio refs, 12 files total; first 5 reference images free then 8 cr each; reference video/audio each total <=15s                                                                                |\\n| T1: Text, first/last-frame, or mixed-reference video with native audio and stronger prompt adherence           | `minimax-h3-max`         | 5-15s; 5/8 cr/s at 480p/768p plus pooled reference tokens; up to 9 image, 3 video, 3 audio refs, 12 files total; seed and disabled/balanced/quality prompt expansion; provider safety checker off by default                                                   |\\n| T2: Images pinned to specific moments (keyframes); by name otherwise                                           | `flux-3`                 | 5-20s (auto for text/first-frame only); 720p/1080p; up to 10 keyframes; `--quality draft` is 720p-only at ~1/3 the cost                                                                                                                                        |\\n| T1: Video/audio references, mixed reference media, broad aspect ratios, frame-mode first+last frame, or 11-15s | `seedance-2`             | 4-15s or auto; up to 9 image, 3 video, and 3 audio refs; audio toggle; Mini/Fast are 480p/720p only                                                                                                                                                            |\\n| T1: Single takes past 15s, or more references than Seedance 2.0 allows                                         | `seedance-2.5`           | 4-30s or auto; up to 30 image, 10 video, and 10 audio refs (50 files total); one quality tier; 480p/720p/1080p                                                                                                                                                 |\\n| T2: Fast polished 3-15s video with first frame, multi-prompt, and native audio                                 | `kling-v3-turbo`         | Audio always on; Pro default; no end frame, reference-media mode, or elements                                                                                                                                                                                  |\\n| T1: Cinematic 3-15s with reference images, image/video elements, first+last frame, audio, or 4K                | `kling-o3`               | 7 combined image refs/elements, reduced to 4 with a video element; Standard/Pro/4K                                                                                                                                                                             |\\n| T1: Kling 3-15s image-to-video with first+last frame, image/video elements, multi-prompt, audio, or 4K         | `kling-3.0`              | Elements require a start image; image or video elements can bind voice_id; Standard/Pro/4K                                                                                                                                                                     |\\n| T2: User explicitly requests Veo, or the selected workflow specifically needs Veo                              | `google-veo3.1`          | Good fallback, but not the preferred general model                                                                                                                                                                                                             |\\n\\nRouting rules:\\n\\n- Inexpensive pass or draft at 480p/768p with native audio: use MiniMax H3 Max (5/8 cr/s plus reference tokens).\\n- Grok 1.5 reference mode accepts 1-7 images only. Address them in array order as `<IMAGE_0>` through `<IMAGE_6>`. Do not combine reference images with `--start-image`, `--end-image`, `--ref-video`, or `--ref-audio`.\\n- Grok 1.5 first-frame mode accepts one `--start-image`, derives the output aspect ratio from that image, and does not support `--end-image`. Text and first-frame modes support 480p, 720p, or 1080p. Reference mode supports 480p or 720p.\\n- Grok 1.5 always generates native audio. Do not pass `--no-audio`, `--seed`, `--negative`, or `--quality`.\\n- Around 11-15 seconds with native audio: use Seedance, Kling 3.0 / O3, or MiniMax H3 Max, not Gemini. Past 15 seconds: Seedance 2.5.\\n- Dialogue: write the line in the prompt, in quotes, with who says it and how. `gemini-omni-1.1-flash`, `seedance-2.5`, `seedance-2`, `kling-3.0` and `kling-o3` speak it natively; add `--ref-audio` on Seedance or a bound Kling voice for a specific voice. Do not generate speech separately and lip-sync it on.\\n- One existing source video that should be edited: use `videodraft edit video`, which auto-selects Gemini Omni 1.1 Flash for a source up to 10s. Generic `generate video --ref-video` retains source-edit behavior when `--video-task` is omitted, but the dedicated edit command is clearer.\\n- Video supplied as a creative reference: Gemini Omni 1.1 Flash accepts up to 3 videos of at most 3 seconds each, including mixed image and video input. Creative video references are accepted on `--video-task generate` ONLY: edit and extend take exactly one input video, so `--ref-video` cannot accompany `--source-video` or `--previous-interaction-id`. Use Seedance 2.5 for more or longer video/audio references, or Seedance 2.0 when quality-tier control matters.\\n- First and last frame control: every Tier 1 video model supports it (Gemini Omni 1.1 Flash, Seedance, Kling O3, Kling 3.0, MiniMax H3 Max). For Gemini, every start/end frame counts toward the 10-image total, leaving up to 9 references with a start frame or 8 with both frames.\\n- Extension with a 1-30s uploaded source uses Gemini Omni 1.1 Flash plus `--source-video` and `--video-task extend` (or `--extend`). Pass an explicit 3-10s output duration; the model appends it at the end, up to 40 seconds total. Creative `--ref-video` clips CANNOT accompany the source: edit and extend take exactly one input video. New dialogue is allowed only when the source video is silent; adding speech on top of a source that already has speech is refused with \\"the model is currently unable to process speech edits\\". Continuation uses `--previous-interaction-id <id>` and defaults to a conversational edit; `--video-task extend` lengthens it. A continuation is submitted as the prior turn\'s output video, so it obeys the same source limits (<=30s to extend, <=10s to edit) and the same silent-source dialogue rule. 40s total is reachable only by extending from a source of 30s or less, so a ladder dead-ends past 30s. Fal returns interaction IDs, but its currently published callable v1.1 endpoints do not expose continuation/extension or mixed source-edit references; never infer a route or silently fall back to paid Google.\\n- Wan 3.0 reference mode and frame mode are separate. It accepts 10 images, 5 videos, and 5 audio clips, at most 20 media files total. Video and audio each total at most 15 seconds. `--file-url` and `--web-url` require `--thinking`. `--auto-duration` cannot be combined with `--duration`.\\n- MiniMax H3 and H3 Max reference mode and first-plus-last-frame mode are separate. Audio cannot be the only reference. Address references as `Image 1`, `Video 1`, and `Audio 1` in array order.\\n- Seedance reference mode and first-plus-last-frame mode are separate. Do not promise reference video/audio plus a last frame in one generation.\\n- Multi-prompt sequencing: use Kling 3.0 Turbo, Kling O3, or Kling 3.0.\\n- Kling 3.0 image-to-video and Kling O3 reference-to-video accept repeatable structured `--element` JSON. Each element is image-backed (`frontal_image_url` plus 1-3 `reference_image_urls`) or video-backed (`video_url`). Either form may include `voice_id`. Keep the voice ID inside the same element so the association is preserved. Reference them as `@Element1`, `@Element2`. Kling V3 Turbo rejects elements.\\n- Kling 2.6 Pro image-to-video accepts one or two repeatable `--voice-id` values. Cite them as `<<<voice_1>>>` and `<<<voice_2>>>` in the prompt. Voice control costs 17 cr/s. Use `videodraft kling-voices list|create|delete` to manage the separate Kling video-control voice library. Creating a voice requires a clean 5-30 second, up-to-50MB single-speaker `.mp3`, `.wav`, `.mp4`, or `.mov` sample plus `--confirm-consent`. Creation costs 1 VideoDraft credit on the platform Fal account and 0 credits with Fal BYOK; use the create command\'s `--estimate` flag to check without creating.\\n- Kling V3 voice control costs 16 cr/s for Standard and 20 cr/s for Pro.\\n- Seedance quality: `mini` for the lowest cost, `fast` for speed, `standard` for maximum quality and for 1080p/4K. Seedance 2.5 has a single tier and ignores `--quality`.\\n- Longer than 15 seconds, or more than 9 image / 3 video / 3 audio references: use Seedance 2.5. It reaches 30s and 30/10/10 references (50 files total) at 480p/720p/1080p, but has no 4K.\\n- Seedance 2.x allows real people by default, the same as AI Studio: Byteplus first, a submit-time Fal fallback, and Fal\'s higher tier-specific rate. Turn it off with MCP `allow_real_people: false` or CLI `--no-allow-real-people` for the lower Byteplus-only rate, only when the user wants the cheapest run and nothing in the job is a real identifiable person (text-only requests, non-people, anime, clearly synthetic or stylized characters).\\n- If a Seedance request made with the option off fails with `SEEDANCE_REAL_PERSON_OPT_IN_REQUIRED`, estimate the higher rate, follow the user\'s spend policy, and retry once with the option on. The response also carries `retry_with: { allow_real_people: true }`, `cli_flag: \\"--allow-real-people\\"`, and `retry_policy: \\"once\\"`. If the option was already on, do not repeat the same request. Byteplus may accept a task and reject the output later. VideoDraft refunds that failed generation, but it cannot reroute the asynchronous failure to Fal. Rephrase or change the references instead.\\n\\n### Video edit and motion-control categories\\n\\nUse `videodraft models video --category video_edit` for existing-video transforms and `--category motion_control` for motion transfer.\\n\\n| Need                                       | Command/model                                                                | Important limits                                                                                                                                          |\\n| ------------------------------------------ | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |\\n| Most edits of a source up to 10s (DEFAULT) | `videodraft edit video <video> \\"...\\"` (auto-selects `gemini-omni-1.1-flash`) | Source <=10s or it REFUSES; up to 10 image refs and 3 creative video refs <=3s each; 360p/720p/1080p/4K; audio always regenerated (no `--preserve-audio`) |\\n| Cheapest simple prompt edit                | `videodraft edit video <video> \\"...\\" --model grok-imagine-video-edit`        | No image refs; source silently truncated to 8s; auto/480p/720p                                                                                            |\\n| Edit with several image references         | `--model happy-horse-video-edit --ref ...`                                   | Up to 5 refs; 720p/1080p; source silently truncated to 15s; highest rate (28-56 cr/s)                                                                     |\\n| Controlled Kling edit                      | `--model kling-o3-video-ref-edit --ref ...`                                  | Up to 4 refs; Standard/Pro; source silently clamped to 3-10s                                                                                              |\\n| Transfer reference motion to an image      | `videodraft edit motion <image> [direction] --motion-video <video>`          | Prompt/direction is optional; Kling V3 default; optional one image-only `--element`; element requires video orientation                                   |\\n\\nIf the user explicitly names one of these models, preserve it. The CLI uploads local source videos and reference images automatically. Editing returns an async job and waits by default.\\n\\n**Omit `--model` and the SERVER chooses**, because only it can measure the source. It picks `gemini-omni-1.1-flash` for any source up to 10s. When that is not safe (source longer than 10s, unmeasurable duration, `--preserve-audio`, more than 10 refs, or Fal BYOK with refs) it spends nothing and returns a priced menu: per model, the seconds it would edit, the seconds it would drop, and the credit cost. The CLI prints that table and exits 2. Show it to the user, then re-run with `--model`.\\n\\n**Truncation is the trap here.** Only Gemini refuses a source it cannot fully consume. Every other edit model accepts a 30s clip and returns an edit of its first 8-15 seconds with no error. `videodraft edit video` now warns when this will happen and the tool response carries `source.truncated` / `source.dropped_seconds`; relay it to the user rather than letting them discover it in the output.\\n\\nTo edit a longer source without losing its tail, cut it into <=10s pieces with `videodraft_editor`, edit each with Gemini, then reassemble and export there. VideoDraft has no server-side split/concat, so this needs the native editor.\\n\\nKling O3 is also exposed for reference generation. `videodraft generate video --model kling-o3-video-ref-edit` requires exactly one `--ref-video` and generates a new reference-guided clip. Wan 3.0 handles new text, frame, and mixed-reference generation, but is not an existing-source edit model.\\n\\n### Reference-first video workflow\\n\\n- Prefer a start frame or reference image whenever a specific character, product, location, style, composition, or brand identity must stay recognizable.\\n- If the user gives a reference, pass it. Never silently replace it with a text description.\\n- If no reference exists and continuity matters, generate a still first with the user\'s explicitly requested compatible image model, otherwise use Nano Banana 2. Wait for the image URL, then animate it with the selected video model. Confirm the combined image plus video cost before starting.\\n- For multi-shot scenes, generate shot images with `videodraft shots <project_id> --model <selected-image-model> --grid`. Preserve an explicitly requested compatible image model; otherwise use `nano-banana-2`. The grid establishes the scene and characters together, then decodes into individual shot images.\\n- Animate the decoded shot images as per-shot start frames or references. Do not independently text-generate each video clip when the shots need to match.\\n- Pure text-to-video remains appropriate for generic one-off footage where no subject, composition, or continuity needs to be preserved.\\n\\n### Audio\\n\\n- **Seed Audio 1.0**: use `videodraft generate audio` for open-ended speech, sound, music, or prompt-driven audio editing. It accepts up to three audio references or one image. Address audio references as `@Audio1`, `@Audio2`, and `@Audio3`. Preset and custom cloned voice IDs are supported. Output is up to 120 seconds. There is no requested-duration input. The CLI automatically retries transient responses with one idempotency key. To recover after the CLI process itself is interrupted, set `--idempotency-key <uuid>` on the original command and reuse it.\\n- **Voiceover/TTS**: prefer ElevenLabs. Brittney is the platform default voice; under ElevenLabs BYOK, use a compatible voice from the user\'s account. Honor another supported voice/provider when the user explicitly selects it.\\n- **Dialogue, voice changing, and dubbing**: ElevenLabs only.\\n- **Sound effects**: ElevenLabs Sound Effects only.\\n- **Music**: use `lyria-3.5` for all music, short or long (up to ~3 minutes), with vocals/lyrics or instrumental music. When `--model` is omitted the CLI sends no model and the server default applies, which is `lyria-3.5` wherever the backend supports it. If the server answers that `lyria-3.5` is an unknown model, that backend predates it: rerun without `--model` (the server default then applies), or use `lyria-3-pro-preview` for a track longer than 30 seconds. `lyria-3-clip-preview` (fixed ~30s) and `lyria-3-pro-preview` remain available for explicit requests. Lyria length and structure are prompt-guided, not exact; for an instrumental, include \\"instrumental only, no vocals\\" in the prompt. `--length` and `--instrumental` only apply to ElevenLabs. Use `elevenlabs-music-v2.5` when a specified 3-300 second length, composition plan, or style reference track matters. Lyria references: up to 10 images on Google, 1 on Fal BYOK; 3.5 Fal prompts are 1-5000 characters (an image-only request gets a neutral prompt). `elevenlabs-music` is an alias for v2.5. Use `elevenlabs-music-v1` only when the user asks for v1 by name; it takes a prompt, `--length` and `--instrumental` only.\\n- **ElevenLabs Music v2.5 inputs**: either a prompt (`--length`, `--instrumental`) or a composition plan, never both. A plan is 1-30 sections of 3-120 seconds each, up to 300 seconds in total, and `--plan`/`--section` pick v2.5 when `--model` is omitted. Empty section parts default to 20 seconds and an instrumental part. Build one with repeatable `--section \\"<seconds>|<style, style>|<text>\\"` (use `\\\\n` for line breaks) or pass `--plan plan.json` with `{\\"chunks\\":[{\\"text\\",\\"duration_ms\\",\\"positive_styles\\",\\"negative_styles\\",\\"context_adherence\\",\\"audio_reference\\"}]}`. Section text is an optional `[Section name]`, lyric lines, and `{inline directions}`. Put 6-7 specific English styles on the first section; it sets the genre. `--ref-audio <url|file>` adds a style reference clip to the first section (window up to 30 seconds via `--ref-start`/`--ref-end` in ms, `--ref-strength low|medium|high|xhigh`); local files are uploaded, including relative `audio_reference.audio_url` paths in a plan file. `--seed` works only with a plan. `--format` picks the output (`mp3_48000_192` default on v2.5; `pcm_*`, `ulaw_8000` and `alaw_8000` arrive as stereo WAV files). Style references don\'t run on the user\'s own ElevenLabs key; with that key connected, drop the reference or ask the user to turn the key off. The CLI retries transient responses with one idempotency key; set `--idempotency-key <uuid>` to recover after an interruption.\\n- Voice Changer and Dubbing require the source media duration and currently accept source media up to 300 seconds.\\n\\n**User-supplied ElevenLabs voice IDs:** voiceover, dialogue, and voice changing accept raw IDs (16-64 alphanumeric characters) or `elevenlabs-<id>`. `videodraft models voices` / MCP `list_available_voices` is for discovery, not an allowlist. Pass a supplied ID directly even when it is absent from the catalog; do not reject it or substitute a catalog voice. The voice must be accessible to the provider account used for generation. Private or cloned voices may require the user\'s connected ElevenLabs key. A failed voice listing does not prove that a supplied ID cannot generate; a connected key with generation access may still work. If the provider rejects generation access, report that error rather than silently changing the voice.\\n\\nUse `--voice <id>` for voiceover and voice changing, and repeat `--line \\"<id>:Text\\"` for dialogue. These examples show both ID forms; replace the sample IDs with the user\'s supplied IDs:\\n\\n```bash\\nvideodraft generate voiceover \\"Hello there.\\" --voice kPzsL2i3teMYv0FxEYQ6 --download ./media/voiceover.mp3\\nvideodraft generate dialogue --line \\"kPzsL2i3teMYv0FxEYQ6:Hello.\\" --line \\"elevenlabs-kmSVBPu7loj4ayNinwWM:Welcome back.\\" --download ./media/dialogue.mp3\\nvideodraft generate voice-changer ./media/source.wav --voice elevenlabs-kPzsL2i3teMYv0FxEYQ6 --duration 12 --download ./media/changed-voice.mp3\\n```\\n\\nFor MCP, use `generate_voiceover.voice_id`, `generate_dialogue.lines[].voice_id`, or `change_voice.voice_id` with either form. ElevenLabs IDs are separate from Kling video-control voice IDs and MiniMax `custom-*` cloned-voice IDs. Do not convert IDs from those systems into ElevenLabs IDs.\\n\\n### Avatar / talking head\\n\\n**First decide the framing, not just \\"someone talks\\".** This lane animates a PORTRAIT facing the lens. A character delivering a line inside a real scene, with blocking, framing or camera movement, belongs to `generate video` instead: write the dialogue in the prompt and `gemini-omni-1.1-flash`, `seedance-2.5`, `seedance-2`, `kling-3.0` or `kling-o3` voices it natively (add a Seedance `--ref-audio` clip or a Kling voice bound per element for a specific voice). That is the default for any talking character; never plan silent video + TTS + lip-sync. Sending a cinematic shot to Fabric returns a head-on talking headshot, not the shot that was asked for. `videodraft models video --json` lists these under `recommended.in_scene_dialogue`.\\n\\nFor a presenter, spokesperson or explainer speaking to camera, VEED Fabric is the preferred model. Choose the dedicated path from the media the user already has:\\n\\n| Starting media                             | Command                                                                   | Use                                                        |\\n| ------------------------------------------ | ------------------------------------------------------------------------- | ---------------------------------------------------------- |\\n| Portrait + script, reusable avatar record  | `videodraft avatar create <portrait> --script \\"...\\"` then `avatar render` | Managed avatar flow with bundled speech preparation        |\\n| Portrait + text                            | `videodraft avatar fabric <portrait> --text \\"...\\"`                        | One-off direct VEED Fabric text mode                       |\\n| Portrait + existing audio                  | `videodraft avatar fabric <portrait> --audio <audio>`                     | One-off direct VEED Fabric audio lip sync                  |\\n| Portrait + existing audio, short and sharp | `videodraft avatar h3-lipsync <portrait> --audio <audio>`                 | MiniMax H3 Max Lip Sync, 5-14.8s at up to 2K               |\\n| Existing video + existing audio            | `videodraft avatar lipsync <video> --audio <audio>`                       | Sync Labs Lipsync 2 (Tier 2): re-dub existing footage only |\\n\\nThe managed renderer is VEED Fabric Fast (`veed/fabric-1.0/fast`). Direct Fabric, MiniMax H3 Max Lip Sync, and Sync Labs are paid AI Studio generations and return async job IDs.\\n\\n1. Obtain the avatar image. Prefer the user\'s supplied portrait or an existing character. If none exists, use the user\'s explicitly requested compatible image model, otherwise generate a front-facing head-and-shoulders portrait with `nano-banana-2`, direct eye contact, a natural expression, and a clean background. Match the intended video aspect ratio when practical.\\n2. If the portrait is visibly soft or too small, run Topaz image enhancement/upscaling before animation.\\n3. Generate a script only if needed: `videodraft avatar script \\"<idea>\\"`.\\n4. Create the avatar record and speech: `videodraft avatar create <portrait-url-or-file> --script \\"...\\" --voice <id> --ar 9:16`. Prefer ElevenLabs when unspecified, but honor another explicitly selected supported voice/provider.\\n5. Render with VEED Fabric: `videodraft avatar render <avatar_video_id> --resolution 720p`.\\n\\nThe portrait is passed as the avatar\'s character image, not as a generic video\'s start frame. Prefer rendering directly at 720p. Use 480p only when the user prioritizes lower cost. Avatar script generation and `avatar create` (including speech) are bundled/free. Confirm the Fabric render cost, plus portrait generation or upscaling when needed.\\n\\nDirect Fabric text/audio, H3 Max Lip Sync, and Sync Labs do not use the managed avatar record. The CLI uploads local portrait, video, and audio files automatically. `avatar fabric --speed fast` applies only to audio mode. `avatar h3-lipsync` takes no prompt: pick `--resolution 480P|768P|1080P|2K` (default 768P), an optional `--seed`, `--no-transcription` to sync without transcribing the audio (transcription is on by default), and `--safety-checker` only when the user asks for Fal\'s checker. The portrait\'s width / height must be 0.4-2.5, and audio shorter than 5 seconds is refused before any charge. Sync costs 5 credits per verified audio second; under Fal BYOK, `sync_mode` remains available but `temperature` and `active_speaker` are ignored by the provider.\\n\\n### Upscaling / enhancement\\n\\n- **Images**: Topaz via `videodraft upscale image <url-or-file> --scale 1x|2x|4x [--mode precision|generative|creative] [--model <name>]`. Modes: `generative` (default; Wonder 3.5, Topaz\'s recommended model for AI-generated images; `Redefine` takes `--prompt`, `--creativity 1-6`, `--texture 1-5`), `precision` (faithful and cheapest; Standard V2, High Fidelity V3, Low Resolution V2, CGI, Text Refine; use for clean real photos), `creative` (Bloom 2; artistic, `--prompt`, `--creativity 1-9`). Extra knobs: `--no-face-enhance`, `--face-strength`, `--sharpen`, `--denoise`, `--fix-compression`, `--format png`. Use 1x for light enhancement without enlargement, 2x as the general default, and 4x only when the source quality and target size justify it. The server must verify dimensions from a readable image of at most 50 MB; `--width` and `--height` are compatibility hints and cannot bypass a failed probe. The result is synchronous. Cost: 8 credits per started 24 MP of output in precision, per 8 MP (Wonder 3/3.5) or 4 MP in generative, per 2 MP in creative.\\n- **Videos**: Topaz via `videodraft upscale video <url-or-file> --resolution 720p|1080p|4k` (preferred) or `--scale 2x`, plus `--mode precision|generative|creative` and `--model <name>`. `generative` (default; Starlight Precise 2.6, Topaz\'s recommended model for AI-generated footage; Starlight Fast 2 at half price) costs 12 credits/s up to 1080p and 26 at 4K. `precision` (Proteus, Proteus Natural, Iris, Gaia 2 for animation, Rhea, Theia, Artemis, Dione) is 6x cheaper at 1 / 2 / 6 credits per second for 720p / 1080p / 4K output; use it for real footage or when cost matters. `creative` (Astra 2, `--prompt`, `--creativity`, `--realism`, `--sharp`) always renders 4K at 50 credits/s. `--fps 60` delivers 60fps on the same pass; any output above 30fps (including a 50/60fps source) doubles every rate; the server must verify duration, dimensions, and frame rate from an MP4/MOV source of at most 100 MB. `--duration`, `--width`, `--height`, and `--source-fps` are compatibility hints and cannot override billing or bypass a failed probe. The same source-verification requirement applies to frame interpolation. `--scale` also accepts intermediate factors such as `1.5x`. Max source length 5 minutes. The job is asynchronous; the CLI waits by default, while MCP callers poll `check_generation_status`. MCP video input must be VideoDraft-hosted, so upload local or external sources first.\\n- **Frame interpolation / slow motion**: `videodraft interpolate <url-or-file> --fps 60 [--model Apollo|Chronos|Aion] [--slowdown 1-8]` (MCP `interpolate_video`). Resolution is unchanged. Apollo (default) for smooth general conversion, Chronos for natural slow motion, Aion for extreme slow motion. Apollo/Chronos cost 3 credits per output second up to 1080p (6 at 4K); Aion 5 / 17. These rates cover targets up to 60fps; above 60fps multiply by target FPS / 60 (120fps doubles the rate). Output seconds = source seconds \xD7 slowdown. The final charge rounds up to a whole credit.\\n- Use upscaling to preserve the image/video while improving detail, resolution, or cleanup. It cannot fix the wrong subject, misspelled text, bad framing, unwanted objects, broken continuity, or incorrect motion. Use an edit or regeneration for those problems. Keep `generative` for AI-generated sources; switch to `precision` for clean real photos/footage or a cheap pass, and `creative` only when the user wants an artistic reinterpretation.\\n- For a new Fabric avatar, render directly at 720p instead of rendering at 480p and then upscaling. Upscale the source portrait first only when the portrait itself is low quality.\\n\\n## Capability gotchas\\n\\n- Each model\'s `inputs` block is authoritative: supported `aspect_ratios`, `resolutions`, `quality_options`, `start_frame`/`end_frame`, `max_reference_images/videos/audio`, `multi_prompt`, `audio_toggle`. Passing an unsupported input fails with a clear error \u2014 check first, don\'t trial-and-error paid calls.\\n- Most video models support only 16:9 / 9:16 / 1:1. A 3:4 request hard-fails on most.\\n- `--seed` reproduces a specific output on models that support it (e.g. Flux, Ideogram V4). GPT Image 2.5 rejects any explicit seed; older models may ignore unsupported seeds. You do not need a seed for variation \u2014 `--num` already varies.\\n- `--rendering-speed` applies to Ideogram (V3: `Default`/`Turbo`/`Quality`; V4: `Turbo`/`Balanced`/`Quality`) and affects image cost \u2014 pass it to `videodraft costs ... --rendering-speed <tier>` for an accurate estimate. Always trust `videodraft models image --json` over this list; new models and tiers appear there the moment the platform ships them, with no CLI update.\\n- `seedream-v5-pro` supports unified text-to-image and reference-image editing with up to 10 image references. Use `--resolution 1K` for 7 credits/image or `--resolution 2K` for 14 credits/image.\\n- Reference inputs: `--ref <img>` (images, including up to 10 total for Gemini Omni 1.1 Flash and Wan 3.0, and 7 for Grok 1.5), `--source-video <v>` (Gemini uploaded edit/extension source), `--ref-video <v>` (up to 3 creative videos <=3s each for Gemini Omni 1.1 Flash; also Wan 3.0, MiniMax H3, MiniMax H3 Max, and Seedance 2), `--ref-audio <a>` (Wan 3.0, MiniMax H3, MiniMax H3 Max, Seedance 2), and `--element \'<json>\'` or `--element @elements.json` for Kling V3/O3. For an exact Seedance 2.x reference-video `--estimate`, add `--ref-video-seconds <combined-seconds>`; Seedance bills input seconds alongside output. Wan 3.0 and MiniMax H3 do not bill input reference seconds; MiniMax H3 Max bills them as pooled reference tokens. The CLI uploads local media references and every structured element without flattening the source/reference roles. `--segment \\"<prompt>:<seconds>\\"` (repeatable) drives Kling 3.0, Kling 3.0 Turbo, and O3 multi-prompt generation. Use 1-6 segments of 1-15 whole seconds each, with 3-15 seconds total. `generate image --video-ref` is the nano-banana-2 video reference.\\n- The top-level prompt is OPTIONAL for Gemini Omni 1.1 Flash media-input or continuation calls, Wan 3.0 frame/reference modes, `generate video` with multi-prompt models, and Kling 3.0 Turbo (`--model kling-v3-turbo`) image-to-video. Text-only Gemini and Wan calls still require a prompt unless their live schema says otherwise.\\n- Hosted AI Production fallback: `videodraft produce <project> --mode full_video` generates one Seedance 2 video per scene, with real people allowed by default at the higher Fal-tier rate on every submitted scene segment; add `--no-allow-real-people` for the lower Byteplus-only rate when no scene shows a real identifiable person. The MCP equivalent is `produce_project` with `mode: \\"full_video\\"` (and `allow_real_people: false` to opt out). If a partial opted-out run returns `SEEDANCE_REAL_PERSON_OPT_IN_REQUIRED`, rerun the same project once with an explicit `--allow-real-people` after cost confirmation. The server reconciles asynchronous results first, preserves running/completed jobs, and retries only failed placeholders carrying that exact code. Poll with `videodraft generations`, then `videodraft finalize <project>` swaps them into the hosted timeline before `export`. In VideoDraft ADE, do not choose this path while `videodraft_editor` is available unless the user explicitly requests hosted production. Generate or download the scene assets, import them, and assemble/export with the native editor instead. If the user explicitly requests another compatible video model for a hosted production, do not use this fixed Seedance path; generate the project shots manually with the requested model and attach them to the hosted timeline.\\n\\n## Cost model\\n\\n- Images: per image (\xD7 `--num`). Matrix-priced models (GPT-Image, Nano Banana Pro, Seedream v5 Pro) vary by resolution/quality.\\n- Video: usually credits/second \xD7 duration; rate depends on model + resolution + quality + native audio on/off.\\n- Gemini Omni 1.1 Flash: 3 / 10 / 15 / 30 credits per output second at 360p / 720p / 1080p / 4K (720p default). Extend appends an explicit 3-10 seconds to a 1-30s source, whether uploaded or resolved from a prior interaction; 40 seconds total is reachable only while the source stays at or under 30s. Fal BYOK generation and basic source edits cost zero VideoDraft credits; continuation, extension, and separate creative references on a source edit are unavailable under Fal BYOK.\\n- MiniMax H3: 5 / 6 / 13 / 16 credits per output second at 480p / 768p / 2K / 4K (768p default). The first 5 reference images are included, then 8 credits for each additional image. Reference video and reference audio are NOT billed.\\n- MiniMax H3 Max: 5 credits per output second at 480p or 8 credits per second at 768p (default), plus pooled reference tokens. The first 4,096 reference tokens are free and each additional 1,000 costs 2 credits. An image is `(width x height) / 1024` tokens (a 1024x1024 reference is 1,024, so four of them are free); a reference video is 2,886 tokens per second at 480p or 7,459 at 768p; reference audio is about 2,121 per second. Pass `--ref-audio-seconds` for an exact estimate with audio references. The server measures each reference image, so a quote that assumes 1024x1024 is a floor.\\n- Wan 3.0: 7 / 14 / 28 credits per output second at 480p / 720p / 1080p. Auto duration reserves 30 seconds and reconciles unused credits from the provider-reported output duration. Fal BYOK charges zero VideoDraft credits.\\n- Grok Imagine Video 1.5: 8 credits/output second at 480p, 14 at 720p, or 25 at 1080p, plus 1 credit for each first-frame or reference image. Native generated audio is part of every output.\\n- Kling voice control: 17 credits/output second for Kling 2.6 Pro, 16 at Kling V3 Standard, and 20 at Kling V3 Pro.\\n- Shot-image batches: one image per shot (+1 grid image per scene in `--grid` mode) \u2014 the largest single spend in the pipeline.\\n- VEED Fabric avatar renders: ~10 credits/sec at 480p, ~20/sec at 720p. Avatar creation and its speech are bundled/free; only optional portrait generation/upscaling adds cost before the render.\\n- Direct VEED Fabric: text or normal audio is 8 credits/sec at 480p and 15/sec at 720p; fast audio is 10/sec at 480p and 20/sec at 720p.\\n- MiniMax H3 Max Lip Sync: 5 / 8 / 16 / 32 credits per output second at 480P / 768P (default) / 1080P / 2K. The video runs as long as the audio (at least 5s; only the first 14.8s is used), billed on the server-measured length rounded up, so at most 15 seconds. Use MP3, WAV, M4A (AAC), or AAC audio; other formats run only on the user\'s own Fal key.\\n- Sync Labs Lipsync 2: 5 credits per verified audio second.\\n- Voiceover TTS: 10 credits per 1000 characters for standard voices, 30 per 1000 for cloned `custom-*` voices (min 1, pro-rated); applies to standalone voiceovers AND per-scene narration during `produce`. Silent tracks are free. Voice cloning itself is a flat 150 credits per clone.\\n- Lyria music: flat per track, 4 credits (Clip) / 10 credits (3.5) / 8 credits (legacy Pro). Fal BYOK uses zero VideoDraft credits.\\n- Seed Audio 1.0: 19 credits per actual output minute, prorated and rounded up to a whole credit. VideoDraft reserves the 120-second maximum of 38 credits and refunds the unused portion after generation. Fal BYOK is free.\\n- ElevenLabs audio: sound effects are per second, dialogue is per character, music/voice-changer/dubbing are per started minute. ElevenLabs Music v2.5 and v1 both cost 60 credits per started output minute; estimate a composition plan with its total length. Voice changer and dubbing reject source media above 300s in the current synchronous flow.\\n- Seedance 2.0 / 2.5 real people: allowed by default, which keeps Byteplus first, permits a submit-time Fal fallback, and prices at Fal\'s rate for that tier: 2.0 Mini 8/16 cr/s, Fast 11/25, Standard 14/31/69/156, 2.5 23/48/114 for 480p/720p/1080p. `--no-allow-real-people` uses the Byteplus-priced path instead (2.0 Mini 4/8, Fast 6/13, Standard 7/16/38/78, 2.5 11/24/57); Byteplus refuses real-person likenesses, so a likeness-policy failure then does not fall back. The gap is roughly 2x but not exactly: the Seedance 2.0 1080p pair is 38/69, or about 1.82x. If Byteplus accepts the task and later rejects the generated output, VideoDraft refunds the failure but does not resubmit it to Fal. Turn the option off only for the cheapest run when nothing in the job is a real identifiable person.\\n- Grok Imagine images: `grok-imagine` is a flat 2 cr (3 with a reference). `grok-imagine-2.0` is a separate, newer model priced by resolution and quality: 1K 4 (low) / 6 (medium), 2K 6 / 8, plus 1 cr per reference image (up to 3). v1 is NOT superseded \u2014 pick it when cost matters more than 2K.\\n- xAI bills refused requests, so failed Grok generations are not refunded.\\n- Upscales: priced by output size, mode, and (video) duration/fps; see the Upscaling section above.\\n\\nQuote before spending:\\n\\n```bash\\nvideodraft costs gemini-omni-1.1-flash --type video --duration 8 --resolution 720p --audio\\nvideodraft costs topaz-upscale-video --type video --duration 10 --width 1920 --height 1080 --resolution 4k --mode generative\\nvideodraft costs topaz-upscale --type image --width 2048 --height 2048 --scale 2x\\nvideodraft costs topaz-interpolate-video --type video --duration 10 --width 1920 --height 1080 --fps 60 --topaz-model Apollo\\nvideodraft costs minimax-h3 --type video --duration 10 --resolution 2K --ref-images 7\\nvideodraft costs minimax-h3-max --type video --duration 10 --resolution 768p --ref-images 2\\nvideodraft costs grok-imagine-video-1.5 --type video --duration 8 --resolution 720p --ref-images 4\\nvideodraft costs seedance-2 --type video --duration 15 --resolution 720p --quality standard --audio\\nvideodraft costs grok-imagine-2.0 --type image --resolution 2K --quality medium --num 2\\nvideodraft costs seedance-2 --type video --duration 15 --resolution 720p --quality standard --audio --no-allow-real-people # lower Byteplus-only rate\\nvideodraft costs elevenlabs-dubbing --type audio --duration 60\\nvideodraft costs seed-audio-1.0 --type audio --duration 60 # scenario only; model controls actual length\\nvideodraft costs elevenlabs-dialogue --type audio --chars 350\\nvideodraft costs voiceover --type audio --chars 800    # TTS: 10 cr / 1000 chars\\nvideodraft generate video \\"...\\" --model gemini-omni-1.1-flash --estimate # same quote, inline\\nvideodraft generate video \\"...\\" --model minimax-h3-max --duration 8 --resolution 768p --prompt-expansion-mode balanced\\n```\\n","references/pipeline.md":"# VideoDraft pipeline reference\\n\\nEverything here describes the hosted fallback pipeline through the CLI (`videodraft <command>` / `videodraft call <tool>`) or hosted MCP connector (tool names in backticks). When the local `videodraft_editor` MCP is available, do not use hosted production or export by default. Use hosted tools only for asset generation and optional script/storyboard stages, then import the results and finish with the native editor reference linked from SKILL.md. Continue through `produce_project` and `export_video` only when the user explicitly requests a hosted web production or the native editor is unavailable.\\n\\nUse direct asset tools for standalone images, clips, audio, upscales, and descriptions. Use a hosted project when the user explicitly wants the editable web project, when a hosted storyboard stage is useful, or when the native editor is unavailable. Script-only uses a script-stage project and stops at the script. In VideoDraft ADE with editor tools present, stop before hosted production, import the generated assets, and build/export the native project.\\n\\n## Stages and their tools\\n\\n| Stage                                    | CLI                                                                         | Underlying tool                             |\\n| ---------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------- |\\n| Idea \u2192 full storyboard project           | `videodraft create \\"<idea>\\"`                                                | `generate_storyboard_from_idea`             |\\n| Idea \u2192 script only (stop there)          | `videodraft create \\"<idea>\\" --script-only`                                  | `generate_script_from_idea`                 |\\n| Footage IS the video                     | `videodraft call generate_storyboard_from_media`                            | `generate_storyboard_from_media`            |\\n| Batch shot images                        | `videodraft shots <project>`                                                | `generate_shot_images`                      |\\n| One shot image                           | `videodraft generate image --project <id> --scene N --shot M`               | `generate_image`                            |\\n| Produce (voiceover, captions, timeline)  | `videodraft produce <project>`                                              | `produce_project`                           |\\n| Seedance full-video production           | `videodraft produce <project> --mode full_video`                            | `produce_project` with `mode: \\"full_video\\"` |\\n| Per-shot motion prompts                  | `videodraft video-prompts <project>`                                        | `generate_video_prompts`                    |\\n| Motion clip for a shot                   | `videodraft generate video --project <id>`                                  | `generate_video`                            |\\n| Attach a finished clip to the timeline   | `videodraft attach <project> --scene N --shot M --media <url> --type video` | `attach_media_to_shot`                      |\\n| Find free b-roll (no credits)            | `videodraft stock search \\"<query>\\"`                                         | `search_stock_media`                        |\\n| Copy stock media onto the CDN            | `videodraft stock import <ref>`                                             | `import_stock_media`                        |\\n| Background music                         | `videodraft generate music --attach <project>`                              | `generate_music` / `set_background_music`   |\\n| Song with vocals, lyrics or sections     | `videodraft generate music --model elevenlabs-music-v2.5 --section \\"...\\"`   | `generate_music` with `composition_plan`    |\\n| General or reference-driven audio        | `videodraft generate audio \\"...\\"`                                           | `generate_audio`                            |\\n| Sound effect                             | `videodraft generate sound-effect \\"...\\"`                                    | `generate_sound_effect`                     |\\n| Dialogue audio                           | `videodraft generate dialogue --line \\"voice:text\\"`                          | `generate_dialogue`                         |\\n| Voice changer                            | `videodraft generate voice-changer <audio>`                                 | `change_voice`                              |\\n| Dubbing                                  | `videodraft generate dub <audio_or_video>`                                  | `dub_media`                                 |\\n| Scene voiceover                          | `videodraft generate voiceover --project <id> --scene N`                    | `generate_voiceover`                        |\\n| Avatar script                            | `videodraft avatar script \\"<idea>\\"`                                         | `generate_avatar_script`                    |\\n| Avatar + speech                          | `videodraft avatar create <portrait> --script \\"...\\"`                        | `create_avatar_video`                       |\\n| Talking-head render                      | `videodraft avatar render <avatar_video_id>`                                | `render_avatar_video` + `get_avatar_video`  |\\n| Direct portrait + text/audio             | `videodraft avatar fabric <portrait> --text \\"...\\"` or `--audio <file>`      | `generate_veed_fabric_video`                |\\n| Short portrait clip from audio, up to 2K | `videodraft avatar h3-lipsync <portrait> --audio <file>`                    | `generate_minimax_h3_lipsync_video`         |\\n| Existing video + replacement audio       | `videodraft avatar lipsync <video> --audio <file>`                          | `generate_sync_lipsync_video`               |\\n| Existing-video AI edit                   | `videodraft edit video <video> \\"<change>\\" --model <video-edit-model>`       | `edit_video`                                |\\n| Motion transfer                          | `videodraft edit motion <image> [direction] --motion-video <video>`         | `generate_motion_control_video`             |\\n| Image enhancement/upscale                | `videodraft upscale image <image>`                                          | `upscale_image`                             |\\n| Video enhancement/upscale                | `videodraft upscale video <video>`                                          | `upscale_video`                             |\\n| Frame rate / slow motion                 | `videodraft interpolate <video> --fps 60 [--slowdown 4]`                    | `interpolate_video`                         |\\n| Final MP4                                | `videodraft export <project>`                                               | `export_video` + `check_export_status`      |\\n\\n## Rules that prevent broken results\\n\\n- **The storyboard is generated FROM the script**, never from the raw idea. `videodraft create` runs the whole chain correctly. Don\'t call `generate_storyboard_scenes` with a raw idea as the \\"script\\".\\n- **Visual consistency**: never generate a storyboard shot in isolation. Shot prompts carry `[[asset:Name]]` / `[[shot:X-Y]]` tags that `generate_shot_images` resolves against the project\'s visual assets and prior shots. When generating a single shot whose prompt has no tags, pass `--ref` images yourself (the project\'s visual assets and/or the previous shot\'s image; `projects get` exposes both). For scenes with multiple shots or recurring characters, prefer `videodraft shots <project> --model <selected-image-model> --grid`: preserve an explicitly requested compatible image model, otherwise use `nano-banana-2`. It creates one coherent scene grid, then decodes it into individual shot images.\\n- **Reference-first video**: when identity, styling, or composition matters, do not generate each motion clip from text alone. Generate or select the shot still first, then pass the decoded shot image as `--start-image` or `--ref` to the selected video model. AI Production already composes scene grids and sends them to Seedance as references. If the user explicitly requests another compatible video model, bypass fixed Seedance full-video mode and generate the per-shot clips with the requested model, using the individual decoded shot images as anchors.\\n- **Seedance full-video real people**: hosted `full_video` allows real people by default, which applies Fal-tier pricing to every submitted segment and permits the Byteplus-to-Fal fallback. For the lower Byteplus-only rate when no scene grid shows a real identifiable person (non-people, anime, clearly synthetic or stylized characters), use `videodraft produce <project> --mode full_video --no-allow-real-people`, or MCP `produce_project` with `mode: \\"full_video\\", allow_real_people: false`. If a partial opted-out run returns `SEEDANCE_REAL_PERSON_OPT_IN_REQUIRED`, re-estimate, follow the user\'s spend-confirmation preference, and rerun the same project once with an explicit `--allow-real-people` / `allow_real_people: true`. The server reconciles asynchronous results first, preserves running/completed jobs, and retries only failed placeholders carrying that exact code. Do not loop when it was already on. VideoDraft refunds a Byteplus task rejected after asynchronous acceptance, but cannot reroute it; rephrase or change the scene references instead.\\n- **Hold off generating shot images while the user is still iterating** on storyboard structure.\\n- **produce \u2192 export ordering**: `export` requires a produced project where every production scene has timeline media. If `produce` returns `generating_shot_images`, poll the job ids it returns, then re-run produce.\\n- **Do not attach motion clips before production exists**: run `produce` successfully first, then attach finished motion clips to the production timeline. Attaching before `production_data` exists cannot place them in the final timeline.\\n- **Generated motion clips do not auto-attach**: after `generate video` completes, attach the clip with `attach_media_to_shot` (`media_type:\\"video\\"`, include `duration_seconds`) \u2014 it replaces the production timeline clip while keeping the storyboard still.\\n- **Talking heads use dedicated avatar tools**: do not use `generate video`. Use managed `avatar create` and `avatar render` for reusable avatars, direct `avatar fabric` for a portrait plus text/audio, `avatar h3-lipsync` for a short (5-14.8s) portrait clip from existing audio at up to 2K, and `avatar lipsync` for an existing video plus replacement audio. Reuse a supplied person image or generate a clear front-facing portrait with the explicitly requested compatible image model, otherwise Nano Banana 2. Managed avatar creation and speech are bundled/free; direct Fabric, H3 Max Lip Sync, Sync, and render are paid.\\n- **Existing-video edits use their own category**: call `edit_video` or `videodraft edit video` with a `video_edit` model when transforming the source itself. Kling O3 also has a reference-generation mode that creates a new guided clip. Wan 3.0 is a text/frame/reference generation model, not a source-video editor. Motion transfer similarly uses `generate_motion_control_video` or `videodraft edit motion` with a `motion_control` model.\\n- **Upscaling preserves rather than redesigns**: use Topaz when resolution, detail, or cleanup is the problem (generative mode by default: Wonder 3.5 / Starlight Precise 2.6, Topaz\'s pick for AI sources; precision for real photos/footage or the cheapest pass; creative only for an artistic reinterpretation; `interpolate` for frame rate or slow motion). Regenerate or edit when the subject, text, framing, continuity, or motion is wrong. Upscale a low-quality avatar portrait before Fabric; do not render a new avatar at 480p just to upscale the result.\\n- **Timeouts on the one-shot create**: if `create` times out at the transport layer, the project was still created server-side \u2014 `videodraft projects list`, take the most recent, and resume with its id. Don\'t start a duplicate.\\n\\n## User-attached media: classify roles first\\n\\nFor EACH attached file decide:\\n\\n- **visual_asset** \u2014 recurring reference (character / product / location / style). Upload, then pass in `visual_assets` of `generate_storyboard_from_idea` (via `videodraft call`), or add to an existing project with `add_visual_assets`. Type must be one of `character | object | location | style | custom` with a short name + concrete description.\\n- **shot** \u2014 the media IS footage for the video. Whole video = footage \u2192 `generate_storyboard_from_media`. Idea + footage \u2192 `generate_storyboard_from_idea` with `shot_media`. Existing storyboard \u2192 `attach_media_to_shots`.\\n- **reference** \u2014 inspiration only \u2192 fold a description into the idea/instructions; don\'t place it as a shot or asset.\\n\\nAmbiguous (e.g. a person holding a product)? Ask the user.\\n\\nUploads persist in the media library \u2014 recall later with `videodraft media list`.\\n\\n## Editing project data safely\\n\\n1. `videodraft call get_project_schema` \u2014 read the structure once per session.\\n2. `videodraft projects get <id> --raw` \u2014 the exact editable blob.\\n3. Modify; then `videodraft call update_project --stdin` with `{\\"project_id\\": \\"...\\", \\"data\\": {...}}`.\\n   - Objects deep-merge key-by-key; **arrays replace wholesale** \u2014 send the complete array you\'re changing (e.g. all of `storyboard.scenes`).\\n   - Scene shot arrays (`image_prompt` / `shot_types` / `shot_actions` / `search_prompt` / `preview_media`) are auto-aligned; fix-ups come back as warnings.\\n4. Snapshot before risky edits: `videodraft checkpoint create <id> --name \\"before re-script\\"`. Restore with `videodraft checkpoint restore <id> <version>`.\\n\\n## AI Studio sessions (standalone generations)\\n\\nProject generations group automatically, and standalone work is grouped per conversation (MCP) or per working directory (CLI) by the connection session \u2014 see the \\"AI Studio sessions\\" section of SKILL.md. Once the task is clear, give that automatic session a concise 3-6 word title before the first generation:\\n\\n```bash\\nvideodraft sessions name \\"Fox Brand Explorations\\"\\nvideodraft generate image \\"...\\"\\n```\\n\\nNaming creates the session with that title. If generation, a user, or an earlier agent created it first, the existing name is preserved. The command refuses to run while `VIDEODRAFT_SESSION` is set, because that override would send later generations to a different session. Use `sessions create` plus `--session` only to continue or deliberately create a separate group.\\n"}');
+  if ('{"SKILL.md":"---\\nname: videodraft\\ndescription: Create and edit AI videos, images, 3D meshes, Seed Audio, voiceovers, music, sound effects, dialogue, dubbing, storyboards, avatar videos, media upscales, and product/ad videos with VideoDraft. Use whenever the user mentions VideoDraft; asks to generate a video, image, 3D asset, audio asset, ad, explainer, storyboard, avatar, upscale, or batch/CI workflow; wants to download a video from YouTube, Instagram, TikTok, X or another site; or wants to assemble, cut, caption, mix, lay out, inspect, or export a native VideoDraft Editor timeline. Covers the cloud `videodraft` CLI/MCP and local headless `videodraft_editor` MCP. When the editor MCP is exposed, prefer it for production, timeline assembly, and export; use cloud production/export only when explicitly requested or the editor is unavailable.\\n---\\n\\n# VideoDraft\\n\\nVideoDraft is an AI video creation platform where asset generation is the priority lane:\\n\\n- **Asset generation**: standalone images, video clips, Seed Audio, voiceovers, music, sound effects, dialogue, voice-changed audio, dubbed media, upscales, and image descriptions. This is the fastest and most important lane. Treat these as complete deliverables when the user asks for assets.\\n- **Asset I/O**: upload local files, download outputs, auto-upload local references, and save generated media where the user can see it.\\n- **3D assets**: standalone Meshy 7 and Tripo H3.1 meshes, multi-view generation, complete artifact downloads, and Meshy humanoid rigging through MCP/CLI. Read [references/3d.md](references/3d.md), or `videodraft skills show 3d`. These assets have their own saved library and do not require an AI Studio session or web viewer.\\n- **Native editing**: local `.vdproject` timelines, cuts, layouts, captions, effects, audio, and exports through the headless VideoDraft Editor. Inside VideoDraft ADE, this is the default production and export lane whenever `videodraft_editor` is available.\\n- **Hosted project production**: idea \u2192 script \u2192 storyboard \u2192 hosted production timeline \u2192 exported MP4. Use the early stages for scripts, storyboards, and generated assets when useful. Treat hosted production and export as a fallback when the native editor is unavailable, or as an explicit destination when the user asks for an editable web project or hosted workflow.\\n\\n## How to connect\\n\\nGeneration billing is selected in VideoDraft Settings \u2192 API keys. Where enabled,\\n**VideoDraft routing** chooses an equivalent provider internally without changing\\nthe quoted customer credit price. A selected personal key is exclusive: never\\nswitch to VideoDraft credits or another key after an unsupported-model or\\nprovider error. Keep the canonical VideoDraft model ID in CLI/MCP calls. Poll\\nthe original generation after a timeout instead of starting another paid job.\\nNew provider connections can support only a subset of models and settings;\\nfollow the server\'s availability response. ElevenLabs remains audio-only.\\nFor Pika GPT Image 2.5, supply an explicit quality (`low`, `medium`, `high`,\\n`xhigh`, or `max`); `auto` is not supported by that connection. Nano Banana 2\\nLite is 1K only. Never remove requested controls or substitute a different\\nmodel merely to make a personal connection accept the job.\\n\\nCloud generation has two equivalent surfaces (same backend, credits, and hosted projects). Native timeline editing is a separate local surface:\\n\\n1. **CLI** (preferred when you have a shell): run `videodraft` if it\'s on PATH; otherwise `npx -y videodraft@latest` runs it with no install (needs Node \u226520; the `-y` skips npx\'s install prompt so it runs non-interactively; the package is fetched on first use and cached). For heavy use, `npm install -g videodraft`. If there\'s no Node/shell here but the MCP connector below is available, use that instead; if neither works, tell the user how to install (https://videodraft.ai/cli).\\n   - Auth \u2014 pick by context, don\'t guess:\\n     \u2022 INTERACTIVE (a human is in the session, e.g. Claude Code / Codex): on exit code 3 (\\"not authenticated\\"), tell the user to run `videodraft login` in their terminal \u2014 it opens their browser for a one-click VideoDraft sign-in (OAuth), no key to copy. Wait for them to confirm it succeeded, then retry the command. This is the preferred path when the user is present.\\n     \u2022 HEADLESS / CI (no browser): set `VIDEODRAFT_API_KEY=vd_mcp_...` (a token the user mints at https://app.videodraft.ai/mcp-keys).\\n     \u2022 SECURITY: never ask the user to paste a `vd_mcp_...` token into the chat \u2014 use browser `login` or the env var so the token never lands in the transcript.\\n   - Every command accepts `--json` (parse this, don\'t scrape text). Exit codes: 0 ok, 1 error, 2 usage, 3 auth (see Auth above), 4 insufficient credits (\u2192 tell the user, don\'t retry).\\n   - Tool discovery: start with `videodraft tools list` for the grouped catalog, then narrow with `videodraft tools list --lane assets`, `--lane asset_io`, `--lane project_data`, or `--lane production`.\\n   - Asset lane: `videodraft generate ...`, `videodraft edit video|motion`, `videodraft avatar ...`, `videodraft upscale ...`, `videodraft interpolate ...`, `videodraft upload`, and `videodraft download`.\\n   - Full API access: `videodraft tools schema <name>`, `videodraft call <tool> --args \'<json>\'`.\\n2. **MCP connector**: if VideoDraft MCP tools (e.g. `generate_storyboard_from_idea`) are available, call them directly \u2014 the CLI\'s curated commands map 1:1 onto these tools.\\n3. **Native editor MCP** (`videodraft_editor`): prefer this for project production, timeline assembly, cutting, layouts, transitions, captions, audio placement, and final export. Inside VideoDraft ADE on a supported Mac, Claude, Codex, OpenCode and Grok receive it automatically in both Code and VideoDraft modes. It runs headlessly, so an Open Editor click is not required. Start with `project_manage` (`operation: \\"project\\"`, action `list`, `open`, or `create`); standalone asset generation remains in the cloud CLI or MCP.\\n\\nSend native editor edits serially, batching everything a request needs into one `edit_apply` recipe. Pass the latest `context` when a person may be editing at the same time, so a stale write is refused. See [references/editor.md](references/editor.md) for project selection, media import, timing units, edit recipes, verification, export, and the `videodraft-editor` terminal bridge.\\n\\nIf you are reading this skill through `videodraft skills show skill`, run `videodraft skills show editor` before native editor work to load that reference.\\n\\n**VideoDraft ADE routing rule:** the presence of `videodraft_editor` means the native editor is ready, even when no editor window is visible. Use cloud tools to generate or source assets and, when helpful, scripts or storyboards. Do not call hosted `produce_project` / `videodraft produce` or `export_video` / `videodraft export` by default. Import the assets into the native project, assemble there, and export with native `delivery_manage` `submit`. Use hosted production/export only when the user explicitly asks for the web workflow or the native editor tools are unavailable. Do not silently fall back to hosted production after a native tool error.\\n\\n## First decision: asset, hosted project, or native edit?\\n\\n- **One standalone asset** (image, clip, voiceover, music track, sound effect, dialogue track, voice-changed file, dubbed media file, upscale, or description): generate it directly. Do NOT create a project.\\n  - `videodraft generate image \\"a red fox in snow, cinematic\\" --ar 16:9 --download ./out/`\\n  - `videodraft generate video \\"slow dolly over a misty lake\\" --model gemini-omni-1.1-flash --duration 6 --download ./out/`\\n- **Any final video, production timeline, existing footage, local `.vdproject`, or hands-on edit**: use `videodraft_editor` when available. List or open the intended local project, or create a native project for a new production. The editor can work without showing its UI.\\n- **A small set of related assets**: still stay in the asset lane. They are grouped automatically (see [AI Studio sessions](#ai-studio-sessions)); give the current group one useful task-specific name with `videodraft sessions name \\"<name>\\"`. Switch to a project only when the deliverable matches the project criteria below or the user asks to attach the assets to one.\\n- **A generated multi-scene video / ad / explainer**: when the editor is available, use hosted tools only for any needed script, storyboard, shot planning, or generated assets; stop before hosted production, import the assets, and build/export the native timeline. A hosted project is optional unless the user wants the web project or its storyboard workflow.\\n- **A hosted web project or hosted export**: use the hosted pipeline only when the user explicitly asks for it or the native editor is unavailable.\\n- **Just a script** (no video asked for): A script-only request creates a script-stage project but stops at the script. Use `videodraft create \\"...\\" --script-only`; do not build a storyboard the user didn\'t ask for.\\n- **Iterating on existing work**: identify the surface first. Use `project_manage` `project` with `action: \\"list\\"` for native projects and `videodraft projects list` only for hosted work. Never create a replacement project just to change an existing one.\\n\\n## Choose the model from the task\\n\\nIf the user names a model, use it when compatible. If it cannot handle the request, explain why and recommend alternatives instead of silently switching. Otherwise inspect the inputs, duration, audio, quality, speed, and cost, check the live catalog, and pass an explicit model.\\n\\n### Seedance 2.x real-person rule\\n\\nSeedance 2.0 and 2.5 allow real people by default, the same as AI Studio:\\n\\n- The default is true. Generation tries Byteplus first and can fall back to Fal, which allows real-person likenesses, so a person in the prompt, a start frame, end frame, reference image, or reference video does not hard-fail. The request is charged at Fal\'s higher tier-specific rate even if Byteplus serves it.\\n- Turn it off for the cheapest run, only when the user wants that and nothing in the job is a real identifiable person (text-only requests, non-people, anime, clearly synthetic or stylized characters). For MCP use `allow_real_people: false`. For the CLI use `--no-allow-real-people`. That pins the job to the lower-priced Byteplus path, and a Byteplus likeness-policy refusal does not fall back to Fal. Pass the same value to `get_model_costs` or `videodraft costs` so the estimate matches the charge.\\n- If a request made with the option off fails with code `SEEDANCE_REAL_PERSON_OPT_IN_REQUIRED`, estimate the higher rate, follow the user\'s spend-confirmation preference, and retry exactly once with the option on. The structured recovery fields are `retryable: true`, `retry_with: { allow_real_people: true }`, `cli_flag: \\"--allow-real-people\\"`, and `retry_policy: \\"once\\"`. CLI `--json` submit errors expose them under `details`; `status` and `wait` include them on the failed job result. Do not treat an unrelated moderation or provider error as that signal.\\n- Do not loop when the option was on. Byteplus can accept a task and reject its generated output later. VideoDraft refunds that failed generation, but the late asynchronous failure cannot be rerouted to Fal. Rephrase the prompt or use different references before trying again.\\n- For hosted AI Production, the same default applies to every Seedance scene segment: `produce_project` with `mode: \\"full_video\\"` and `videodraft produce <project> --mode full_video` allow real people unless you pass `allow_real_people: false` or `--no-allow-real-people`. If an earlier run with the option off partially submitted and returns the opt-in code, rerun that same project once with an explicit `allow_real_people: true` / `--allow-real-people`. The server reconciles asynchronous results first, preserves running/completed jobs, and resubmits only failed scene-video placeholders carrying the exact opt-in signal. Keep the native-first VideoDraft ADE routing rule above: hosted full-video production is still explicit/fallback-only when the local editor is available.\\n\\n**How to pick a model. Follow this order every time:**\\n\\n1. The user named a model: use it, never substitute.\\n2. Otherwise pick a **Tier 1** model.\\n3. Use a **Tier 2** model only when no Tier 1 model supports the request, and say why. Never pick Tier 2 on your own for price, speed, novelty or variety.\\n\\nTier 1: images `nano-banana-2`, `nano-banana-pro`, `nano-banana-2-lite`, `gpt-image-2.5-flare`, `gpt-image-2.5-sunburst`, and `recraft-v4` for vector/SVG only; videos `gemini-omni-1.1-flash`, `seedance-2.5`, `seedance-2`, `kling-3.0`, `kling-o3`, `minimax-h3-max`; video edits `gemini-omni-1.1-flash`; talking-head portraits `veed-fabric`, `minimax-h3-max-lipsync`; motion transfer `kling-v3-motion-control`; audio ElevenLabs for speech tools, Lyria 3.5 for music at any length.\\n\\nTier 2 is every other catalog model (`wan-3.0`, `flux-3`, `minimax-h3`, `kling-v3-turbo`, `kling-2.6-pro`, `grok-imagine-video-1.5`, `happy-horse`, Veo 3.1, Sora, Seedream, Grok Imagine images, FLUX images, `sync-lipsync-2` and the rest). All of them stay available by name. Real Tier 2-only jobs: document or web-page references (`wan-3.0`), keyframes pinned to timestamps (`flux-3`), re-syncing existing footage (`sync-lipsync-2`).\\n\\nEvery `videodraft models image|video|audio --json` entry carries `tier` (1 or 2), and the top-level `recommended` array is Tier 1, best first. That catalog beats this page when they disagree.\\n\\n**Speech in video:** write the dialogue in the video prompt. `gemini-omni-1.1-flash`, `seedance-2.5`, `seedance-2`, `kling-3.0` and `kling-o3` speak it natively. For a specific voice add a Seedance reference audio clip (`--ref-audio`) or a Kling bound voice. Do not plan silent video + TTS + lip-sync. Lip-sync tools are only for a portrait presenter talking to camera, or for re-syncing footage that already exists. Off-screen narration and voiceover are unaffected: keep using `generate voiceover` for those.\\n\\n**Images:**\\n\\n- `nano-banana-2`: general default, editing, consistency, and references.\\n- `nano-banana-pro`: maximum quality. `nano-banana-2-lite`: fast, inexpensive drafts.\\n- `gpt-image-2.5-flare`: replaces the GPT Image 2 recommendation for posters, logos, signs, title cards, readable text and composition. Use `gpt-image-2.5-sunburst` for extra precision/detail. Both use the same basic options as GPT Image 2: references (up to 16), aspect ratio, 1K/2K/4K resolution, image count (1-4), and quality. Quality adds xhigh/max; auto is charged at the max tier. Other model recommendations are unchanged; explicit `gpt-image-2` requests still use GPT Image 2.\\n\\n**Videos:**\\n\\n- `gemini-omni-1.1-flash`: general default for 3-10s generation, image-to-video, uploaded source edits up to 10s, and silent or voiceover-backed shots (audio is always on, so describe quiet ambience with no speech and mute or mix it on the timeline; only a file with no audio track at all needs `kling-3.0`, `kling-o3` or Seedance with `--no-audio`). It supports first and last frames, up to 10 total image inputs, up to 3 creative reference videos of at most 3 seconds each on `--video-task generate` ONLY, uploaded-video extension, and continuation of an earlier generation through `--previous-interaction-id`. Output is 360p/720p/1080p/4K at 3/10/15/30 cr/s with audio always on. Use `--source-video` for the uploaded edit/extension source; extension sources must be 1-30s. Edit and extend accept EXACTLY ONE input video, so `--ref-video` cannot accompany `--source-video` or `--previous-interaction-id`; only `--ref` images can. One `--ref-video` with no separate source remains a legacy source edit. A previous interaction defaults to conversational edit; add `--video-task extend` or `--extend` with an explicit 3-10s duration to append at the end. A continuation resolves to the prior turn\'s output and is submitted as an ordinary source, so the same limits apply to it: at most 30s to extend, at most 10s to edit. 40 seconds total is reachable, but only by extending from a source of 30s or less, so a ladder dead-ends once it passes 30s. New dialogue can only be added when the SOURCE video is silent; adding speech on top of a source that already contains speech is refused with \\"the model is currently unable to process speech edits\\". The server safely measures creative-reference durations, or you can repeat `--ref-video-duration` when a host blocks metadata probing. Fal BYOK supports its currently callable v1.1 generation and basic-edit endpoints at zero VideoDraft credits, but Fal does not expose continuation/extension or mixed source-edit references as callable endpoints and VideoDraft must never fall back to paid Google.\\n- `grok-imagine-video-1.5` (Tier 2): 1-15s text, first-frame, or 1-7 reference-image generation with native audio. Text/first-frame modes support 480p, 720p, and 1080p; reference mode supports 480p/720p. Cite references as `<IMAGE_0>` through `<IMAGE_6>`. It has no last frame, seed, negative prompt, quality tier, reference video, or reference audio.\\n- `minimax-h3` (Tier 2): 480p/768p/2K/4K (5/6/13/16 cr/s, 768p default), native stereo audio, and 5-15s text, first/last-frame, or mixed-reference generation. Reference mode accepts up to 9 images, 3 videos, and 3 audio clips, with at most 12 files total. Cite them as `Image 1`, `Video 1`, and `Audio 1` in array order.\\n- `minimax-h3-max`: 480p/768p pricing (5/8 cr/s, 768p default), native audio, and 5-15s text, first/last-frame, or mixed-reference generation. Reference mode accepts up to 9 images, 3 videos, and 3 audio clips, with at most 12 files total, cited as `Image 1`, `Video 1`, and `Audio 1` in array order. It supports a reproducibility seed and `disabled` / `balanced` / `quality` prompt expansion.\\n- `wan-3.0` (Tier 2): unified 2-30s text, first/last-frame, or ordered mixed-reference generation at 480p/720p/1080p (7/14/28 cr/s), with optional native audio. Reference mode accepts up to 10 images, 5 videos, and 5 audio clips, at most 20 media files total; video and audio each total at most 15 seconds. `--auto-duration` reserves 30 seconds and reconciles to the provider-reported output length. Document/web references use `--file-url` or `--web-url` and require `--thinking`.\\n- `flux-3` (Tier 2): Black Forest Labs FLUX 3. 5-20s at 720p/1080p with 24fps native audio, from a prompt, a first frame, first + last frames, or up to 10 keyframes pinned to specific moments (`--keyframe shot.png@2.5`, repeatable). `--quality draft` renders the same shot at 720p for roughly a third of the cost. Auto duration is text/first-frame only.\\n- `seedance-2`: 11-15s, video/audio/mixed references, wider ratios, selectable audio, or first/last frames. `mini` is the economical default; move to `standard` when the user asks for high quality, when a Mini result is not good enough, or for 1080p/4K; `fast` for speed.\\n- `seedance-2.5`: 4-30s single takes and up to 50 references (30 image, 10 video, 10 audio). Same modes as 2.0, one quality tier, 480p/720p/1080p. Reach for it when a shot must run past 15s or carry more references than 2.0 allows.\\n- `kling-o3`: reference images plus structured image/video elements, first/last frames, multi-prompt, audio control, or 4K. O3 allows 7 combined image references and image-backed elements, reduced to 4 combined items when a video-backed element is present. `kling-3.0`: image-to-video can use structured image/video elements and bind a custom Kling voice ID to either element form. Tier 2, by name: `kling-v3-turbo` (fast polished 3-15s with first frame, multi-prompt, and audio, but no elements) and Kling 2.6 Pro (top-level voice IDs cited as `<<<voice_1>>>` and `<<<voice_2>>>`).\\n- Existing-video edits use `videodraft edit video`, not generic generation. `gemini-omni-1.1-flash` is the preferred edit model and is chosen automatically when you omit `--model`: source up to 10s, up to 10 reference images, 360p/720p/1080p/4K with audio. Creative `--ref-video` inputs are NOT accepted on an edit, because an edit takes exactly one input video; use `generate video --video-task generate` to guide a new clip with video references instead. Omitting `--model` on a longer or unmeasurable source spends nothing and prints a priced menu (what each model edits, what it drops, what it costs) so you can put the choice to the user. **Truncation:** only Gemini refuses an over-length source. Happy Horse silently edits just the first 15s, Kling O3 the first 10s, and Grok the first 8s. The command warns you when that will happen; always relay it to the user. Gemini regenerates the audio track, so use Happy Horse or Kling O3 with `--preserve-audio` when the source audio must survive. Choose Grok for the cheapest prompt-only edit, Happy Horse for up to 5 image references, or Kling O3 for controlled reference-image edits.\\n- To edit a source longer than 10s without losing its tail, cut it into <=10s pieces in the native editor, edit each with Gemini, and reassemble. VideoDraft has no server-side split/concat, so this path needs `videodraft_editor`.\\n- Kling O3 also has a reference-generation mode. Use `videodraft generate video --model kling-o3-video-ref-edit` with exactly one `--ref-video` to generate a new guided clip; use `videodraft edit video` when changing the source itself. For new mixed-reference generation use Seedance 2 / 2.5.\\n- Motion transfer uses `videodraft edit motion` with Kling V3 by default, or Kling 2.6 when explicitly requested or lower cost matters. It requires a subject image and a motion-reference video.\\n- Veo 3.1, Sora, Grok, Happy Horse and the other Tier 2 video models: only when explicitly requested or when no Tier 1 model fits.\\n\\n**Audio and utilities:**\\n\\n- Use Seed Audio 1.0 for open-ended text-to-audio, speech/music/sound synthesis, voice conditioning, or prompt-driven editing with up to three audio references or one image. Use `videodraft generate audio`. Reference clips are `@Audio1`, `@Audio2`, and `@Audio3` in array order. There is no duration input. Output is up to two minutes and settles at 19 credits per actual minute, with up to 38 credits reserved during generation. The CLI automatically retries transient responses with one operation key. To recover after the CLI process itself is interrupted, set `--idempotency-key <uuid>` on the original command and reuse it.\\n- Prefer ElevenLabs for voiceover, dialogue, voice changing, dubbing, and sound effects. Honor an explicitly selected supported TTS voice/provider. Use `lyria-3.5` for all music, short or long (up to ~3 minutes, 10 credits flat), with vocals/lyrics or instrumental arrangements. When `--model` is omitted the CLI sends no model and the server default applies, which is `lyria-3.5` wherever the backend supports it. If the server answers that `lyria-3.5` is an unknown model, that backend predates it: rerun without `--model` (the server default then applies), or use `lyria-3-pro-preview` for a track longer than 30 seconds. Ask for the length in the prompt. Keep `lyria-3-clip-preview` (fixed ~30s, 4 credits) and `lyria-3-pro-preview` (8 credits) for explicit requests. For Lyria, put desired length, lyrics and \\"instrumental only, no vocals\\" in the prompt; `--length` and `--instrumental` are ElevenLabs-only. Use ElevenLabs Music for exact timing, composition plans, or a style reference track. Lyria allows 10 reference images on Google, 1 on Fal BYOK; Fal 3.5 prompts are limited to 5000 characters. BYOK uses zero VideoDraft credits. ElevenLabs Music means `elevenlabs-music-v2.5` (`elevenlabs-music` is an alias for it); use `elevenlabs-music-v1` only when the user asks for v1 by name.\\n- ElevenLabs voiceover runs on Eleven v4 in two modes. Standard is the default and the best quality, at 10 credits per 1000 characters. Turbo (Eleven v4 Turbo) is faster, at 5 credits per 1000 characters. Keep Standard unless the user wants faster or cheaper speech. Pick it with `generate voiceover --mode standard|turbo`, `produce --voice-mode standard|turbo`, or MCP `generate_voiceover.mode` / `produce_project.voice_mode`, and quote Turbo with `costs voiceover --chars <n> --mode turbo`. Google, OpenAI and cloned `custom-*` voices ignore the mode (cloned voices cost 30 per 1000). v4 has no style or speed settings and no SSML `<break>` tags; audio tags such as `[whispers]` work. Dialogue stays on Eleven v3.\\n- For ElevenLabs voiceover, dialogue, and voice changing, accept a supplied raw voice ID (16-64 alphanumeric characters) or `elevenlabs-<id>`. The voice catalog is for discovery, not an allowlist. Do not reject or substitute a supplied ID because it is absent from `videodraft models voices` / `list_available_voices`. Use `--voice <id>` for voiceover and voice changing, or repeat `--line \\"<id>:Text\\"` for dialogue; for example, `--voice kPzsL2i3teMYv0FxEYQ6` and `--line \\"elevenlabs-kPzsL2i3teMYv0FxEYQ6:Hello.\\"` use the same voice. The voice must be accessible to the provider account used for generation. Private or cloned voices may require the user\'s connected ElevenLabs key. Kling video-control IDs and MiniMax `custom-*` IDs are separate voice systems.\\n- A character who needs to TALK:\\n  - **Speaking inside a scene**, or any ordinary clip with dialogue: `generate video` with the line in the prompt, in quotes, with who says it and how. `gemini-omni-1.1-flash`, `seedance-2.5`, `seedance-2`, `kling-3.0` and `kling-o3` all voice it natively. For a specific voice use a Seedance `--ref-audio` clip or a Kling voice bound per element. This is the default path; do not generate speech separately and lip-sync it on.\\n  - **Talking to camera from a portrait** (presenter, spokesperson, explainer): the avatar lane, and VEED Fabric is preferred. Use managed `avatar create` then `avatar render` for a reusable avatar record with bundled speech, `avatar fabric` for a one-off portrait plus text or existing audio, and `avatar h3-lipsync` for a short (5-14.8s) portrait clip from existing audio at up to 2K. Not for in-scene shots: Fabric animates a portrait facing the lens, so a cinematic request comes back as a head-on talking headshot.\\n  - **Footage that already exists plus replacement audio** (re-dub, translation): `avatar lipsync`. This is the only job for Sync Labs unless the user names it.\\n- Enhancement: use Topaz image/video upscaling only when the content is already correct. Use image 1x for cleanup, 2x by default, 4x when justified; use video 2x by default. Edit or regenerate creative errors.\\n\\nSee [references/models.md](references/models.md) for the detailed routing table and exact capability limits.\\n\\nProvider routing uses a maintained local price catalog, with exact setting compatibility and account rules. Platform requests prefer Google\'s direct image/video APIs and BytePlus for Seedance 2.0/2.5 before comparing public prices. Seedance 1.5 retains its existing Replicate primary; other models remain price-based. Agents should keep using normal model IDs and `get_model_costs` / `--estimate` for customer credits. Do not choose a vendor from a marketing starting price or retry an accepted generation to chase a lower price. Unknown or expired comparable costs retain the existing route; a selected personal provider key stays exclusive and overrides platform-account preferences.\\n\\nTemporary provider promotions are excluded from routing prices. With an Atlas personal key, H3 Max supports text or first/last-frame generation at 480P/768P only with `prompt_expansion_mode: \\"disabled\\"` and no seed. Balanced/quality expansion, reference generation and H3 Max Lip Sync require the existing Fal path. Atlas H3 Max is not selected automatically while its published price units remain inconsistent.\\n\\n## Matching AI Studio controls\\n\\nUse `models image --json` / `models video --json` for the accepted options. Nano Banana Pro/2 expose `--temperature 0..2` and `--google-search-grounding true|false`. Qwen uses one `--ref` plus `--horizontal-angle 0..360`, `--vertical-angle -30..90`, and `--zoom 0..10`; its text prompt is optional. Recraft generates SVG and accepts `--quality Normal|Pro`, repeatable `--recraft-color \'#RRGGBB\'`, and `--recraft-background \'#RRGGBB\'`. Original Nano Banana and VideoDraft Image use fixed 1K output.\\n\\nKling 3.0 / 2.5 Pro accept `--cfg-scale 0..1` and `--negative \\"\\"` to clear a negative prompt. Seedance 2/2.5, Wan 3.0, FLUX 3 text/first-frame and Gemini Omni generation accept `--auto-duration`; do not combine it with `--duration`. FLUX 3 auto reserves 20 seconds, so its default estimate includes that ceiling. `--model sora-2 --quality pro --resolution 1080p` selects Sora Pro. Kling O3 reference/edit modes accept image-only `--element` objects, at most four combined with `--ref`. Grok v1 accepts image references for clips up to 10 seconds.\\n\\nTopaz image results may be immediate or queued. The CLI waits by default and downloads either result with `--download`; `--no-wait` returns a queued job ID. Raw MCP callers must poll `check_generation_status` when `upscale_image` returns `job_id`.\\n\\n## Prefer references when continuity matters\\n\\nPure text-to-image or text-to-video is fine for a generic one-off asset. When a specific character, product, location, style, composition, or brand identity must survive generation, use references instead of hoping the prompt recreates it.\\n\\n- If the user supplies reference media, preserve and pass it. Never reduce the request to text alone.\\n- When continuity matters, generate/select a strong still first with the selected image model (`nano-banana-2` by default), wait for its URL, then animate it as a start frame/reference. Confirm the combined image and video cost.\\n- When using a hosted storyboard stage for multiple shots, use `videodraft shots <project_id> --model <selected-image-model> --grid`, then animate the decoded shots. Preserve explicit models. In VideoDraft ADE, import the resulting assets into the native editor instead of continuing into hosted production. A requested non-Seedance video model must use manual per-shot generation instead of Seedance full-video mode.\\n\\n## Cost and credits\\n\\nDo not call `videodraft credits` before routine generations. Paid endpoints validate and deduct atomically; if the balance is insufficient, the request is rejected before the provider job starts (CLI exit code 4). Check the balance only when the user asks, gives a credit budget, or a large workflow needs budget planning.\\n\\nFor expensive work, estimate with `--estimate` or `videodraft costs`, state the selected model/settings/cost, and get a go-ahead. This matters most for shot-image batches, long or high-resolution video, AI Production, and paid audio batches. Honor the user\'s confirmation preference for the session.\\n\\nKling voice creation costs 1 VideoDraft credit on the platform Fal account and 0 credits with Fal BYOK. Preview it with `videodraft kling-voices create <sample> --name <name> --estimate`; the estimate does not create a voice or require consent confirmation. Actual creation requires `--confirm-consent`.\\n\\nMiniMax H3 costs 5 / 6 / 13 / 16 credits per output second at 480p / 768p / 2K / 4K (768p by default). In reference mode the first 5 images are included and each additional image costs 8 credits. Reference video and reference audio are NOT billed.\\n\\nMiniMax H3 Max costs 5 credits per output second at 480p and 8 credits per second at 768p (default), plus pooled reference tokens in reference mode: the first 4,096 are free and every 1,000 after that costs 2 credits, where an image is `(width x height) / 1024` tokens, a reference video is 2,886 tokens per second at 480p or 7,459 at 768p, and reference audio is about 2,121 per second. Use `--prompt-expansion-mode disabled|balanced|quality`; balanced is the default. Fal\'s provider safety checker is OFF by default and is not exposed in the app \u2014 only pass `--safety-checker true` if the user explicitly asks for it.\\n\\nWan 3.0 costs 7 / 14 / 28 credits per output second at 480p / 720p / 1080p. Auto duration reserves the 30-second maximum and refunds the unused reserve after the provider reports the actual whole-second output length. Fal BYOK runs on the connected user key and charges zero VideoDraft credits.\\n\\nGrok Imagine Video 1.5 costs 8 credits per output second at 480p, 14 at 720p, or 25 at 1080p, plus 1 credit for each first-frame or reference image. Native audio is always generated.\\n\\n`videodraft models image|video` lists the live image and video catalogs with supported inputs. Video entries are grouped as `generation`, `video_edit`, `motion_control`, `avatar_lipsync`, and `upscale`, and each reports the exact tool. Use `videodraft models video --category video_edit` to narrow the list. `videodraft models audio` lists Seed Audio, Google Lyria, and ElevenLabs audio/media tools, while `videodraft models voices` helps discover TTS voices. Consult them for capabilities; a supplied ElevenLabs voice ID does not need to appear in the voice catalog.\\n\\n## Async jobs\\n\\nImage/video generation is asynchronous: commands submit a job and **wait by default**, printing output URLs (and saving files with `--download`). Large downloaded images also get a downscaled copy in `previews/` next to them (the `preview` field / \\"inspect via preview\\" line in the output) \u2014 **look at the preview, deliver the original**; viewing full-resolution images bloats the chat permanently. In scripts/CI prefer explicit control:\\n\\n```bash\\nJOB=$(videodraft generate image \\"...\\" --no-wait --json | jq -r .job_id)\\nvideodraft wait \\"$JOB\\" --download \\"./outputs/{job_id}_{index}.{ext}\\" --json\\n```\\n\\nFor MANY jobs: submit each with `--no-wait`, collect ALL with one command \u2014 `videodraft wait <id1> <id2> ...` polls every job from one process with one batched request per tick. Do NOT spawn parallel `wait`/`generate --wait` processes for a batch.\\n\\nIf a wait times out, the job is still running server-side \u2014 `videodraft status <job_id>` later. Never re-submit just because a wait timed out (that double-spends credits).\\n\\nFor completed Wan 3.0 jobs, MCP `check_generation_status` and CLI `status`/`wait --json` include `outputMetadata` with Fal\'s returned `seed`, `duration`, and `actual_prompt` when present.\\n\\n## AI Studio sessions\\n\\nStandalone image/video/audio generations are filed into an AI Studio session in the web app. 3D assets use `assets 3d list/get` separately. You do not have to create an AI Studio session:\\n\\n- **MCP hosts** (Claude Code, claude.ai, Codex, VideoDraft ADE): on 2025-era MCP the server mints an `Mcp-Session-Id` on `initialize`; your host echoes it, and this conversation\'s generations land in their own session. On stateless MCP (2026-07-28) hosts that send a conversation id (ChatGPT) get the same. Otherwise `name_current_ai_studio_session` returns `pass_session_id: true` with a `session_id`: pass that `session_id` to every later standalone generation in the conversation. Tool results echo the session as `ai_studio_session_id`.\\n- **CLI**: the same handshake runs once per (profile, server, working directory) and is cached for 12 idle hours, so everything generated from one directory shares one session. `videodraft sessions current` shows it; `videodraft sessions reset` starts a new one.\\n- Project generations (`--project <id>` / `project_id`) always go to that project\'s session.\\n\\nOnce you understand the creative task, name the current automatic session before the first standalone generation:\\n\\n```bash\\nvideodraft sessions name \\"Purple Seal Rescue Short\\"\\n```\\n\\nChoose a concise, specific 3-6 word title for the intended work. Do not copy the client name, date, or exact chat title. Name it once: the operation creates the session with that title. If generation, a user, or an earlier agent created the session first, its existing name is preserved.\\n\\nApart from the `pass_session_id: true` case above, pass `--session <id>` / `session_id` only to **continue earlier work** or create an explicit separate group:\\n\\n```bash\\nSESSION=$(videodraft sessions create \\"Fox brand explorations\\" --json | jq -r \'.session.id\')\\nvideodraft generate image \\"a red fox in snow, cinematic\\" --session \\"$SESSION\\"\\nvideodraft generations --session \\"$SESSION\\"          # what is in it\\nvideodraft sessions list --name fox                  # find it again later\\n```\\n\\n`VIDEODRAFT_SESSION=<id>` sets the default for every command (ignored when `--project` is given). While it is set, `sessions name` refuses to run because that command names the current automatic connection session, not the pinned override; unset it first or rename the pinned session in AI Studio. `VIDEODRAFT_SESSION_SCOPE=<label>` groups several directories into one connection session; `VIDEODRAFT_CLIENT_NAME=<host>` labels the fallback placeholder used when generation creates the session before `sessions name`; `VIDEODRAFT_NO_SESSION=1` disables the handshake. Generations that reach the server with no session at all fall back to the account-wide \\"Agent (MCP)\\" session; if you see work landing there, pass `--session` explicitly.\\n\\n## Generation history\\n\\nPast work is queryable \u2014 reuse a previous setup instead of guessing. `videodraft generations` lists recent generations; scope with `--session <id>` or `--project <id>` (includes collaborators\' rows in shared scopes; pass one, project wins), and filter with `--type`, `--model`, `--favorites`. `--full --json` returns each row\'s exact parameters (aspect ratio, resolution, duration, references) \u2014 the human table stays compact, so pair `--full` with `--json`. `videodraft generation <id>` prints one generation\'s complete recipe (prompt, input image, parameters, outputs); `--favorite` / `--unfavorite` stars it. `videodraft sessions list` shows AI Studio sessions (owned + shared) with `--name` search \u2014 take a session id from there to read its history.\\n\\n## Free stock footage and photos\\n\\nPexels and Pixabay are wired in through `search_stock_media` / `import_stock_media` (`videodraft stock search \\"<query>\\"`, `videodraft stock import <ref>`). Both libraries are free, watermark-free and cost **zero credits**, so use stock for b-roll, establishing shots, backgrounds and ordinary real-world footage, and spend credits on the shots that must be specific: the product, the character, the scripted action.\\n\\n```bash\\nvideodraft stock search \\"city skyline night\\" --min-duration 5 --orientation landscape\\nURL=$(videodraft stock import pexels:video:35379336 --quality hd --json | jq -r .url)\\n```\\n\\n- Always two steps. A search result\'s `preview_url` is a thumbnail for judging the shot; never place it on a timeline, attach it to a shot or send it to a model. `import_stock_media` copies the file onto the VideoDraft CDN and returns the URL every other surface accepts, including the native editor\'s `library_manage` import.\\n- `--quality hd` (default) caps video at 1080p; `4k` caps at 2160p, `best` takes the largest the provider has, `sd` suits rough cuts. Stills ignore quality and import at full size. Use `--orientation portrait` for 9:16, and `--min-resolution 1920` to drop anything below HD on its long edge.\\n- Photos come from Pexels. Pixabay contributes video only, because its full-size image host refuses server-side downloads.\\n- Credit the creator and link the provider page when you show results or deliver the finished work; both come back on every result. Skip clips that imply a person or brand endorses the product, and avoid recognisable logos in ads.\\n- Search and import are rate limited per user (30 searches and 15 imports a minute) and searches are cached for 24h, so a burst of searches while planning a montage is fine. Bulk downloading a stock library is prohibited by both providers. A note saying Pixabay was skipped means its provider budget for that minute is spent; the Pexels results still stand.\\n\\n## Downloading from YouTube, Instagram, TikTok and other sites\\n\\nVideoDraft ships no downloader. When the user asks to pull a video from YouTube, Instagram, TikTok, X, LinkedIn or anywhere else, `yt-dlp` on the user\'s own machine does the work. Check for it with `command -v yt-dlp` before promising anything.\\n\\n**Present:** pin the format. On its defaults yt-dlp takes the best stream, usually VP9 or AV1 in WebM, which the native editor\'s import rejects (mp4, mov and m4v only). This returns one pre-muxed H.264 + AAC MP4 and needs no ffmpeg:\\n\\n```bash\\nyt-dlp -f \\"b[ext=mp4]\\" -o \\"media/%(title)s.%(ext)s\\" \\"<url>\\"\\n```\\n\\n**Missing:** say so in one line, then offer `brew install yt-dlp` only where `brew` exists, and only after asking. With no Homebrew, say the tool is unavailable and stop.\\n\\n- Never install Homebrew, never `sudo`, never write to `/usr/local/bin` or `/opt`, never pipe a script into a shell.\\n- `ffmpeg` is optional, matters only above 720p, and the selector above never needs it.\\n- Auth-gated content needs `--cookies-from-browser`; raise it only after a download fails on auth.\\n- Fetch only what was asked for, never a channel, playlist or back catalogue.\\n\\n## Local files and reference images\\n\\nReference inputs must be public URLs. The CLI uploads local files automatically wherever a URL is expected (`--ref photo.jpg`, `--start-image frame.png`), or explicitly:\\n\\n```bash\\nURL=$(videodraft upload ./product.png --json | jq -r .url)\\n```\\n\\nNever silently drop a reference you couldn\'t upload \u2014 stop and tell the user. Never upload a user\'s file to a third-party host.\\n\\nWhen the user attaches media for a native production, import actual footage into the editor by default. For hosted generation/storyboarding, classify each item before acting: a recurring **visual asset** (character/product/location/style), actual **footage to place as shots**, or **inspiration only**. See [references/pipeline.md](references/pipeline.md) for the hosted role mapping.\\n\\n## Showing media to the user\\n\\nGenerated media is **not** displayed in the chat automatically \u2014 you decide what to show. To preview an asset inline, save it locally (use `--download` so it lands under `media/`) and reference its **local path** as a Markdown link with a **leading `./`**:\\n\\n```\\n[ferrari shot](./media/ferrari_01.png)     \u2190 image card\\n[the clip](./media/clip.mp4)               \u2190 video player\\n[voiceover](./media/vo.mp3)                \u2190 audio player\\n```\\n\\nPut the Markdown link **in your message text** \u2014 video and audio embed exactly like images. Do **not** use `SendUserFile` (or other file-send tools) to display media: that renders inside a collapsible tool card and gets buried in the tool list. The Markdown link in your prose is what produces the inline card.\\n\\nUse the path you saved to: a **workspace-relative** path (`./media/clip.mp4`, or `./<any-folder>/clip.mp4` \u2014 any folder in the workspace works), or the **absolute** path for a file outside the workspace (e.g. `/Users/you/Desktop/clip.mp4` or another workspace\'s path). Both render. Show the finished results worth showing (and only those \u2014 not every intermediate job). A bare CDN URL or a JSON dump of output URLs does **not** render; the local-path Markdown link is what produces an inline card.\\n\\n## Native-first VideoDraft ADE pipeline (idea \u2192 MP4)\\n\\nWhen `videodraft_editor` is present:\\n\\n1. Generate or source the script, storyboard, shot images, clips, voiceovers, music, and other assets through the cloud CLI/MCP as needed.\\n2. Call native `project_manage` (`project`, action `open` or `create`) to open or create the `.vdproject`.\\n3. Call native `library_manage` `import`, wait for imports to become ready, then assemble and refine the timeline with `edit_apply` recipes.\\n4. Call native `delivery_manage` `submit` and use its `jobs` operation for progress and results.\\n\\nDo not run the hosted production or export steps in this path unless the user explicitly asks for a web production.\\n\\n## Hosted fallback pipeline (idea \u2192 MP4)\\n\\nUse this only when there is NO native editor at all, or the user explicitly requests the hosted web\\nworkflow. The native surface is not only the injected `videodraft_editor` MCP: a `videodraft-editor`\\nexecutable on PATH is the same editor reached through its terminal bridge, and\\n[references/editor.md](references/editor.md) covers driving it that way. Treating a missing MCP as\\n\\"no editor\\" sends sessions that have the binary into hosted production for no reason.\\n\\n```bash\\nvideodraft create \\"<idea>\\" --ar 9:16            # project: script \u2192 visual assets \u2192 storyboard\\nvideodraft shots <project_id> --grid --estimate # cost preview, confirm with user\\nvideodraft shots <project_id> --grid            # batch shot images (waits, writes onto shot cards)\\nvideodraft produce <project_id>                 # voiceovers + captions + production timeline\\nvideodraft export <project_id> --download final.mp4\\n```\\n\\nOptional between produce and export: per-shot motion clips (`videodraft generate video ... --project <id>` then place it with `videodraft attach <project> --scene N --shot M --media <url|file> --type video --duration <s>`), music (`videodraft generate music \\"...\\" --attach <project_id>`), and standalone audio assets (`generate audio`, `generate sound-effect`, `generate dialogue`, `generate voice-changer`, `generate dub`). Details, per-step tools and editing rules: [references/pipeline.md](references/pipeline.md).\\n\\n## Avatar and talking-head videos (both surfaces)\\n\\nAvatar generation is cloud-only \u2014 the native editor has no avatar or lipsync tools \u2014 so this applies whether or not `videodraft_editor` is present. Generate the avatar in the cloud; in VideoDraft ADE, import the rendered clip and cut it on the native timeline like any other footage.\\n\\nAvatar/talking-head videos use dedicated commands. For a reusable managed avatar, obtain or generate a clear portrait \u2192 `videodraft avatar script` when needed \u2192 `videodraft avatar create` \u2192 `videodraft avatar render --resolution 720p`. For a one-off portrait, use `videodraft avatar fabric <portrait> --text \\"...\\"` or `--audio <file>`, or `videodraft avatar h3-lipsync <portrait> --audio <file>` for a short high-resolution clip from existing audio. For an existing video plus replacement audio, use `videodraft avatar lipsync <video> --audio <file>`. Managed script/creation is bundled/free; direct Fabric, H3 Max Lip Sync, Sync, the managed Fabric render, and optional portrait generation/upscaling are paid. Confirm expensive steps first.\\n\\n## Working with hosted project data\\n\\nA hosted project is one JSON blob (script, storyboard scenes, shot cards, visual assets, production timeline). To inspect: `videodraft projects get <id>`. To edit: fetch `--raw`, modify, then `videodraft call update_project` \u2014 objects deep-merge, **arrays replace wholesale** (send the complete `storyboard.scenes` array to change one scene). Snapshot first with `videodraft checkpoint create <id>` before risky edits. Schema reference: `videodraft call get_project_schema`. This does not replace native editor tools when `videodraft_editor` is available for the production itself.\\n\\n## More\\n\\n- [references/pipeline.md](references/pipeline.md) \u2014 hosted fallback data model and production workflow\\n- [references/editor.md](references/editor.md) \u2014 native headless editor routing, project selection, import, timeline edits, verification, and export\\n- [references/models.md](references/models.md) \u2014 choosing image/video models, pricing patterns, voices and styles\\n- [references/examples.md](references/examples.md) \u2014 recipes: batch product videos from a CSV, talking-head from a script, changelog video in CI\\n","references/3d.md":"# Standalone 3D assets through MCP and CLI\\n\\nUse this lane for downloadable meshes, textured 3D models, and humanoid rigging. These are independent of AI Studio sessions and do not require a storyboard or web viewer. Never create a project just to generate a mesh. Native editor media import does not establish support for GLB/FBX assets; use external 3D software unless the live editor schema explicitly supports them.\\n\\n## Discover and quote\\n\\n```bash\\nvideodraft models 3d --json\\nvideodraft generate 3d \\"a worn brass telescope\\" --model meshy-7 --estimate\\nvideodraft generate 3d --model tripo-h3.1 --ref ./reference.png --options @options.json --estimate\\nvideodraft rig 3d --estimate\\n```\\n\\nMCP tools: `get_3d_models`, `estimate_3d`, `generate_3d`, `rig_3d`, `check_generation_status`, `list_3d_assets`, `get_3d_asset`, `create_3d_upload`, and `finalize_3d_upload`.\\n\\nThe generator catalog is deliberately limited to `meshy-7` and `tripo-h3.1`. Both expose text/image/multi-image modes; use the live schemas for option availability, view order, limits, topology, texture/PBR, and pose controls. Do not invent common provider option names. Server defaults prioritize quality. Rigging is a separate Meshy operation for compatible textured humanoid GLBs; it is not an arbitrary creature or facial rig service.\\n\\nEvery option is accessible through `--options` JSON (`@path.json` supported), plus repeatable `--option key=value` overrides. Values parse as JSON when valid. Options and explicit input mode affect pricing, so obtain a fresh quote for the exact recipe. Estimates perform no file upload or provider generation. VideoDraft bills whole credits at 100 credits per dollar using the server\'s rounding rules. BYOK costs zero VideoDraft credits and runs on the connected user Fal key. Do not infer the user\'s Fal-account charges from a zero VideoDraft-credit quote.\\n\\n## Generate and retrieve\\n\\n```bash\\nvideodraft generate 3d \\"a worn brass telescope\\" --model meshy-7 --download --json\\nvideodraft generate 3d --model meshy-7 --ref ./hero.png --no-wait --json\\nvideodraft generate 3d --model tripo-h3.1 --input-mode multi_image --ref ./front.png --ref ./left.png --ref ./back.png --ref ./right.png --no-wait --json\\nvideodraft status JOB_ID --json\\nvideodraft wait JOB_ID --download --json\\nvideodraft assets 3d list --status completed --json\\nvideodraft assets 3d get ASSET_ID --download ./media/3d --json\\nvideodraft rig 3d --asset ASSET_ID --download --json\\nvideodraft rig 3d ./textured-humanoid.glb --download --json\\n```\\n\\nLocal image references upload automatically. Local rigging inputs must be self-contained `.glb` files and upload via the dedicated 3D route. Input mode is inferred from reference count unless `--input-mode text|image|multi_image` is supplied. A text prompt requires no images; image mode requires exactly one and no geometry prompt. Meshy multi-image accepts 1-4 views, and Tripo accepts 2-4 in front, left, back, right order. Use Meshy\'s `texture_prompt` option when texturing guidance is needed with image inputs. Do not mix unrelated images as if they were views of the same object.\\n\\nGeneration and rigging wait by default. `--no-wait` returns a persisted job that continues server-side. For many jobs use one `wait ID1 ID2 ... --download`; do not run parallel polling processes. Recover timeout with the same job ID, not another paid generation.\\n\\nSubmission returns a `request_id` UUID. A same-request retry must use `--request-id UUID` and the original arguments. The CLI journals resolved uploads in its private config directory so retries reuse the same remote files. Changed inputs under that UUID are rejected. Submission errors include the UUID in JSON `details.request_id` where available. Never retry a failed request with a new UUID until the prior job status is known.\\n\\n## Complete artifact packages\\n\\n`--download` defaults to `media/3d/<asset_id>/`. A user directory is respected and receives a per-asset folder. `{job_id}` and `{asset_id}` directory templates are accepted. Do not pass a `.glb` filename or a media `{index}.{ext}` template: a 3D result can contain multiple formats and texture/material dependencies.\\n\\nDownloads preserve every returned artifact. The manifest records provider URLs, source filenames, local paths, role, content type, and actual downloaded sizes. glTF/OBJ/MTL references are rewritten to saved dependency paths; binary GLB/FBX and provider ZIPs are retained as returned. Supplied dependency aliases become local copies at the paths needed by original FBX files. Unsafe or colliding aliases produce warnings. Existing packages are never overwritten. A successful package has `manifest.json`; read its `complete` field and `warnings`, plus CLI `package_warnings`. Do not claim a package with unresolved dependencies is ready for offline use.\\n\\nMachine results use `type: \\"model3d\\"` with `output_files` for files and `output_media` only for ordinary preview media. Texture maps and models are not image/video gallery entries. Show a supplied preview via a local image Markdown link and deliver the original mesh/package files. Do not imply an interactive 3D viewer exists in AI Studio or VideoDraft ADE.\\n","references/editor.md":"# Native VideoDraft Editor reference\\n\\nUse this reference when the user wants to assemble, cut, caption, mix, lay out, inspect, or export a local VideoDraft Editor project. The native editor is deterministic and local. Cloud generation remains in the `videodraft` CLI or hosted MCP.\\n\\n## VideoDraft ADE preference rule\\n\\nWhen `videodraft_editor` tools are exposed, treat the native editor as available and make it the default surface for production, timeline assembly, and final export. It is headless by design, so a hidden window or an untouched Open Editor button does not justify using hosted production instead.\\n\\nUse cloud tools for asset generation and optional script/storyboard work, then import the results. Do not call hosted `produce_project` / `videodraft produce` or `export_video` / `videodraft export` unless the user explicitly requests an editable web production or the native editor tools are unavailable. If a native tool call fails after the editor was available, report or recover that native failure rather than silently switching surfaces.\\n\\n## Choose the correct surface\\n\\n- `videodraft` and the hosted VideoDraft MCP generate assets and can manage hosted web projects. They use the user\'s VideoDraft account and credits. In VideoDraft ADE, use them mainly as the source of generated media and optional storyboards for the native production.\\n- `videodraft_editor` edits local `.vdproject` packages. It has no generation, account, model, or credit tools.\\n- Inside VideoDraft ADE on a supported Mac, the editor MCP is injected automatically for Claude, Codex, OpenCode and Grok in both Code and VideoDraft modes. It starts headlessly before the chat opens. The user does not need to click Open Editor, and closing or hiding the editor window does not stop headless editing.\\n- Outside that environment, use the editor only if `videodraft_editor` MCP tools are already exposed or the `videodraft-editor` executable is on PATH. Do not confuse the public `videodraft` cloud CLI with the separate native editor executable.\\n\\nPrefer the direct MCP tools when they are available. The terminal bridge is useful for scripts, diagnostics, or an agent session where the MCP was not injected.\\n\\n## Which editor tools you have\\n\\nCurrent editors expose eight workflow tools: `project_manage`, `edit_snapshot`, `edit_apply`, `edit_undo`, `library_manage`, `inspect`, `speech_apply`, and `delivery_manage`. Use them whenever `edit_apply` is available. Everything below describes them.\\n\\nEarlier editors expose a different set of tools. If `edit_apply` is not in your catalog, follow the live tool descriptions; the working rules below still apply.\\n\\nThe live tool descriptions and schemas are authoritative. When they differ from this reference, follow them.\\n\\nService tools (`project_manage`, `library_manage`, `inspect`, `speech_apply`, `delivery_manage`) take `operation` and `parameters`, plus an optional `context` (see [Keep a reliable editing model](#keep-a-reliable-editing-model)):\\n\\n```json\\n{\\"operation\\": \\"import\\", \\"parameters\\": {\\"source\\": {\\"path\\": \\"/Users/me/clips\\"}}}\\n```\\n\\n### Parameters at a glance\\n\\nEach operation\'s schema has the full list. These are the fields that matter most, and the ones most often confused:\\n\\n| Tool and operation | Key `parameters` |\\n| --- | --- |\\n| `project_manage` `project` | `action` (`list`, `open`, `create`, `close`); `id`, `name` or `path` to open; `name`, `fps`, `aspectRatio`, `quality` to create |\\n| `edit_snapshot` (no `parameters`) | `includeLibrary`, a `startFrame`/`endFrame` window, `offset`/`limit` paging, `context` for later pages |\\n| `edit_apply` (no `parameters`) | `actions`; optional `context`, `requestId`, `previewOnly` |\\n| `library_manage` `import` | `source` with one of `path`, `url`, `bytes` + `mimeType`, or `matte`; optional `name`, `folder`. A `.srt` or `.vtt` file becomes captions |\\n| `library_manage` `list` | `ids` to poll imports, `pending`, `folder` |\\n| `inspect` `timeline` | a `startFrame`/`endFrame` window; there is no clip filter |\\n| `inspect` `frame` | `startFrame` for one frame; add `endFrame` and `maxFrames` to sample a range |\\n| `inspect` `media` | `mediaRef` (a library asset, not a file path), `startSeconds`/`endSeconds` in source seconds, `wordTimestamps`, `overview` |\\n| `inspect` `transcript` | a `startFrame`/`endFrame` window, `granularity` (`words` or `segments`), `clipId` |\\n| `inspect` `color` | `clipId` with `atFrame`, or `mediaRef`; optional `reference` |\\n| `speech_apply` `words` | `words`: transcript word indices, each one index or a `[first, last]` pair; or `matches`: exact words to remove everywhere; `pacing` |\\n| `speech_apply` `silence` | none |\\n| `speech_apply` `captions` | caption `style`, `position` and look fields; it finds the speech itself. `style` `plain` (sentences without a preset) takes `positionY` or `transform.centerY`, not `position` or `punctuation` |\\n| `delivery_manage` `submit` | `mode`, `codec`, `resolution`, `outputPath` (its folder must already exist); `captionGroupId` and `wordTiming` for `srt` and `vtt`; `check: false` skips a video\'s export check |\\n| `delivery_manage` `jobs` | `action` `list` (every job with its progress, warnings, output path and check findings; with a `jobId`, that job with all its findings), `cancel` with a `jobId`, or `dismiss` with a `jobId` and optional `findingIds` |\\n\\n`previewOnly` exists only on `edit_apply`. Service operations apply immediately.\\n\\n### `edit_apply` actions at a glance\\n\\nEvery action puts its fields beside `kind`, for example `{\\"kind\\": \\"adjust\\", \\"clipId\\": \\"c1\\", \\"speed\\": 2}`. `remove`, `adjust`, `replace`, `transition`, `mask`, `text`, `grade` and `effects` take `clipId` for one clip or `clipIds` for several; `animate`, `extract`, and the rows of `move` and `split` take a single `clipId`. Advanced actions cannot take `as`, but their clip ids accept `@name`. The one exception is `transition`, whose own `kind` field names the style, so its fields go inside `parameters`: `{\\"kind\\": \\"transition\\", \\"parameters\\": {\\"clipId\\": \\"c2\\", \\"kind\\": \\"dipToBlack\\"}}`. These `actions` place a clip, warm it and add a vignette:\\n\\n```json\\n[{\\"kind\\": \\"place\\", \\"assetId\\": \\"\u2026\\", \\"atFrame\\": 0, \\"as\\": \\"shot\\"},\\n {\\"kind\\": \\"grade\\", \\"clipId\\": \\"@shot\\", \\"adjustments\\": {\\"temperature\\": 7500}},\\n {\\"kind\\": \\"effects\\", \\"clipId\\": \\"@shot\\", \\"effects\\": [{\\"type\\": \\"finish.vignette\\", \\"params\\": {\\"strength\\": 35}}]}]\\n```\\n\\n| Advanced `kind` | Key fields |\\n| --- | --- |\\n| `place_batch` | `entries: [{mediaRef, startFrame, endFrame or source, trackIndex}]`, not the concise `assetId`, `atFrame`, `durationFrames`; leave `trackIndex` off every entry for a new track |\\n| `insert_batch` | `trackIndex`, `atFrame`, `entries: [{mediaRef, durationFrames or source}]`; later clips move right |\\n| `move` | `moves: [{clipId, toFrame, toTrack}]` |\\n| `remove` | `clipId` or `clipIds`; leaves a gap |\\n| `split` | `splits: [{clipId, atFrame}]`, or `trackIndex` with `frames` |\\n| `extract` | `trackIndex` with `ranges: [[start, end]]` in frames, or `clipId` with `ranges` and `units` (`frames`, or source `seconds`); closes the gap |\\n| `adjust` | `clipId` or `clipIds` plus any of `durationFrames`, `trimStartFrame`, `trimEndFrame`, `speed`, `speedCurve` (`{preset}`, or `{points: [{t, rate}]}` with `t` from 0 to 1 along the source), `preservesPitch`, `volume`, `opacity`, `transform` (`centerX`, `centerY`, `width`, `height`, `flipHorizontal`, `flipVertical`), `blendMode` |\\n| `animate` | `clipId`, `property` (`volume`, `opacity`, `rotation`, `position`, `scale`, `crop`), `keyframes: [[frame, ...values]]` with frames counted from the clip\'s start; `position` is the top-left corner |\\n| `arrange` | `layout`, `slots: [{slot, clipIds or mediaRef, anchor}]`, `fit` (`fill` or `fit`); `mediaRef` slots also need `endFrame` |\\n| `transition` (fields inside `parameters`) | `clipId` or `clipIds` (the clip after each cut), `kind` (`crossDissolve`, `dipToBlack`, `dipToWhite`, `blurDissolve`, `push`, `linearWipe`, `whipPan`, `crossZoom`, or `none` to remove), `durationFrames`, `params` (`direction` 0 to 3 for left, right, up, down; `feather`; `blur`; `intensity`) |\\n| `mask` | `clipId` or `clipIds`, `shape` (`rectangle`, `ellipse`, `none`), `centerX`, `centerY`, `width`, `height` (0 to 1 of the clip\'s own frame), `feather`, `strength`, `inverted` |\\n| `replace` | `clipId` or `clipIds`, `mediaRef` (a library asset of the same kind), `trim` (`keep`, the default, or `reset`), `linkedAudio` (`follow`, the default, or `keep`) |\\n| `tracks` | `reorder: [{trackId, to}]`, `set: [{trackId, muted, hidden, syncLocked}]`, `remove: [{trackId}]`; there is no add, since placing without a track makes one |\\n| `titles` | `entries: [{startFrame, endFrame, content}]`, optionally with `trackIndex` (on every entry or none), `style`, `animation`, `transform` and typography (`fontName`, `fontSize`, `color`) |\\n| `text` | `clipId`, `clipIds` or `captionGroupId`, with `content`, `style`, `position`, `animation` or typography |\\n| `grade` | `clipId` or `clipIds`, `adjustments`, `wheels`, `curves`, `hueCurves`, `lut`, `reset` |\\n| `effects` | `clipId` or `clipIds`, `effects: [{type, params, enabled}]`, `remove: [type]` |\\n\\n- `grade`: `adjustments` holds `exposure` (EV, -4 to 4), `temperature` (kelvin, 1800 to 15000, 6500 neutral, higher is warmer), `tint` (-150 magenta to 150 green); `contrast`, `highlights`, `shadows`, `whites`, `blacks`, `vibrance` and `saturation` are signed percents (-100 to 100, 0 neutral), not factors like 1.2. `wheels`: `shadows`, `midtones`, `highlights`, each `{hue, strength, brightness}`. `curves`: `luma`, `red`, `green`, `blue` as `[x, y]` points from 0 to 1. `hueCurves`: `targets: [{hue, rotate, saturation, lightness}]`. `lut`: `{path, mix}`, with the `storedPath` from `prepare_look`. Out-of-range values are refused.\\n- Effect `type` ids and their knobs, which go inside `params` and run 0 to 100 unless noted. Defaults leave the picture unchanged, so send the knob you want to see:\\n  - `finish.vignette`: `strength` and `curvature` (-100 to 100; positive `strength` darkens the edges), `size`, `falloff`\\n  - `finish.grain`: `strength`, `grainSize` (0.5 to 6 px); `finish.glow`: `strength`, `haloRadius` (px), `cutoff`, `halation`\\n  - `defocus.gaussian`: `blurRadius` (px); `defocus.motion`: `streakLength` (px), `streakAngle` (-180 to 180 degrees)\\n  - `texture.clarity`: `localContrast`, `hazeRemoval` (-100 to 100); `texture.sharpen`: `strength` (0 to 200); `texture.denoise`: `strength`\\n  - `matte.chroma`: `screenHue` (0 to 360 degrees, 120 is green), `range`, `edgeSoftness`, `spillSuppression`\\n- `arrange` layouts and their slots (fill every slot): `fullscreen` (`stage`); `split` (`left`, `right`); `stack` (`top`, `bottom`); `corner_top_left`, `corner_top_right`, `corner_bottom_left`, `corner_bottom_right` (`stage`, `corner`); `quad` (`top_left`, `top_right`, `bottom_left`, `bottom_right`); `side_panel` (`stage`, `panel`); `thirds` (`left`, `middle`, `right`). The layout picks the corner; `anchor` only biases the crop.\\n- `trackIndex` and `toTrack` are an existing track\'s `order` from `edit_snapshot` (0 draws on top), counted at that point in the recipe: a track an earlier action adds shifts them. `tracks` takes `trackId` handles instead.\\n\\n## Start with the intended project\\n\\nAn MCP session can begin without a project selected. Project selection belongs to the session, not to whichever editor window happens to be frontmost.\\n\\n1. If the user named an existing project but its identity is unclear, call `project_manage` with `operation: \\"project\\"` and `parameters.action: \\"list\\"`.\\n2. Open the exact project with `action: \\"open\\"` and the returned `id`, an unambiguous `name`, or the `.vdproject` `path`.\\n3. Create only when the user wants a new local edit. `action: \\"create\\"` accepts optional `name`, `fps`, `aspectRatio`, and `quality`.\\n4. Treat `isActive` as this session\'s target and `isVisible` as the project shown in the UI. Headless editing only needs the session target.\\n5. Use `action: \\"close\\"` only when closing is part of the task. It saves first and never deletes the project. Afterwards other calls answer `no_project` until you open or create a project again.\\n\\nOther `project_manage` operations: `create_timeline` and `select_timeline` for additional timelines, and `configure` for project settings (a frame-rate change applies to every timeline).\\n\\nDo not substitute a hosted project ID for a native project. A hosted project can supply scripts, storyboards, and generated media, but the native edit is a separate `.vdproject` package.\\n\\n## Keep a reliable editing model\\n\\n- Opening or creating a project, and creating or selecting a timeline, returns `data.snapshot` (the `edit_snapshot` view with the library: format, tracks, clips and assets) and a `context`, so you can edit right away. Call `edit_snapshot` only after an out-of-band user edit, to page a long timeline with `offset` and `limit`, or for handles you lack.\\n- `context` (`epoch`, `timelineId`, `revision`) is optional on every write except `edit_undo` and `project_manage` `project`, which take none. Without it, a write applies to the current state. With it, the editor refuses the write if the project changed since that context, which is what you want when a person may be editing at the same time. Every reply returns a fresh `context`. After `context_expired` (a reopen or restart), take a new snapshot.\\n- Timeline positions and durations are frames at `format.fps`. `sourceSeconds` values are seconds in the source file. Pass values as returned; do not multiply or divide by fps yourself.\\n- IDs are short handles. Pass them back exactly as returned; do not derive them from UUIDs. Tracks keep stable handles; indexes can change.\\n- When the user says \\"this clip\\", \\"these captions\\", or \\"here\\", take a fresh `edit_snapshot` (a one-frame window is enough). Its `selection` names what they selected in the project\'s window, in the snapshot\'s handles: `clipIds`, `captionGroupIds`, a `gap`, the marked `range`, and library `mediaIds`; no `selection` means nothing is selected. `currentFrame` is the playhead. `visible: false` means the user is not looking at this project.\\n- Send writes serially. Parallel writes against one project race each other\'s context.\\n- A refused call answers `status: \\"rejected\\"`: nothing changed, so fix what the message names and send it again. A service write that answers `failed` may have applied before a save or connection failed; inspect before repeating it.\\n- Use `inspect` for detail and verification: `timeline` for exact clip and track properties, `frame` for rendered frames of the composited result, `media` before describing source content, `color` for scopes, and `transcript` to locate spoken words.\\n- Volume values, including volume keyframes, are linear from `0` to `1`.\\n\\n## Edit with recipes\\n\\n`edit_apply` takes an ordered list of `actions`, plus an optional `context` and `requestId`. The editor validates the whole recipe before changing anything, then applies it as one undo step. If any action fails, nothing changes and the error names the action. An applied reply lists the resulting `clips` (position, length, source window, text); use it to confirm the edit instead of re-reading.\\n\\n- Concise actions: `place` (an `assetId` at `atFrame`, optionally on a `trackId`, with `durationFrames` or `sourceSeconds`, `mode` `overwrite` or `insert`), `trim` (a `clipId` to a `sourceSeconds` window), and `title` (`text` at `atFrame` for `durationFrames`, optional `look` and `motion`). Name an action with `as` and address its clip in later actions as `@name`.\\n- Advanced actions put their fields beside `kind` too: `place_batch`, `insert_batch`, `move`, `remove`, `split`, `extract`, `adjust`, `animate`, `arrange`, `transition` (fields inside `parameters`), `mask`, `replace`, `tracks`, `titles`, `text`, `grade`, and `effects`. Their field help lists every supported effect, grading control, mask, layout, speed curve, and caption control.\\n- Use `arrange` for split screens, picture-in-picture, grids, and canvas placement, and `tracks` to fix stacking. Do not synthesize layouts from generic transforms or keyframes.\\n- Use `replace` to swap a clip\'s media and keep its timing, effects, keyframes, and links, for example a re-render of the same shot. `trim: \\"keep\\"` holds the clip\'s source offsets; `trim: \\"reset\\"` plays the new media from its first frame and keeps linked audio in sync.\\n- Put every edit a request needs into one recipe: placing, trimming, titling, grading and effects together are one call and one undo step. Use `previewOnly: true` to validate a large or risky recipe without editing.\\n- Send a `requestId` when a retry must not edit twice: repeating the identical request with the same `requestId` returns the original receipt, even after a dropped connection. Without one, a repeated request applies again. Use a new `requestId` for a different edit.\\n- `applied_unsaved` means the edit applied but saving failed. If you sent your own `requestId`, repeat the identical request to retry the save, not the edit. Without one, do not resend: a repeat would apply the edit again.\\n- `edit_undo` reverses this connection\'s latest edit while it is still the top undo step. It never undoes the user\'s own edits. Take a new snapshot afterward.\\n\\nEdits are undoable. Do not ask for confirmation before each ordinary edit. Ask one focused question only when the user\'s creative direction is materially ambiguous.\\n\\n## Bring generated or local media into the editor\\n\\nFor b-roll and establishing shots, search free stock first (`videodraft stock search \\"<query>\\"`), import the pick with `videodraft stock import <ref>`, and feed the returned CDN URL to `library_manage` `import` as `source.url`. It costs no credits.\\n\\nOtherwise use cloud generation for new assets, save or download the outputs, then call `library_manage` with `operation: \\"import\\"`:\\n\\n- `source.path`: absolute local file or directory. A directory imports recursively and preserves its folder structure.\\n- `source.url`: HTTPS asset URL. Set `mimeType` when a signed URL has no usable extension.\\n- `source.bytes`: small base64 media with a required `mimeType`.\\n- `source.matte`: generated solid-color image.\\n\\nReadiness differs by source, and so does the poll that detects it:\\n\\n- **URL and single-file path** imports return `status: \\"downloading\\"` with one `mediaRef`. Poll `library_manage` `list` with `parameters.ids: [mediaRef]` until `generationStatus` is absent.\\n- **Directory** imports also return `status: \\"downloading\\"` with one placeholder `mediaRef` for the batch. Poll it the same way; the folder\'s assets appear when `generationStatus` clears. (`pending: true` remains a fallback that lists every unresolved import.)\\n- **Inline bytes and matte** imports finish inline and come back `status: \\"ready\\"`; no polling is needed.\\n\\nAn import\'s `mediaRef` is the `assetId` that recipe actions take. Never place a pending asset on the timeline. `generationStatus` is the signal: `preparing`, `generating`, `downloading`, and `rendering` mean keep polling, absent means usable, and **`failed` is terminal**. Report it or retry the import explicitly; never poll on. Do not treat \\"not downloading\\" as ready.\\n\\nA `.srt` or `.vtt` caption file (by `path`, `url`, or `bytes` with `mimeType` `application/x-subrip`, `text/srt`, or `text/vtt`) is not added to the library. Its captions go onto a new caption track at the times the file gives, as one undo step, and the reply names the new `captionGroupId` to restyle with a `text` action.\\n\\nFor a batch of local outputs, download them into one workspace directory and import that directory once when practical. This is safer and faster than racing many import calls.\\n\\nTo apply a LUT, first store it with `library_manage` `prepare_look` (`parameters.path` to a `.cube` file), then use the returned `storedPath` in a `grade` action.\\n\\n## Speech edits\\n\\n`speech_apply` runs speech work as separate operations, not recipe actions: `words` removes transcript words, `silence` trims dead air, and `captions` generates styled captions. Read a fresh transcript with `inspect` `transcript` after any speech edit, because word positions change.\\n\\n## Service operations and timeouts\\n\\n`project_manage`, `library_manage`, `speech_apply`, and `delivery_manage` writes have no retry receipts. After a timeout, inspect the outcome (a snapshot, a library `list`, or delivery `jobs`) before repeating a write. A failed service write may have applied an edit before saving failed, so read its `data` and the current state.\\n\\n## Edit and verify\\n\\nA dependable sequence:\\n\\n1. `project_manage` to select or create the local project; its reply carries the snapshot.\\n2. `inspect` `media` when content selection matters.\\n3. One `edit_apply` recipe with every clip, track, layout, text, audio, color, and effect change the request needs; `speech_apply` for word cuts, silence, and captions.\\n4. Check the reply\'s `clips`; use `inspect` `frame` only when visual composition or layer order matters.\\n5. `edit_undo` if the result is wrong and the next recipe would not cleanly correct it.\\n\\n## Export\\n\\nCall `delivery_manage` with `operation: \\"submit\\"`. Submission is not completion: it returns a job, destination, and `started` or `queued` status.\\n\\n- Use `mode: \\"video\\"` for H.264, H.265, or ProRes.\\n- Use `mode: \\"xml\\"` (XMEML) for Premiere Pro **and DaVinci Resolve**. Resolve reads XMEML natively. Use `fcpxml` only for Final Cut Pro; sending Resolve an FCPXML produces a package it cannot open cleanly.\\n- Use `mode: \\"videodraft\\"` for a self-contained project package.\\n- Use `mode: \\"srt\\"` or `mode: \\"vtt\\"` for a subtitle file of the captions: words and timing only, without styling. `captionGroupId` picks a caption group; `wordTiming: true` adds each word\'s start to a `vtt`.\\n- Omit `outputPath` unless the user named a destination; the default is `~/Downloads`. The editor does not create folders, so a named destination\'s folder must already exist.\\n- Use `operation: \\"jobs\\"` with `parameters.action` `list` to follow progress, warnings, and results. Cancel only when the user asks or the just-queued settings were wrong. Do not infer that an export is stuck from elapsed time alone.\\n- A finished video export is then checked in the background for black picture, gaps, sound that drops out or clips, and missing media. `list` shows each job\'s `findingCount` and its first three findings; `list` with that `jobId` returns every finding. Findings are warnings on a completed export: tell the user what was found and where, rather than treating the export as failed.\\n\\n## Terminal bridge\\n\\nVideoDraft desktop terminals expose `videodraft-editor`, which controls the same process and tools:\\n\\n```bash\\nvideodraft-editor status\\nvideodraft-editor list-tools\\nvideodraft-editor tool project_manage --json \'{\\"operation\\":\\"project\\",\\"parameters\\":{\\"action\\":\\"list\\"}}\'\\nvideodraft-editor tool edit_snapshot --project \\"/path/to/My Video.vdproject\\" --json \'{\\"includeLibrary\\":true}\'\\nvideodraft-editor show\\nvideodraft-editor hide\\n```\\n\\nEach `videodraft-editor` invocation is a separate connection, so a project opened by one call is NOT remembered by the next. Pass `--project <path>` on every `tool` call that operates on a project; without it, a follow-up call answers `no_project` (no project is open for this session) even though the open succeeded. For the same reason, `edit_undo` has nothing to undo from the terminal: it only reverses an edit made on its own connection.\\n\\nControl and tool commands auto-start a headless editor if none is running. `show` only reveals the already-running UI. Use `videodraft-editor tool <name> --json -` to read a JSON object from stdin when shell quoting would be fragile. Never read, copy, or expose the editor\'s rotating local authentication secret.\\n","references/examples.md":"# Recipes\\n\\nWorking patterns for common asks. All assume auth (`videodraft login` once, or `VIDEODRAFT_API_KEY` in the environment) and use `--json` for parsing.\\n\\nInside VideoDraft ADE, if a native editor is available, use these recipes for asset generation and\\noptional script/storyboard stages. Hand the results to the editor for production and export ONLY\\nwhen the deliverable the user asked for is a composed production. A standalone output \u2014 the batch\\nproduct clips in recipe 1, the upscale in recipe 7 \u2014 is finished when it is generated; importing it\\ninto a project and exporting a timeline builds an edit nobody asked for. Recipes below that call `videodraft produce` or `videodraft export` are hosted fallbacks only. Do not choose them over the available native editor unless the user explicitly asks for the hosted web workflow.\\n\\n## 1. Batch product videos from a CSV\\n\\nOne 9:16 product clip per row of `products.csv` (`name,image_url,tagline`):\\n\\n```bash\\n#!/usr/bin/env bash\\nset -euo pipefail\\nmkdir -p outputs\\n\\nwhile IFS=, read -r name image tagline; do\\n  job=$(videodraft generate video \\\\\\n    \\"Premium product shot of ${name}: ${tagline}. Slow orbit, studio lighting.\\" \\\\\\n    --model gemini-omni-1.1-flash --ar 9:16 --duration 6 \\\\\\n    --start-image \\"$image\\" \\\\\\n    --no-wait --json | jq -r .job_id)\\n  echo \\"$name,$job\\" >> outputs/jobs.csv\\ndone < <(tail -n +2 products.csv)\\n\\n# Collect ALL results with ONE process (batched polling \u2014 one request per tick)\\nvideodraft wait $(cut -d, -f2 outputs/jobs.csv) \\\\\\n  --download \\"outputs/{job_id}_{index}.{ext}\\" --json > outputs/results.json\\n# map job ids back to product names via outputs/jobs.csv\\n```\\n\\nSubmit-then-collect parallelizes server-side generation; the single multi-id `wait` keeps it to one local process and one batched poll request per tick no matter how many jobs. Gemini Omni 1.1 Flash is selected because these are six-second first-frame product clips. Estimate first: `videodraft costs gemini-omni-1.1-flash --type video --duration 6 --resolution 720p --audio` \xD7 rows, and confirm with the user.\\n\\nExtend an uploaded clip or conversationally edit an official Google interaction with Gemini Omni 1.1 Flash:\\n\\nEach extension appends 3-10 seconds at the end. Edit and extend accept EXACTLY ONE input video, so `--ref-video` cannot accompany `--source-video` or `--previous-interaction-id`; only `--ref` images can. New dialogue is allowed only when the source video is silent, so a chain of spoken beats must carry its speech in the first turn. A continuation is submitted as the prior turn\'s output, so 40 seconds total is reachable only by extending from a source of 30s or less, and a ladder dead-ends past 30s.\\n\\n```bash\\n# Uploaded-video extension. Reference IMAGES are fine here; reference videos are not.\\nvideodraft generate video --model gemini-omni-1.1-flash \\\\\\n  --source-video ./ending.mp4 --ref ./wardrobe.png \\\\\\n  --extend --duration 6 --resolution 1080p \\\\\\n  --download ./media/extended.mp4\\n\\n# Conversational edit from the interaction_id of an earlier generation. Add --extend to lengthen instead.\\nvideodraft generate video --model gemini-omni-1.1-flash \\\\\\n  --previous-interaction-id \\"$INTERACTION_ID\\" \\\\\\n  --resolution 720p \\\\\\n  --download ./media/continued.mp4\\n```\\n\\nFal BYOK supports the currently callable Gemini Omni 1.1 generation and basic source-edit endpoints at zero VideoDraft credits. Its published callable v1.1 endpoints do not expose continuation, extension, or separate creative references on a source edit. Do not infer a Fal route or retry on paid Google while Fal BYOK is active.\\n\\n## 2. Hosted full marketing video from one idea (fallback)\\n\\n```bash\\nvideodraft create \\"30-second launch video for Solace, a sleep-tracking ring. Calm, premium, dark palette.\\" \\\\\\n  --ar 9:16 --style cinematic --json > project.json\\nPROJECT=$(jq -r .project_id project.json)\\n\\nvideodraft shots \\"$PROJECT\\" --grid --estimate          # show the user the cost; get a go-ahead\\nvideodraft shots \\"$PROJECT\\" --grid\\nvideodraft produce \\"$PROJECT\\"\\nvideodraft generate music \\"minimal ambient, warm pads, 60 BPM\\" --attach \\"$PROJECT\\"\\nvideodraft generate audio \\"Extend @Audio1 into a 20-second transition\\" --ref-audio ./intro.wav --format wav --download ./transition.wav\\nvideodraft export \\"$PROJECT\\" --download solace-launch.mp4\\n```\\n\\nUse this complete hosted path only when the user requested a web project or the native editor is unavailable. Otherwise stop after the storyboard/assets, import them into the native `.vdproject`, and export with `delivery_manage`. The hosted project stays editable at the URL in `project.json` (`.urls`).\\n\\n## 3. Talking-head (avatar) video\\n\\nWhen the user has no portrait, generate a clear front-facing avatar image first. Skip this step when they supplied one or an existing character should be reused.\\n\\n```bash\\nvideodraft generate image \\\\\\n  \\"Front-facing head-and-shoulders portrait of a friendly coffee expert, direct eye contact, natural expression, clean studio background\\" \\\\\\n  --model nano-banana-2 --ar 9:16 --download ./media/avatar.png\\n\\nSCRIPT=$(videodraft avatar script \\"why our espresso subscription saves you money\\" --style ad-style --json | jq -r .script)\\nAVATAR=$(videodraft avatar create ./media/avatar.png --script \\"$SCRIPT\\" --voice elevenlabs-kPzsL2i3teMYv0FxEYQ6 --ar 9:16 --json | jq -r .avatar_video_id)\\nvideodraft avatar render \\"$AVATAR\\" --resolution 720p   # VEED Fabric paid step; confirm cost first (~20 credits/sec)\\n```\\n\\n`avatar script` and `avatar create` (including speech) are bundled/free. In this example only the optional portrait generation and Fabric render spend credits.\\n\\nIf the portrait is low resolution, enhance it before `avatar create`:\\n\\n```bash\\nvideodraft upscale image ./founder-small.jpg --scale 2x --download ./media/founder-upscaled.png\\n```\\n\\nFor a one-off portrait animation without creating a managed avatar record:\\n\\n```bash\\nvideodraft avatar fabric ./founder.jpg \\\\\\n  --text \\"Welcome to the weekly product update.\\" \\\\\\n  --voice-description \\"warm, confident American presenter\\" \\\\\\n  --resolution 720p --download ./media/presenter.mp4\\n```\\n\\nFor a short, sharp clip from speech or a song the user already has (5-14.8s of audio is used):\\n\\n```bash\\nvideodraft avatar h3-lipsync ./singer.png --audio ./chorus.mp3 \\\\\\n  --resolution 1080P --audio-duration 12 --estimate\\nvideodraft avatar h3-lipsync ./singer.png --audio ./chorus.mp3 \\\\\\n  --resolution 1080P --download ./media/singer-lipsync.mp4\\n```\\n\\nWhen the user already has both the video and replacement speech:\\n\\n```bash\\nvideodraft avatar lipsync ./presenter.mp4 \\\\\\n  --audio ./localized-voiceover.mp3 \\\\\\n  --sync-mode loop --download ./media/presenter-localized.mp4\\n```\\n\\nEdit an existing video with a dedicated edit model:\\n\\n```bash\\nvideodraft models video --category video_edit\\nvideodraft edit video ./product-demo.mp4 \\\\\\n  \\"Preserve the product but follow the reference camera rhythm\\" \\\\\\n  --model gemini-omni-1.1-flash --ref-video ./camera-rhythm.mp4 \\\\\\n  --ref-video-duration 2.5 --resolution 1080p \\\\\\n  --download ./media/product-demo-reframed.mp4\\n\\nvideodraft edit video ./product-demo.mp4 \\\\\\n  \\"Turn the room into a warm evening scene while preserving the product and camera motion\\" \\\\\\n  --model kling-o3-video-ref-edit --ref ./evening-style.jpg \\\\\\n  --preserve-audio --download ./media/product-demo-evening.mp4\\n```\\n\\nTransfer motion from a reference clip onto a character image:\\n\\n```bash\\nvideodraft edit motion ./character.png \\\\\\n  \\"Apply the dancer\'s movement to this character while preserving identity\\" \\\\\\n  --motion-video ./dance-reference.mp4 \\\\\\n  --model kling-v3-motion-control --quality pro \\\\\\n  --download ./media/character-dance.mp4\\n```\\n\\n## 4. Hosted changelog video in CI\\n\\nIn a GitHub Action with `VIDEODRAFT_API_KEY` set as a secret:\\n\\n```bash\\nNOTES=$(git log --oneline v1.2.0..HEAD | head -20)\\nvideodraft create \\"Weekly product update video. Energetic, 20 seconds. Changes: ${NOTES}\\" --ar 16:9 --json > p.json\\nPROJECT=$(jq -r .project_id p.json)\\nvideodraft shots \\"$PROJECT\\" && videodraft produce \\"$PROJECT\\"\\nvideodraft export \\"$PROJECT\\" --download changelog.mp4 --wait-timeout 30m\\n```\\n\\n## 5. Variations and picking a winner\\n\\n```bash\\nvideodraft generate image \\"logo concept: minimalist fox, geometric\\" --num 4 --download \\"./concepts/{job_id}_{index}.{ext}\\" --json\\n# Show all 4 to the user; regenerate the chosen one at higher res:\\nvideodraft generate image \\"<same prompt>\\" --model nano-banana-pro --resolution 4K\\n```\\n\\n## 6. Reaching tools without a curated command\\n\\n```bash\\nvideodraft tools list --json | jq -r \'.[].name\'\\nvideodraft tools schema attach_media_to_shot --json\\nvideodraft call attach_media_to_shot --args \'{\\"project_id\\":\\"...\\",\\"scene_index\\":0,\\"shot_index\\":1,\\"media_url\\":\\"https://...\\",\\"media_type\\":\\"video\\",\\"duration_seconds\\":6}\'\\n```\\n\\nAnything the hosted VideoDraft MCP exposes, including character studio, product studio, and hosted project data, is reachable this way even before it gets a curated command. Native `.vdproject` editing uses the separate `videodraft_editor` MCP described in SKILL.md.\\n\\n## 7. Enhance an existing asset without changing it\\n\\n```bash\\n# Light image cleanup, no enlargement\\nvideodraft upscale image ./poster.png --scale 1x --download ./media/poster-enhanced.png\\n\\n# General image and video enlargement\\nvideodraft upscale image ./frame.png --scale 2x --download ./media/frame-2x.png\\nvideodraft upscale video ./clip.mp4 --resolution 1080p --download ./media/clip-1080p.mp4\\n\\n# Rebuild detail in a tiny/blurry source (generative), or reimagine it (creative)\\nvideodraft upscale image ./tiny.jpg --scale 4x --mode generative --model \\"Wonder 3.5\\" --download ./media/tiny-4x.png\\nvideodraft upscale video ./ai-clip.mp4 --resolution 4k --mode generative --download ./media/ai-clip-4k.mp4\\n\\n# Smoother motion or slow motion (resolution unchanged)\\nvideodraft interpolate ./clip.mp4 --fps 60 --download ./media/clip-60fps.mp4\\nvideodraft interpolate ./clip.mp4 --model Chronos --slowdown 4 --download ./media/clip-slowmo.mp4\\n```\\n\\nUse these when the content is correct and only quality or resolution needs improvement. If the poster text, composition, subject, or motion is wrong, edit or regenerate instead.\\n","references/models.md":"# Choosing models (and predicting cost)\\n\\nAlways consult the live catalog instead of memorizing this page \u2014 models change weekly:\\n\\n```bash\\nvideodraft models image --json     # every image model + inputs (aspect ratios, resolutions, max refs)\\nvideodraft models video --json     # every video model + inputs + per-second pricing metadata\\nvideodraft models audio --json     # standalone audio/media models + pricing inputs\\nvideodraft models voices --json    # TTS voices\\nvideodraft models styles --json    # visual style presets\\n```\\n\\n## Task-based model selection\\n\\nFollow this order every time:\\n\\n1. The user named a model: use it, never substitute.\\n2. Otherwise pick a **Tier 1** model from the task\'s inputs, duration, audio, quality, speed, and cost, and pass it explicitly instead of relying on a blind platform fallback.\\n3. Use a **Tier 2** model only when no Tier 1 model supports the request, and say why. Never pick Tier 2 on your own for price, speed, novelty or variety.\\n\\nTier 1 is the rows marked **T1** below. Every other catalog model is Tier 2 and stays available by name. The catalogs carry this themselves: every `videodraft models image|video|audio --json` entry has `tier` (1 or 2) plus `recommended` / `recommended_for`, and the top-level `recommended` array is Tier 1, best first. Trust the catalog over this page when they disagree.\\n\\n### Images\\n\\n| Need                                                                                       | Choose                   | Why                                                               |\\n| ------------------------------------------------------------------------------------------ | ------------------------ | ----------------------------------------------------------------- |\\n| T1: Most generation, editing, character consistency, or reference work                     | `nano-banana-2`          | Best general default; 1K/2K/4K and up to 14 reference images      |\\n| T1: Highest-quality complex generation or reasoning                                        | `nano-banana-pro`        | Premium Nano Banana quality and reasoning                         |\\n| T1: Fast, inexpensive drafts and iteration                                                 | `nano-banana-2-lite`     | Fastest/cheapest Nano Banana option; 1K only, up to 14 references |\\n| T1: Posters, title cards, signs, logos, or any image with important readable text          | `gpt-image-2.5-flare`    | Fast OpenAI option; 16 references, 1K/2K/4K and PNG output        |\\n| T1: Complex multi-image composition, precise editing, or a strong alternate interpretation | `gpt-image-2.5-sunburst` | More fidelity/detail; 16 references, quality through max          |\\n| T1: Vector / SVG output (logos, icons, illustrations that must scale)                      | `recraft-v4`             | Recraft V4.1 text-to-vector; SVG only, no reference images        |\\n| T2: By name, or an explicitly requested xAI look                                           | `grok-imagine`           | 2 cr flat (3 with a reference); 1 reference image                 |\\n| T2: xAI at 2K or with a quality tier, up to 3 edit references                              | `grok-imagine-2.0`       | 1K 4 (low) / 6 (medium), 2K 6 / 8, +1 cr per reference image      |\\n\\nGPT Image 2.5 has two IDs: `gpt-image-2.5-flare` replaces the former GPT Image 2 recommendation; `gpt-image-2.5-sunburst` is the precision/detail alternative. Other model recommendations are unchanged. Explicit `gpt-image-2` selections continue to use the previous model.\\n\\nUse the same basic image controls as GPT Image 2: `--ref`, `--ar`, `--resolution 1K|2K|4K`, `--quality`, and `--num 1..4`. GPT Image 2.5 quality supports auto/low/medium/high/xhigh/max. Auto is priced at Max in customer-credit estimates. The default platform path uses OpenAI; a selected personal connection stays exclusive. A Pika personal connection requires an explicit quality from low/medium/high/xhigh/max because its upstream API has no auto value. Other unsupported connection settings return an error instead of switching payer or changing the request.\\n\\n```bash\\nvideodraft generate image \'A blue glass bird\' --model gpt-image-2.5-flare --ar 1:1 --resolution 2K --quality high --estimate\\nvideodraft generate image \'A blue glass bird\' --model gpt-image-2.5-flare --ar 1:1 --resolution 2K --quality high --num 2\\n```\\n\\n`videodraft shots` forwards resolution and quality for both normal and grid generation. Estimates use the project\'s model and aspect when omitted; grid canvas costs may differ from ordinary shot costs. Use `videodraft costs --model <id> --ar <ratio> --resolution <tier> --quality <tier>` for a specific per-image quote.\\n\\n### Videos\\n\\n| Need                                                                                                           | Choose                   | Important limits                                                                                                                                                                                                                                               |\\n| -------------------------------------------------------------------------------------------------------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\\n| T1: Most generation, first/last-frame, mixed-reference, source-edit, or extension requests                     | `gemini-omni-1.1-flash`  | 3-10s output; 360p/720p/1080p/4K at 3/10/15/30 cr/s; audio always; up to 10 image inputs, and 3 reference videos <=3s on generate only; edit source <=10s; continuation or 3-10s extension of a 1-30s source, 40s total reachable only by extending from <=30s |\\n| T2: Grok 1.5 text, first-frame, or 1-7 image-reference clips with native audio and optional 1080p              | `grok-imagine-video-1.5` | 1-15s; 480p/720p/1080p for text/first-frame; references are 480p/720p only; no last frame                                                                                                                                                                      |\\n| T2: Document or webpage reference generation; by name otherwise                                                | `wan-3.0`                | 2-30s or auto; 480p/720p/1080p at 7/14/28 cr/s; 10 image, 5 video, 5 audio refs, 20 media files total; document/web refs require thinking                                                                                                                      |\\n| T2: 480p/768p/2K/4K with native stereo audio, first/last frames, or mixed image/video/audio references         | `minimax-h3`             | 5-15s; 5/6/13/16 cr/s by resolution; up to 9 image, 3 video, 3 audio refs, 12 files total; first 5 reference images free then 8 cr each; reference video/audio each total <=15s                                                                                |\\n| T1: Text, first/last-frame, or mixed-reference video with native audio and stronger prompt adherence           | `minimax-h3-max`         | 5-15s; 5/8 cr/s at 480p/768p plus pooled reference tokens; up to 9 image, 3 video, 3 audio refs, 12 files total; seed and disabled/balanced/quality prompt expansion; provider safety checker off by default                                                   |\\n| T2: Images pinned to specific moments (keyframes); by name otherwise                                           | `flux-3`                 | 5-20s (auto for text/first-frame only); 720p/1080p; up to 10 keyframes; `--quality draft` is 720p-only at ~1/3 the cost                                                                                                                                        |\\n| T1: Video/audio references, mixed reference media, broad aspect ratios, frame-mode first+last frame, or 11-15s | `seedance-2`             | 4-15s or auto; up to 9 image, 3 video, and 3 audio refs; audio toggle; Mini/Fast are 480p/720p only                                                                                                                                                            |\\n| T1: Single takes past 15s, or more references than Seedance 2.0 allows                                         | `seedance-2.5`           | 4-30s or auto; up to 30 image, 10 video, and 10 audio refs (50 files total); one quality tier; 480p/720p/1080p                                                                                                                                                 |\\n| T2: Fast polished 3-15s video with first frame, multi-prompt, and native audio                                 | `kling-v3-turbo`         | Audio always on; Pro default; no end frame, reference-media mode, or elements                                                                                                                                                                                  |\\n| T1: Cinematic 3-15s with reference images, image/video elements, first+last frame, audio, or 4K                | `kling-o3`               | 7 combined image refs/elements, reduced to 4 with a video element; Standard/Pro/4K                                                                                                                                                                             |\\n| T1: Kling 3-15s image-to-video with first+last frame, image/video elements, multi-prompt, audio, or 4K         | `kling-3.0`              | Elements require a start image; image or video elements can bind voice_id; Standard/Pro/4K                                                                                                                                                                     |\\n| T2: User explicitly requests Veo, or the selected workflow specifically needs Veo                              | `google-veo3.1`          | Good fallback, but not the preferred general model                                                                                                                                                                                                             |\\n\\nRouting rules:\\n\\n- Inexpensive pass or draft at 480p/768p with native audio: use MiniMax H3 Max (5/8 cr/s plus reference tokens).\\n- Grok 1.5 reference mode accepts 1-7 images only. Address them in array order as `<IMAGE_0>` through `<IMAGE_6>`. Do not combine reference images with `--start-image`, `--end-image`, `--ref-video`, or `--ref-audio`.\\n- Grok 1.5 first-frame mode accepts one `--start-image`, derives the output aspect ratio from that image, and does not support `--end-image`. Text and first-frame modes support 480p, 720p, or 1080p. Reference mode supports 480p or 720p.\\n- Grok 1.5 always generates native audio. Do not pass `--no-audio`, `--seed`, `--negative`, or `--quality`.\\n- Around 11-15 seconds with native audio: use Seedance, Kling 3.0 / O3, or MiniMax H3 Max, not Gemini. Past 15 seconds: Seedance 2.5.\\n- Dialogue: write the line in the prompt, in quotes, with who says it and how. `gemini-omni-1.1-flash`, `seedance-2.5`, `seedance-2`, `kling-3.0` and `kling-o3` speak it natively; add `--ref-audio` on Seedance or a bound Kling voice for a specific voice. Do not generate speech separately and lip-sync it on.\\n- One existing source video that should be edited: use `videodraft edit video`, which auto-selects Gemini Omni 1.1 Flash for a source up to 10s. Generic `generate video --ref-video` retains source-edit behavior when `--video-task` is omitted, but the dedicated edit command is clearer.\\n- Video supplied as a creative reference: Gemini Omni 1.1 Flash accepts up to 3 videos of at most 3 seconds each, including mixed image and video input. Creative video references are accepted on `--video-task generate` ONLY: edit and extend take exactly one input video, so `--ref-video` cannot accompany `--source-video` or `--previous-interaction-id`. Use Seedance 2.5 for more or longer video/audio references, or Seedance 2.0 when quality-tier control matters.\\n- First and last frame control: every Tier 1 video model supports it (Gemini Omni 1.1 Flash, Seedance, Kling O3, Kling 3.0, MiniMax H3 Max). For Gemini, every start/end frame counts toward the 10-image total, leaving up to 9 references with a start frame or 8 with both frames.\\n- Extension with a 1-30s uploaded source uses Gemini Omni 1.1 Flash plus `--source-video` and `--video-task extend` (or `--extend`). Pass an explicit 3-10s output duration; the model appends it at the end, up to 40 seconds total. Creative `--ref-video` clips CANNOT accompany the source: edit and extend take exactly one input video. New dialogue is allowed only when the source video is silent; adding speech on top of a source that already has speech is refused with \\"the model is currently unable to process speech edits\\". Continuation uses `--previous-interaction-id <id>` and defaults to a conversational edit; `--video-task extend` lengthens it. A continuation is submitted as the prior turn\'s output video, so it obeys the same source limits (<=30s to extend, <=10s to edit) and the same silent-source dialogue rule. 40s total is reachable only by extending from a source of 30s or less, so a ladder dead-ends past 30s. Fal returns interaction IDs, but its currently published callable v1.1 endpoints do not expose continuation/extension or mixed source-edit references; never infer a route or silently fall back to paid Google.\\n- Wan 3.0 reference mode and frame mode are separate. It accepts 10 images, 5 videos, and 5 audio clips, at most 20 media files total. Video and audio each total at most 15 seconds. `--file-url` and `--web-url` require `--thinking`. `--auto-duration` cannot be combined with `--duration`.\\n- MiniMax H3 and H3 Max reference mode and first-plus-last-frame mode are separate. Audio cannot be the only reference. Address references as `Image 1`, `Video 1`, and `Audio 1` in array order.\\n- Seedance reference mode and first-plus-last-frame mode are separate. Do not promise reference video/audio plus a last frame in one generation.\\n- Multi-prompt sequencing: use Kling 3.0 Turbo, Kling O3, or Kling 3.0.\\n- Kling 3.0 image-to-video and Kling O3 reference-to-video accept repeatable structured `--element` JSON. Each element is image-backed (`frontal_image_url` plus 1-3 `reference_image_urls`) or video-backed (`video_url`). Either form may include `voice_id`. Keep the voice ID inside the same element so the association is preserved. Reference them as `@Element1`, `@Element2`. Kling V3 Turbo rejects elements.\\n- Kling 2.6 Pro image-to-video accepts one or two repeatable `--voice-id` values. Cite them as `<<<voice_1>>>` and `<<<voice_2>>>` in the prompt. Voice control costs 17 cr/s. Use `videodraft kling-voices list|create|delete` to manage the separate Kling video-control voice library. Creating a voice requires a clean 5-30 second, up-to-50MB single-speaker `.mp3`, `.wav`, `.mp4`, or `.mov` sample plus `--confirm-consent`. Creation costs 1 VideoDraft credit on the platform Fal account and 0 credits with Fal BYOK; use the create command\'s `--estimate` flag to check without creating.\\n- Kling V3 voice control costs 16 cr/s for Standard and 20 cr/s for Pro.\\n- Seedance quality: `mini` for the lowest cost, `fast` for speed, `standard` for maximum quality and for 1080p/4K. Seedance 2.5 has a single tier and ignores `--quality`.\\n- Longer than 15 seconds, or more than 9 image / 3 video / 3 audio references: use Seedance 2.5. It reaches 30s and 30/10/10 references (50 files total) at 480p/720p/1080p, but has no 4K.\\n- Seedance 2.x allows real people by default, the same as AI Studio: Byteplus first, a submit-time Fal fallback, and Fal\'s higher tier-specific rate. Turn it off with MCP `allow_real_people: false` or CLI `--no-allow-real-people` for the lower Byteplus-only rate, only when the user wants the cheapest run and nothing in the job is a real identifiable person (text-only requests, non-people, anime, clearly synthetic or stylized characters).\\n- If a Seedance request made with the option off fails with `SEEDANCE_REAL_PERSON_OPT_IN_REQUIRED`, estimate the higher rate, follow the user\'s spend policy, and retry once with the option on. The response also carries `retry_with: { allow_real_people: true }`, `cli_flag: \\"--allow-real-people\\"`, and `retry_policy: \\"once\\"`. If the option was already on, do not repeat the same request. Byteplus may accept a task and reject the output later. VideoDraft refunds that failed generation, but it cannot reroute the asynchronous failure to Fal. Rephrase or change the references instead.\\n\\n### Video edit and motion-control categories\\n\\nUse `videodraft models video --category video_edit` for existing-video transforms and `--category motion_control` for motion transfer.\\n\\n| Need                                       | Command/model                                                                | Important limits                                                                                                                                          |\\n| ------------------------------------------ | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |\\n| Most edits of a source up to 10s (DEFAULT) | `videodraft edit video <video> \\"...\\"` (auto-selects `gemini-omni-1.1-flash`) | Source <=10s or it REFUSES; up to 10 image refs and 3 creative video refs <=3s each; 360p/720p/1080p/4K; audio always regenerated (no `--preserve-audio`) |\\n| Cheapest simple prompt edit                | `videodraft edit video <video> \\"...\\" --model grok-imagine-video-edit`        | No image refs; source silently truncated to 8s; auto/480p/720p                                                                                            |\\n| Edit with several image references         | `--model happy-horse-video-edit --ref ...`                                   | Up to 5 refs; 720p/1080p; source silently truncated to 15s; highest rate (28-56 cr/s)                                                                     |\\n| Controlled Kling edit                      | `--model kling-o3-video-ref-edit --ref ...`                                  | Up to 4 refs; Standard/Pro; source silently clamped to 3-10s                                                                                              |\\n| Transfer reference motion to an image      | `videodraft edit motion <image> [direction] --motion-video <video>`          | Prompt/direction is optional; Kling V3 default; optional one image-only `--element`; element requires video orientation                                   |\\n\\nIf the user explicitly names one of these models, preserve it. The CLI uploads local source videos and reference images automatically. Editing returns an async job and waits by default.\\n\\n**Omit `--model` and the SERVER chooses**, because only it can measure the source. It picks `gemini-omni-1.1-flash` for any source up to 10s. When that is not safe (source longer than 10s, unmeasurable duration, `--preserve-audio`, more than 10 refs, or Fal BYOK with refs) it spends nothing and returns a priced menu: per model, the seconds it would edit, the seconds it would drop, and the credit cost. The CLI prints that table and exits 2. Show it to the user, then re-run with `--model`.\\n\\n**Truncation is the trap here.** Only Gemini refuses a source it cannot fully consume. Every other edit model accepts a 30s clip and returns an edit of its first 8-15 seconds with no error. `videodraft edit video` now warns when this will happen and the tool response carries `source.truncated` / `source.dropped_seconds`; relay it to the user rather than letting them discover it in the output.\\n\\nTo edit a longer source without losing its tail, cut it into <=10s pieces with `videodraft_editor`, edit each with Gemini, then reassemble and export there. VideoDraft has no server-side split/concat, so this needs the native editor.\\n\\nKling O3 is also exposed for reference generation. `videodraft generate video --model kling-o3-video-ref-edit` requires exactly one `--ref-video` and generates a new reference-guided clip. Wan 3.0 handles new text, frame, and mixed-reference generation, but is not an existing-source edit model.\\n\\n### Reference-first video workflow\\n\\n- Prefer a start frame or reference image whenever a specific character, product, location, style, composition, or brand identity must stay recognizable.\\n- If the user gives a reference, pass it. Never silently replace it with a text description.\\n- If no reference exists and continuity matters, generate a still first with the user\'s explicitly requested compatible image model, otherwise use Nano Banana 2. Wait for the image URL, then animate it with the selected video model. Confirm the combined image plus video cost before starting.\\n- For multi-shot scenes, generate shot images with `videodraft shots <project_id> --model <selected-image-model> --grid`. Preserve an explicitly requested compatible image model; otherwise use `nano-banana-2`. The grid establishes the scene and characters together, then decodes into individual shot images.\\n- Animate the decoded shot images as per-shot start frames or references. Do not independently text-generate each video clip when the shots need to match.\\n- Pure text-to-video remains appropriate for generic one-off footage where no subject, composition, or continuity needs to be preserved.\\n\\n### Audio\\n\\n- **Seed Audio 1.0**: use `videodraft generate audio` for open-ended speech, sound, music, or prompt-driven audio editing. It accepts up to three audio references or one image. Address audio references as `@Audio1`, `@Audio2`, and `@Audio3`. Preset and custom cloned voice IDs are supported. Output is up to 120 seconds. There is no requested-duration input. The CLI automatically retries transient responses with one idempotency key. To recover after the CLI process itself is interrupted, set `--idempotency-key <uuid>` on the original command and reuse it.\\n- **Voiceover/TTS**: prefer ElevenLabs. Brittney is the platform default voice; under ElevenLabs BYOK, use a compatible voice from the user\'s account. Honor another supported voice/provider when the user explicitly selects it. ElevenLabs voices run on Eleven v4 in one of two modes: Standard (the default, best quality) or Turbo (Eleven v4 Turbo, faster and half the price). Keep Standard unless the user wants faster or cheaper speech. Pick the mode with `generate voiceover --mode standard|turbo` or `produce --voice-mode standard|turbo`; over MCP, pass `mode` to `generate_voiceover` or `voice_mode` to `produce_project`. Google, OpenAI and cloned `custom-*` voices ignore it. v4 takes no style or speed settings and no SSML `<break>` tags; audio tags such as `[whispers]` work. Dialogue stays on Eleven v3.\\n- **Dialogue, voice changing, and dubbing**: ElevenLabs only.\\n- **Sound effects**: ElevenLabs Sound Effects only.\\n- **Music**: use `lyria-3.5` for all music, short or long (up to ~3 minutes), with vocals/lyrics or instrumental music. When `--model` is omitted the CLI sends no model and the server default applies, which is `lyria-3.5` wherever the backend supports it. If the server answers that `lyria-3.5` is an unknown model, that backend predates it: rerun without `--model` (the server default then applies), or use `lyria-3-pro-preview` for a track longer than 30 seconds. `lyria-3-clip-preview` (fixed ~30s) and `lyria-3-pro-preview` remain available for explicit requests. Lyria length and structure are prompt-guided, not exact; for an instrumental, include \\"instrumental only, no vocals\\" in the prompt. `--length` and `--instrumental` only apply to ElevenLabs. Use `elevenlabs-music-v2.5` when a specified 3-300 second length, composition plan, or style reference track matters. Lyria references: up to 10 images on Google, 1 on Fal BYOK; 3.5 Fal prompts are 1-5000 characters (an image-only request gets a neutral prompt). `elevenlabs-music` is an alias for v2.5. Use `elevenlabs-music-v1` only when the user asks for v1 by name; it takes a prompt, `--length` and `--instrumental` only.\\n- **ElevenLabs Music v2.5 inputs**: either a prompt (`--length`, `--instrumental`) or a composition plan, never both. A plan is 1-30 sections of 3-120 seconds each, up to 300 seconds in total, and `--plan`/`--section` pick v2.5 when `--model` is omitted. Empty section parts default to 20 seconds and an instrumental part. Build one with repeatable `--section \\"<seconds>|<style, style>|<text>\\"` (use `\\\\n` for line breaks) or pass `--plan plan.json` with `{\\"chunks\\":[{\\"text\\",\\"duration_ms\\",\\"positive_styles\\",\\"negative_styles\\",\\"context_adherence\\",\\"audio_reference\\"}]}`. Section text is an optional `[Section name]`, lyric lines, and `{inline directions}`. Put 6-7 specific English styles on the first section; it sets the genre. `--ref-audio <url|file>` adds a style reference clip to the first section (window up to 30 seconds via `--ref-start`/`--ref-end` in ms, `--ref-strength low|medium|high|xhigh`); local files are uploaded, including relative `audio_reference.audio_url` paths in a plan file. `--seed` works only with a plan. `--format` picks the output (`mp3_48000_192` default on v2.5; `pcm_*`, `ulaw_8000` and `alaw_8000` arrive as stereo WAV files). Style references don\'t run on the user\'s own ElevenLabs key; with that key connected, drop the reference or ask the user to turn the key off. The CLI retries transient responses with one idempotency key; set `--idempotency-key <uuid>` to recover after an interruption.\\n- Voice Changer and Dubbing require the source media duration and currently accept source media up to 300 seconds.\\n\\n**User-supplied ElevenLabs voice IDs:** voiceover, dialogue, and voice changing accept raw IDs (16-64 alphanumeric characters) or `elevenlabs-<id>`. `videodraft models voices` / MCP `list_available_voices` is for discovery, not an allowlist. Pass a supplied ID directly even when it is absent from the catalog; do not reject it or substitute a catalog voice. The voice must be accessible to the provider account used for generation. Private or cloned voices may require the user\'s connected ElevenLabs key. A failed voice listing does not prove that a supplied ID cannot generate; a connected key with generation access may still work. If the provider rejects generation access, report that error rather than silently changing the voice.\\n\\nUse `--voice <id>` for voiceover and voice changing, and repeat `--line \\"<id>:Text\\"` for dialogue. These examples show both ID forms; replace the sample IDs with the user\'s supplied IDs:\\n\\n```bash\\nvideodraft generate voiceover \\"Hello there.\\" --voice kPzsL2i3teMYv0FxEYQ6 --download ./media/voiceover.mp3\\nvideodraft generate dialogue --line \\"kPzsL2i3teMYv0FxEYQ6:Hello.\\" --line \\"elevenlabs-kmSVBPu7loj4ayNinwWM:Welcome back.\\" --download ./media/dialogue.mp3\\nvideodraft generate voice-changer ./media/source.wav --voice elevenlabs-kPzsL2i3teMYv0FxEYQ6 --duration 12 --download ./media/changed-voice.mp3\\n```\\n\\nFor MCP, use `generate_voiceover.voice_id`, `generate_dialogue.lines[].voice_id`, or `change_voice.voice_id` with either form. ElevenLabs IDs are separate from Kling video-control voice IDs and MiniMax `custom-*` cloned-voice IDs. Do not convert IDs from those systems into ElevenLabs IDs.\\n\\n### Avatar / talking head\\n\\n**First decide the framing, not just \\"someone talks\\".** This lane animates a PORTRAIT facing the lens. A character delivering a line inside a real scene, with blocking, framing or camera movement, belongs to `generate video` instead: write the dialogue in the prompt and `gemini-omni-1.1-flash`, `seedance-2.5`, `seedance-2`, `kling-3.0` or `kling-o3` voices it natively (add a Seedance `--ref-audio` clip or a Kling voice bound per element for a specific voice). That is the default for any talking character; never plan silent video + TTS + lip-sync. Sending a cinematic shot to Fabric returns a head-on talking headshot, not the shot that was asked for. `videodraft models video --json` lists these under `recommended.in_scene_dialogue`.\\n\\nFor a presenter, spokesperson or explainer speaking to camera, VEED Fabric is the preferred model. Choose the dedicated path from the media the user already has:\\n\\n| Starting media                             | Command                                                                   | Use                                                        |\\n| ------------------------------------------ | ------------------------------------------------------------------------- | ---------------------------------------------------------- |\\n| Portrait + script, reusable avatar record  | `videodraft avatar create <portrait> --script \\"...\\"` then `avatar render` | Managed avatar flow with bundled speech preparation        |\\n| Portrait + text                            | `videodraft avatar fabric <portrait> --text \\"...\\"`                        | One-off direct VEED Fabric text mode                       |\\n| Portrait + existing audio                  | `videodraft avatar fabric <portrait> --audio <audio>`                     | One-off direct VEED Fabric audio lip sync                  |\\n| Portrait + existing audio, short and sharp | `videodraft avatar h3-lipsync <portrait> --audio <audio>`                 | MiniMax H3 Max Lip Sync, 5-14.8s at up to 2K               |\\n| Existing video + existing audio            | `videodraft avatar lipsync <video> --audio <audio>`                       | Sync Labs Lipsync 2 (Tier 2): re-dub existing footage only |\\n\\nThe managed renderer is VEED Fabric Fast (`veed/fabric-1.0/fast`). Direct Fabric, MiniMax H3 Max Lip Sync, and Sync Labs are paid AI Studio generations and return async job IDs.\\n\\n1. Obtain the avatar image. Prefer the user\'s supplied portrait or an existing character. If none exists, use the user\'s explicitly requested compatible image model, otherwise generate a front-facing head-and-shoulders portrait with `nano-banana-2`, direct eye contact, a natural expression, and a clean background. Match the intended video aspect ratio when practical.\\n2. If the portrait is visibly soft or too small, run Topaz image enhancement/upscaling before animation.\\n3. Generate a script only if needed: `videodraft avatar script \\"<idea>\\"`.\\n4. Create the avatar record and speech: `videodraft avatar create <portrait-url-or-file> --script \\"...\\" --voice <id> --ar 9:16`. Prefer ElevenLabs when unspecified, but honor another explicitly selected supported voice/provider.\\n5. Render with VEED Fabric: `videodraft avatar render <avatar_video_id> --resolution 720p`.\\n\\nThe portrait is passed as the avatar\'s character image, not as a generic video\'s start frame. Prefer rendering directly at 720p. Use 480p only when the user prioritizes lower cost. Avatar script generation and `avatar create` (including speech) are bundled/free. Confirm the Fabric render cost, plus portrait generation or upscaling when needed.\\n\\nDirect Fabric text/audio, H3 Max Lip Sync, and Sync Labs do not use the managed avatar record. The CLI uploads local portrait, video, and audio files automatically. `avatar fabric --speed fast` applies only to audio mode. `avatar h3-lipsync` takes no prompt: pick `--resolution 480P|768P|1080P|2K` (default 768P), an optional `--seed`, `--no-transcription` to sync without transcribing the audio (transcription is on by default), and `--safety-checker` only when the user asks for Fal\'s checker. The portrait\'s width / height must be 0.4-2.5, and audio shorter than 5 seconds is refused before any charge. Sync costs 5 credits per verified audio second; under Fal BYOK, `sync_mode` remains available but `temperature` and `active_speaker` are ignored by the provider.\\n\\n### Upscaling / enhancement\\n\\n- **Images**: Topaz via `videodraft upscale image <url-or-file> --scale 1x|2x|4x [--mode precision|generative|creative] [--model <name>]`. Modes: `generative` (default; Wonder 3.5, Topaz\'s recommended model for AI-generated images; `Redefine` takes `--prompt`, `--creativity 1-6`, `--texture 1-5`), `precision` (faithful and cheapest; Standard V2, High Fidelity V3, Low Resolution V2, CGI, Text Refine; use for clean real photos), `creative` (Bloom 2; artistic, `--prompt`, `--creativity 1-9`). Extra knobs: `--no-face-enhance`, `--face-strength`, `--sharpen`, `--denoise`, `--fix-compression`, `--format png`. Use 1x for light enhancement without enlargement, 2x as the general default, and 4x only when the source quality and target size justify it. The server must verify dimensions from a readable image of at most 50 MB; `--width` and `--height` are compatibility hints and cannot bypass a failed probe. The result may be immediate or queued; the CLI waits by default. Use `--no-wait` for an async job ID, and poll it with `status` or `wait`. Cost: 8 credits per started 24 MP of output in precision, per 8 MP (Wonder 3/3.5) or 4 MP in generative, per 2 MP in creative.\\n- **Videos**: Topaz via `videodraft upscale video <url-or-file> --resolution 720p|1080p|4k` (preferred) or `--scale 2x`, plus `--mode precision|generative|creative` and `--model <name>`. `generative` (default; Starlight Precise 2.6, Topaz\'s recommended model for AI-generated footage; Starlight Fast 2 at half price) costs 12 credits/s up to 1080p and 26 at 4K. `precision` (Proteus, Proteus Natural, Iris, Gaia 2 for animation, Rhea, Theia, Artemis, Dione) is 6x cheaper at 1 / 2 / 6 credits per second for 720p / 1080p / 4K output; use it for real footage or when cost matters. `creative` (Astra 2, `--prompt`, `--creativity`, `--realism`, `--sharp`) always renders 4K at 50 credits/s. `--fps 60` delivers 60fps on the same pass; any output above 30fps (including a 50/60fps source) doubles every rate; the server must verify duration, dimensions, and frame rate from an MP4/MOV source of at most 100 MB. `--duration`, `--width`, `--height`, and `--source-fps` are compatibility hints and cannot override billing or bypass a failed probe. The same source-verification requirement applies to frame interpolation. `--scale` also accepts intermediate factors such as `1.5x`. Max source length 5 minutes. The job is asynchronous; the CLI waits by default, while MCP callers poll `check_generation_status`. MCP video input must be VideoDraft-hosted, so upload local or external sources first.\\n- **Frame interpolation / slow motion**: `videodraft interpolate <url-or-file> --fps 60 [--model Apollo|Chronos|Aion] [--slowdown 1-8]` (MCP `interpolate_video`). Resolution is unchanged. Apollo (default) for smooth general conversion, Chronos for natural slow motion, Aion for extreme slow motion. Apollo/Chronos cost 3 credits per output second up to 1080p (6 at 4K); Aion 5 / 17. These rates cover targets up to 60fps; above 60fps multiply by target FPS / 60 (120fps doubles the rate). Output seconds = source seconds \xD7 slowdown. The final charge rounds up to a whole credit.\\n- Use upscaling to preserve the image/video while improving detail, resolution, or cleanup. It cannot fix the wrong subject, misspelled text, bad framing, unwanted objects, broken continuity, or incorrect motion. Use an edit or regeneration for those problems. Keep `generative` for AI-generated sources; switch to `precision` for clean real photos/footage or a cheap pass, and `creative` only when the user wants an artistic reinterpretation.\\n- For a new Fabric avatar, render directly at 720p instead of rendering at 480p and then upscaling. Upscale the source portrait first only when the portrait itself is low quality.\\n\\n## Capability gotchas\\n\\n- Each model\'s `inputs` block is authoritative: supported `aspect_ratios`, `resolutions`, `quality_options`, `start_frame`/`end_frame`, `max_reference_images/videos/audio`, `multi_prompt`, `audio_toggle`. Passing an unsupported input fails with a clear error \u2014 check first, don\'t trial-and-error paid calls.\\n- Most video models support only 16:9 / 9:16 / 1:1. A 3:4 request hard-fails on most.\\n- `--seed` reproduces a specific output on models that support it (e.g. Flux, Ideogram V4). GPT Image 2.5 rejects any explicit seed; older models may ignore unsupported seeds. You do not need a seed for variation \u2014 `--num` already varies.\\n- `--rendering-speed` applies to Ideogram (V3: `Default`/`Turbo`/`Quality`; V4: `Turbo`/`Balanced`/`Quality`) and affects image cost \u2014 pass it to `videodraft costs ... --rendering-speed <tier>` for an accurate estimate. Always trust `videodraft models image --json` over this list; new models and tiers appear there the moment the platform ships them, with no CLI update.\\n- `seedream-v5-pro` supports unified text-to-image and reference-image editing with up to 10 image references. Use `--resolution 1K` for 7 credits/image or `--resolution 2K` for 14 credits/image.\\n- Reference inputs: `--ref <img>` (images, including up to 10 total for Gemini Omni 1.1 Flash and Wan 3.0, and 7 for Grok 1.5), `--source-video <v>` (Gemini uploaded edit/extension source), `--ref-video <v>` (up to 3 creative videos <=3s each for Gemini Omni 1.1 Flash; also Wan 3.0, MiniMax H3, MiniMax H3 Max, and Seedance 2), `--ref-audio <a>` (Wan 3.0, MiniMax H3, MiniMax H3 Max, Seedance 2), and `--element \'<json>\'` or `--element @elements.json` for Kling V3/O3. For an exact Seedance 2.x reference-video `--estimate`, add `--ref-video-seconds <combined-seconds>`; Seedance bills input seconds alongside output. Wan 3.0 and MiniMax H3 do not bill input reference seconds; MiniMax H3 Max bills them as pooled reference tokens. The CLI uploads local media references and every structured element without flattening the source/reference roles. `--segment \\"<prompt>:<seconds>\\"` (repeatable) drives Kling 3.0, Kling 3.0 Turbo, and O3 multi-prompt generation. Use 1-6 segments of 1-15 whole seconds each, with 3-15 seconds total. `generate image --video-ref` is the nano-banana-2 video reference.\\n- The top-level prompt is OPTIONAL for Gemini Omni 1.1 Flash media-input or continuation calls, Wan 3.0 frame/reference modes, `generate video` with multi-prompt models, and Kling 3.0 Turbo (`--model kling-v3-turbo`) image-to-video. Text-only Gemini and Wan calls still require a prompt unless their live schema says otherwise.\\n- Hosted AI Production fallback: `videodraft produce <project> --mode full_video` generates one Seedance 2 video per scene, with real people allowed by default at the higher Fal-tier rate on every submitted scene segment; add `--no-allow-real-people` for the lower Byteplus-only rate when no scene shows a real identifiable person. The MCP equivalent is `produce_project` with `mode: \\"full_video\\"` (and `allow_real_people: false` to opt out). If a partial opted-out run returns `SEEDANCE_REAL_PERSON_OPT_IN_REQUIRED`, rerun the same project once with an explicit `--allow-real-people` after cost confirmation. The server reconciles asynchronous results first, preserves running/completed jobs, and retries only failed placeholders carrying that exact code. Poll with `videodraft generations`, then `videodraft finalize <project>` swaps them into the hosted timeline before `export`. In VideoDraft ADE, do not choose this path while `videodraft_editor` is available unless the user explicitly requests hosted production. Generate or download the scene assets, import them, and assemble/export with the native editor instead. If the user explicitly requests another compatible video model for a hosted production, do not use this fixed Seedance path; generate the project shots manually with the requested model and attach them to the hosted timeline.\\n\\n## Cost model\\n\\n- Images: per image (\xD7 `--num`). Matrix-priced models (GPT-Image, Nano Banana Pro, Seedream v5 Pro) vary by resolution/quality.\\n- Video: usually credits/second \xD7 duration; rate depends on model + resolution + quality + native audio on/off.\\n- Gemini Omni 1.1 Flash: 3 / 10 / 15 / 30 credits per output second at 360p / 720p / 1080p / 4K (720p default). Extend appends an explicit 3-10 seconds to a 1-30s source, whether uploaded or resolved from a prior interaction; 40 seconds total is reachable only while the source stays at or under 30s. Fal BYOK generation and basic source edits cost zero VideoDraft credits; continuation, extension, and separate creative references on a source edit are unavailable under Fal BYOK.\\n- MiniMax H3: 5 / 6 / 13 / 16 credits per output second at 480p / 768p / 2K / 4K (768p default). The first 5 reference images are included, then 8 credits for each additional image. Reference video and reference audio are NOT billed.\\n- MiniMax H3 Max: 5 credits per output second at 480p or 8 credits per second at 768p (default), plus pooled reference tokens. The first 4,096 reference tokens are free and each additional 1,000 costs 2 credits. An image is `(width x height) / 1024` tokens (a 1024x1024 reference is 1,024, so four of them are free); a reference video is 2,886 tokens per second at 480p or 7,459 at 768p; reference audio is about 2,121 per second. Pass `--ref-audio-seconds` for an exact estimate with audio references. The server measures each reference image, so a quote that assumes 1024x1024 is a floor.\\n- Wan 3.0: 7 / 14 / 28 credits per output second at 480p / 720p / 1080p. Auto duration reserves 30 seconds and reconciles unused credits from the provider-reported output duration. Fal BYOK charges zero VideoDraft credits.\\n- Grok Imagine Video 1.5: 8 credits/output second at 480p, 14 at 720p, or 25 at 1080p, plus 1 credit for each first-frame or reference image. Native generated audio is part of every output.\\n- Kling voice control: 17 credits/output second for Kling 2.6 Pro, 16 at Kling V3 Standard, and 20 at Kling V3 Pro.\\n- Shot-image batches: one image per shot (+1 grid image per scene in `--grid` mode) \u2014 the largest single spend in the pipeline.\\n- VEED Fabric avatar renders: ~10 credits/sec at 480p, ~20/sec at 720p. Avatar creation and its speech are bundled/free; only optional portrait generation/upscaling adds cost before the render.\\n- Direct VEED Fabric: text or normal audio is 8 credits/sec at 480p and 15/sec at 720p; fast audio is 10/sec at 480p and 20/sec at 720p.\\n- MiniMax H3 Max Lip Sync: 5 / 8 / 16 / 32 credits per output second at 480P / 768P (default) / 1080P / 2K. The video runs as long as the audio (at least 5s; only the first 14.8s is used), billed on the server-measured length rounded up, so at most 15 seconds. Use MP3, WAV, M4A (AAC), or AAC audio; other formats run only on the user\'s own Fal key.\\n- Sync Labs Lipsync 2: 5 credits per verified audio second.\\n- Voiceover TTS: 10 credits per 1000 characters for standard voices (including ElevenLabs Standard, Eleven v4), 5 per 1000 for ElevenLabs Turbo (Eleven v4 Turbo), and 30 per 1000 for cloned `custom-*` voices (min 1, pro-rated); applies to standalone voiceovers AND per-scene narration during `produce`. Quote Turbo with model id `voiceover-turbo` (CLI: `costs voiceover --mode turbo`) and cloned voices with `voiceover-cloned`. Silent tracks are free. Voice cloning itself is a flat 150 credits per clone.\\n- Lyria music: flat per track, 4 credits (Clip) / 10 credits (3.5) / 8 credits (legacy Pro). Fal BYOK uses zero VideoDraft credits.\\n- Seed Audio 1.0: 19 credits per actual output minute, prorated and rounded up to a whole credit. VideoDraft reserves the 120-second maximum of 38 credits and refunds the unused portion after generation. Fal BYOK is free.\\n- ElevenLabs audio: sound effects are per second, dialogue is per character, music/voice-changer/dubbing are per started minute. ElevenLabs Music v2.5 and v1 both cost 60 credits per started output minute; estimate a composition plan with its total length. Voice changer and dubbing reject source media above 300s in the current synchronous flow.\\n- Seedance 2.0 / 2.5 real people: allowed by default, which keeps Byteplus first, permits a submit-time Fal fallback, and prices at Fal\'s rate for that tier: 2.0 Mini 8/16 cr/s, Fast 11/25, Standard 14/31/69/156, 2.5 23/48/114 for 480p/720p/1080p. `--no-allow-real-people` uses the Byteplus-priced path instead (2.0 Mini 4/8, Fast 6/13, Standard 7/16/38/78, 2.5 11/24/57); Byteplus refuses real-person likenesses, so a likeness-policy failure then does not fall back. The gap is roughly 2x but not exactly: the Seedance 2.0 1080p pair is 38/69, or about 1.82x. If Byteplus accepts the task and later rejects the generated output, VideoDraft refunds the failure but does not resubmit it to Fal. Turn the option off only for the cheapest run when nothing in the job is a real identifiable person.\\n- Grok Imagine images: `grok-imagine` is a flat 2 cr (3 with a reference). `grok-imagine-2.0` is a separate, newer model priced by resolution and quality: 1K 4 (low) / 6 (medium), 2K 6 / 8, plus 1 cr per reference image (up to 3). v1 is NOT superseded \u2014 pick it when cost matters more than 2K.\\n- xAI bills refused requests, so failed Grok generations are not refunded.\\n- Upscales: priced by output size, mode, and (video) duration/fps; see the Upscaling section above.\\n\\nQuote before spending:\\n\\n```bash\\nvideodraft costs gemini-omni-1.1-flash --type video --duration 8 --resolution 720p --audio\\nvideodraft costs topaz-upscale-video --type video --duration 10 --width 1920 --height 1080 --resolution 4k --mode generative\\nvideodraft costs topaz-upscale --type image --width 2048 --height 2048 --scale 2x\\nvideodraft costs topaz-interpolate-video --type video --duration 10 --width 1920 --height 1080 --fps 60 --topaz-model Apollo\\nvideodraft costs minimax-h3 --type video --duration 10 --resolution 2K --ref-images 7\\nvideodraft costs minimax-h3-max --type video --duration 10 --resolution 768p --ref-images 2\\nvideodraft costs grok-imagine-video-1.5 --type video --duration 8 --resolution 720p --ref-images 4\\nvideodraft costs seedance-2 --type video --duration 15 --resolution 720p --quality standard --audio\\nvideodraft costs grok-imagine-2.0 --type image --resolution 2K --quality medium --num 2\\nvideodraft costs seedance-2 --type video --duration 15 --resolution 720p --quality standard --audio --no-allow-real-people # lower Byteplus-only rate\\nvideodraft costs elevenlabs-dubbing --type audio --duration 60\\nvideodraft costs seed-audio-1.0 --type audio --duration 60 # scenario only; model controls actual length\\nvideodraft costs elevenlabs-dialogue --type audio --chars 350\\nvideodraft costs voiceover --type audio --chars 800    # TTS: 10 cr / 1000 chars\\nvideodraft costs voiceover --type audio --chars 800 --mode turbo # ElevenLabs Turbo: 5 cr / 1000 chars\\nvideodraft generate video \\"...\\" --model gemini-omni-1.1-flash --estimate # same quote, inline\\nvideodraft generate video \\"...\\" --model minimax-h3-max --duration 8 --resolution 768p --prompt-expansion-mode balanced\\n```\\n","references/pipeline.md":"# VideoDraft pipeline reference\\n\\nEverything here describes the hosted fallback pipeline through the CLI (`videodraft <command>` / `videodraft call <tool>`) or hosted MCP connector (tool names in backticks). When the local `videodraft_editor` MCP is available, do not use hosted production or export by default. Use hosted tools only for asset generation and optional script/storyboard stages, then import the results and finish with the native editor reference linked from SKILL.md. Continue through `produce_project` and `export_video` only when the user explicitly requests a hosted web production or the native editor is unavailable.\\n\\nUse direct asset tools for standalone images, clips, audio, upscales, and descriptions. Use a hosted project when the user explicitly wants the editable web project, when a hosted storyboard stage is useful, or when the native editor is unavailable. Script-only uses a script-stage project and stops at the script. In VideoDraft ADE with editor tools present, stop before hosted production, import the generated assets, and build/export the native project.\\n\\n## Stages and their tools\\n\\n| Stage                                    | CLI                                                                         | Underlying tool                             |\\n| ---------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------- |\\n| Idea \u2192 full storyboard project           | `videodraft create \\"<idea>\\"`                                                | `generate_storyboard_from_idea`             |\\n| Idea \u2192 script only (stop there)          | `videodraft create \\"<idea>\\" --script-only`                                  | `generate_script_from_idea`                 |\\n| Footage IS the video                     | `videodraft call generate_storyboard_from_media`                            | `generate_storyboard_from_media`            |\\n| Batch shot images                        | `videodraft shots <project>`                                                | `generate_shot_images`                      |\\n| One shot image                           | `videodraft generate image --project <id> --scene N --shot M`               | `generate_image`                            |\\n| Produce (voiceover, captions, timeline)  | `videodraft produce <project>`                                              | `produce_project`                           |\\n| Seedance full-video production           | `videodraft produce <project> --mode full_video`                            | `produce_project` with `mode: \\"full_video\\"` |\\n| Per-shot motion prompts                  | `videodraft video-prompts <project>`                                        | `generate_video_prompts`                    |\\n| Motion clip for a shot                   | `videodraft generate video --project <id>`                                  | `generate_video`                            |\\n| Attach a finished clip to the timeline   | `videodraft attach <project> --scene N --shot M --media <url> --type video` | `attach_media_to_shot`                      |\\n| Find free b-roll (no credits)            | `videodraft stock search \\"<query>\\"`                                         | `search_stock_media`                        |\\n| Copy stock media onto the CDN            | `videodraft stock import <ref>`                                             | `import_stock_media`                        |\\n| Background music                         | `videodraft generate music --attach <project>`                              | `generate_music` / `set_background_music`   |\\n| Song with vocals, lyrics or sections     | `videodraft generate music --model elevenlabs-music-v2.5 --section \\"...\\"`   | `generate_music` with `composition_plan`    |\\n| General or reference-driven audio        | `videodraft generate audio \\"...\\"`                                           | `generate_audio`                            |\\n| Sound effect                             | `videodraft generate sound-effect \\"...\\"`                                    | `generate_sound_effect`                     |\\n| Dialogue audio                           | `videodraft generate dialogue --line \\"voice:text\\"`                          | `generate_dialogue`                         |\\n| Voice changer                            | `videodraft generate voice-changer <audio>`                                 | `change_voice`                              |\\n| Dubbing                                  | `videodraft generate dub <audio_or_video>`                                  | `dub_media`                                 |\\n| Scene voiceover                          | `videodraft generate voiceover --project <id> --scene N`                    | `generate_voiceover`                        |\\n| Avatar script                            | `videodraft avatar script \\"<idea>\\"`                                         | `generate_avatar_script`                    |\\n| Avatar + speech                          | `videodraft avatar create <portrait> --script \\"...\\"`                        | `create_avatar_video`                       |\\n| Talking-head render                      | `videodraft avatar render <avatar_video_id>`                                | `render_avatar_video` + `get_avatar_video`  |\\n| Direct portrait + text/audio             | `videodraft avatar fabric <portrait> --text \\"...\\"` or `--audio <file>`      | `generate_veed_fabric_video`                |\\n| Short portrait clip from audio, up to 2K | `videodraft avatar h3-lipsync <portrait> --audio <file>`                    | `generate_minimax_h3_lipsync_video`         |\\n| Existing video + replacement audio       | `videodraft avatar lipsync <video> --audio <file>`                          | `generate_sync_lipsync_video`               |\\n| Existing-video AI edit                   | `videodraft edit video <video> \\"<change>\\" --model <video-edit-model>`       | `edit_video`                                |\\n| Motion transfer                          | `videodraft edit motion <image> [direction] --motion-video <video>`         | `generate_motion_control_video`             |\\n| Image enhancement/upscale                | `videodraft upscale image <image>`                                          | `upscale_image`                             |\\n| Video enhancement/upscale                | `videodraft upscale video <video>`                                          | `upscale_video`                             |\\n| Frame rate / slow motion                 | `videodraft interpolate <video> --fps 60 [--slowdown 4]`                    | `interpolate_video`                         |\\n| Final MP4                                | `videodraft export <project>`                                               | `export_video` + `check_export_status`      |\\n\\n## Rules that prevent broken results\\n\\n- **The storyboard is generated FROM the script**, never from the raw idea. `videodraft create` runs the whole chain correctly. Don\'t call `generate_storyboard_scenes` with a raw idea as the \\"script\\".\\n- **Visual consistency**: never generate a storyboard shot in isolation. Shot prompts carry `[[asset:Name]]` / `[[shot:X-Y]]` tags that `generate_shot_images` resolves against the project\'s visual assets and prior shots. When generating a single shot whose prompt has no tags, pass `--ref` images yourself (the project\'s visual assets and/or the previous shot\'s image; `projects get` exposes both). For scenes with multiple shots or recurring characters, prefer `videodraft shots <project> --model <selected-image-model> --grid`: preserve an explicitly requested compatible image model, otherwise use `nano-banana-2`. It creates one coherent scene grid, then decodes it into individual shot images.\\n- **Reference-first video**: when identity, styling, or composition matters, do not generate each motion clip from text alone. Generate or select the shot still first, then pass the decoded shot image as `--start-image` or `--ref` to the selected video model. AI Production already composes scene grids and sends them to Seedance as references. If the user explicitly requests another compatible video model, bypass fixed Seedance full-video mode and generate the per-shot clips with the requested model, using the individual decoded shot images as anchors.\\n- **Seedance full-video real people**: hosted `full_video` allows real people by default, which applies Fal-tier pricing to every submitted segment and permits the Byteplus-to-Fal fallback. For the lower Byteplus-only rate when no scene grid shows a real identifiable person (non-people, anime, clearly synthetic or stylized characters), use `videodraft produce <project> --mode full_video --no-allow-real-people`, or MCP `produce_project` with `mode: \\"full_video\\", allow_real_people: false`. If a partial opted-out run returns `SEEDANCE_REAL_PERSON_OPT_IN_REQUIRED`, re-estimate, follow the user\'s spend-confirmation preference, and rerun the same project once with an explicit `--allow-real-people` / `allow_real_people: true`. The server reconciles asynchronous results first, preserves running/completed jobs, and retries only failed placeholders carrying that exact code. Do not loop when it was already on. VideoDraft refunds a Byteplus task rejected after asynchronous acceptance, but cannot reroute it; rephrase or change the scene references instead.\\n- **Narration voice mode**: ElevenLabs narration runs on Eleven v4. Standard is the default and the best quality, at 10 credits per 1000 characters. `videodraft produce <project> --voice-mode turbo` (MCP `produce_project` with `voice_mode: \\"turbo\\"`) uses Eleven v4 Turbo, which is faster at 5 credits per 1000 characters. For one scene, `videodraft generate voiceover --project <id> --scene N --mode turbo` (MCP `generate_voiceover` with `mode: \\"turbo\\"`) does the same. Google, OpenAI and cloned `custom-*` voices ignore the mode.\\n- **Hold off generating shot images while the user is still iterating** on storyboard structure.\\n- **produce \u2192 export ordering**: `export` requires a produced project where every production scene has timeline media. If `produce` returns `generating_shot_images`, poll the job ids it returns, then re-run produce.\\n- **Do not attach motion clips before production exists**: run `produce` successfully first, then attach finished motion clips to the production timeline. Attaching before `production_data` exists cannot place them in the final timeline.\\n- **Generated motion clips do not auto-attach**: after `generate video` completes, attach the clip with `attach_media_to_shot` (`media_type:\\"video\\"`, include `duration_seconds`) \u2014 it replaces the production timeline clip while keeping the storyboard still.\\n- **Talking heads use dedicated avatar tools**: do not use `generate video`. Use managed `avatar create` and `avatar render` for reusable avatars, direct `avatar fabric` for a portrait plus text/audio, `avatar h3-lipsync` for a short (5-14.8s) portrait clip from existing audio at up to 2K, and `avatar lipsync` for an existing video plus replacement audio. Reuse a supplied person image or generate a clear front-facing portrait with the explicitly requested compatible image model, otherwise Nano Banana 2. Managed avatar creation and speech are bundled/free; direct Fabric, H3 Max Lip Sync, Sync, and render are paid.\\n- **Existing-video edits use their own category**: call `edit_video` or `videodraft edit video` with a `video_edit` model when transforming the source itself. Kling O3 also has a reference-generation mode that creates a new guided clip. Wan 3.0 is a text/frame/reference generation model, not a source-video editor. Motion transfer similarly uses `generate_motion_control_video` or `videodraft edit motion` with a `motion_control` model.\\n- **Upscaling preserves rather than redesigns**: use Topaz when resolution, detail, or cleanup is the problem (generative mode by default: Wonder 3.5 / Starlight Precise 2.6, Topaz\'s pick for AI sources; precision for real photos/footage or the cheapest pass; creative only for an artistic reinterpretation; `interpolate` for frame rate or slow motion). Regenerate or edit when the subject, text, framing, continuity, or motion is wrong. Upscale a low-quality avatar portrait before Fabric; do not render a new avatar at 480p just to upscale the result.\\n- **Timeouts on the one-shot create**: if `create` times out at the transport layer, the project was still created server-side \u2014 `videodraft projects list`, take the most recent, and resume with its id. Don\'t start a duplicate.\\n\\n## User-attached media: classify roles first\\n\\nFor EACH attached file decide:\\n\\n- **visual_asset** \u2014 recurring reference (character / product / location / style). Upload, then pass in `visual_assets` of `generate_storyboard_from_idea` (via `videodraft call`), or add to an existing project with `add_visual_assets`. Type must be one of `character | object | location | style | custom` with a short name + concrete description.\\n- **shot** \u2014 the media IS footage for the video. Whole video = footage \u2192 `generate_storyboard_from_media`. Idea + footage \u2192 `generate_storyboard_from_idea` with `shot_media`. Existing storyboard \u2192 `attach_media_to_shots`.\\n- **reference** \u2014 inspiration only \u2192 fold a description into the idea/instructions; don\'t place it as a shot or asset.\\n\\nAmbiguous (e.g. a person holding a product)? Ask the user.\\n\\nUploads persist in the media library \u2014 recall later with `videodraft media list`.\\n\\n## Editing project data safely\\n\\n1. `videodraft call get_project_schema` \u2014 read the structure once per session.\\n2. `videodraft projects get <id> --raw` \u2014 the exact editable blob.\\n3. Modify; then `videodraft call update_project --stdin` with `{\\"project_id\\": \\"...\\", \\"data\\": {...}}`.\\n   - Objects deep-merge key-by-key; **arrays replace wholesale** \u2014 send the complete array you\'re changing (e.g. all of `storyboard.scenes`).\\n   - Scene shot arrays (`image_prompt` / `shot_types` / `shot_actions` / `search_prompt` / `preview_media`) are auto-aligned; fix-ups come back as warnings.\\n4. Snapshot before risky edits: `videodraft checkpoint create <id> --name \\"before re-script\\"`. Restore with `videodraft checkpoint restore <id> <version>`.\\n\\n## AI Studio sessions (standalone generations)\\n\\nProject generations group automatically, and standalone work is grouped per conversation (MCP) or per working directory (CLI) by the connection session \u2014 see the \\"AI Studio sessions\\" section of SKILL.md. Once the task is clear, give that automatic session a concise 3-6 word title before the first generation:\\n\\n```bash\\nvideodraft sessions name \\"Fox Brand Explorations\\"\\nvideodraft generate image \\"...\\"\\n```\\n\\nNaming creates the session with that title. If generation, a user, or an earlier agent created it first, the existing name is preserved. The command refuses to run while `VIDEODRAFT_SESSION` is set, because that override would send later generations to a different session. Use `sessions create` plus `--session` only to continue or deliberately create a separate group.\\n"}') {
+    return JSON.parse('{"SKILL.md":"---\\nname: videodraft\\ndescription: Create and edit AI videos, images, 3D meshes, Seed Audio, voiceovers, music, sound effects, dialogue, dubbing, storyboards, avatar videos, media upscales, and product/ad videos with VideoDraft. Use whenever the user mentions VideoDraft; asks to generate a video, image, 3D asset, audio asset, ad, explainer, storyboard, avatar, upscale, or batch/CI workflow; wants to download a video from YouTube, Instagram, TikTok, X or another site; or wants to assemble, cut, caption, mix, lay out, inspect, or export a native VideoDraft Editor timeline. Covers the cloud `videodraft` CLI/MCP and local headless `videodraft_editor` MCP. When the editor MCP is exposed, prefer it for production, timeline assembly, and export; use cloud production/export only when explicitly requested or the editor is unavailable.\\n---\\n\\n# VideoDraft\\n\\nVideoDraft is an AI video creation platform where asset generation is the priority lane:\\n\\n- **Asset generation**: standalone images, video clips, Seed Audio, voiceovers, music, sound effects, dialogue, voice-changed audio, dubbed media, upscales, and image descriptions. This is the fastest and most important lane. Treat these as complete deliverables when the user asks for assets.\\n- **Asset I/O**: upload local files, download outputs, auto-upload local references, and save generated media where the user can see it.\\n- **3D assets**: standalone Meshy 7 and Tripo H3.1 meshes, multi-view generation, complete artifact downloads, and Meshy humanoid rigging through MCP/CLI. Read [references/3d.md](references/3d.md), or `videodraft skills show 3d`. These assets have their own saved library and do not require an AI Studio session or web viewer.\\n- **Native editing**: local `.vdproject` timelines, cuts, layouts, captions, effects, audio, and exports through the headless VideoDraft Editor. Inside VideoDraft ADE, this is the default production and export lane whenever `videodraft_editor` is available.\\n- **Hosted project production**: idea \u2192 script \u2192 storyboard \u2192 hosted production timeline \u2192 exported MP4. Use the early stages for scripts, storyboards, and generated assets when useful. Treat hosted production and export as a fallback when the native editor is unavailable, or as an explicit destination when the user asks for an editable web project or hosted workflow.\\n\\n## How to connect\\n\\nGeneration billing is selected in VideoDraft Settings \u2192 API keys. Where enabled,\\n**VideoDraft routing** chooses an equivalent provider internally without changing\\nthe quoted customer credit price. A selected personal key is exclusive: never\\nswitch to VideoDraft credits or another key after an unsupported-model or\\nprovider error. Keep the canonical VideoDraft model ID in CLI/MCP calls. Poll\\nthe original generation after a timeout instead of starting another paid job.\\nNew provider connections can support only a subset of models and settings;\\nfollow the server\'s availability response. ElevenLabs remains audio-only.\\nFor Pika GPT Image 2.5, supply an explicit quality (`low`, `medium`, `high`,\\n`xhigh`, or `max`); `auto` is not supported by that connection. Nano Banana 2\\nLite is 1K only. Never remove requested controls or substitute a different\\nmodel merely to make a personal connection accept the job.\\n\\nCloud generation has two equivalent surfaces (same backend, credits, and hosted projects). Native timeline editing is a separate local surface:\\n\\n1. **CLI** (preferred when you have a shell): run `videodraft` if it\'s on PATH; otherwise `npx -y videodraft@latest` runs it with no install (needs Node \u226520; the `-y` skips npx\'s install prompt so it runs non-interactively; the package is fetched on first use and cached). For heavy use, `npm install -g videodraft`. If there\'s no Node/shell here but the MCP connector below is available, use that instead; if neither works, tell the user how to install (https://videodraft.ai/cli).\\n   - Auth \u2014 pick by context, don\'t guess:\\n     \u2022 INTERACTIVE (a human is in the session, e.g. Claude Code / Codex): on exit code 3 (\\"not authenticated\\"), tell the user to run `videodraft login` in their terminal \u2014 it opens their browser for a one-click VideoDraft sign-in (OAuth), no key to copy. Wait for them to confirm it succeeded, then retry the command. This is the preferred path when the user is present.\\n     \u2022 HEADLESS / CI (no browser): set `VIDEODRAFT_API_KEY=vd_mcp_...` (a token the user mints at https://app.videodraft.ai/mcp-keys).\\n     \u2022 SECURITY: never ask the user to paste a `vd_mcp_...` token into the chat \u2014 use browser `login` or the env var so the token never lands in the transcript.\\n   - Every command accepts `--json` (parse this, don\'t scrape text). Exit codes: 0 ok, 1 error, 2 usage, 3 auth (see Auth above), 4 insufficient credits (\u2192 tell the user, don\'t retry).\\n   - Tool discovery: start with `videodraft tools list` for the grouped catalog, then narrow with `videodraft tools list --lane assets`, `--lane asset_io`, `--lane project_data`, or `--lane production`.\\n   - Asset lane: `videodraft generate ...`, `videodraft edit video|motion`, `videodraft avatar ...`, `videodraft upscale ...`, `videodraft interpolate ...`, `videodraft upload`, and `videodraft download`.\\n   - Full API access: `videodraft tools schema <name>`, `videodraft call <tool> --args \'<json>\'`.\\n2. **MCP connector**: if VideoDraft MCP tools (e.g. `generate_storyboard_from_idea`) are available, call them directly \u2014 the CLI\'s curated commands map 1:1 onto these tools.\\n3. **Native editor MCP** (`videodraft_editor`): prefer this for project production, timeline assembly, cutting, layouts, transitions, captions, audio placement, and final export. Inside VideoDraft ADE on a supported Mac, Claude, Codex, OpenCode and Grok receive it automatically in both Code and VideoDraft modes. It runs headlessly, so an Open Editor click is not required. Start with `project_manage` (`operation: \\"project\\"`, action `list`, `open`, or `create`); standalone asset generation remains in the cloud CLI or MCP.\\n\\nSend native editor edits serially, batching everything a request needs into one `edit_apply` recipe. Pass the latest `context` when a person may be editing at the same time, so a stale write is refused. See [references/editor.md](references/editor.md) for project selection, media import, timing units, edit recipes, verification, export, and the `videodraft-editor` terminal bridge.\\n\\nIf you are reading this skill through `videodraft skills show skill`, run `videodraft skills show editor` before native editor work to load that reference.\\n\\n**VideoDraft ADE routing rule:** the presence of `videodraft_editor` means the native editor is ready, even when no editor window is visible. Use cloud tools to generate or source assets and, when helpful, scripts or storyboards. Do not call hosted `produce_project` / `videodraft produce` or `export_video` / `videodraft export` by default. Import the assets into the native project, assemble there, and export with native `delivery_manage` `submit`. Use hosted production/export only when the user explicitly asks for the web workflow or the native editor tools are unavailable. Do not silently fall back to hosted production after a native tool error.\\n\\n## First decision: asset, hosted project, or native edit?\\n\\n- **One standalone asset** (image, clip, voiceover, music track, sound effect, dialogue track, voice-changed file, dubbed media file, upscale, or description): generate it directly. Do NOT create a project.\\n  - `videodraft generate image \\"a red fox in snow, cinematic\\" --ar 16:9 --download ./out/`\\n  - `videodraft generate video \\"slow dolly over a misty lake\\" --model gemini-omni-1.1-flash --duration 6 --download ./out/`\\n- **Any final video, production timeline, existing footage, local `.vdproject`, or hands-on edit**: use `videodraft_editor` when available. List or open the intended local project, or create a native project for a new production. The editor can work without showing its UI.\\n- **A small set of related assets**: still stay in the asset lane. They are grouped automatically (see [AI Studio sessions](#ai-studio-sessions)); give the current group one useful task-specific name with `videodraft sessions name \\"<name>\\"`. Switch to a project only when the deliverable matches the project criteria below or the user asks to attach the assets to one.\\n- **A generated multi-scene video / ad / explainer**: when the editor is available, use hosted tools only for any needed script, storyboard, shot planning, or generated assets; stop before hosted production, import the assets, and build/export the native timeline. A hosted project is optional unless the user wants the web project or its storyboard workflow.\\n- **A hosted web project or hosted export**: use the hosted pipeline only when the user explicitly asks for it or the native editor is unavailable.\\n- **Just a script** (no video asked for): A script-only request creates a script-stage project but stops at the script. Use `videodraft create \\"...\\" --script-only`; do not build a storyboard the user didn\'t ask for.\\n- **Iterating on existing work**: identify the surface first. Use `project_manage` `project` with `action: \\"list\\"` for native projects and `videodraft projects list` only for hosted work. Never create a replacement project just to change an existing one.\\n\\n## Choose the model from the task\\n\\nIf the user names a model, use it when compatible. If it cannot handle the request, explain why and recommend alternatives instead of silently switching. Otherwise inspect the inputs, duration, audio, quality, speed, and cost, check the live catalog, and pass an explicit model.\\n\\n### Seedance 2.x real-person rule\\n\\nSeedance 2.0 and 2.5 allow real people by default, the same as AI Studio:\\n\\n- The default is true. Generation tries Byteplus first and can fall back to Fal, which allows real-person likenesses, so a person in the prompt, a start frame, end frame, reference image, or reference video does not hard-fail. The request is charged at Fal\'s higher tier-specific rate even if Byteplus serves it.\\n- Turn it off for the cheapest run, only when the user wants that and nothing in the job is a real identifiable person (text-only requests, non-people, anime, clearly synthetic or stylized characters). For MCP use `allow_real_people: false`. For the CLI use `--no-allow-real-people`. That pins the job to the lower-priced Byteplus path, and a Byteplus likeness-policy refusal does not fall back to Fal. Pass the same value to `get_model_costs` or `videodraft costs` so the estimate matches the charge.\\n- If a request made with the option off fails with code `SEEDANCE_REAL_PERSON_OPT_IN_REQUIRED`, estimate the higher rate, follow the user\'s spend-confirmation preference, and retry exactly once with the option on. The structured recovery fields are `retryable: true`, `retry_with: { allow_real_people: true }`, `cli_flag: \\"--allow-real-people\\"`, and `retry_policy: \\"once\\"`. CLI `--json` submit errors expose them under `details`; `status` and `wait` include them on the failed job result. Do not treat an unrelated moderation or provider error as that signal.\\n- Do not loop when the option was on. Byteplus can accept a task and reject its generated output later. VideoDraft refunds that failed generation, but the late asynchronous failure cannot be rerouted to Fal. Rephrase the prompt or use different references before trying again.\\n- For hosted AI Production, the same default applies to every Seedance scene segment: `produce_project` with `mode: \\"full_video\\"` and `videodraft produce <project> --mode full_video` allow real people unless you pass `allow_real_people: false` or `--no-allow-real-people`. If an earlier run with the option off partially submitted and returns the opt-in code, rerun that same project once with an explicit `allow_real_people: true` / `--allow-real-people`. The server reconciles asynchronous results first, preserves running/completed jobs, and resubmits only failed scene-video placeholders carrying the exact opt-in signal. Keep the native-first VideoDraft ADE routing rule above: hosted full-video production is still explicit/fallback-only when the local editor is available.\\n\\n**How to pick a model. Follow this order every time:**\\n\\n1. The user named a model: use it, never substitute.\\n2. Otherwise pick a **Tier 1** model.\\n3. Use a **Tier 2** model only when no Tier 1 model supports the request, and say why. Never pick Tier 2 on your own for price, speed, novelty or variety.\\n\\nTier 1: images `nano-banana-2`, `nano-banana-pro`, `nano-banana-2-lite`, `gpt-image-2.5-flare`, `gpt-image-2.5-sunburst`, and `recraft-v4` for vector/SVG only; videos `gemini-omni-1.1-flash`, `seedance-2.5`, `seedance-2`, `kling-3.0`, `kling-o3`, `minimax-h3-max`; video edits `gemini-omni-1.1-flash`; talking-head portraits `veed-fabric`, `minimax-h3-max-lipsync`; motion transfer `kling-v3-motion-control`; audio ElevenLabs for speech tools, Lyria 3.5 for music at any length.\\n\\nTier 2 is every other catalog model (`wan-3.0`, `flux-3`, `minimax-h3`, `kling-v3-turbo`, `kling-2.6-pro`, `grok-imagine-video-1.5`, `happy-horse`, Veo 3.1, Sora, Seedream, Grok Imagine images, FLUX images, `sync-lipsync-2` and the rest). All of them stay available by name. Real Tier 2-only jobs: document or web-page references (`wan-3.0`), keyframes pinned to timestamps (`flux-3`), re-syncing existing footage (`sync-lipsync-2`).\\n\\nEvery `videodraft models image|video|audio --json` entry carries `tier` (1 or 2), and the top-level `recommended` array is Tier 1, best first. That catalog beats this page when they disagree.\\n\\n**Speech in video:** write the dialogue in the video prompt. `gemini-omni-1.1-flash`, `seedance-2.5`, `seedance-2`, `kling-3.0` and `kling-o3` speak it natively. For a specific voice add a Seedance reference audio clip (`--ref-audio`) or a Kling bound voice. Do not plan silent video + TTS + lip-sync. Lip-sync tools are only for a portrait presenter talking to camera, or for re-syncing footage that already exists. Off-screen narration and voiceover are unaffected: keep using `generate voiceover` for those.\\n\\n**Images:**\\n\\n- `nano-banana-2`: general default, editing, consistency, and references.\\n- `nano-banana-pro`: maximum quality. `nano-banana-2-lite`: fast, inexpensive drafts.\\n- `gpt-image-2.5-flare`: replaces the GPT Image 2 recommendation for posters, logos, signs, title cards, readable text and composition. Use `gpt-image-2.5-sunburst` for extra precision/detail. Both use the same basic options as GPT Image 2: references (up to 16), aspect ratio, 1K/2K/4K resolution, image count (1-4), and quality. Quality adds xhigh/max; auto is charged at the max tier. Other model recommendations are unchanged; explicit `gpt-image-2` requests still use GPT Image 2.\\n\\n**Videos:**\\n\\n- `gemini-omni-1.1-flash`: general default for 3-10s generation, image-to-video, uploaded source edits up to 10s, and silent or voiceover-backed shots (audio is always on, so describe quiet ambience with no speech and mute or mix it on the timeline; only a file with no audio track at all needs `kling-3.0`, `kling-o3` or Seedance with `--no-audio`). It supports first and last frames, up to 10 total image inputs, up to 3 creative reference videos of at most 3 seconds each on `--video-task generate` ONLY, uploaded-video extension, and continuation of an earlier generation through `--previous-interaction-id`. Output is 360p/720p/1080p/4K at 3/10/15/30 cr/s with audio always on. Use `--source-video` for the uploaded edit/extension source; extension sources must be 1-30s. Edit and extend accept EXACTLY ONE input video, so `--ref-video` cannot accompany `--source-video` or `--previous-interaction-id`; only `--ref` images can. One `--ref-video` with no separate source remains a legacy source edit. A previous interaction defaults to conversational edit; add `--video-task extend` or `--extend` with an explicit 3-10s duration to append at the end. A continuation resolves to the prior turn\'s output and is submitted as an ordinary source, so the same limits apply to it: at most 30s to extend, at most 10s to edit. 40 seconds total is reachable, but only by extending from a source of 30s or less, so a ladder dead-ends once it passes 30s. New dialogue can only be added when the SOURCE video is silent; adding speech on top of a source that already contains speech is refused with \\"the model is currently unable to process speech edits\\". The server safely measures creative-reference durations, or you can repeat `--ref-video-duration` when a host blocks metadata probing. Fal BYOK supports its currently callable v1.1 generation and basic-edit endpoints at zero VideoDraft credits, but Fal does not expose continuation/extension or mixed source-edit references as callable endpoints and VideoDraft must never fall back to paid Google.\\n- `grok-imagine-video-1.5` (Tier 2): 1-15s text, first-frame, or 1-7 reference-image generation with native audio. Text/first-frame modes support 480p, 720p, and 1080p; reference mode supports 480p/720p. Cite references as `<IMAGE_0>` through `<IMAGE_6>`. It has no last frame, seed, negative prompt, quality tier, reference video, or reference audio.\\n- `minimax-h3` (Tier 2): 480p/768p/2K/4K (5/6/13/16 cr/s, 768p default), native stereo audio, and 5-15s text, first/last-frame, or mixed-reference generation. Reference mode accepts up to 9 images, 3 videos, and 3 audio clips, with at most 12 files total. Cite them as `Image 1`, `Video 1`, and `Audio 1` in array order.\\n- `minimax-h3-max`: 480p/768p pricing (5/8 cr/s, 768p default), native audio, and 5-15s text, first/last-frame, or mixed-reference generation. Reference mode accepts up to 9 images, 3 videos, and 3 audio clips, with at most 12 files total, cited as `Image 1`, `Video 1`, and `Audio 1` in array order. It supports a reproducibility seed and `disabled` / `balanced` / `quality` prompt expansion.\\n- `wan-3.0` (Tier 2): unified 2-30s text, first/last-frame, or ordered mixed-reference generation at 480p/720p/1080p (7/14/28 cr/s), with optional native audio. Reference mode accepts up to 10 images, 5 videos, and 5 audio clips, at most 20 media files total; video and audio each total at most 15 seconds. `--auto-duration` reserves 30 seconds and reconciles to the provider-reported output length. Document/web references use `--file-url` or `--web-url` and require `--thinking`.\\n- `flux-3` (Tier 2): Black Forest Labs FLUX 3. 5-20s at 720p/1080p with 24fps native audio, from a prompt, a first frame, first + last frames, or up to 10 keyframes pinned to specific moments (`--keyframe shot.png@2.5`, repeatable). `--quality draft` renders the same shot at 720p for roughly a third of the cost. Auto duration is text/first-frame only.\\n- `seedance-2`: 11-15s, video/audio/mixed references, wider ratios, selectable audio, or first/last frames. `mini` is the economical default; move to `standard` when the user asks for high quality, when a Mini result is not good enough, or for 1080p/4K; `fast` for speed.\\n- `seedance-2.5`: 4-30s single takes and up to 50 references (30 image, 10 video, 10 audio). Same modes as 2.0, one quality tier, 480p/720p/1080p. Reach for it when a shot must run past 15s or carry more references than 2.0 allows.\\n- `kling-o3`: reference images plus structured image/video elements, first/last frames, multi-prompt, audio control, or 4K. O3 allows 7 combined image references and image-backed elements, reduced to 4 combined items when a video-backed element is present. `kling-3.0`: image-to-video can use structured image/video elements and bind a custom Kling voice ID to either element form. Tier 2, by name: `kling-v3-turbo` (fast polished 3-15s with first frame, multi-prompt, and audio, but no elements) and Kling 2.6 Pro (top-level voice IDs cited as `<<<voice_1>>>` and `<<<voice_2>>>`).\\n- Existing-video edits use `videodraft edit video`, not generic generation. `gemini-omni-1.1-flash` is the preferred edit model and is chosen automatically when you omit `--model`: source up to 10s, up to 10 reference images, 360p/720p/1080p/4K with audio. Creative `--ref-video` inputs are NOT accepted on an edit, because an edit takes exactly one input video; use `generate video --video-task generate` to guide a new clip with video references instead. Omitting `--model` on a longer or unmeasurable source spends nothing and prints a priced menu (what each model edits, what it drops, what it costs) so you can put the choice to the user. **Truncation:** only Gemini refuses an over-length source. Happy Horse silently edits just the first 15s, Kling O3 the first 10s, and Grok the first 8s. The command warns you when that will happen; always relay it to the user. Gemini regenerates the audio track, so use Happy Horse or Kling O3 with `--preserve-audio` when the source audio must survive. Choose Grok for the cheapest prompt-only edit, Happy Horse for up to 5 image references, or Kling O3 for controlled reference-image edits.\\n- To edit a source longer than 10s without losing its tail, cut it into <=10s pieces in the native editor, edit each with Gemini, and reassemble. VideoDraft has no server-side split/concat, so this path needs `videodraft_editor`.\\n- Kling O3 also has a reference-generation mode. Use `videodraft generate video --model kling-o3-video-ref-edit` with exactly one `--ref-video` to generate a new guided clip; use `videodraft edit video` when changing the source itself. For new mixed-reference generation use Seedance 2 / 2.5.\\n- Motion transfer uses `videodraft edit motion` with Kling V3 by default, or Kling 2.6 when explicitly requested or lower cost matters. It requires a subject image and a motion-reference video.\\n- Veo 3.1, Sora, Grok, Happy Horse and the other Tier 2 video models: only when explicitly requested or when no Tier 1 model fits.\\n\\n**Audio and utilities:**\\n\\n- Use Seed Audio 1.0 for open-ended text-to-audio, speech/music/sound synthesis, voice conditioning, or prompt-driven editing with up to three audio references or one image. Use `videodraft generate audio`. Reference clips are `@Audio1`, `@Audio2`, and `@Audio3` in array order. There is no duration input. Output is up to two minutes and settles at 19 credits per actual minute, with up to 38 credits reserved during generation. The CLI automatically retries transient responses with one operation key. To recover after the CLI process itself is interrupted, set `--idempotency-key <uuid>` on the original command and reuse it.\\n- Prefer ElevenLabs for voiceover, dialogue, voice changing, dubbing, and sound effects. Honor an explicitly selected supported TTS voice/provider. Use `lyria-3.5` for all music, short or long (up to ~3 minutes, 10 credits flat), with vocals/lyrics or instrumental arrangements. When `--model` is omitted the CLI sends no model and the server default applies, which is `lyria-3.5` wherever the backend supports it. If the server answers that `lyria-3.5` is an unknown model, that backend predates it: rerun without `--model` (the server default then applies), or use `lyria-3-pro-preview` for a track longer than 30 seconds. Ask for the length in the prompt. Keep `lyria-3-clip-preview` (fixed ~30s, 4 credits) and `lyria-3-pro-preview` (8 credits) for explicit requests. For Lyria, put desired length, lyrics and \\"instrumental only, no vocals\\" in the prompt; `--length` and `--instrumental` are ElevenLabs-only. Use ElevenLabs Music for exact timing, composition plans, or a style reference track. Lyria allows 10 reference images on Google, 1 on Fal BYOK; Fal 3.5 prompts are limited to 5000 characters. BYOK uses zero VideoDraft credits. ElevenLabs Music means `elevenlabs-music-v2.5` (`elevenlabs-music` is an alias for it); use `elevenlabs-music-v1` only when the user asks for v1 by name.\\n- ElevenLabs voiceover runs on Eleven v4 in two modes. Standard is the default and the best quality, at 10 credits per 1000 characters. Turbo (Eleven v4 Turbo) is faster, at 5 credits per 1000 characters. Keep Standard unless the user wants faster or cheaper speech. Pick it with `generate voiceover --mode standard|turbo`, `produce --voice-mode standard|turbo`, or MCP `generate_voiceover.mode` / `produce_project.voice_mode`, and quote Turbo with `costs voiceover --chars <n> --mode turbo`. Google, OpenAI and cloned `custom-*` voices ignore the mode (cloned voices cost 30 per 1000). v4 has no style or speed settings and no SSML `<break>` tags; audio tags such as `[whispers]` work. Dialogue stays on Eleven v3.\\n- For ElevenLabs voiceover, dialogue, and voice changing, accept a supplied raw voice ID (16-64 alphanumeric characters) or `elevenlabs-<id>`. The voice catalog is for discovery, not an allowlist. Do not reject or substitute a supplied ID because it is absent from `videodraft models voices` / `list_available_voices`. Use `--voice <id>` for voiceover and voice changing, or repeat `--line \\"<id>:Text\\"` for dialogue; for example, `--voice kPzsL2i3teMYv0FxEYQ6` and `--line \\"elevenlabs-kPzsL2i3teMYv0FxEYQ6:Hello.\\"` use the same voice. The voice must be accessible to the provider account used for generation. Private or cloned voices may require the user\'s connected ElevenLabs key. Kling video-control IDs and MiniMax `custom-*` IDs are separate voice systems.\\n- A character who needs to TALK:\\n  - **Speaking inside a scene**, or any ordinary clip with dialogue: `generate video` with the line in the prompt, in quotes, with who says it and how. `gemini-omni-1.1-flash`, `seedance-2.5`, `seedance-2`, `kling-3.0` and `kling-o3` all voice it natively. For a specific voice use a Seedance `--ref-audio` clip or a Kling voice bound per element. This is the default path; do not generate speech separately and lip-sync it on.\\n  - **Talking to camera from a portrait** (presenter, spokesperson, explainer): the avatar lane, and VEED Fabric is preferred. Use managed `avatar create` then `avatar render` for a reusable avatar record with bundled speech, `avatar fabric` for a one-off portrait plus text or existing audio, and `avatar h3-lipsync` for a short (5-14.8s) portrait clip from existing audio at up to 2K. Not for in-scene shots: Fabric animates a portrait facing the lens, so a cinematic request comes back as a head-on talking headshot.\\n  - **Footage that already exists plus replacement audio** (re-dub, translation): `avatar lipsync`. This is the only job for Sync Labs unless the user names it.\\n- Enhancement: use Topaz image/video upscaling only when the content is already correct. Use image 1x for cleanup, 2x by default, 4x when justified; use video 2x by default. Edit or regenerate creative errors.\\n\\nSee [references/models.md](references/models.md) for the detailed routing table and exact capability limits.\\n\\nProvider routing uses a maintained local price catalog, with exact setting compatibility and account rules. Platform requests prefer Google\'s direct image/video APIs and BytePlus for Seedance 2.0/2.5 before comparing public prices. Seedance 1.5 retains its existing Replicate primary; other models remain price-based. Agents should keep using normal model IDs and `get_model_costs` / `--estimate` for customer credits. Do not choose a vendor from a marketing starting price or retry an accepted generation to chase a lower price. Unknown or expired comparable costs retain the existing route; a selected personal provider key stays exclusive and overrides platform-account preferences.\\n\\nTemporary provider promotions are excluded from routing prices. With an Atlas personal key, H3 Max supports text or first/last-frame generation at 480P/768P only with `prompt_expansion_mode: \\"disabled\\"` and no seed. Balanced/quality expansion, reference generation and H3 Max Lip Sync require the existing Fal path. Atlas H3 Max is not selected automatically while its published price units remain inconsistent.\\n\\n## Matching AI Studio controls\\n\\nUse `models image --json` / `models video --json` for the accepted options. Nano Banana Pro/2 expose `--temperature 0..2` and `--google-search-grounding true|false`. Qwen uses one `--ref` plus `--horizontal-angle 0..360`, `--vertical-angle -30..90`, and `--zoom 0..10`; its text prompt is optional. Recraft generates SVG and accepts `--quality Normal|Pro`, repeatable `--recraft-color \'#RRGGBB\'`, and `--recraft-background \'#RRGGBB\'`. Original Nano Banana and VideoDraft Image use fixed 1K output.\\n\\nKling 3.0 / 2.5 Pro accept `--cfg-scale 0..1` and `--negative \\"\\"` to clear a negative prompt. Seedance 2/2.5, Wan 3.0, FLUX 3 text/first-frame and Gemini Omni generation accept `--auto-duration`; do not combine it with `--duration`. FLUX 3 auto reserves 20 seconds, so its default estimate includes that ceiling. `--model sora-2 --quality pro --resolution 1080p` selects Sora Pro. Kling O3 reference/edit modes accept image-only `--element` objects, at most four combined with `--ref`. Grok v1 accepts image references for clips up to 10 seconds.\\n\\nTopaz image results may be immediate or queued. The CLI waits by default and downloads either result with `--download`; `--no-wait` returns a queued job ID. Raw MCP callers must poll `check_generation_status` when `upscale_image` returns `job_id`.\\n\\n## Prefer references when continuity matters\\n\\nPure text-to-image or text-to-video is fine for a generic one-off asset. When a specific character, product, location, style, composition, or brand identity must survive generation, use references instead of hoping the prompt recreates it.\\n\\n- If the user supplies reference media, preserve and pass it. Never reduce the request to text alone.\\n- When continuity matters, generate/select a strong still first with the selected image model (`nano-banana-2` by default), wait for its URL, then animate it as a start frame/reference. Confirm the combined image and video cost.\\n- When using a hosted storyboard stage for multiple shots, use `videodraft shots <project_id> --model <selected-image-model> --grid`, then animate the decoded shots. Preserve explicit models. In VideoDraft ADE, import the resulting assets into the native editor instead of continuing into hosted production. A requested non-Seedance video model must use manual per-shot generation instead of Seedance full-video mode.\\n\\n## Cost and credits\\n\\nDo not call `videodraft credits` before routine generations. Paid endpoints validate and deduct atomically; if the balance is insufficient, the request is rejected before the provider job starts (CLI exit code 4). Check the balance only when the user asks, gives a credit budget, or a large workflow needs budget planning.\\n\\nFor expensive work, estimate with `--estimate` or `videodraft costs`, state the selected model/settings/cost, and get a go-ahead. This matters most for shot-image batches, long or high-resolution video, AI Production, and paid audio batches. Honor the user\'s confirmation preference for the session.\\n\\nKling voice creation costs 1 VideoDraft credit on the platform Fal account and 0 credits with Fal BYOK. Preview it with `videodraft kling-voices create <sample> --name <name> --estimate`; the estimate does not create a voice or require consent confirmation. Actual creation requires `--confirm-consent`.\\n\\nMiniMax H3 costs 5 / 6 / 13 / 16 credits per output second at 480p / 768p / 2K / 4K (768p by default). In reference mode the first 5 images are included and each additional image costs 8 credits. Reference video and reference audio are NOT billed.\\n\\nMiniMax H3 Max costs 5 credits per output second at 480p and 8 credits per second at 768p (default), plus pooled reference tokens in reference mode: the first 4,096 are free and every 1,000 after that costs 2 credits, where an image is `(width x height) / 1024` tokens, a reference video is 2,886 tokens per second at 480p or 7,459 at 768p, and reference audio is about 2,121 per second. Use `--prompt-expansion-mode disabled|balanced|quality`; balanced is the default. Fal\'s provider safety checker is OFF by default and is not exposed in the app \u2014 only pass `--safety-checker true` if the user explicitly asks for it.\\n\\nWan 3.0 costs 7 / 14 / 28 credits per output second at 480p / 720p / 1080p. Auto duration reserves the 30-second maximum and refunds the unused reserve after the provider reports the actual whole-second output length. Fal BYOK runs on the connected user key and charges zero VideoDraft credits.\\n\\nGrok Imagine Video 1.5 costs 8 credits per output second at 480p, 14 at 720p, or 25 at 1080p, plus 1 credit for each first-frame or reference image. Native audio is always generated.\\n\\n`videodraft models image|video` lists the live image and video catalogs with supported inputs. Video entries are grouped as `generation`, `video_edit`, `motion_control`, `avatar_lipsync`, and `upscale`, and each reports the exact tool. Use `videodraft models video --category video_edit` to narrow the list. `videodraft models audio` lists Seed Audio, Google Lyria, and ElevenLabs audio/media tools, while `videodraft models voices` helps discover TTS voices. Consult them for capabilities; a supplied ElevenLabs voice ID does not need to appear in the voice catalog.\\n\\n## Async jobs\\n\\nImage/video generation is asynchronous: commands submit a job and **wait by default**, printing output URLs (and saving files with `--download`). Large downloaded images also get a downscaled copy in `previews/` next to them (the `preview` field / \\"inspect via preview\\" line in the output) \u2014 **look at the preview, deliver the original**; viewing full-resolution images bloats the chat permanently. In scripts/CI prefer explicit control:\\n\\n```bash\\nJOB=$(videodraft generate image \\"...\\" --no-wait --json | jq -r .job_id)\\nvideodraft wait \\"$JOB\\" --download \\"./outputs/{job_id}_{index}.{ext}\\" --json\\n```\\n\\nFor MANY jobs: submit each with `--no-wait`, collect ALL with one command \u2014 `videodraft wait <id1> <id2> ...` polls every job from one process with one batched request per tick. Do NOT spawn parallel `wait`/`generate --wait` processes for a batch.\\n\\nIf a wait times out, the job is still running server-side \u2014 `videodraft status <job_id>` later. Never re-submit just because a wait timed out (that double-spends credits).\\n\\nFor completed Wan 3.0 jobs, MCP `check_generation_status` and CLI `status`/`wait --json` include `outputMetadata` with Fal\'s returned `seed`, `duration`, and `actual_prompt` when present.\\n\\n## AI Studio sessions\\n\\nStandalone image/video/audio generations are filed into an AI Studio session in the web app. 3D assets use `assets 3d list/get` separately. You do not have to create an AI Studio session:\\n\\n- **MCP hosts** (Claude Code, claude.ai, Codex, VideoDraft ADE): on 2025-era MCP the server mints an `Mcp-Session-Id` on `initialize`; your host echoes it, and this conversation\'s generations land in their own session. On stateless MCP (2026-07-28) hosts that send a conversation id (ChatGPT) get the same. Otherwise `name_current_ai_studio_session` returns `pass_session_id: true` with a `session_id`: pass that `session_id` to every later standalone generation in the conversation. Tool results echo the session as `ai_studio_session_id`.\\n- **CLI**: the same handshake runs once per (profile, server, working directory) and is cached for 12 idle hours, so everything generated from one directory shares one session. `videodraft sessions current` shows it; `videodraft sessions reset` starts a new one.\\n- Project generations (`--project <id>` / `project_id`) always go to that project\'s session.\\n\\nOnce you understand the creative task, name the current automatic session before the first standalone generation:\\n\\n```bash\\nvideodraft sessions name \\"Purple Seal Rescue Short\\"\\n```\\n\\nChoose a concise, specific 3-6 word title for the intended work. Do not copy the client name, date, or exact chat title. Name it once: the operation creates the session with that title. If generation, a user, or an earlier agent created the session first, its existing name is preserved.\\n\\nApart from the `pass_session_id: true` case above, pass `--session <id>` / `session_id` only to **continue earlier work** or create an explicit separate group:\\n\\n```bash\\nSESSION=$(videodraft sessions create \\"Fox brand explorations\\" --json | jq -r \'.session.id\')\\nvideodraft generate image \\"a red fox in snow, cinematic\\" --session \\"$SESSION\\"\\nvideodraft generations --session \\"$SESSION\\"          # what is in it\\nvideodraft sessions list --name fox                  # find it again later\\n```\\n\\n`VIDEODRAFT_SESSION=<id>` sets the default for every command (ignored when `--project` is given). While it is set, `sessions name` refuses to run because that command names the current automatic connection session, not the pinned override; unset it first or rename the pinned session in AI Studio. `VIDEODRAFT_SESSION_SCOPE=<label>` groups several directories into one connection session; `VIDEODRAFT_CLIENT_NAME=<host>` labels the fallback placeholder used when generation creates the session before `sessions name`; `VIDEODRAFT_NO_SESSION=1` disables the handshake. Generations that reach the server with no session at all fall back to the account-wide \\"Agent (MCP)\\" session; if you see work landing there, pass `--session` explicitly.\\n\\n## Generation history\\n\\nPast work is queryable \u2014 reuse a previous setup instead of guessing. `videodraft generations` lists recent generations; scope with `--session <id>` or `--project <id>` (includes collaborators\' rows in shared scopes; pass one, project wins), and filter with `--type`, `--model`, `--favorites`. `--full --json` returns each row\'s exact parameters (aspect ratio, resolution, duration, references) \u2014 the human table stays compact, so pair `--full` with `--json`. `videodraft generation <id>` prints one generation\'s complete recipe (prompt, input image, parameters, outputs); `--favorite` / `--unfavorite` stars it. `videodraft sessions list` shows AI Studio sessions (owned + shared) with `--name` search \u2014 take a session id from there to read its history.\\n\\n## Free stock footage and photos\\n\\nPexels and Pixabay are wired in through `search_stock_media` / `import_stock_media` (`videodraft stock search \\"<query>\\"`, `videodraft stock import <ref>`). Both libraries are free, watermark-free and cost **zero credits**, so use stock for b-roll, establishing shots, backgrounds and ordinary real-world footage, and spend credits on the shots that must be specific: the product, the character, the scripted action.\\n\\n```bash\\nvideodraft stock search \\"city skyline night\\" --min-duration 5 --orientation landscape\\nURL=$(videodraft stock import pexels:video:35379336 --quality hd --json | jq -r .url)\\n```\\n\\n- Always two steps. A search result\'s `preview_url` is a thumbnail for judging the shot; never place it on a timeline, attach it to a shot or send it to a model. `import_stock_media` copies the file onto the VideoDraft CDN and returns the URL every other surface accepts, including the native editor\'s `library_manage` import.\\n- `--quality hd` (default) caps video at 1080p; `4k` caps at 2160p, `best` takes the largest the provider has, `sd` suits rough cuts. Stills ignore quality and import at full size. Use `--orientation portrait` for 9:16, and `--min-resolution 1920` to drop anything below HD on its long edge.\\n- Photos come from Pexels. Pixabay contributes video only, because its full-size image host refuses server-side downloads.\\n- Credit the creator and link the provider page when you show results or deliver the finished work; both come back on every result. Skip clips that imply a person or brand endorses the product, and avoid recognisable logos in ads.\\n- Search and import are rate limited per user (30 searches and 15 imports a minute) and searches are cached for 24h, so a burst of searches while planning a montage is fine. Bulk downloading a stock library is prohibited by both providers. A note saying Pixabay was skipped means its provider budget for that minute is spent; the Pexels results still stand.\\n\\n## Downloading from YouTube, Instagram, TikTok and other sites\\n\\nVideoDraft ships no downloader. When the user asks to pull a video from YouTube, Instagram, TikTok, X, LinkedIn or anywhere else, `yt-dlp` on the user\'s own machine does the work. Check for it with `command -v yt-dlp` before promising anything.\\n\\n**Present:** pin the format. On its defaults yt-dlp takes the best stream, usually VP9 or AV1 in WebM, which the native editor\'s import rejects (mp4, mov and m4v only). This returns one pre-muxed H.264 + AAC MP4 and needs no ffmpeg:\\n\\n```bash\\nyt-dlp -f \\"b[ext=mp4]\\" -o \\"media/%(title)s.%(ext)s\\" \\"<url>\\"\\n```\\n\\n**Missing:** say so in one line, then offer `brew install yt-dlp` only where `brew` exists, and only after asking. With no Homebrew, say the tool is unavailable and stop.\\n\\n- Never install Homebrew, never `sudo`, never write to `/usr/local/bin` or `/opt`, never pipe a script into a shell.\\n- `ffmpeg` is optional, matters only above 720p, and the selector above never needs it.\\n- Auth-gated content needs `--cookies-from-browser`; raise it only after a download fails on auth.\\n- Fetch only what was asked for, never a channel, playlist or back catalogue.\\n\\n## Local files and reference images\\n\\nReference inputs must be public URLs. The CLI uploads local files automatically wherever a URL is expected (`--ref photo.jpg`, `--start-image frame.png`), or explicitly:\\n\\n```bash\\nURL=$(videodraft upload ./product.png --json | jq -r .url)\\n```\\n\\nNever silently drop a reference you couldn\'t upload \u2014 stop and tell the user. Never upload a user\'s file to a third-party host.\\n\\nWhen the user attaches media for a native production, import actual footage into the editor by default. For hosted generation/storyboarding, classify each item before acting: a recurring **visual asset** (character/product/location/style), actual **footage to place as shots**, or **inspiration only**. See [references/pipeline.md](references/pipeline.md) for the hosted role mapping.\\n\\n## Showing media to the user\\n\\nGenerated media is **not** displayed in the chat automatically \u2014 you decide what to show. To preview an asset inline, save it locally (use `--download` so it lands under `media/`) and reference its **local path** as a Markdown link with a **leading `./`**:\\n\\n```\\n[ferrari shot](./media/ferrari_01.png)     \u2190 image card\\n[the clip](./media/clip.mp4)               \u2190 video player\\n[voiceover](./media/vo.mp3)                \u2190 audio player\\n```\\n\\nPut the Markdown link **in your message text** \u2014 video and audio embed exactly like images. Do **not** use `SendUserFile` (or other file-send tools) to display media: that renders inside a collapsible tool card and gets buried in the tool list. The Markdown link in your prose is what produces the inline card.\\n\\nUse the path you saved to: a **workspace-relative** path (`./media/clip.mp4`, or `./<any-folder>/clip.mp4` \u2014 any folder in the workspace works), or the **absolute** path for a file outside the workspace (e.g. `/Users/you/Desktop/clip.mp4` or another workspace\'s path). Both render. Show the finished results worth showing (and only those \u2014 not every intermediate job). A bare CDN URL or a JSON dump of output URLs does **not** render; the local-path Markdown link is what produces an inline card.\\n\\n## Native-first VideoDraft ADE pipeline (idea \u2192 MP4)\\n\\nWhen `videodraft_editor` is present:\\n\\n1. Generate or source the script, storyboard, shot images, clips, voiceovers, music, and other assets through the cloud CLI/MCP as needed.\\n2. Call native `project_manage` (`project`, action `open` or `create`) to open or create the `.vdproject`.\\n3. Call native `library_manage` `import`, wait for imports to become ready, then assemble and refine the timeline with `edit_apply` recipes.\\n4. Call native `delivery_manage` `submit` and use its `jobs` operation for progress and results.\\n\\nDo not run the hosted production or export steps in this path unless the user explicitly asks for a web production.\\n\\n## Hosted fallback pipeline (idea \u2192 MP4)\\n\\nUse this only when there is NO native editor at all, or the user explicitly requests the hosted web\\nworkflow. The native surface is not only the injected `videodraft_editor` MCP: a `videodraft-editor`\\nexecutable on PATH is the same editor reached through its terminal bridge, and\\n[references/editor.md](references/editor.md) covers driving it that way. Treating a missing MCP as\\n\\"no editor\\" sends sessions that have the binary into hosted production for no reason.\\n\\n```bash\\nvideodraft create \\"<idea>\\" --ar 9:16            # project: script \u2192 visual assets \u2192 storyboard\\nvideodraft shots <project_id> --grid --estimate # cost preview, confirm with user\\nvideodraft shots <project_id> --grid            # batch shot images (waits, writes onto shot cards)\\nvideodraft produce <project_id>                 # voiceovers + captions + production timeline\\nvideodraft export <project_id> --download final.mp4\\n```\\n\\nOptional between produce and export: per-shot motion clips (`videodraft generate video ... --project <id>` then place it with `videodraft attach <project> --scene N --shot M --media <url|file> --type video --duration <s>`), music (`videodraft generate music \\"...\\" --attach <project_id>`), and standalone audio assets (`generate audio`, `generate sound-effect`, `generate dialogue`, `generate voice-changer`, `generate dub`). Details, per-step tools and editing rules: [references/pipeline.md](references/pipeline.md).\\n\\n## Avatar and talking-head videos (both surfaces)\\n\\nAvatar generation is cloud-only \u2014 the native editor has no avatar or lipsync tools \u2014 so this applies whether or not `videodraft_editor` is present. Generate the avatar in the cloud; in VideoDraft ADE, import the rendered clip and cut it on the native timeline like any other footage.\\n\\nAvatar/talking-head videos use dedicated commands. For a reusable managed avatar, obtain or generate a clear portrait \u2192 `videodraft avatar script` when needed \u2192 `videodraft avatar create` \u2192 `videodraft avatar render --resolution 720p`. For a one-off portrait, use `videodraft avatar fabric <portrait> --text \\"...\\"` or `--audio <file>`, or `videodraft avatar h3-lipsync <portrait> --audio <file>` for a short high-resolution clip from existing audio. For an existing video plus replacement audio, use `videodraft avatar lipsync <video> --audio <file>`. Managed script/creation is bundled/free; direct Fabric, H3 Max Lip Sync, Sync, the managed Fabric render, and optional portrait generation/upscaling are paid. Confirm expensive steps first.\\n\\n## Working with hosted project data\\n\\nA hosted project is one JSON blob (script, storyboard scenes, shot cards, visual assets, production timeline). To inspect: `videodraft projects get <id>`. To edit: fetch `--raw`, modify, then `videodraft call update_project` \u2014 objects deep-merge, **arrays replace wholesale** (send the complete `storyboard.scenes` array to change one scene). Snapshot first with `videodraft checkpoint create <id>` before risky edits. Schema reference: `videodraft call get_project_schema`. This does not replace native editor tools when `videodraft_editor` is available for the production itself.\\n\\n## More\\n\\n- [references/pipeline.md](references/pipeline.md) \u2014 hosted fallback data model and production workflow\\n- [references/editor.md](references/editor.md) \u2014 native headless editor routing, project selection, import, timeline edits, verification, and export\\n- [references/models.md](references/models.md) \u2014 choosing image/video models, pricing patterns, voices and styles\\n- [references/examples.md](references/examples.md) \u2014 recipes: batch product videos from a CSV, talking-head from a script, changelog video in CI\\n","references/3d.md":"# Standalone 3D assets through MCP and CLI\\n\\nUse this lane for downloadable meshes, textured 3D models, and humanoid rigging. These are independent of AI Studio sessions and do not require a storyboard or web viewer. Never create a project just to generate a mesh. Native editor media import does not establish support for GLB/FBX assets; use external 3D software unless the live editor schema explicitly supports them.\\n\\n## Discover and quote\\n\\n```bash\\nvideodraft models 3d --json\\nvideodraft generate 3d \\"a worn brass telescope\\" --model meshy-7 --estimate\\nvideodraft generate 3d --model tripo-h3.1 --ref ./reference.png --options @options.json --estimate\\nvideodraft rig 3d --estimate\\n```\\n\\nMCP tools: `get_3d_models`, `estimate_3d`, `generate_3d`, `rig_3d`, `check_generation_status`, `list_3d_assets`, `get_3d_asset`, `create_3d_upload`, and `finalize_3d_upload`.\\n\\nThe generator catalog is deliberately limited to `meshy-7` and `tripo-h3.1`. Both expose text/image/multi-image modes; use the live schemas for option availability, view order, limits, topology, texture/PBR, and pose controls. Do not invent common provider option names. Server defaults prioritize quality. Rigging is a separate Meshy operation for compatible textured humanoid GLBs; it is not an arbitrary creature or facial rig service.\\n\\nEvery option is accessible through `--options` JSON (`@path.json` supported), plus repeatable `--option key=value` overrides. Values parse as JSON when valid. Options and explicit input mode affect pricing, so obtain a fresh quote for the exact recipe. Estimates perform no file upload or provider generation. VideoDraft bills whole credits at 100 credits per dollar using the server\'s rounding rules. BYOK costs zero VideoDraft credits and runs on the connected user Fal key. Do not infer the user\'s Fal-account charges from a zero VideoDraft-credit quote.\\n\\n## Generate and retrieve\\n\\n```bash\\nvideodraft generate 3d \\"a worn brass telescope\\" --model meshy-7 --download --json\\nvideodraft generate 3d --model meshy-7 --ref ./hero.png --no-wait --json\\nvideodraft generate 3d --model tripo-h3.1 --input-mode multi_image --ref ./front.png --ref ./left.png --ref ./back.png --ref ./right.png --no-wait --json\\nvideodraft status JOB_ID --json\\nvideodraft wait JOB_ID --download --json\\nvideodraft assets 3d list --status completed --json\\nvideodraft assets 3d get ASSET_ID --download ./media/3d --json\\nvideodraft rig 3d --asset ASSET_ID --download --json\\nvideodraft rig 3d ./textured-humanoid.glb --download --json\\n```\\n\\nLocal image references upload automatically. Local rigging inputs must be self-contained `.glb` files and upload via the dedicated 3D route. Input mode is inferred from reference count unless `--input-mode text|image|multi_image` is supplied. A text prompt requires no images; image mode requires exactly one and no geometry prompt. Meshy multi-image accepts 1-4 views, and Tripo accepts 2-4 in front, left, back, right order. Use Meshy\'s `texture_prompt` option when texturing guidance is needed with image inputs. Do not mix unrelated images as if they were views of the same object.\\n\\nGeneration and rigging wait by default. `--no-wait` returns a persisted job that continues server-side. For many jobs use one `wait ID1 ID2 ... --download`; do not run parallel polling processes. Recover timeout with the same job ID, not another paid generation.\\n\\nSubmission returns a `request_id` UUID. A same-request retry must use `--request-id UUID` and the original arguments. The CLI journals resolved uploads in its private config directory so retries reuse the same remote files. Changed inputs under that UUID are rejected. Submission errors include the UUID in JSON `details.request_id` where available. Never retry a failed request with a new UUID until the prior job status is known.\\n\\n## Complete artifact packages\\n\\n`--download` defaults to `media/3d/<asset_id>/`. A user directory is respected and receives a per-asset folder. `{job_id}` and `{asset_id}` directory templates are accepted. Do not pass a `.glb` filename or a media `{index}.{ext}` template: a 3D result can contain multiple formats and texture/material dependencies.\\n\\nDownloads preserve every returned artifact. The manifest records provider URLs, source filenames, local paths, role, content type, and actual downloaded sizes. glTF/OBJ/MTL references are rewritten to saved dependency paths; binary GLB/FBX and provider ZIPs are retained as returned. Supplied dependency aliases become local copies at the paths needed by original FBX files. Unsafe or colliding aliases produce warnings. Existing packages are never overwritten. A successful package has `manifest.json`; read its `complete` field and `warnings`, plus CLI `package_warnings`. Do not claim a package with unresolved dependencies is ready for offline use.\\n\\nMachine results use `type: \\"model3d\\"` with `output_files` for files and `output_media` only for ordinary preview media. Texture maps and models are not image/video gallery entries. Show a supplied preview via a local image Markdown link and deliver the original mesh/package files. Do not imply an interactive 3D viewer exists in AI Studio or VideoDraft ADE.\\n","references/editor.md":"# Native VideoDraft Editor reference\\n\\nUse this reference when the user wants to assemble, cut, caption, mix, lay out, inspect, or export a local VideoDraft Editor project. The native editor is deterministic and local. Cloud generation remains in the `videodraft` CLI or hosted MCP.\\n\\n## VideoDraft ADE preference rule\\n\\nWhen `videodraft_editor` tools are exposed, treat the native editor as available and make it the default surface for production, timeline assembly, and final export. It is headless by design, so a hidden window or an untouched Open Editor button does not justify using hosted production instead.\\n\\nUse cloud tools for asset generation and optional script/storyboard work, then import the results. Do not call hosted `produce_project` / `videodraft produce` or `export_video` / `videodraft export` unless the user explicitly requests an editable web production or the native editor tools are unavailable. If a native tool call fails after the editor was available, report or recover that native failure rather than silently switching surfaces.\\n\\n## Choose the correct surface\\n\\n- `videodraft` and the hosted VideoDraft MCP generate assets and can manage hosted web projects. They use the user\'s VideoDraft account and credits. In VideoDraft ADE, use them mainly as the source of generated media and optional storyboards for the native production.\\n- `videodraft_editor` edits local `.vdproject` packages. It has no generation, account, model, or credit tools.\\n- Inside VideoDraft ADE on a supported Mac, the editor MCP is injected automatically for Claude, Codex, OpenCode and Grok in both Code and VideoDraft modes. It starts headlessly before the chat opens. The user does not need to click Open Editor, and closing or hiding the editor window does not stop headless editing.\\n- Outside that environment, use the editor only if `videodraft_editor` MCP tools are already exposed or the `videodraft-editor` executable is on PATH. Do not confuse the public `videodraft` cloud CLI with the separate native editor executable.\\n\\nPrefer the direct MCP tools when they are available. The terminal bridge is useful for scripts, diagnostics, or an agent session where the MCP was not injected.\\n\\n## Which editor tools you have\\n\\nCurrent editors expose eight workflow tools: `project_manage`, `edit_snapshot`, `edit_apply`, `edit_undo`, `library_manage`, `inspect`, `speech_apply`, and `delivery_manage`. Use them whenever `edit_apply` is available. Everything below describes them.\\n\\nEarlier editors expose a different set of tools. If `edit_apply` is not in your catalog, follow the live tool descriptions; the working rules below still apply.\\n\\nThe live tool descriptions and schemas are authoritative. When they differ from this reference, follow them.\\n\\nService tools (`project_manage`, `library_manage`, `inspect`, `speech_apply`, `delivery_manage`) take `operation` and `parameters`, plus an optional `context` (see [Keep a reliable editing model](#keep-a-reliable-editing-model)):\\n\\n```json\\n{\\"operation\\": \\"import\\", \\"parameters\\": {\\"source\\": {\\"path\\": \\"/Users/me/clips\\"}}}\\n```\\n\\n### Parameters at a glance\\n\\nEach operation\'s schema has the full list. These are the fields that matter most, and the ones most often confused:\\n\\n| Tool and operation | Key `parameters` |\\n| --- | --- |\\n| `project_manage` `project` | `action` (`list`, `open`, `create`, `close`); `id`, `name` or `path` to open; `name`, `fps`, `aspectRatio`, `quality` to create |\\n| `edit_snapshot` (no `parameters`) | `includeLibrary`, a `startFrame`/`endFrame` window, `offset`/`limit` paging, `context` for later pages |\\n| `edit_apply` (no `parameters`) | `actions`; optional `context`, `requestId`, `previewOnly` |\\n| `library_manage` `import` | `source` with one of `path`, `url`, `bytes` + `mimeType`, or `matte`; optional `name`, `folder`. A `.srt` or `.vtt` file becomes captions |\\n| `library_manage` `list` | `ids` to poll imports, `pending`, `folder` |\\n| `inspect` `timeline` | a `startFrame`/`endFrame` window; there is no clip filter |\\n| `inspect` `frame` | `startFrame` for one frame; add `endFrame` and `maxFrames` to sample a range |\\n| `inspect` `media` | `mediaRef` (a library asset, not a file path), `startSeconds`/`endSeconds` in source seconds, `wordTimestamps`, `overview` |\\n| `inspect` `transcript` | a `startFrame`/`endFrame` window, `granularity` (`words` or `segments`), `clipId` |\\n| `inspect` `color` | `clipId` with `atFrame`, or `mediaRef`; optional `reference` |\\n| `speech_apply` `words` | `words`: transcript word indices, each one index or a `[first, last]` pair; or `matches`: exact words to remove everywhere; `pacing` |\\n| `speech_apply` `silence` | none |\\n| `speech_apply` `captions` | caption `style`, `position` and look fields; it finds the speech itself. `style` `plain` (sentences without a preset) takes `positionY` or `transform.centerY`, not `position` or `punctuation` |\\n| `delivery_manage` `submit` | `mode`, `codec`, `resolution`, `outputPath` (its folder must already exist); `captionGroupId` and `wordTiming` for `srt` and `vtt`; `check: false` skips a video\'s export check |\\n| `delivery_manage` `jobs` | `action` `list` (every job with its progress, warnings, output path and check findings; with a `jobId`, that job with all its findings), `cancel` with a `jobId`, or `dismiss` with a `jobId` and optional `findingIds` |\\n\\n`previewOnly` exists only on `edit_apply`. Service operations apply immediately.\\n\\n### `edit_apply` actions at a glance\\n\\nEvery action puts its fields beside `kind`, for example `{\\"kind\\": \\"adjust\\", \\"clipId\\": \\"c1\\", \\"speed\\": 2}`. `remove`, `adjust`, `replace`, `transition`, `mask`, `text`, `grade` and `effects` take `clipId` for one clip or `clipIds` for several; `animate`, `extract`, and the rows of `move` and `split` take a single `clipId`. Advanced actions cannot take `as`, but their clip ids accept `@name`. The one exception is `transition`, whose own `kind` field names the style, so its fields go inside `parameters`: `{\\"kind\\": \\"transition\\", \\"parameters\\": {\\"clipId\\": \\"c2\\", \\"kind\\": \\"dipToBlack\\"}}`. These `actions` place a clip, warm it and add a vignette:\\n\\n```json\\n[{\\"kind\\": \\"place\\", \\"assetId\\": \\"\u2026\\", \\"atFrame\\": 0, \\"as\\": \\"shot\\"},\\n {\\"kind\\": \\"grade\\", \\"clipId\\": \\"@shot\\", \\"adjustments\\": {\\"temperature\\": 7500}},\\n {\\"kind\\": \\"effects\\", \\"clipId\\": \\"@shot\\", \\"effects\\": [{\\"type\\": \\"finish.vignette\\", \\"params\\": {\\"strength\\": 35}}]}]\\n```\\n\\n| Advanced `kind` | Key fields |\\n| --- | --- |\\n| `place_batch` | `entries: [{mediaRef, startFrame, endFrame or source, trackIndex}]`, not the concise `assetId`, `atFrame`, `durationFrames`; leave `trackIndex` off every entry for a new track |\\n| `insert_batch` | `trackIndex`, `atFrame`, `entries: [{mediaRef, durationFrames or source}]`; later clips move right |\\n| `move` | `moves: [{clipId, toFrame, toTrack}]` |\\n| `remove` | `clipId` or `clipIds`; leaves a gap |\\n| `split` | `splits: [{clipId, atFrame}]`, or `trackIndex` with `frames` |\\n| `extract` | `trackIndex` with `ranges: [[start, end]]` in frames, or `clipId` with `ranges` and `units` (`frames`, or source `seconds`); closes the gap |\\n| `adjust` | `clipId` or `clipIds` plus any of `durationFrames`, `trimStartFrame`, `trimEndFrame`, `speed`, `speedCurve` (`{preset}`, or `{points: [{t, rate}]}` with `t` from 0 to 1 along the source), `preservesPitch`, `volume`, `opacity`, `transform` (`centerX`, `centerY`, `width`, `height`, `flipHorizontal`, `flipVertical`), `blendMode` |\\n| `animate` | `clipId`, `property` (`volume`, `opacity`, `rotation`, `position`, `scale`, `crop`), `keyframes: [[frame, ...values]]` with frames counted from the clip\'s start; `position` is the top-left corner |\\n| `arrange` | `layout`, `slots: [{slot, clipIds or mediaRef, anchor}]`, `fit` (`fill` or `fit`); `mediaRef` slots also need `endFrame` |\\n| `transition` (fields inside `parameters`) | `clipId` or `clipIds` (the clip after each cut), `kind` (`crossDissolve`, `dipToBlack`, `dipToWhite`, `blurDissolve`, `push`, `linearWipe`, `whipPan`, `crossZoom`, or `none` to remove), `durationFrames`, `params` (`direction` 0 to 3 for left, right, up, down; `feather`; `blur`; `intensity`) |\\n| `mask` | `clipId` or `clipIds`, `shape` (`rectangle`, `ellipse`, `none`), `centerX`, `centerY`, `width`, `height` (0 to 1 of the clip\'s own frame), `feather`, `strength`, `inverted` |\\n| `replace` | `clipId` or `clipIds`, `mediaRef` (a library asset of the same kind), `trim` (`keep`, the default, or `reset`), `linkedAudio` (`follow`, the default, or `keep`) |\\n| `tracks` | `reorder: [{trackId, to}]`, `set: [{trackId, muted, hidden, syncLocked}]`, `remove: [{trackId}]`; there is no add, since placing without a track makes one |\\n| `titles` | `entries: [{startFrame, endFrame, content}]`, optionally with `trackIndex` (on every entry or none), `style`, `animation`, `transform` and typography (`fontName`, `fontSize`, `color`) |\\n| `text` | `clipId`, `clipIds` or `captionGroupId`, with `content`, `style`, `position`, `animation` or typography |\\n| `grade` | `clipId` or `clipIds`, `adjustments`, `wheels`, `curves`, `hueCurves`, `lut`, `reset` |\\n| `effects` | `clipId` or `clipIds`, `effects: [{type, params, enabled}]`, `remove: [type]` |\\n\\n- `grade`: `adjustments` holds `exposure` (EV, -4 to 4), `temperature` (kelvin, 1800 to 15000, 6500 neutral, higher is warmer), `tint` (-150 magenta to 150 green); `contrast`, `highlights`, `shadows`, `whites`, `blacks`, `vibrance` and `saturation` are signed percents (-100 to 100, 0 neutral), not factors like 1.2. `wheels`: `shadows`, `midtones`, `highlights`, each `{hue, strength, brightness}`. `curves`: `luma`, `red`, `green`, `blue` as `[x, y]` points from 0 to 1. `hueCurves`: `targets: [{hue, rotate, saturation, lightness}]`. `lut`: `{path, mix}`, with the `storedPath` from `prepare_look`. Out-of-range values are refused.\\n- Effect `type` ids and their knobs, which go inside `params` and run 0 to 100 unless noted. Defaults leave the picture unchanged, so send the knob you want to see:\\n  - `finish.vignette`: `strength` and `curvature` (-100 to 100; positive `strength` darkens the edges), `size`, `falloff`\\n  - `finish.grain`: `strength`, `grainSize` (0.5 to 6 px); `finish.glow`: `strength`, `haloRadius` (px), `cutoff`, `halation`\\n  - `defocus.gaussian`: `blurRadius` (px); `defocus.motion`: `streakLength` (px), `streakAngle` (-180 to 180 degrees)\\n  - `texture.clarity`: `localContrast`, `hazeRemoval` (-100 to 100); `texture.sharpen`: `strength` (0 to 200); `texture.denoise`: `strength`\\n  - `matte.chroma`: `screenHue` (0 to 360 degrees, 120 is green), `range`, `edgeSoftness`, `spillSuppression`\\n- `arrange` layouts and their slots (fill every slot): `fullscreen` (`stage`); `split` (`left`, `right`); `stack` (`top`, `bottom`); `corner_top_left`, `corner_top_right`, `corner_bottom_left`, `corner_bottom_right` (`stage`, `corner`); `quad` (`top_left`, `top_right`, `bottom_left`, `bottom_right`); `side_panel` (`stage`, `panel`); `thirds` (`left`, `middle`, `right`). The layout picks the corner; `anchor` only biases the crop.\\n- `trackIndex` and `toTrack` are an existing track\'s `order` from `edit_snapshot` (0 draws on top), counted at that point in the recipe: a track an earlier action adds shifts them. `tracks` takes `trackId` handles instead.\\n\\n## Start with the intended project\\n\\nAn MCP session can begin without a project selected. Project selection belongs to the session, not to whichever editor window happens to be frontmost.\\n\\n1. If the user named an existing project but its identity is unclear, call `project_manage` with `operation: \\"project\\"` and `parameters.action: \\"list\\"`.\\n2. Open the exact project with `action: \\"open\\"` and the returned `id`, an unambiguous `name`, or the `.vdproject` `path`.\\n3. Create only when the user wants a new local edit. `action: \\"create\\"` accepts optional `name`, `fps`, `aspectRatio`, and `quality`.\\n4. Treat `isActive` as this session\'s target and `isVisible` as the project shown in the UI. Headless editing only needs the session target.\\n5. Use `action: \\"close\\"` only when closing is part of the task. It saves first and never deletes the project. Afterwards other calls answer `no_project` until you open or create a project again.\\n\\nOther `project_manage` operations: `create_timeline` and `select_timeline` for additional timelines, and `configure` for project settings (a frame-rate change applies to every timeline).\\n\\nDo not substitute a hosted project ID for a native project. A hosted project can supply scripts, storyboards, and generated media, but the native edit is a separate `.vdproject` package.\\n\\n## Keep a reliable editing model\\n\\n- Opening or creating a project, and creating or selecting a timeline, returns `data.snapshot` (the `edit_snapshot` view with the library: format, tracks, clips and assets) and a `context`, so you can edit right away. Call `edit_snapshot` only after an out-of-band user edit, to page a long timeline with `offset` and `limit`, or for handles you lack.\\n- `context` (`epoch`, `timelineId`, `revision`) is optional on every write except `edit_undo` and `project_manage` `project`, which take none. Without it, a write applies to the current state. With it, the editor refuses the write if the project changed since that context, which is what you want when a person may be editing at the same time. Every reply returns a fresh `context`. After `context_expired` (a reopen or restart), take a new snapshot.\\n- Timeline positions and durations are frames at `format.fps`. `sourceSeconds` values are seconds in the source file. Pass values as returned; do not multiply or divide by fps yourself.\\n- IDs are short handles. Pass them back exactly as returned; do not derive them from UUIDs. Tracks keep stable handles; indexes can change.\\n- When the user says \\"this clip\\", \\"these captions\\", or \\"here\\", take a fresh `edit_snapshot` (a one-frame window is enough). Its `selection` names what they selected in the project\'s window, in the snapshot\'s handles: `clipIds`, `captionGroupIds`, a `gap`, the marked `range`, and library `mediaIds`; no `selection` means nothing is selected. `currentFrame` is the playhead. `visible: false` means the user is not looking at this project.\\n- Send writes serially. Parallel writes against one project race each other\'s context.\\n- A refused call answers `status: \\"rejected\\"`: nothing changed, so fix what the message names and send it again. A service write that answers `failed` may have applied before a save or connection failed; inspect before repeating it.\\n- Use `inspect` for detail and verification: `timeline` for exact clip and track properties, `frame` for rendered frames of the composited result, `media` before describing source content, `color` for scopes, and `transcript` to locate spoken words.\\n- Volume values, including volume keyframes, are linear from `0` to `1`.\\n\\n## Edit with recipes\\n\\n`edit_apply` takes an ordered list of `actions`, plus an optional `context` and `requestId`. The editor validates the whole recipe before changing anything, then applies it as one undo step. If any action fails, nothing changes and the error names the action. An applied reply lists the resulting `clips` (position, length, source window, text); use it to confirm the edit instead of re-reading.\\n\\n- Concise actions: `place` (an `assetId` at `atFrame`, optionally on a `trackId`, with `durationFrames` or `sourceSeconds`, `mode` `overwrite` or `insert`), `trim` (a `clipId` to a `sourceSeconds` window), and `title` (`text` at `atFrame` for `durationFrames`, optional `look` and `motion`). Name an action with `as` and address its clip in later actions as `@name`.\\n- Advanced actions put their fields beside `kind` too: `place_batch`, `insert_batch`, `move`, `remove`, `split`, `extract`, `adjust`, `animate`, `arrange`, `transition` (fields inside `parameters`), `mask`, `replace`, `tracks`, `titles`, `text`, `grade`, and `effects`. Their field help lists every supported effect, grading control, mask, layout, speed curve, and caption control.\\n- Use `arrange` for split screens, picture-in-picture, grids, and canvas placement, and `tracks` to fix stacking. Do not synthesize layouts from generic transforms or keyframes.\\n- Use `replace` to swap a clip\'s media and keep its timing, effects, keyframes, and links, for example a re-render of the same shot. `trim: \\"keep\\"` holds the clip\'s source offsets; `trim: \\"reset\\"` plays the new media from its first frame and keeps linked audio in sync.\\n- Put every edit a request needs into one recipe: placing, trimming, titling, grading and effects together are one call and one undo step. Use `previewOnly: true` to validate a large or risky recipe without editing.\\n- Send a `requestId` when a retry must not edit twice: repeating the identical request with the same `requestId` returns the original receipt, even after a dropped connection. Without one, a repeated request applies again. Use a new `requestId` for a different edit.\\n- `applied_unsaved` means the edit applied but saving failed. If you sent your own `requestId`, repeat the identical request to retry the save, not the edit. Without one, do not resend: a repeat would apply the edit again.\\n- `edit_undo` reverses this connection\'s latest edit while it is still the top undo step. It never undoes the user\'s own edits. Take a new snapshot afterward.\\n\\nEdits are undoable. Do not ask for confirmation before each ordinary edit. Ask one focused question only when the user\'s creative direction is materially ambiguous.\\n\\n## Bring generated or local media into the editor\\n\\nFor b-roll and establishing shots, search free stock first (`videodraft stock search \\"<query>\\"`), import the pick with `videodraft stock import <ref>`, and feed the returned CDN URL to `library_manage` `import` as `source.url`. It costs no credits.\\n\\nOtherwise use cloud generation for new assets, save or download the outputs, then call `library_manage` with `operation: \\"import\\"`:\\n\\n- `source.path`: absolute local file or directory. A directory imports recursively and preserves its folder structure.\\n- `source.url`: HTTPS asset URL. Set `mimeType` when a signed URL has no usable extension.\\n- `source.bytes`: small base64 media with a required `mimeType`.\\n- `source.matte`: generated solid-color image.\\n\\nReadiness differs by source, and so does the poll that detects it:\\n\\n- **URL and single-file path** imports return `status: \\"downloading\\"` with one `mediaRef`. Poll `library_manage` `list` with `parameters.ids: [mediaRef]` until `generationStatus` is absent.\\n- **Directory** imports also return `status: \\"downloading\\"` with one placeholder `mediaRef` for the batch. Poll it the same way; the folder\'s assets appear when `generationStatus` clears. (`pending: true` remains a fallback that lists every unresolved import.)\\n- **Inline bytes and matte** imports finish inline and come back `status: \\"ready\\"`; no polling is needed.\\n\\nAn import\'s `mediaRef` is the `assetId` that recipe actions take. Never place a pending asset on the timeline. `generationStatus` is the signal: `preparing`, `generating`, `downloading`, and `rendering` mean keep polling, absent means usable, and **`failed` is terminal**. Report it or retry the import explicitly; never poll on. Do not treat \\"not downloading\\" as ready.\\n\\nA `.srt` or `.vtt` caption file (by `path`, `url`, or `bytes` with `mimeType` `application/x-subrip`, `text/srt`, or `text/vtt`) is not added to the library. Its captions go onto a new caption track at the times the file gives, as one undo step, and the reply names the new `captionGroupId` to restyle with a `text` action.\\n\\nFor a batch of local outputs, download them into one workspace directory and import that directory once when practical. This is safer and faster than racing many import calls.\\n\\nTo apply a LUT, first store it with `library_manage` `prepare_look` (`parameters.path` to a `.cube` file), then use the returned `storedPath` in a `grade` action.\\n\\n## Speech edits\\n\\n`speech_apply` runs speech work as separate operations, not recipe actions: `words` removes transcript words, `silence` trims dead air, and `captions` generates styled captions. Read a fresh transcript with `inspect` `transcript` after any speech edit, because word positions change.\\n\\n## Service operations and timeouts\\n\\n`project_manage`, `library_manage`, `speech_apply`, and `delivery_manage` writes have no retry receipts. After a timeout, inspect the outcome (a snapshot, a library `list`, or delivery `jobs`) before repeating a write. A failed service write may have applied an edit before saving failed, so read its `data` and the current state.\\n\\n## Edit and verify\\n\\nA dependable sequence:\\n\\n1. `project_manage` to select or create the local project; its reply carries the snapshot.\\n2. `inspect` `media` when content selection matters.\\n3. One `edit_apply` recipe with every clip, track, layout, text, audio, color, and effect change the request needs; `speech_apply` for word cuts, silence, and captions.\\n4. Check the reply\'s `clips`; use `inspect` `frame` only when visual composition or layer order matters.\\n5. `edit_undo` if the result is wrong and the next recipe would not cleanly correct it.\\n\\n## Export\\n\\nCall `delivery_manage` with `operation: \\"submit\\"`. Submission is not completion: it returns a job, destination, and `started` or `queued` status.\\n\\n- Use `mode: \\"video\\"` for H.264, H.265, or ProRes.\\n- Use `mode: \\"xml\\"` (XMEML) for Premiere Pro **and DaVinci Resolve**. Resolve reads XMEML natively. Use `fcpxml` only for Final Cut Pro; sending Resolve an FCPXML produces a package it cannot open cleanly.\\n- Use `mode: \\"videodraft\\"` for a self-contained project package.\\n- Use `mode: \\"srt\\"` or `mode: \\"vtt\\"` for a subtitle file of the captions: words and timing only, without styling. `captionGroupId` picks a caption group; `wordTiming: true` adds each word\'s start to a `vtt`.\\n- Omit `outputPath` unless the user named a destination; the default is `~/Downloads`. The editor does not create folders, so a named destination\'s folder must already exist.\\n- Use `operation: \\"jobs\\"` with `parameters.action` `list` to follow progress, warnings, and results. Cancel only when the user asks or the just-queued settings were wrong. Do not infer that an export is stuck from elapsed time alone.\\n- A finished video export is then checked in the background for black picture, gaps, sound that drops out or clips, and missing media. `list` shows each job\'s `findingCount` and its first three findings; `list` with that `jobId` returns every finding. Findings are warnings on a completed export: tell the user what was found and where, rather than treating the export as failed.\\n\\n## Terminal bridge\\n\\nVideoDraft desktop terminals expose `videodraft-editor`, which controls the same process and tools:\\n\\n```bash\\nvideodraft-editor status\\nvideodraft-editor list-tools\\nvideodraft-editor tool project_manage --json \'{\\"operation\\":\\"project\\",\\"parameters\\":{\\"action\\":\\"list\\"}}\'\\nvideodraft-editor tool edit_snapshot --project \\"/path/to/My Video.vdproject\\" --json \'{\\"includeLibrary\\":true}\'\\nvideodraft-editor show\\nvideodraft-editor hide\\n```\\n\\nEach `videodraft-editor` invocation is a separate connection, so a project opened by one call is NOT remembered by the next. Pass `--project <path>` on every `tool` call that operates on a project; without it, a follow-up call answers `no_project` (no project is open for this session) even though the open succeeded. For the same reason, `edit_undo` has nothing to undo from the terminal: it only reverses an edit made on its own connection.\\n\\nControl and tool commands auto-start a headless editor if none is running. `show` only reveals the already-running UI. Use `videodraft-editor tool <name> --json -` to read a JSON object from stdin when shell quoting would be fragile. Never read, copy, or expose the editor\'s rotating local authentication secret.\\n","references/examples.md":"# Recipes\\n\\nWorking patterns for common asks. All assume auth (`videodraft login` once, or `VIDEODRAFT_API_KEY` in the environment) and use `--json` for parsing.\\n\\nInside VideoDraft ADE, if a native editor is available, use these recipes for asset generation and\\noptional script/storyboard stages. Hand the results to the editor for production and export ONLY\\nwhen the deliverable the user asked for is a composed production. A standalone output \u2014 the batch\\nproduct clips in recipe 1, the upscale in recipe 7 \u2014 is finished when it is generated; importing it\\ninto a project and exporting a timeline builds an edit nobody asked for. Recipes below that call `videodraft produce` or `videodraft export` are hosted fallbacks only. Do not choose them over the available native editor unless the user explicitly asks for the hosted web workflow.\\n\\n## 1. Batch product videos from a CSV\\n\\nOne 9:16 product clip per row of `products.csv` (`name,image_url,tagline`):\\n\\n```bash\\n#!/usr/bin/env bash\\nset -euo pipefail\\nmkdir -p outputs\\n\\nwhile IFS=, read -r name image tagline; do\\n  job=$(videodraft generate video \\\\\\n    \\"Premium product shot of ${name}: ${tagline}. Slow orbit, studio lighting.\\" \\\\\\n    --model gemini-omni-1.1-flash --ar 9:16 --duration 6 \\\\\\n    --start-image \\"$image\\" \\\\\\n    --no-wait --json | jq -r .job_id)\\n  echo \\"$name,$job\\" >> outputs/jobs.csv\\ndone < <(tail -n +2 products.csv)\\n\\n# Collect ALL results with ONE process (batched polling \u2014 one request per tick)\\nvideodraft wait $(cut -d, -f2 outputs/jobs.csv) \\\\\\n  --download \\"outputs/{job_id}_{index}.{ext}\\" --json > outputs/results.json\\n# map job ids back to product names via outputs/jobs.csv\\n```\\n\\nSubmit-then-collect parallelizes server-side generation; the single multi-id `wait` keeps it to one local process and one batched poll request per tick no matter how many jobs. Gemini Omni 1.1 Flash is selected because these are six-second first-frame product clips. Estimate first: `videodraft costs gemini-omni-1.1-flash --type video --duration 6 --resolution 720p --audio` \xD7 rows, and confirm with the user.\\n\\nExtend an uploaded clip or conversationally edit an official Google interaction with Gemini Omni 1.1 Flash:\\n\\nEach extension appends 3-10 seconds at the end. Edit and extend accept EXACTLY ONE input video, so `--ref-video` cannot accompany `--source-video` or `--previous-interaction-id`; only `--ref` images can. New dialogue is allowed only when the source video is silent, so a chain of spoken beats must carry its speech in the first turn. A continuation is submitted as the prior turn\'s output, so 40 seconds total is reachable only by extending from a source of 30s or less, and a ladder dead-ends past 30s.\\n\\n```bash\\n# Uploaded-video extension. Reference IMAGES are fine here; reference videos are not.\\nvideodraft generate video --model gemini-omni-1.1-flash \\\\\\n  --source-video ./ending.mp4 --ref ./wardrobe.png \\\\\\n  --extend --duration 6 --resolution 1080p \\\\\\n  --download ./media/extended.mp4\\n\\n# Conversational edit from the interaction_id of an earlier generation. Add --extend to lengthen instead.\\nvideodraft generate video --model gemini-omni-1.1-flash \\\\\\n  --previous-interaction-id \\"$INTERACTION_ID\\" \\\\\\n  --resolution 720p \\\\\\n  --download ./media/continued.mp4\\n```\\n\\nFal BYOK supports the currently callable Gemini Omni 1.1 generation and basic source-edit endpoints at zero VideoDraft credits. Its published callable v1.1 endpoints do not expose continuation, extension, or separate creative references on a source edit. Do not infer a Fal route or retry on paid Google while Fal BYOK is active.\\n\\n## 2. Hosted full marketing video from one idea (fallback)\\n\\n```bash\\nvideodraft create \\"30-second launch video for Solace, a sleep-tracking ring. Calm, premium, dark palette.\\" \\\\\\n  --ar 9:16 --style cinematic --json > project.json\\nPROJECT=$(jq -r .project_id project.json)\\n\\nvideodraft shots \\"$PROJECT\\" --grid --estimate          # show the user the cost; get a go-ahead\\nvideodraft shots \\"$PROJECT\\" --grid\\nvideodraft produce \\"$PROJECT\\"\\nvideodraft generate music \\"minimal ambient, warm pads, 60 BPM\\" --attach \\"$PROJECT\\"\\nvideodraft generate audio \\"Extend @Audio1 into a 20-second transition\\" --ref-audio ./intro.wav --format wav --download ./transition.wav\\nvideodraft export \\"$PROJECT\\" --download solace-launch.mp4\\n```\\n\\nUse this complete hosted path only when the user requested a web project or the native editor is unavailable. Otherwise stop after the storyboard/assets, import them into the native `.vdproject`, and export with `delivery_manage`. The hosted project stays editable at the URL in `project.json` (`.urls`).\\n\\n## 3. Talking-head (avatar) video\\n\\nWhen the user has no portrait, generate a clear front-facing avatar image first. Skip this step when they supplied one or an existing character should be reused.\\n\\n```bash\\nvideodraft generate image \\\\\\n  \\"Front-facing head-and-shoulders portrait of a friendly coffee expert, direct eye contact, natural expression, clean studio background\\" \\\\\\n  --model nano-banana-2 --ar 9:16 --download ./media/avatar.png\\n\\nSCRIPT=$(videodraft avatar script \\"why our espresso subscription saves you money\\" --style ad-style --json | jq -r .script)\\nAVATAR=$(videodraft avatar create ./media/avatar.png --script \\"$SCRIPT\\" --voice elevenlabs-kPzsL2i3teMYv0FxEYQ6 --ar 9:16 --json | jq -r .avatar_video_id)\\nvideodraft avatar render \\"$AVATAR\\" --resolution 720p   # VEED Fabric paid step; confirm cost first (~20 credits/sec)\\n```\\n\\n`avatar script` and `avatar create` (including speech) are bundled/free. In this example only the optional portrait generation and Fabric render spend credits.\\n\\nIf the portrait is low resolution, enhance it before `avatar create`:\\n\\n```bash\\nvideodraft upscale image ./founder-small.jpg --scale 2x --download ./media/founder-upscaled.png\\n```\\n\\nFor a one-off portrait animation without creating a managed avatar record:\\n\\n```bash\\nvideodraft avatar fabric ./founder.jpg \\\\\\n  --text \\"Welcome to the weekly product update.\\" \\\\\\n  --voice-description \\"warm, confident American presenter\\" \\\\\\n  --resolution 720p --download ./media/presenter.mp4\\n```\\n\\nFor a short, sharp clip from speech or a song the user already has (5-14.8s of audio is used):\\n\\n```bash\\nvideodraft avatar h3-lipsync ./singer.png --audio ./chorus.mp3 \\\\\\n  --resolution 1080P --audio-duration 12 --estimate\\nvideodraft avatar h3-lipsync ./singer.png --audio ./chorus.mp3 \\\\\\n  --resolution 1080P --download ./media/singer-lipsync.mp4\\n```\\n\\nWhen the user already has both the video and replacement speech:\\n\\n```bash\\nvideodraft avatar lipsync ./presenter.mp4 \\\\\\n  --audio ./localized-voiceover.mp3 \\\\\\n  --sync-mode loop --download ./media/presenter-localized.mp4\\n```\\n\\nEdit an existing video with a dedicated edit model:\\n\\n```bash\\nvideodraft models video --category video_edit\\nvideodraft edit video ./product-demo.mp4 \\\\\\n  \\"Preserve the product but follow the reference camera rhythm\\" \\\\\\n  --model gemini-omni-1.1-flash --ref-video ./camera-rhythm.mp4 \\\\\\n  --ref-video-duration 2.5 --resolution 1080p \\\\\\n  --download ./media/product-demo-reframed.mp4\\n\\nvideodraft edit video ./product-demo.mp4 \\\\\\n  \\"Turn the room into a warm evening scene while preserving the product and camera motion\\" \\\\\\n  --model kling-o3-video-ref-edit --ref ./evening-style.jpg \\\\\\n  --preserve-audio --download ./media/product-demo-evening.mp4\\n```\\n\\nTransfer motion from a reference clip onto a character image:\\n\\n```bash\\nvideodraft edit motion ./character.png \\\\\\n  \\"Apply the dancer\'s movement to this character while preserving identity\\" \\\\\\n  --motion-video ./dance-reference.mp4 \\\\\\n  --model kling-v3-motion-control --quality pro \\\\\\n  --download ./media/character-dance.mp4\\n```\\n\\n## 4. Hosted changelog video in CI\\n\\nIn a GitHub Action with `VIDEODRAFT_API_KEY` set as a secret:\\n\\n```bash\\nNOTES=$(git log --oneline v1.2.0..HEAD | head -20)\\nvideodraft create \\"Weekly product update video. Energetic, 20 seconds. Changes: ${NOTES}\\" --ar 16:9 --json > p.json\\nPROJECT=$(jq -r .project_id p.json)\\nvideodraft shots \\"$PROJECT\\" && videodraft produce \\"$PROJECT\\"\\nvideodraft export \\"$PROJECT\\" --download changelog.mp4 --wait-timeout 30m\\n```\\n\\n## 5. Variations and picking a winner\\n\\n```bash\\nvideodraft generate image \\"logo concept: minimalist fox, geometric\\" --num 4 --download \\"./concepts/{job_id}_{index}.{ext}\\" --json\\n# Show all 4 to the user; regenerate the chosen one at higher res:\\nvideodraft generate image \\"<same prompt>\\" --model nano-banana-pro --resolution 4K\\n```\\n\\n## 6. Reaching tools without a curated command\\n\\n```bash\\nvideodraft tools list --json | jq -r \'.[].name\'\\nvideodraft tools schema attach_media_to_shot --json\\nvideodraft call attach_media_to_shot --args \'{\\"project_id\\":\\"...\\",\\"scene_index\\":0,\\"shot_index\\":1,\\"media_url\\":\\"https://...\\",\\"media_type\\":\\"video\\",\\"duration_seconds\\":6}\'\\n```\\n\\nAnything the hosted VideoDraft MCP exposes, including character studio, product studio, and hosted project data, is reachable this way even before it gets a curated command. Native `.vdproject` editing uses the separate `videodraft_editor` MCP described in SKILL.md.\\n\\n## 7. Enhance an existing asset without changing it\\n\\n```bash\\n# Light image cleanup, no enlargement\\nvideodraft upscale image ./poster.png --scale 1x --download ./media/poster-enhanced.png\\n\\n# General image and video enlargement\\nvideodraft upscale image ./frame.png --scale 2x --download ./media/frame-2x.png\\nvideodraft upscale video ./clip.mp4 --resolution 1080p --download ./media/clip-1080p.mp4\\n\\n# Rebuild detail in a tiny/blurry source (generative), or reimagine it (creative)\\nvideodraft upscale image ./tiny.jpg --scale 4x --mode generative --model \\"Wonder 3.5\\" --download ./media/tiny-4x.png\\nvideodraft upscale video ./ai-clip.mp4 --resolution 4k --mode generative --download ./media/ai-clip-4k.mp4\\n\\n# Smoother motion or slow motion (resolution unchanged)\\nvideodraft interpolate ./clip.mp4 --fps 60 --download ./media/clip-60fps.mp4\\nvideodraft interpolate ./clip.mp4 --model Chronos --slowdown 4 --download ./media/clip-slowmo.mp4\\n```\\n\\nUse these when the content is correct and only quality or resolution needs improvement. If the poster text, composition, subject, or motion is wrong, edit or regenerate instead.\\n","references/models.md":"# Choosing models (and predicting cost)\\n\\nAlways consult the live catalog instead of memorizing this page \u2014 models change weekly:\\n\\n```bash\\nvideodraft models image --json     # every image model + inputs (aspect ratios, resolutions, max refs)\\nvideodraft models video --json     # every video model + inputs + per-second pricing metadata\\nvideodraft models audio --json     # standalone audio/media models + pricing inputs\\nvideodraft models voices --json    # TTS voices\\nvideodraft models styles --json    # visual style presets\\n```\\n\\n## Task-based model selection\\n\\nFollow this order every time:\\n\\n1. The user named a model: use it, never substitute.\\n2. Otherwise pick a **Tier 1** model from the task\'s inputs, duration, audio, quality, speed, and cost, and pass it explicitly instead of relying on a blind platform fallback.\\n3. Use a **Tier 2** model only when no Tier 1 model supports the request, and say why. Never pick Tier 2 on your own for price, speed, novelty or variety.\\n\\nTier 1 is the rows marked **T1** below. Every other catalog model is Tier 2 and stays available by name. The catalogs carry this themselves: every `videodraft models image|video|audio --json` entry has `tier` (1 or 2) plus `recommended` / `recommended_for`, and the top-level `recommended` array is Tier 1, best first. Trust the catalog over this page when they disagree.\\n\\n### Images\\n\\n| Need                                                                                       | Choose                   | Why                                                               |\\n| ------------------------------------------------------------------------------------------ | ------------------------ | ----------------------------------------------------------------- |\\n| T1: Most generation, editing, character consistency, or reference work                     | `nano-banana-2`          | Best general default; 1K/2K/4K and up to 14 reference images      |\\n| T1: Highest-quality complex generation or reasoning                                        | `nano-banana-pro`        | Premium Nano Banana quality and reasoning                         |\\n| T1: Fast, inexpensive drafts and iteration                                                 | `nano-banana-2-lite`     | Fastest/cheapest Nano Banana option; 1K only, up to 14 references |\\n| T1: Posters, title cards, signs, logos, or any image with important readable text          | `gpt-image-2.5-flare`    | Fast OpenAI option; 16 references, 1K/2K/4K and PNG output        |\\n| T1: Complex multi-image composition, precise editing, or a strong alternate interpretation | `gpt-image-2.5-sunburst` | More fidelity/detail; 16 references, quality through max          |\\n| T1: Vector / SVG output (logos, icons, illustrations that must scale)                      | `recraft-v4`             | Recraft V4.1 text-to-vector; SVG only, no reference images        |\\n| T2: By name, or an explicitly requested xAI look                                           | `grok-imagine`           | 2 cr flat (3 with a reference); 1 reference image                 |\\n| T2: xAI at 2K or with a quality tier, up to 3 edit references                              | `grok-imagine-2.0`       | 1K 4 (low) / 6 (medium), 2K 6 / 8, +1 cr per reference image      |\\n\\nGPT Image 2.5 has two IDs: `gpt-image-2.5-flare` replaces the former GPT Image 2 recommendation; `gpt-image-2.5-sunburst` is the precision/detail alternative. Other model recommendations are unchanged. Explicit `gpt-image-2` selections continue to use the previous model.\\n\\nUse the same basic image controls as GPT Image 2: `--ref`, `--ar`, `--resolution 1K|2K|4K`, `--quality`, and `--num 1..4`. GPT Image 2.5 quality supports auto/low/medium/high/xhigh/max. Auto is priced at Max in customer-credit estimates. The default platform path uses OpenAI; a selected personal connection stays exclusive. A Pika personal connection requires an explicit quality from low/medium/high/xhigh/max because its upstream API has no auto value. Other unsupported connection settings return an error instead of switching payer or changing the request.\\n\\n```bash\\nvideodraft generate image \'A blue glass bird\' --model gpt-image-2.5-flare --ar 1:1 --resolution 2K --quality high --estimate\\nvideodraft generate image \'A blue glass bird\' --model gpt-image-2.5-flare --ar 1:1 --resolution 2K --quality high --num 2\\n```\\n\\n`videodraft shots` forwards resolution and quality for both normal and grid generation. Estimates use the project\'s model and aspect when omitted; grid canvas costs may differ from ordinary shot costs. Use `videodraft costs --model <id> --ar <ratio> --resolution <tier> --quality <tier>` for a specific per-image quote.\\n\\n### Videos\\n\\n| Need                                                                                                           | Choose                   | Important limits                                                                                                                                                                                                                                               |\\n| -------------------------------------------------------------------------------------------------------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\\n| T1: Most generation, first/last-frame, mixed-reference, source-edit, or extension requests                     | `gemini-omni-1.1-flash`  | 3-10s output; 360p/720p/1080p/4K at 3/10/15/30 cr/s; audio always; up to 10 image inputs, and 3 reference videos <=3s on generate only; edit source <=10s; continuation or 3-10s extension of a 1-30s source, 40s total reachable only by extending from <=30s |\\n| T2: Grok 1.5 text, first-frame, or 1-7 image-reference clips with native audio and optional 1080p              | `grok-imagine-video-1.5` | 1-15s; 480p/720p/1080p for text/first-frame; references are 480p/720p only; no last frame                                                                                                                                                                      |\\n| T2: Document or webpage reference generation; by name otherwise                                                | `wan-3.0`                | 2-30s or auto; 480p/720p/1080p at 7/14/28 cr/s; 10 image, 5 video, 5 audio refs, 20 media files total; document/web refs require thinking                                                                                                                      |\\n| T2: 480p/768p/2K/4K with native stereo audio, first/last frames, or mixed image/video/audio references         | `minimax-h3`             | 5-15s; 5/6/13/16 cr/s by resolution; up to 9 image, 3 video, 3 audio refs, 12 files total; first 5 reference images free then 8 cr each; reference video/audio each total <=15s                                                                                |\\n| T1: Text, first/last-frame, or mixed-reference video with native audio and stronger prompt adherence           | `minimax-h3-max`         | 5-15s; 5/8 cr/s at 480p/768p plus pooled reference tokens; up to 9 image, 3 video, 3 audio refs, 12 files total; seed and disabled/balanced/quality prompt expansion; provider safety checker off by default                                                   |\\n| T2: Images pinned to specific moments (keyframes); by name otherwise                                           | `flux-3`                 | 5-20s (auto for text/first-frame only); 720p/1080p; up to 10 keyframes; `--quality draft` is 720p-only at ~1/3 the cost                                                                                                                                        |\\n| T1: Video/audio references, mixed reference media, broad aspect ratios, frame-mode first+last frame, or 11-15s | `seedance-2`             | 4-15s or auto; up to 9 image, 3 video, and 3 audio refs; audio toggle; Mini/Fast are 480p/720p only                                                                                                                                                            |\\n| T1: Single takes past 15s, or more references than Seedance 2.0 allows                                         | `seedance-2.5`           | 4-30s or auto; up to 30 image, 10 video, and 10 audio refs (50 files total); one quality tier; 480p/720p/1080p                                                                                                                                                 |\\n| T2: Fast polished 3-15s video with first frame, multi-prompt, and native audio                                 | `kling-v3-turbo`         | Audio always on; Pro default; no end frame, reference-media mode, or elements                                                                                                                                                                                  |\\n| T1: Cinematic 3-15s with reference images, image/video elements, first+last frame, audio, or 4K                | `kling-o3`               | 7 combined image refs/elements, reduced to 4 with a video element; Standard/Pro/4K                                                                                                                                                                             |\\n| T1: Kling 3-15s image-to-video with first+last frame, image/video elements, multi-prompt, audio, or 4K         | `kling-3.0`              | Elements require a start image; image or video elements can bind voice_id; Standard/Pro/4K                                                                                                                                                                     |\\n| T2: User explicitly requests Veo, or the selected workflow specifically needs Veo                              | `google-veo3.1`          | Good fallback, but not the preferred general model                                                                                                                                                                                                             |\\n\\nRouting rules:\\n\\n- Inexpensive pass or draft at 480p/768p with native audio: use MiniMax H3 Max (5/8 cr/s plus reference tokens).\\n- Grok 1.5 reference mode accepts 1-7 images only. Address them in array order as `<IMAGE_0>` through `<IMAGE_6>`. Do not combine reference images with `--start-image`, `--end-image`, `--ref-video`, or `--ref-audio`.\\n- Grok 1.5 first-frame mode accepts one `--start-image`, derives the output aspect ratio from that image, and does not support `--end-image`. Text and first-frame modes support 480p, 720p, or 1080p. Reference mode supports 480p or 720p.\\n- Grok 1.5 always generates native audio. Do not pass `--no-audio`, `--seed`, `--negative`, or `--quality`.\\n- Around 11-15 seconds with native audio: use Seedance, Kling 3.0 / O3, or MiniMax H3 Max, not Gemini. Past 15 seconds: Seedance 2.5.\\n- Dialogue: write the line in the prompt, in quotes, with who says it and how. `gemini-omni-1.1-flash`, `seedance-2.5`, `seedance-2`, `kling-3.0` and `kling-o3` speak it natively; add `--ref-audio` on Seedance or a bound Kling voice for a specific voice. Do not generate speech separately and lip-sync it on.\\n- One existing source video that should be edited: use `videodraft edit video`, which auto-selects Gemini Omni 1.1 Flash for a source up to 10s. Generic `generate video --ref-video` retains source-edit behavior when `--video-task` is omitted, but the dedicated edit command is clearer.\\n- Video supplied as a creative reference: Gemini Omni 1.1 Flash accepts up to 3 videos of at most 3 seconds each, including mixed image and video input. Creative video references are accepted on `--video-task generate` ONLY: edit and extend take exactly one input video, so `--ref-video` cannot accompany `--source-video` or `--previous-interaction-id`. Use Seedance 2.5 for more or longer video/audio references, or Seedance 2.0 when quality-tier control matters.\\n- First and last frame control: every Tier 1 video model supports it (Gemini Omni 1.1 Flash, Seedance, Kling O3, Kling 3.0, MiniMax H3 Max). For Gemini, every start/end frame counts toward the 10-image total, leaving up to 9 references with a start frame or 8 with both frames.\\n- Extension with a 1-30s uploaded source uses Gemini Omni 1.1 Flash plus `--source-video` and `--video-task extend` (or `--extend`). Pass an explicit 3-10s output duration; the model appends it at the end, up to 40 seconds total. Creative `--ref-video` clips CANNOT accompany the source: edit and extend take exactly one input video. New dialogue is allowed only when the source video is silent; adding speech on top of a source that already has speech is refused with \\"the model is currently unable to process speech edits\\". Continuation uses `--previous-interaction-id <id>` and defaults to a conversational edit; `--video-task extend` lengthens it. A continuation is submitted as the prior turn\'s output video, so it obeys the same source limits (<=30s to extend, <=10s to edit) and the same silent-source dialogue rule. 40s total is reachable only by extending from a source of 30s or less, so a ladder dead-ends past 30s. Fal returns interaction IDs, but its currently published callable v1.1 endpoints do not expose continuation/extension or mixed source-edit references; never infer a route or silently fall back to paid Google.\\n- Wan 3.0 reference mode and frame mode are separate. It accepts 10 images, 5 videos, and 5 audio clips, at most 20 media files total. Video and audio each total at most 15 seconds. `--file-url` and `--web-url` require `--thinking`. `--auto-duration` cannot be combined with `--duration`.\\n- MiniMax H3 and H3 Max reference mode and first-plus-last-frame mode are separate. Audio cannot be the only reference. Address references as `Image 1`, `Video 1`, and `Audio 1` in array order.\\n- Seedance reference mode and first-plus-last-frame mode are separate. Do not promise reference video/audio plus a last frame in one generation.\\n- Multi-prompt sequencing: use Kling 3.0 Turbo, Kling O3, or Kling 3.0.\\n- Kling 3.0 image-to-video and Kling O3 reference-to-video accept repeatable structured `--element` JSON. Each element is image-backed (`frontal_image_url` plus 1-3 `reference_image_urls`) or video-backed (`video_url`). Either form may include `voice_id`. Keep the voice ID inside the same element so the association is preserved. Reference them as `@Element1`, `@Element2`. Kling V3 Turbo rejects elements.\\n- Kling 2.6 Pro image-to-video accepts one or two repeatable `--voice-id` values. Cite them as `<<<voice_1>>>` and `<<<voice_2>>>` in the prompt. Voice control costs 17 cr/s. Use `videodraft kling-voices list|create|delete` to manage the separate Kling video-control voice library. Creating a voice requires a clean 5-30 second, up-to-50MB single-speaker `.mp3`, `.wav`, `.mp4`, or `.mov` sample plus `--confirm-consent`. Creation costs 1 VideoDraft credit on the platform Fal account and 0 credits with Fal BYOK; use the create command\'s `--estimate` flag to check without creating.\\n- Kling V3 voice control costs 16 cr/s for Standard and 20 cr/s for Pro.\\n- Seedance quality: `mini` for the lowest cost, `fast` for speed, `standard` for maximum quality and for 1080p/4K. Seedance 2.5 has a single tier and ignores `--quality`.\\n- Longer than 15 seconds, or more than 9 image / 3 video / 3 audio references: use Seedance 2.5. It reaches 30s and 30/10/10 references (50 files total) at 480p/720p/1080p, but has no 4K.\\n- Seedance 2.x allows real people by default, the same as AI Studio: Byteplus first, a submit-time Fal fallback, and Fal\'s higher tier-specific rate. Turn it off with MCP `allow_real_people: false` or CLI `--no-allow-real-people` for the lower Byteplus-only rate, only when the user wants the cheapest run and nothing in the job is a real identifiable person (text-only requests, non-people, anime, clearly synthetic or stylized characters).\\n- If a Seedance request made with the option off fails with `SEEDANCE_REAL_PERSON_OPT_IN_REQUIRED`, estimate the higher rate, follow the user\'s spend policy, and retry once with the option on. The response also carries `retry_with: { allow_real_people: true }`, `cli_flag: \\"--allow-real-people\\"`, and `retry_policy: \\"once\\"`. If the option was already on, do not repeat the same request. Byteplus may accept a task and reject the output later. VideoDraft refunds that failed generation, but it cannot reroute the asynchronous failure to Fal. Rephrase or change the references instead.\\n\\n### Video edit and motion-control categories\\n\\nUse `videodraft models video --category video_edit` for existing-video transforms and `--category motion_control` for motion transfer.\\n\\n| Need                                       | Command/model                                                                | Important limits                                                                                                                                          |\\n| ------------------------------------------ | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |\\n| Most edits of a source up to 10s (DEFAULT) | `videodraft edit video <video> \\"...\\"` (auto-selects `gemini-omni-1.1-flash`) | Source <=10s or it REFUSES; up to 10 image refs and 3 creative video refs <=3s each; 360p/720p/1080p/4K; audio always regenerated (no `--preserve-audio`) |\\n| Cheapest simple prompt edit                | `videodraft edit video <video> \\"...\\" --model grok-imagine-video-edit`        | No image refs; source silently truncated to 8s; auto/480p/720p                                                                                            |\\n| Edit with several image references         | `--model happy-horse-video-edit --ref ...`                                   | Up to 5 refs; 720p/1080p; source silently truncated to 15s; highest rate (28-56 cr/s)                                                                     |\\n| Controlled Kling edit                      | `--model kling-o3-video-ref-edit --ref ...`                                  | Up to 4 refs; Standard/Pro; source silently clamped to 3-10s                                                                                              |\\n| Transfer reference motion to an image      | `videodraft edit motion <image> [direction] --motion-video <video>`          | Prompt/direction is optional; Kling V3 default; optional one image-only `--element`; element requires video orientation                                   |\\n\\nIf the user explicitly names one of these models, preserve it. The CLI uploads local source videos and reference images automatically. Editing returns an async job and waits by default.\\n\\n**Omit `--model` and the SERVER chooses**, because only it can measure the source. It picks `gemini-omni-1.1-flash` for any source up to 10s. When that is not safe (source longer than 10s, unmeasurable duration, `--preserve-audio`, more than 10 refs, or Fal BYOK with refs) it spends nothing and returns a priced menu: per model, the seconds it would edit, the seconds it would drop, and the credit cost. The CLI prints that table and exits 2. Show it to the user, then re-run with `--model`.\\n\\n**Truncation is the trap here.** Only Gemini refuses a source it cannot fully consume. Every other edit model accepts a 30s clip and returns an edit of its first 8-15 seconds with no error. `videodraft edit video` now warns when this will happen and the tool response carries `source.truncated` / `source.dropped_seconds`; relay it to the user rather than letting them discover it in the output.\\n\\nTo edit a longer source without losing its tail, cut it into <=10s pieces with `videodraft_editor`, edit each with Gemini, then reassemble and export there. VideoDraft has no server-side split/concat, so this needs the native editor.\\n\\nKling O3 is also exposed for reference generation. `videodraft generate video --model kling-o3-video-ref-edit` requires exactly one `--ref-video` and generates a new reference-guided clip. Wan 3.0 handles new text, frame, and mixed-reference generation, but is not an existing-source edit model.\\n\\n### Reference-first video workflow\\n\\n- Prefer a start frame or reference image whenever a specific character, product, location, style, composition, or brand identity must stay recognizable.\\n- If the user gives a reference, pass it. Never silently replace it with a text description.\\n- If no reference exists and continuity matters, generate a still first with the user\'s explicitly requested compatible image model, otherwise use Nano Banana 2. Wait for the image URL, then animate it with the selected video model. Confirm the combined image plus video cost before starting.\\n- For multi-shot scenes, generate shot images with `videodraft shots <project_id> --model <selected-image-model> --grid`. Preserve an explicitly requested compatible image model; otherwise use `nano-banana-2`. The grid establishes the scene and characters together, then decodes into individual shot images.\\n- Animate the decoded shot images as per-shot start frames or references. Do not independently text-generate each video clip when the shots need to match.\\n- Pure text-to-video remains appropriate for generic one-off footage where no subject, composition, or continuity needs to be preserved.\\n\\n### Audio\\n\\n- **Seed Audio 1.0**: use `videodraft generate audio` for open-ended speech, sound, music, or prompt-driven audio editing. It accepts up to three audio references or one image. Address audio references as `@Audio1`, `@Audio2`, and `@Audio3`. Preset and custom cloned voice IDs are supported. Output is up to 120 seconds. There is no requested-duration input. The CLI automatically retries transient responses with one idempotency key. To recover after the CLI process itself is interrupted, set `--idempotency-key <uuid>` on the original command and reuse it.\\n- **Voiceover/TTS**: prefer ElevenLabs. Brittney is the platform default voice; under ElevenLabs BYOK, use a compatible voice from the user\'s account. Honor another supported voice/provider when the user explicitly selects it. ElevenLabs voices run on Eleven v4 in one of two modes: Standard (the default, best quality) or Turbo (Eleven v4 Turbo, faster and half the price). Keep Standard unless the user wants faster or cheaper speech. Pick the mode with `generate voiceover --mode standard|turbo` or `produce --voice-mode standard|turbo`; over MCP, pass `mode` to `generate_voiceover` or `voice_mode` to `produce_project`. Google, OpenAI and cloned `custom-*` voices ignore it. v4 takes no style or speed settings and no SSML `<break>` tags; audio tags such as `[whispers]` work. Dialogue stays on Eleven v3.\\n- **Dialogue, voice changing, and dubbing**: ElevenLabs only.\\n- **Sound effects**: ElevenLabs Sound Effects only.\\n- **Music**: use `lyria-3.5` for all music, short or long (up to ~3 minutes), with vocals/lyrics or instrumental music. When `--model` is omitted the CLI sends no model and the server default applies, which is `lyria-3.5` wherever the backend supports it. If the server answers that `lyria-3.5` is an unknown model, that backend predates it: rerun without `--model` (the server default then applies), or use `lyria-3-pro-preview` for a track longer than 30 seconds. `lyria-3-clip-preview` (fixed ~30s) and `lyria-3-pro-preview` remain available for explicit requests. Lyria length and structure are prompt-guided, not exact; for an instrumental, include \\"instrumental only, no vocals\\" in the prompt. `--length` and `--instrumental` only apply to ElevenLabs. Use `elevenlabs-music-v2.5` when a specified 3-300 second length, composition plan, or style reference track matters. Lyria references: up to 10 images on Google, 1 on Fal BYOK; 3.5 Fal prompts are 1-5000 characters (an image-only request gets a neutral prompt). `elevenlabs-music` is an alias for v2.5. Use `elevenlabs-music-v1` only when the user asks for v1 by name; it takes a prompt, `--length` and `--instrumental` only.\\n- **ElevenLabs Music v2.5 inputs**: either a prompt (`--length`, `--instrumental`) or a composition plan, never both. A plan is 1-30 sections of 3-120 seconds each, up to 300 seconds in total, and `--plan`/`--section` pick v2.5 when `--model` is omitted. Empty section parts default to 20 seconds and an instrumental part. Build one with repeatable `--section \\"<seconds>|<style, style>|<text>\\"` (use `\\\\n` for line breaks) or pass `--plan plan.json` with `{\\"chunks\\":[{\\"text\\",\\"duration_ms\\",\\"positive_styles\\",\\"negative_styles\\",\\"context_adherence\\",\\"audio_reference\\"}]}`. Section text is an optional `[Section name]`, lyric lines, and `{inline directions}`. Put 6-7 specific English styles on the first section; it sets the genre. `--ref-audio <url|file>` adds a style reference clip to the first section (window up to 30 seconds via `--ref-start`/`--ref-end` in ms, `--ref-strength low|medium|high|xhigh`); local files are uploaded, including relative `audio_reference.audio_url` paths in a plan file. `--seed` works only with a plan. `--format` picks the output (`mp3_48000_192` default on v2.5; `pcm_*`, `ulaw_8000` and `alaw_8000` arrive as stereo WAV files). Style references don\'t run on the user\'s own ElevenLabs key; with that key connected, drop the reference or ask the user to turn the key off. The CLI retries transient responses with one idempotency key; set `--idempotency-key <uuid>` to recover after an interruption.\\n- Voice Changer and Dubbing require the source media duration and currently accept source media up to 300 seconds.\\n\\n**User-supplied ElevenLabs voice IDs:** voiceover, dialogue, and voice changing accept raw IDs (16-64 alphanumeric characters) or `elevenlabs-<id>`. `videodraft models voices` / MCP `list_available_voices` is for discovery, not an allowlist. Pass a supplied ID directly even when it is absent from the catalog; do not reject it or substitute a catalog voice. The voice must be accessible to the provider account used for generation. Private or cloned voices may require the user\'s connected ElevenLabs key. A failed voice listing does not prove that a supplied ID cannot generate; a connected key with generation access may still work. If the provider rejects generation access, report that error rather than silently changing the voice.\\n\\nUse `--voice <id>` for voiceover and voice changing, and repeat `--line \\"<id>:Text\\"` for dialogue. These examples show both ID forms; replace the sample IDs with the user\'s supplied IDs:\\n\\n```bash\\nvideodraft generate voiceover \\"Hello there.\\" --voice kPzsL2i3teMYv0FxEYQ6 --download ./media/voiceover.mp3\\nvideodraft generate dialogue --line \\"kPzsL2i3teMYv0FxEYQ6:Hello.\\" --line \\"elevenlabs-kmSVBPu7loj4ayNinwWM:Welcome back.\\" --download ./media/dialogue.mp3\\nvideodraft generate voice-changer ./media/source.wav --voice elevenlabs-kPzsL2i3teMYv0FxEYQ6 --duration 12 --download ./media/changed-voice.mp3\\n```\\n\\nFor MCP, use `generate_voiceover.voice_id`, `generate_dialogue.lines[].voice_id`, or `change_voice.voice_id` with either form. ElevenLabs IDs are separate from Kling video-control voice IDs and MiniMax `custom-*` cloned-voice IDs. Do not convert IDs from those systems into ElevenLabs IDs.\\n\\n### Avatar / talking head\\n\\n**First decide the framing, not just \\"someone talks\\".** This lane animates a PORTRAIT facing the lens. A character delivering a line inside a real scene, with blocking, framing or camera movement, belongs to `generate video` instead: write the dialogue in the prompt and `gemini-omni-1.1-flash`, `seedance-2.5`, `seedance-2`, `kling-3.0` or `kling-o3` voices it natively (add a Seedance `--ref-audio` clip or a Kling voice bound per element for a specific voice). That is the default for any talking character; never plan silent video + TTS + lip-sync. Sending a cinematic shot to Fabric returns a head-on talking headshot, not the shot that was asked for. `videodraft models video --json` lists these under `recommended.in_scene_dialogue`.\\n\\nFor a presenter, spokesperson or explainer speaking to camera, VEED Fabric is the preferred model. Choose the dedicated path from the media the user already has:\\n\\n| Starting media                             | Command                                                                   | Use                                                        |\\n| ------------------------------------------ | ------------------------------------------------------------------------- | ---------------------------------------------------------- |\\n| Portrait + script, reusable avatar record  | `videodraft avatar create <portrait> --script \\"...\\"` then `avatar render` | Managed avatar flow with bundled speech preparation        |\\n| Portrait + text                            | `videodraft avatar fabric <portrait> --text \\"...\\"`                        | One-off direct VEED Fabric text mode                       |\\n| Portrait + existing audio                  | `videodraft avatar fabric <portrait> --audio <audio>`                     | One-off direct VEED Fabric audio lip sync                  |\\n| Portrait + existing audio, short and sharp | `videodraft avatar h3-lipsync <portrait> --audio <audio>`                 | MiniMax H3 Max Lip Sync, 5-14.8s at up to 2K               |\\n| Existing video + existing audio            | `videodraft avatar lipsync <video> --audio <audio>`                       | Sync Labs Lipsync 2 (Tier 2): re-dub existing footage only |\\n\\nThe managed renderer is VEED Fabric Fast (`veed/fabric-1.0/fast`). Direct Fabric, MiniMax H3 Max Lip Sync, and Sync Labs are paid AI Studio generations and return async job IDs.\\n\\n1. Obtain the avatar image. Prefer the user\'s supplied portrait or an existing character. If none exists, use the user\'s explicitly requested compatible image model, otherwise generate a front-facing head-and-shoulders portrait with `nano-banana-2`, direct eye contact, a natural expression, and a clean background. Match the intended video aspect ratio when practical.\\n2. If the portrait is visibly soft or too small, run Topaz image enhancement/upscaling before animation.\\n3. Generate a script only if needed: `videodraft avatar script \\"<idea>\\"`.\\n4. Create the avatar record and speech: `videodraft avatar create <portrait-url-or-file> --script \\"...\\" --voice <id> --ar 9:16`. Prefer ElevenLabs when unspecified, but honor another explicitly selected supported voice/provider.\\n5. Render with VEED Fabric: `videodraft avatar render <avatar_video_id> --resolution 720p`.\\n\\nThe portrait is passed as the avatar\'s character image, not as a generic video\'s start frame. Prefer rendering directly at 720p. Use 480p only when the user prioritizes lower cost. Avatar script generation and `avatar create` (including speech) are bundled/free. Confirm the Fabric render cost, plus portrait generation or upscaling when needed.\\n\\nDirect Fabric text/audio, H3 Max Lip Sync, and Sync Labs do not use the managed avatar record. The CLI uploads local portrait, video, and audio files automatically. `avatar fabric --speed fast` applies only to audio mode. `avatar h3-lipsync` takes no prompt: pick `--resolution 480P|768P|1080P|2K` (default 768P), an optional `--seed`, `--no-transcription` to sync without transcribing the audio (transcription is on by default), and `--safety-checker` only when the user asks for Fal\'s checker. The portrait\'s width / height must be 0.4-2.5, and audio shorter than 5 seconds is refused before any charge. Sync costs 5 credits per verified audio second; under Fal BYOK, `sync_mode` remains available but `temperature` and `active_speaker` are ignored by the provider.\\n\\n### Upscaling / enhancement\\n\\n- **Images**: Topaz via `videodraft upscale image <url-or-file> --scale 1x|2x|4x [--mode precision|generative|creative] [--model <name>]`. Modes: `generative` (default; Wonder 3.5, Topaz\'s recommended model for AI-generated images; `Redefine` takes `--prompt`, `--creativity 1-6`, `--texture 1-5`), `precision` (faithful and cheapest; Standard V2, High Fidelity V3, Low Resolution V2, CGI, Text Refine; use for clean real photos), `creative` (Bloom 2; artistic, `--prompt`, `--creativity 1-9`). Extra knobs: `--no-face-enhance`, `--face-strength`, `--sharpen`, `--denoise`, `--fix-compression`, `--format png`. Use 1x for light enhancement without enlargement, 2x as the general default, and 4x only when the source quality and target size justify it. The server must verify dimensions from a readable image of at most 50 MB; `--width` and `--height` are compatibility hints and cannot bypass a failed probe. The result may be immediate or queued; the CLI waits by default. Use `--no-wait` for an async job ID, and poll it with `status` or `wait`. Cost: 8 credits per started 24 MP of output in precision, per 8 MP (Wonder 3/3.5) or 4 MP in generative, per 2 MP in creative.\\n- **Videos**: Topaz via `videodraft upscale video <url-or-file> --resolution 720p|1080p|4k` (preferred) or `--scale 2x`, plus `--mode precision|generative|creative` and `--model <name>`. `generative` (default; Starlight Precise 2.6, Topaz\'s recommended model for AI-generated footage; Starlight Fast 2 at half price) costs 12 credits/s up to 1080p and 26 at 4K. `precision` (Proteus, Proteus Natural, Iris, Gaia 2 for animation, Rhea, Theia, Artemis, Dione) is 6x cheaper at 1 / 2 / 6 credits per second for 720p / 1080p / 4K output; use it for real footage or when cost matters. `creative` (Astra 2, `--prompt`, `--creativity`, `--realism`, `--sharp`) always renders 4K at 50 credits/s. `--fps 60` delivers 60fps on the same pass; any output above 30fps (including a 50/60fps source) doubles every rate; the server must verify duration, dimensions, and frame rate from an MP4/MOV source of at most 100 MB. `--duration`, `--width`, `--height`, and `--source-fps` are compatibility hints and cannot override billing or bypass a failed probe. The same source-verification requirement applies to frame interpolation. `--scale` also accepts intermediate factors such as `1.5x`. Max source length 5 minutes. The job is asynchronous; the CLI waits by default, while MCP callers poll `check_generation_status`. MCP video input must be VideoDraft-hosted, so upload local or external sources first.\\n- **Frame interpolation / slow motion**: `videodraft interpolate <url-or-file> --fps 60 [--model Apollo|Chronos|Aion] [--slowdown 1-8]` (MCP `interpolate_video`). Resolution is unchanged. Apollo (default) for smooth general conversion, Chronos for natural slow motion, Aion for extreme slow motion. Apollo/Chronos cost 3 credits per output second up to 1080p (6 at 4K); Aion 5 / 17. These rates cover targets up to 60fps; above 60fps multiply by target FPS / 60 (120fps doubles the rate). Output seconds = source seconds \xD7 slowdown. The final charge rounds up to a whole credit.\\n- Use upscaling to preserve the image/video while improving detail, resolution, or cleanup. It cannot fix the wrong subject, misspelled text, bad framing, unwanted objects, broken continuity, or incorrect motion. Use an edit or regeneration for those problems. Keep `generative` for AI-generated sources; switch to `precision` for clean real photos/footage or a cheap pass, and `creative` only when the user wants an artistic reinterpretation.\\n- For a new Fabric avatar, render directly at 720p instead of rendering at 480p and then upscaling. Upscale the source portrait first only when the portrait itself is low quality.\\n\\n## Capability gotchas\\n\\n- Each model\'s `inputs` block is authoritative: supported `aspect_ratios`, `resolutions`, `quality_options`, `start_frame`/`end_frame`, `max_reference_images/videos/audio`, `multi_prompt`, `audio_toggle`. Passing an unsupported input fails with a clear error \u2014 check first, don\'t trial-and-error paid calls.\\n- Most video models support only 16:9 / 9:16 / 1:1. A 3:4 request hard-fails on most.\\n- `--seed` reproduces a specific output on models that support it (e.g. Flux, Ideogram V4). GPT Image 2.5 rejects any explicit seed; older models may ignore unsupported seeds. You do not need a seed for variation \u2014 `--num` already varies.\\n- `--rendering-speed` applies to Ideogram (V3: `Default`/`Turbo`/`Quality`; V4: `Turbo`/`Balanced`/`Quality`) and affects image cost \u2014 pass it to `videodraft costs ... --rendering-speed <tier>` for an accurate estimate. Always trust `videodraft models image --json` over this list; new models and tiers appear there the moment the platform ships them, with no CLI update.\\n- `seedream-v5-pro` supports unified text-to-image and reference-image editing with up to 10 image references. Use `--resolution 1K` for 7 credits/image or `--resolution 2K` for 14 credits/image.\\n- Reference inputs: `--ref <img>` (images, including up to 10 total for Gemini Omni 1.1 Flash and Wan 3.0, and 7 for Grok 1.5), `--source-video <v>` (Gemini uploaded edit/extension source), `--ref-video <v>` (up to 3 creative videos <=3s each for Gemini Omni 1.1 Flash; also Wan 3.0, MiniMax H3, MiniMax H3 Max, and Seedance 2), `--ref-audio <a>` (Wan 3.0, MiniMax H3, MiniMax H3 Max, Seedance 2), and `--element \'<json>\'` or `--element @elements.json` for Kling V3/O3. For an exact Seedance 2.x reference-video `--estimate`, add `--ref-video-seconds <combined-seconds>`; Seedance bills input seconds alongside output. Wan 3.0 and MiniMax H3 do not bill input reference seconds; MiniMax H3 Max bills them as pooled reference tokens. The CLI uploads local media references and every structured element without flattening the source/reference roles. `--segment \\"<prompt>:<seconds>\\"` (repeatable) drives Kling 3.0, Kling 3.0 Turbo, and O3 multi-prompt generation. Use 1-6 segments of 1-15 whole seconds each, with 3-15 seconds total. `generate image --video-ref` is the nano-banana-2 video reference.\\n- The top-level prompt is OPTIONAL for Gemini Omni 1.1 Flash media-input or continuation calls, Wan 3.0 frame/reference modes, `generate video` with multi-prompt models, and Kling 3.0 Turbo (`--model kling-v3-turbo`) image-to-video. Text-only Gemini and Wan calls still require a prompt unless their live schema says otherwise.\\n- Hosted AI Production fallback: `videodraft produce <project> --mode full_video` generates one Seedance 2 video per scene, with real people allowed by default at the higher Fal-tier rate on every submitted scene segment; add `--no-allow-real-people` for the lower Byteplus-only rate when no scene shows a real identifiable person. The MCP equivalent is `produce_project` with `mode: \\"full_video\\"` (and `allow_real_people: false` to opt out). If a partial opted-out run returns `SEEDANCE_REAL_PERSON_OPT_IN_REQUIRED`, rerun the same project once with an explicit `--allow-real-people` after cost confirmation. The server reconciles asynchronous results first, preserves running/completed jobs, and retries only failed placeholders carrying that exact code. Poll with `videodraft generations`, then `videodraft finalize <project>` swaps them into the hosted timeline before `export`. In VideoDraft ADE, do not choose this path while `videodraft_editor` is available unless the user explicitly requests hosted production. Generate or download the scene assets, import them, and assemble/export with the native editor instead. If the user explicitly requests another compatible video model for a hosted production, do not use this fixed Seedance path; generate the project shots manually with the requested model and attach them to the hosted timeline.\\n\\n## Cost model\\n\\n- Images: per image (\xD7 `--num`). Matrix-priced models (GPT-Image, Nano Banana Pro, Seedream v5 Pro) vary by resolution/quality.\\n- Video: usually credits/second \xD7 duration; rate depends on model + resolution + quality + native audio on/off.\\n- Gemini Omni 1.1 Flash: 3 / 10 / 15 / 30 credits per output second at 360p / 720p / 1080p / 4K (720p default). Extend appends an explicit 3-10 seconds to a 1-30s source, whether uploaded or resolved from a prior interaction; 40 seconds total is reachable only while the source stays at or under 30s. Fal BYOK generation and basic source edits cost zero VideoDraft credits; continuation, extension, and separate creative references on a source edit are unavailable under Fal BYOK.\\n- MiniMax H3: 5 / 6 / 13 / 16 credits per output second at 480p / 768p / 2K / 4K (768p default). The first 5 reference images are included, then 8 credits for each additional image. Reference video and reference audio are NOT billed.\\n- MiniMax H3 Max: 5 credits per output second at 480p or 8 credits per second at 768p (default), plus pooled reference tokens. The first 4,096 reference tokens are free and each additional 1,000 costs 2 credits. An image is `(width x height) / 1024` tokens (a 1024x1024 reference is 1,024, so four of them are free); a reference video is 2,886 tokens per second at 480p or 7,459 at 768p; reference audio is about 2,121 per second. Pass `--ref-audio-seconds` for an exact estimate with audio references. The server measures each reference image, so a quote that assumes 1024x1024 is a floor.\\n- Wan 3.0: 7 / 14 / 28 credits per output second at 480p / 720p / 1080p. Auto duration reserves 30 seconds and reconciles unused credits from the provider-reported output duration. Fal BYOK charges zero VideoDraft credits.\\n- Grok Imagine Video 1.5: 8 credits/output second at 480p, 14 at 720p, or 25 at 1080p, plus 1 credit for each first-frame or reference image. Native generated audio is part of every output.\\n- Kling voice control: 17 credits/output second for Kling 2.6 Pro, 16 at Kling V3 Standard, and 20 at Kling V3 Pro.\\n- Shot-image batches: one image per shot (+1 grid image per scene in `--grid` mode) \u2014 the largest single spend in the pipeline.\\n- VEED Fabric avatar renders: ~10 credits/sec at 480p, ~20/sec at 720p. Avatar creation and its speech are bundled/free; only optional portrait generation/upscaling adds cost before the render.\\n- Direct VEED Fabric: text or normal audio is 8 credits/sec at 480p and 15/sec at 720p; fast audio is 10/sec at 480p and 20/sec at 720p.\\n- MiniMax H3 Max Lip Sync: 5 / 8 / 16 / 32 credits per output second at 480P / 768P (default) / 1080P / 2K. The video runs as long as the audio (at least 5s; only the first 14.8s is used), billed on the server-measured length rounded up, so at most 15 seconds. Use MP3, WAV, M4A (AAC), or AAC audio; other formats run only on the user\'s own Fal key.\\n- Sync Labs Lipsync 2: 5 credits per verified audio second.\\n- Voiceover TTS: 10 credits per 1000 characters for standard voices (including ElevenLabs Standard, Eleven v4), 5 per 1000 for ElevenLabs Turbo (Eleven v4 Turbo), and 30 per 1000 for cloned `custom-*` voices (min 1, pro-rated); applies to standalone voiceovers AND per-scene narration during `produce`. Quote Turbo with model id `voiceover-turbo` (CLI: `costs voiceover --mode turbo`) and cloned voices with `voiceover-cloned`. Silent tracks are free. Voice cloning itself is a flat 150 credits per clone.\\n- Lyria music: flat per track, 4 credits (Clip) / 10 credits (3.5) / 8 credits (legacy Pro). Fal BYOK uses zero VideoDraft credits.\\n- Seed Audio 1.0: 19 credits per actual output minute, prorated and rounded up to a whole credit. VideoDraft reserves the 120-second maximum of 38 credits and refunds the unused portion after generation. Fal BYOK is free.\\n- ElevenLabs audio: sound effects are per second, dialogue is per character, music/voice-changer/dubbing are per started minute. ElevenLabs Music v2.5 and v1 both cost 60 credits per started output minute; estimate a composition plan with its total length. Voice changer and dubbing reject source media above 300s in the current synchronous flow.\\n- Seedance 2.0 / 2.5 real people: allowed by default, which keeps Byteplus first, permits a submit-time Fal fallback, and prices at Fal\'s rate for that tier: 2.0 Mini 8/16 cr/s, Fast 11/25, Standard 14/31/69/156, 2.5 23/48/114 for 480p/720p/1080p. `--no-allow-real-people` uses the Byteplus-priced path instead (2.0 Mini 4/8, Fast 6/13, Standard 7/16/38/78, 2.5 11/24/57); Byteplus refuses real-person likenesses, so a likeness-policy failure then does not fall back. The gap is roughly 2x but not exactly: the Seedance 2.0 1080p pair is 38/69, or about 1.82x. If Byteplus accepts the task and later rejects the generated output, VideoDraft refunds the failure but does not resubmit it to Fal. Turn the option off only for the cheapest run when nothing in the job is a real identifiable person.\\n- Grok Imagine images: `grok-imagine` is a flat 2 cr (3 with a reference). `grok-imagine-2.0` is a separate, newer model priced by resolution and quality: 1K 4 (low) / 6 (medium), 2K 6 / 8, plus 1 cr per reference image (up to 3). v1 is NOT superseded \u2014 pick it when cost matters more than 2K.\\n- xAI bills refused requests, so failed Grok generations are not refunded.\\n- Upscales: priced by output size, mode, and (video) duration/fps; see the Upscaling section above.\\n\\nQuote before spending:\\n\\n```bash\\nvideodraft costs gemini-omni-1.1-flash --type video --duration 8 --resolution 720p --audio\\nvideodraft costs topaz-upscale-video --type video --duration 10 --width 1920 --height 1080 --resolution 4k --mode generative\\nvideodraft costs topaz-upscale --type image --width 2048 --height 2048 --scale 2x\\nvideodraft costs topaz-interpolate-video --type video --duration 10 --width 1920 --height 1080 --fps 60 --topaz-model Apollo\\nvideodraft costs minimax-h3 --type video --duration 10 --resolution 2K --ref-images 7\\nvideodraft costs minimax-h3-max --type video --duration 10 --resolution 768p --ref-images 2\\nvideodraft costs grok-imagine-video-1.5 --type video --duration 8 --resolution 720p --ref-images 4\\nvideodraft costs seedance-2 --type video --duration 15 --resolution 720p --quality standard --audio\\nvideodraft costs grok-imagine-2.0 --type image --resolution 2K --quality medium --num 2\\nvideodraft costs seedance-2 --type video --duration 15 --resolution 720p --quality standard --audio --no-allow-real-people # lower Byteplus-only rate\\nvideodraft costs elevenlabs-dubbing --type audio --duration 60\\nvideodraft costs seed-audio-1.0 --type audio --duration 60 # scenario only; model controls actual length\\nvideodraft costs elevenlabs-dialogue --type audio --chars 350\\nvideodraft costs voiceover --type audio --chars 800    # TTS: 10 cr / 1000 chars\\nvideodraft costs voiceover --type audio --chars 800 --mode turbo # ElevenLabs Turbo: 5 cr / 1000 chars\\nvideodraft generate video \\"...\\" --model gemini-omni-1.1-flash --estimate # same quote, inline\\nvideodraft generate video \\"...\\" --model minimax-h3-max --duration 8 --resolution 768p --prompt-expansion-mode balanced\\n```\\n","references/pipeline.md":"# VideoDraft pipeline reference\\n\\nEverything here describes the hosted fallback pipeline through the CLI (`videodraft <command>` / `videodraft call <tool>`) or hosted MCP connector (tool names in backticks). When the local `videodraft_editor` MCP is available, do not use hosted production or export by default. Use hosted tools only for asset generation and optional script/storyboard stages, then import the results and finish with the native editor reference linked from SKILL.md. Continue through `produce_project` and `export_video` only when the user explicitly requests a hosted web production or the native editor is unavailable.\\n\\nUse direct asset tools for standalone images, clips, audio, upscales, and descriptions. Use a hosted project when the user explicitly wants the editable web project, when a hosted storyboard stage is useful, or when the native editor is unavailable. Script-only uses a script-stage project and stops at the script. In VideoDraft ADE with editor tools present, stop before hosted production, import the generated assets, and build/export the native project.\\n\\n## Stages and their tools\\n\\n| Stage                                    | CLI                                                                         | Underlying tool                             |\\n| ---------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------- |\\n| Idea \u2192 full storyboard project           | `videodraft create \\"<idea>\\"`                                                | `generate_storyboard_from_idea`             |\\n| Idea \u2192 script only (stop there)          | `videodraft create \\"<idea>\\" --script-only`                                  | `generate_script_from_idea`                 |\\n| Footage IS the video                     | `videodraft call generate_storyboard_from_media`                            | `generate_storyboard_from_media`            |\\n| Batch shot images                        | `videodraft shots <project>`                                                | `generate_shot_images`                      |\\n| One shot image                           | `videodraft generate image --project <id> --scene N --shot M`               | `generate_image`                            |\\n| Produce (voiceover, captions, timeline)  | `videodraft produce <project>`                                              | `produce_project`                           |\\n| Seedance full-video production           | `videodraft produce <project> --mode full_video`                            | `produce_project` with `mode: \\"full_video\\"` |\\n| Per-shot motion prompts                  | `videodraft video-prompts <project>`                                        | `generate_video_prompts`                    |\\n| Motion clip for a shot                   | `videodraft generate video --project <id>`                                  | `generate_video`                            |\\n| Attach a finished clip to the timeline   | `videodraft attach <project> --scene N --shot M --media <url> --type video` | `attach_media_to_shot`                      |\\n| Find free b-roll (no credits)            | `videodraft stock search \\"<query>\\"`                                         | `search_stock_media`                        |\\n| Copy stock media onto the CDN            | `videodraft stock import <ref>`                                             | `import_stock_media`                        |\\n| Background music                         | `videodraft generate music --attach <project>`                              | `generate_music` / `set_background_music`   |\\n| Song with vocals, lyrics or sections     | `videodraft generate music --model elevenlabs-music-v2.5 --section \\"...\\"`   | `generate_music` with `composition_plan`    |\\n| General or reference-driven audio        | `videodraft generate audio \\"...\\"`                                           | `generate_audio`                            |\\n| Sound effect                             | `videodraft generate sound-effect \\"...\\"`                                    | `generate_sound_effect`                     |\\n| Dialogue audio                           | `videodraft generate dialogue --line \\"voice:text\\"`                          | `generate_dialogue`                         |\\n| Voice changer                            | `videodraft generate voice-changer <audio>`                                 | `change_voice`                              |\\n| Dubbing                                  | `videodraft generate dub <audio_or_video>`                                  | `dub_media`                                 |\\n| Scene voiceover                          | `videodraft generate voiceover --project <id> --scene N`                    | `generate_voiceover`                        |\\n| Avatar script                            | `videodraft avatar script \\"<idea>\\"`                                         | `generate_avatar_script`                    |\\n| Avatar + speech                          | `videodraft avatar create <portrait> --script \\"...\\"`                        | `create_avatar_video`                       |\\n| Talking-head render                      | `videodraft avatar render <avatar_video_id>`                                | `render_avatar_video` + `get_avatar_video`  |\\n| Direct portrait + text/audio             | `videodraft avatar fabric <portrait> --text \\"...\\"` or `--audio <file>`      | `generate_veed_fabric_video`                |\\n| Short portrait clip from audio, up to 2K | `videodraft avatar h3-lipsync <portrait> --audio <file>`                    | `generate_minimax_h3_lipsync_video`         |\\n| Existing video + replacement audio       | `videodraft avatar lipsync <video> --audio <file>`                          | `generate_sync_lipsync_video`               |\\n| Existing-video AI edit                   | `videodraft edit video <video> \\"<change>\\" --model <video-edit-model>`       | `edit_video`                                |\\n| Motion transfer                          | `videodraft edit motion <image> [direction] --motion-video <video>`         | `generate_motion_control_video`             |\\n| Image enhancement/upscale                | `videodraft upscale image <image>`                                          | `upscale_image`                             |\\n| Video enhancement/upscale                | `videodraft upscale video <video>`                                          | `upscale_video`                             |\\n| Frame rate / slow motion                 | `videodraft interpolate <video> --fps 60 [--slowdown 4]`                    | `interpolate_video`                         |\\n| Final MP4                                | `videodraft export <project>`                                               | `export_video` + `check_export_status`      |\\n\\n## Rules that prevent broken results\\n\\n- **The storyboard is generated FROM the script**, never from the raw idea. `videodraft create` runs the whole chain correctly. Don\'t call `generate_storyboard_scenes` with a raw idea as the \\"script\\".\\n- **Visual consistency**: never generate a storyboard shot in isolation. Shot prompts carry `[[asset:Name]]` / `[[shot:X-Y]]` tags that `generate_shot_images` resolves against the project\'s visual assets and prior shots. When generating a single shot whose prompt has no tags, pass `--ref` images yourself (the project\'s visual assets and/or the previous shot\'s image; `projects get` exposes both). For scenes with multiple shots or recurring characters, prefer `videodraft shots <project> --model <selected-image-model> --grid`: preserve an explicitly requested compatible image model, otherwise use `nano-banana-2`. It creates one coherent scene grid, then decodes it into individual shot images.\\n- **Reference-first video**: when identity, styling, or composition matters, do not generate each motion clip from text alone. Generate or select the shot still first, then pass the decoded shot image as `--start-image` or `--ref` to the selected video model. AI Production already composes scene grids and sends them to Seedance as references. If the user explicitly requests another compatible video model, bypass fixed Seedance full-video mode and generate the per-shot clips with the requested model, using the individual decoded shot images as anchors.\\n- **Seedance full-video real people**: hosted `full_video` allows real people by default, which applies Fal-tier pricing to every submitted segment and permits the Byteplus-to-Fal fallback. For the lower Byteplus-only rate when no scene grid shows a real identifiable person (non-people, anime, clearly synthetic or stylized characters), use `videodraft produce <project> --mode full_video --no-allow-real-people`, or MCP `produce_project` with `mode: \\"full_video\\", allow_real_people: false`. If a partial opted-out run returns `SEEDANCE_REAL_PERSON_OPT_IN_REQUIRED`, re-estimate, follow the user\'s spend-confirmation preference, and rerun the same project once with an explicit `--allow-real-people` / `allow_real_people: true`. The server reconciles asynchronous results first, preserves running/completed jobs, and retries only failed placeholders carrying that exact code. Do not loop when it was already on. VideoDraft refunds a Byteplus task rejected after asynchronous acceptance, but cannot reroute it; rephrase or change the scene references instead.\\n- **Narration voice mode**: ElevenLabs narration runs on Eleven v4. Standard is the default and the best quality, at 10 credits per 1000 characters. `videodraft produce <project> --voice-mode turbo` (MCP `produce_project` with `voice_mode: \\"turbo\\"`) uses Eleven v4 Turbo, which is faster at 5 credits per 1000 characters. For one scene, `videodraft generate voiceover --project <id> --scene N --mode turbo` (MCP `generate_voiceover` with `mode: \\"turbo\\"`) does the same. Google, OpenAI and cloned `custom-*` voices ignore the mode.\\n- **Hold off generating shot images while the user is still iterating** on storyboard structure.\\n- **produce \u2192 export ordering**: `export` requires a produced project where every production scene has timeline media. If `produce` returns `generating_shot_images`, poll the job ids it returns, then re-run produce.\\n- **Do not attach motion clips before production exists**: run `produce` successfully first, then attach finished motion clips to the production timeline. Attaching before `production_data` exists cannot place them in the final timeline.\\n- **Generated motion clips do not auto-attach**: after `generate video` completes, attach the clip with `attach_media_to_shot` (`media_type:\\"video\\"`, include `duration_seconds`) \u2014 it replaces the production timeline clip while keeping the storyboard still.\\n- **Talking heads use dedicated avatar tools**: do not use `generate video`. Use managed `avatar create` and `avatar render` for reusable avatars, direct `avatar fabric` for a portrait plus text/audio, `avatar h3-lipsync` for a short (5-14.8s) portrait clip from existing audio at up to 2K, and `avatar lipsync` for an existing video plus replacement audio. Reuse a supplied person image or generate a clear front-facing portrait with the explicitly requested compatible image model, otherwise Nano Banana 2. Managed avatar creation and speech are bundled/free; direct Fabric, H3 Max Lip Sync, Sync, and render are paid.\\n- **Existing-video edits use their own category**: call `edit_video` or `videodraft edit video` with a `video_edit` model when transforming the source itself. Kling O3 also has a reference-generation mode that creates a new guided clip. Wan 3.0 is a text/frame/reference generation model, not a source-video editor. Motion transfer similarly uses `generate_motion_control_video` or `videodraft edit motion` with a `motion_control` model.\\n- **Upscaling preserves rather than redesigns**: use Topaz when resolution, detail, or cleanup is the problem (generative mode by default: Wonder 3.5 / Starlight Precise 2.6, Topaz\'s pick for AI sources; precision for real photos/footage or the cheapest pass; creative only for an artistic reinterpretation; `interpolate` for frame rate or slow motion). Regenerate or edit when the subject, text, framing, continuity, or motion is wrong. Upscale a low-quality avatar portrait before Fabric; do not render a new avatar at 480p just to upscale the result.\\n- **Timeouts on the one-shot create**: if `create` times out at the transport layer, the project was still created server-side \u2014 `videodraft projects list`, take the most recent, and resume with its id. Don\'t start a duplicate.\\n\\n## User-attached media: classify roles first\\n\\nFor EACH attached file decide:\\n\\n- **visual_asset** \u2014 recurring reference (character / product / location / style). Upload, then pass in `visual_assets` of `generate_storyboard_from_idea` (via `videodraft call`), or add to an existing project with `add_visual_assets`. Type must be one of `character | object | location | style | custom` with a short name + concrete description.\\n- **shot** \u2014 the media IS footage for the video. Whole video = footage \u2192 `generate_storyboard_from_media`. Idea + footage \u2192 `generate_storyboard_from_idea` with `shot_media`. Existing storyboard \u2192 `attach_media_to_shots`.\\n- **reference** \u2014 inspiration only \u2192 fold a description into the idea/instructions; don\'t place it as a shot or asset.\\n\\nAmbiguous (e.g. a person holding a product)? Ask the user.\\n\\nUploads persist in the media library \u2014 recall later with `videodraft media list`.\\n\\n## Editing project data safely\\n\\n1. `videodraft call get_project_schema` \u2014 read the structure once per session.\\n2. `videodraft projects get <id> --raw` \u2014 the exact editable blob.\\n3. Modify; then `videodraft call update_project --stdin` with `{\\"project_id\\": \\"...\\", \\"data\\": {...}}`.\\n   - Objects deep-merge key-by-key; **arrays replace wholesale** \u2014 send the complete array you\'re changing (e.g. all of `storyboard.scenes`).\\n   - Scene shot arrays (`image_prompt` / `shot_types` / `shot_actions` / `search_prompt` / `preview_media`) are auto-aligned; fix-ups come back as warnings.\\n4. Snapshot before risky edits: `videodraft checkpoint create <id> --name \\"before re-script\\"`. Restore with `videodraft checkpoint restore <id> <version>`.\\n\\n## AI Studio sessions (standalone generations)\\n\\nProject generations group automatically, and standalone work is grouped per conversation (MCP) or per working directory (CLI) by the connection session \u2014 see the \\"AI Studio sessions\\" section of SKILL.md. Once the task is clear, give that automatic session a concise 3-6 word title before the first generation:\\n\\n```bash\\nvideodraft sessions name \\"Fox Brand Explorations\\"\\nvideodraft generate image \\"...\\"\\n```\\n\\nNaming creates the session with that title. If generation, a user, or an earlier agent created it first, the existing name is preserved. The command refuses to run while `VIDEODRAFT_SESSION` is set, because that override would send later generations to a different session. Use `sessions create` plus `--session` only to continue or deliberately create a separate group.\\n"}');
   }
   const root = bundledSkillDir();
   const files = {};
@@ -7981,6 +8130,14 @@ function registerEditCommands(program) {
   edit.command("video <video_url_or_file> <prompt...>").description("Edit an existing video with a dedicated video-edit model").option(
     "--model <id>",
     "gemini-omni-1.1-flash (preferred, auto-selected for sources up to 10s) | grok-imagine-video-edit | kling-o3-video-ref-edit | happy-horse-video-edit"
+  ).option(
+    "--element <json|@file>",
+    "Kling O3 image-only element (repeatable)",
+    collect2,
+    []
+  ).option("--seed <n>", "Happy Horse Video Edit reproducibility seed").option(
+    "--safety-checker <true|false>",
+    "Happy Horse Video Edit provider safety checker"
   ).option("--ref <url|file>", "reference image (repeatable)", collect2, []).option(
     "--ref-video <url|file>",
     "deprecated: Gemini Omni 1.1 Flash edits accept exactly one input video, so a creative reference video cannot accompany the source",
@@ -8002,6 +8159,24 @@ function registerEditCommands(program) {
     const ctx = buildContext(this);
     const opts = this.opts();
     const model = validateEditModel(opts.model);
+    const rawElements = parseKlingElements(opts.element ?? []);
+    if (rawElements.length && (model !== "kling-o3-video-ref-edit" || rawElements.some((e) => e.video_url || e.voice_id)))
+      throw new UsageError(
+        "--element requires Kling O3 Video Ref/Edit and image-only elements without voice_id."
+      );
+    if (rawElements.length + (opts.ref?.length ?? 0) > 4 && model === "kling-o3-video-ref-edit")
+      throw new UsageError(
+        "Kling O3 accepts at most 4 combined elements and reference images."
+      );
+    const editSeed = opts.seed === void 0 ? void 0 : Number(opts.seed);
+    if (editSeed !== void 0 && (model !== "happy-horse-video-edit" || !Number.isSafeInteger(editSeed)))
+      throw new UsageError(
+        "--seed requires Happy Horse Video Edit and a safe integer."
+      );
+    if (opts.safetyChecker !== void 0 && (model !== "happy-horse-video-edit" || !["true", "false"].includes(opts.safetyChecker)))
+      throw new UsageError(
+        "--safety-checker requires Happy Horse Video Edit and true or false."
+      );
     const duration = positiveNumber2(opts.duration, "--duration");
     const sceneIndex = nonNegativeInteger(opts.scene, "--scene");
     const shotIndex = nonNegativeInteger(opts.shot, "--shot");
@@ -8082,10 +8257,11 @@ function registerEditCommands(program) {
         "--duration is estimate-only for video edits. Submitted edits follow the source and model duration."
       );
     }
-    const [[videoUrl], referenceImages, referenceVideos] = await Promise.all([
+    const [[videoUrl], referenceImages, referenceVideos, elements] = await Promise.all([
       resolveRefs(ctx, [videoSource]),
       resolveRefs(ctx, opts.ref ?? []),
-      resolveRefs(ctx, opts.refVideo ?? [])
+      resolveRefs(ctx, opts.refVideo ?? []),
+      resolveKlingElements(ctx, rawElements)
     ]);
     capture("cli_edit", {
       kind: "video",
@@ -8095,6 +8271,9 @@ function registerEditCommands(program) {
     const submitted = await ctx.client.callTool(
       "edit_video",
       compact({
+        ...elements.length ? { elements } : {},
+        seed: editSeed,
+        enable_safety_checker: opts.safetyChecker === void 0 ? void 0 : opts.safetyChecker === "true",
         model,
         prompt: promptWords.join(" ").trim(),
         video_url: videoUrl,