@docyrus/animaguru 0.17.0 → 0.18.0

package/README.md

@@ -221,16 +221,50 @@ animaguru assets generate PROJECT_ID --type video --model fal/minimax-h3-max \
 
 `--end-reference` can be used without `--reference`; the video then ends on that image. `--soundtrack` takes a music, speech or SFX asset's `file` SHA and replaces the generated sound; the video must be at least 2 seconds. Text-to-video takes `--aspect-ratio` 21:9, 16:9 (default), 4:3, 1:1, 3:4 or 9:16. Extensions take a video asset's SHA as `--source` (1.6–60 seconds, up to 50 MB), bill `--seconds` of new footage, offer 2K, and keep the source's shape unless `--aspect-ratio` crops it. `--extend-output continuation` returns only a 1.625-second overlap and the new footage. Extensions take up to three comma-separated `--audio-references` (2–15 seconds each, 15 seconds in total); refer to them in the prompt as Audio 1, Audio 2 and so on. `--prompt-expansion` is `disabled` (default), `balanced` or `quality`; for extensions, any value other than `disabled` turns expansion on. Each model's `videoProfiles` entry in `catalog` lists its workflows, resolutions and options. The server needs `AI_PROVIDER_KEY_FAL`.
 
+CLI 0.18.0 adds MiniMax H3 Max's eight other workflows (`fal/minimax-h3-max`, not Turbo):
+
+```sh
+# Keep Marie the same across scenes: reference images, a clip and audio, named in the prompt.
+animaguru assets generate PROJECT_ID --type video --model fal/minimax-h3-max \
+  --workflow reference-to-video --name "Marie at the market" \
+  --prompt "Image 1 is Marie. She walks through the market in Video 1's style, humming Audio 1" \
+  --references CHARACTER_SHEET_SHA,MARKET_SHA --reference-videos CLIP_SHA --audio-references SONG_SHA \
+  --seconds 6.5 --resolution 768p --dry-run
+# Make the face in an image say saved speech; the video lasts as long as the speech.
+animaguru assets generate PROJECT_ID --type video --model fal/minimax-h3-max \
+  --workflow lip-sync --name "Marie explains" --reference PORTRAIT_SHA --soundtrack SPEECH_SHA \
+  --transcribe --resolution 768p --dry-run
+# Orbit the camera half way around a still scene.
+animaguru assets generate PROJECT_ID --type video --model fal/minimax-h3-max \
+  --workflow camera-controls --name "Product reveal" --reference PRODUCT_SHA \
+  --camera "0,0,10,1;1,180,10,1.2" --seconds 6 --dry-run
+# Film in a preset look.
+animaguru assets generate PROJECT_ID --type video --model fal/minimax-h3-max \
+  --workflow style --style vhs --damage light --name "Home video" \
+  --prompt "A birthday party in a backyard, 1989" --aspect-ratio 4:3 --dry-run
+```
+
+- `reference-to-video` keeps the subjects or look of up to nine `--references` images, three `--reference-videos` (2–15 seconds each, 15 in total) and three `--audio-references`, twelve files in all. Name them in the prompt as Image 1, Video 1, Audio 1 and so on. It can also open on `--reference`, end on `--end-reference`, and pass `--middle-reference` at `--middle-seconds`; a middle image needs both of the others and 480p or 768p. `--aspect-ratio auto` (default) follows the inputs.
+- `lip-sync` makes the face in `--reference` (an image between 2:5 and 5:2) say `--soundtrack`, speech of 5 seconds to 15 minutes. It takes no prompt and goes up to 2K. `--transcribe` transcribes the speech to guide the mouth. Past 15 seconds it costs 1.2× per second.
+- `camera-controls` moves the camera around `--reference` along `--camera` keyframes `time,azimuth,elevation,distance`. `time` runs from 0 at the start to 1 at the end, and the angles are in degrees (elevation −90 to 90). Use 2–12 keyframes, separated by semicolons. Without a prompt the scene stays still and only the camera moves.
+- `insert-video` adds a new scene of `--seconds` (5–13) to `--source`, starting `--insert-at` seconds in and handing back to the source at `--resume-at`. The prompt, `--references` and `--reference-videos` guide the scene. It renders at 480p or 768p, and `--no-color-match` turns off matching the source's colors.
+- `recast` puts the people in `--references` (one photo each, up to four, left to right) in place of the people in `--source` (5–30 seconds), at 768p or 1080p. Pass `--subject-consent` only after each person in the photos agreed to appear. `--enhance-realism` blends them in more naturally.
+- `relight` relights `--source` (up to 15 seconds) from `--lighting`, an image of a sphere lit the way you want. It takes no prompt, keeps the source's shape unless `--aspect-ratio` crops it, and goes up to 2K.
+- `3d-to-video` turns `--source`, a 3D render up to 15 seconds long, into realistic footage. It follows up to eight `--references`, or draws its own (`--generated-references`, 1–8, default 2). It takes no seed and costs at least 5 seconds.
+- `style` films in a preset look: `vhs` (with `--damage light|medium|heavy`), `retro-toon-70s`, `low-poly`, `hand-drawn` or `16bit-pixel`. It renders at 768p for 5–15 whole seconds, from the prompt with `--aspect-ratio`, or from `--reference` as the first frame.
+
+H3 takes fractions of a second (`--seconds 6.5`). Lip-sync, recast, relight and 3d-to-video last as long as their speech or video, and `--seconds` doesn't apply to them. Reference images, clips and audio past fal's included allowance add to the cost; so do the references 3d-to-video draws. Their `--dry-run` asks the server, which measures the saved files. `--resolution` and `--mode` default to the first the workflow offers.
+
 Images have a full background by default; `--transparent` requests a cutout. CLI 0.17.0 adds `--references`, `--mask` and the 16:9 and 9:16 shapes. `--aspect-ratio` is 1:1 (default, 1024×1024), 3:2 (1536×1024), 2:3 (1024×1536), 16:9 (1536×864) or 9:16 (864×1536). `--references` takes up to four comma-separated blob SHAs of this project's images (including attached uploads) or sprite art, and the new image follows them: generate a character sheet once, then reference it in every scene to keep the character consistent. Refer to them in the prompt as Image 1, Image 2 and so on, and say what to take from each. Each reference adds a little to the estimate. `--mask` edits only part of Image 1, the first reference: give up to eight rectangles as `x,y,width,height` fractions of its size from the top left, separated by semicolons (`0,0,1,0.4` is the top 40%). The rest of the image is kept, and the result keeps Image 1's shape, which must be one of the five above. Gemini speech's `--prompt` is the verbatim transcript, and `--delivery` controls how it sounds without being spoken. Gemini speech supports both `gemini-3.8-flash-tts` and `gemini-3.8-flash-lite-tts`. Music uses Lyria. Google audio requires the server's `AI_PROVIDER_KEY_GOOGLE` secret; no provider keys are stored in the CLI.
 
-Preview a validated request and its estimated credits offline with `--dry-run`, without signing in or spending credits:
+Preview a validated request and its estimated credits with `--dry-run`, without spending credits; most dry runs work offline without signing in:
 
 ```sh
 animaguru assets generate PROJECT_ID --type music --name "Theme" \
   --prompt "A gentle instrumental theme" --dry-run
 ```
 
-Dry-run estimates use the CLI's bundled rates and do not check server configuration, remaining credits or reference ownership; the server performs those checks before actual generation. Omit `--dry-run` and pass `--yes` to submit. Actual provider usage determines the charge. Asset requests can also be supplied as JSON using the web API's shared schema:
+Dry-run estimates use the CLI's bundled rates and do not check server configuration, remaining credits or reference ownership; the server performs those checks before actual generation. The exceptions are H3 Max's lip-sync, recast, relight, 3d-to-video, reference-to-video and insert-video: their prices depend on the saved files' lengths and shapes, so their dry runs are signed-in server estimates. Omit `--dry-run` and pass `--yes` to submit. Actual provider usage determines the charge. Asset requests can also be supplied as JSON using the web API's shared schema:
 
 ```json
 {"type":"speech","name":"Welcome","prompt":"Welcome, traveler.","model":"gemini-3.8-flash-lite-tts","voice":"Kore","delivery":"Warm and welcoming"}

package/dist/animaguru.js

@@ -19761,7 +19761,7 @@ var require_ignore2 = __commonJS({
 // cli/package.json
 var package_default = {
   name: "@docyrus/animaguru",
-  version: "0.17.0",
+  version: "0.18.0",
   description: "Agent-friendly AnimaGuru CLI built with CrustJS",
   type: "module",
   bin: {
@@ -25339,7 +25339,12 @@ var SPRITE_IMAGE_MODEL_IDS = SPRITE_IMAGE_MODELS.map((m) => m.id);
 function spriteImageModel(id2) {
   return SPRITE_IMAGE_MODELS.find((m) => m.id === id2) ?? SPRITE_IMAGE_MODELS[0];
 }
-var VIDEO_WORKFLOWS = ["image-to-video", "text-to-video", "extend-video"];
+var VIDEO_WORKFLOWS = ["image-to-video", "text-to-video", "extend-video", "reference-to-video", "lip-sync", "camera-controls", "insert-video", "recast", "relight", "3d-to-video", "style"];
+var STUDIO_VIDEO_WORKFLOWS = ["image-to-video", "text-to-video", "extend-video"];
+var MEDIA_LENGTH_WORKFLOWS = ["lip-sync", "recast", "relight", "3d-to-video"];
+var lengthFromMedia = (workflow) => MEDIA_LENGTH_WORKFLOWS.includes(workflow);
+var VIDEO_STYLES = ["vhs", "retro-toon-70s", "low-poly", "hand-drawn", "16bit-pixel"];
+var VHS_DAMAGE_LEVELS = ["light", "medium", "heavy"];
 var VIDEO_RESOLUTIONS = ["480p", "768p", "1080p", "2k"];
 var VIDEO_ASPECT_RATIOS = ["21:9", "16:9", "4:3", "1:1", "3:4", "9:16"];
 var PROMPT_EXPANSION_MODES = ["disabled", "balanced", "quality"];
@@ -25347,6 +25352,15 @@ var EXTEND_OUTPUTS = ["extended", "continuation"];
 var SOUNDTRACK_MAX_BYTES = 15 * 1024 * 1024;
 var EXTEND_SOURCE_MAX_BYTES = 50 * 1024 * 1024;
 var MAX_AUDIO_REFERENCES = 3;
+var MAX_VIDEO_REFERENCE_IMAGES = 9;
+var MAX_REFERENCE_VIDEOS = 3;
+var MAX_REFERENCE_FILES = 12;
+var MAX_RECAST_PEOPLE = 4;
+var MAX_3D_REFERENCES = 8;
+var MAX_CAMERA_KEYFRAMES = 12;
+var MAX_CAMERA_TURNS = 32;
+var H3_MAX = "minimax/h3-max";
+var h3Endpoints = (route) => ({ "image-to-video": `${route}/image-to-video`, "text-to-video": `${route}/text-to-video`, "extend-video": `${route}/extend-video` });
 var SPRITE_VIDEO_MODELS = [
   {
     id: "pruna/p-video-2-pro",
@@ -25375,9 +25389,27 @@ var SPRITE_VIDEO_MODELS = [
     label: "MiniMax H3 Max (fal.ai)",
     provider: "fal",
     workflows: VIDEO_WORKFLOWS,
-    endpoints: { "image-to-video": "minimax/h3-max/image-to-video", "text-to-video": "minimax/h3-max/text-to-video", "extend-video": "minimax/h3-max/extend-video" },
+    endpoints: {
+      ...h3Endpoints(H3_MAX),
+      "reference-to-video": `${H3_MAX}/reference-to-video`,
+      "lip-sync": `${H3_MAX}/lip-sync/image-to-video`,
+      "camera-controls": `${H3_MAX}/camera-controls`,
+      "insert-video": `${H3_MAX}/insert-video`,
+      recast: `${H3_MAX}/recast`,
+      relight: `${H3_MAX}/relight`,
+      "3d-to-video": `${H3_MAX}/3d-to-video`,
+      style: `${H3_MAX}/styles`
+    },
     resolutions: ["480p", "768p", "1080p"],
-    extendResolutions: VIDEO_RESOLUTIONS,
+    workflowOptions: {
+      "extend-video": { resolutions: VIDEO_RESOLUTIONS },
+      "lip-sync": { resolutions: VIDEO_RESOLUTIONS, seconds: { min: 5, max: 900, fractional: true } },
+      "insert-video": { resolutions: ["480p", "768p"], seconds: { min: 5, max: 13, fractional: true }, creditsPerSecond: { "480p": 5, "768p": 6 } },
+      recast: { resolutions: ["768p", "1080p"], seconds: { min: 5, max: 30, fractional: true }, creditsPerSecond: { "768p": 30, "1080p": 45 } },
+      relight: { resolutions: VIDEO_RESOLUTIONS, seconds: { min: 2.33, max: 15, fractional: true } },
+      "3d-to-video": { seconds: { min: 1, max: 15, fractional: true } },
+      style: { resolutions: ["768p"], seconds: { min: 5, max: 15 } }
+    },
     modes: ["quality"],
     lastFrame: true,
     endFrameOnly: true,
@@ -25385,16 +25417,16 @@ var SPRITE_VIDEO_MODELS = [
     promptExpansion: PROMPT_EXPANSION_MODES,
     audio: true,
     estimatedCreditsPerSecond: { "480p": { quality: 5 }, "768p": { quality: 8 }, "1080p": { quality: 16 }, "2k": { quality: 32 } },
-    seconds: { min: 1, max: 15 }
+    seconds: { min: 1, max: 15, fractional: true }
   },
   {
     id: "fal/minimax-h3-max-turbo",
     label: "MiniMax H3 Max Turbo (fal.ai)",
     provider: "fal",
-    workflows: VIDEO_WORKFLOWS,
-    endpoints: { "image-to-video": "minimax/h3-max-turbo/image-to-video", "text-to-video": "minimax/h3-max-turbo/text-to-video", "extend-video": "minimax/h3-max-turbo/extend-video" },
+    workflows: STUDIO_VIDEO_WORKFLOWS,
+    endpoints: h3Endpoints("minimax/h3-max-turbo"),
     resolutions: ["480p", "768p", "1080p"],
-    extendResolutions: VIDEO_RESOLUTIONS,
+    workflowOptions: { "extend-video": { resolutions: VIDEO_RESOLUTIONS } },
     modes: ["speed"],
     lastFrame: true,
     endFrameOnly: true,
@@ -25402,7 +25434,7 @@ var SPRITE_VIDEO_MODELS = [
     promptExpansion: PROMPT_EXPANSION_MODES,
     audio: true,
     estimatedCreditsPerSecond: { "480p": { speed: 2.5 }, "768p": { speed: 4 }, "1080p": { speed: 8 }, "2k": { speed: 16 } },
-    seconds: { min: 1, max: 15 }
+    seconds: { min: 1, max: 15, fractional: true }
   }
 ];
 var SPRITE_VIDEO_MODEL_IDS = SPRITE_VIDEO_MODELS.map((m) => m.id);
@@ -25411,12 +25443,31 @@ function spriteVideoModel(id2) {
   return SPRITE_VIDEO_MODELS.find((m) => m.id === id2) ?? SPRITE_VIDEO_MODELS[0];
 }
 function videoResolutions(model, workflow = "image-to-video") {
-  return workflow === "extend-video" ? model.extendResolutions ?? model.resolutions : model.resolutions;
-}
-function spriteVideoEstimate(model, p) {
+  return model.workflowOptions?.[workflow]?.resolutions ?? model.resolutions;
+}
+function videoSeconds(model, workflow = "image-to-video") {
+  return model.workflowOptions?.[workflow]?.seconds ?? model.seconds;
+}
+var INCLUDED_REFERENCE_TOKENS = 4096;
+var imageReferenceTokens = (size) => size && size[0] > 0 && size[1] > 0 ? 32 * Math.ceil(32 * Math.max(...size) / Math.min(...size)) : 1824;
+var clipReferenceTokens = (seconds2, resolution) => Math.ceil(Math.max(0, seconds2) * (resolution === "480p" ? 2700 : 6900));
+var audioReferenceTokens = (seconds2) => Math.ceil(Math.max(0, seconds2) * 80);
+var DEFAULT_GENERATED_REFERENCES = 2;
+function billedVideoSeconds(model, workflow, seconds2) {
+  const s = videoSeconds(model, workflow).fractional ? seconds2 : Math.round(seconds2);
+  if (workflow === "3d-to-video") return Math.max(5, s);
+  return workflow === "lip-sync" && s > 15 ? s * 1.2 : s;
+}
+function videoCreditsPerSecond(model, p) {
+  const override = model.workflowOptions?.[p.workflow ?? "image-to-video"]?.creditsPerSecond?.[p.resolution];
+  if (override !== void 0) return override;
   const byMode = model.estimatedCreditsPerSecond[p.resolution] ?? model.estimatedCreditsPerSecond[model.resolutions[0]];
-  const perSecond = byMode[p.mode] ?? byMode[model.modes[0]] ?? 0;
-  return Math.max(1, Math.ceil(perSecond * Math.round(p.seconds) * UNITS_PER_CREDIT));
+  return byMode[p.mode] ?? byMode[model.modes[0]] ?? 0;
+}
+function spriteVideoEstimate(model, p, extras2 = {}) {
+  const seconds2 = billedVideoSeconds(model, p.workflow ?? "image-to-video", p.seconds);
+  const beyond = Math.max(0, (extras2.referenceTokens ?? 0) - INCLUDED_REFERENCE_TOKENS) * 2e-3 + (extras2.generatedReferences ?? 0) * 3;
+  return Math.max(1, Math.ceil((videoCreditsPerSecond(model, p) * seconds2 + beyond) * UNITS_PER_CREDIT));
 }
 
 // node_modules/zod/v4/classic/external.js
@@ -46347,55 +46398,214 @@ var MUSIC_MODELS = [{ id: "lyria-3.5", label: "Lyria 3.5" }];
 var SPEECH_VOICES = ["Kore", "Puck", "Charon", "Fenrir", "Aoede", "Leda", "Orus", "Zephyr"];
 var base = { name: external_exports.string().trim().min(1).max(80), prompt: external_exports.string().trim().min(3).max(4e3) };
 var blob = external_exports.string().regex(/^[a-f0-9]{64}$/);
+var cameraKeyframe = external_exports.object({
+  /** When, from 0 at the start of the clip to 1 at its end. */
+  time: external_exports.number().min(0).max(1),
+  /** Degrees around the subject; signed full turns are kept. */
+  azimuth: external_exports.number().min(-360 * MAX_CAMERA_TURNS).max(360 * MAX_CAMERA_TURNS),
+  /** Degrees above (positive) or below the subject. */
+  elevation: external_exports.number().min(-90).max(90),
+  /** Distance from the subject in scene units. */
+  distance: external_exports.number().gt(0).max(100)
+});
 var videoAsset = external_exports.object({
-  ...base,
+  name: base.name,
+  /** Lip-sync and relight take no prompt, and camera-controls, insert-video, recast and 3d-to-video may leave it out. */
+  prompt: external_exports.string().trim().max(4e3).default(""),
   type: external_exports.literal("video"),
   model: external_exports.enum(SPRITE_VIDEO_MODEL_IDS).default(DEFAULT_SPRITE_VIDEO_MODEL),
   workflow: external_exports.enum(VIDEO_WORKFLOWS).default("image-to-video"),
-  /** First frame. */
+  /** First frame; for lip-sync the face that speaks. */
   reference: blob.optional(),
   /** Last frame. */
   endReference: blob.optional(),
-  /** The saved clip to extend. */
+  /** A frame reference-to-video reaches at middleSeconds, between its first and last frames. */
+  middleReference: blob.optional(),
+  middleSeconds: external_exports.number().gt(0).lt(15).optional(),
+  /** The saved clip to extend, insert a scene into, recast, relight, or turn from a 3D render into footage. */
   source: blob.optional(),
-  /** Saved audio pinned as the soundtrack (at least two seconds of video). */
+  /** Saved audio pinned as the soundtrack (at least two seconds of video), or the speech a lip-sync follows. */
   soundtrack: blob.optional(),
-  /** Saved audio guiding an extension's new sound; name each clip's role in the prompt. */
+  /** Saved audio guiding an extension's new sound or a reference-to-video clip; name each clip's role in the prompt. */
   audioReferences: external_exports.array(blob).max(MAX_AUDIO_REFERENCES).default([]),
-  seconds: external_exports.number().int().min(1).max(15).default(5),
-  resolution: external_exports.enum(VIDEO_RESOLUTIONS).default("480p"),
-  mode: external_exports.enum(["cost", "speed", "quality"]).default("cost"),
-  /** A clip written from text (default 16:9), or an extension cropped to a new canvas ("auto" keeps the source's). */
+  /** Images whose subjects or look the clip keeps, named Image 1, Image 2… in the prompt; for recast, one photo per new person. */
+  references: external_exports.array(blob).max(MAX_VIDEO_REFERENCE_IMAGES).optional(),
+  /** Saved clips guiding motion, named Video 1, Video 2… in the prompt. */
+  referenceVideos: external_exports.array(blob).max(MAX_REFERENCE_VIDEOS).optional(),
+  /** The camera's path around the reference image: 2–12 keyframes. */
+  camera: external_exports.array(cameraKeyframe).min(2).max(MAX_CAMERA_KEYFRAMES).optional(),
+  /** Seconds into the source where the inserted scene starts, and where the source resumes after it. */
+  insertAt: external_exports.number().min(1.625).max(60).optional(),
+  resumeAt: external_exports.number().gt(1.625).max(60).optional(),
+  /** Match the inserted scene's colors to the source (fal's default). */
+  colorMatch: external_exports.boolean().optional(),
+  /** Transcribe the speech to guide a lip-sync. */
+  transcribe: external_exports.boolean().optional(),
+  /** Recast: more natural skin and blending of the new people. */
+  enhanceRealism: external_exports.boolean().optional(),
+  /** Recast: the user confirmed that each person in the photos agreed to appear in the video. */
+  subjectConsent: external_exports.literal(true).optional(),
+  /** Relight: a sphere render showing the light to apply. */
+  lighting: blob.optional(),
+  /** 3d-to-video without reference images: how many it may draw itself (default 2). */
+  generatedReferences: external_exports.number().int().min(1).max(8).optional(),
+  style: external_exports.enum(VIDEO_STYLES).optional(),
+  /** VHS tape wear. */
+  damage: external_exports.enum(VHS_DAMAGE_LEVELS).optional(),
+  /** Defaults to 5, within the workflow's range; lip-sync, recast, relight and 3d-to-video take their input's length. */
+  seconds: external_exports.number().min(0.5).max(900).optional(),
+  /** Defaults to the workflow's first resolution. */
+  resolution: external_exports.enum(VIDEO_RESOLUTIONS).optional(),
+  /** Defaults to the model's first mode. */
+  mode: external_exports.enum(["cost", "speed", "quality"]).optional(),
+  /** A clip written from text (default 16:9), or one cropped to a new canvas ("auto" keeps its inputs' shape). */
   aspectRatio: external_exports.enum(["auto", ...VIDEO_ASPECT_RATIOS]).optional(),
   promptExpansion: external_exports.enum(PROMPT_EXPANSION_MODES).default("disabled"),
   seed: external_exports.number().int().min(0).max(2 ** 32 - 1).optional(),
   /** An extension returns the whole clip, or only the new footage after a short overlap. */
   extendOutput: external_exports.enum(EXTEND_OUTPUTS).default("extended")
-}).superRefine((p, ctx) => {
+});
+var ALL = VIDEO_WORKFLOWS;
+var TAKES = {
+  reference: ["image-to-video", "reference-to-video", "lip-sync", "camera-controls", "style"],
+  endReference: ["image-to-video", "reference-to-video"],
+  middleReference: ["reference-to-video"],
+  middleSeconds: ["reference-to-video"],
+  source: ["extend-video", "insert-video", "recast", "relight", "3d-to-video"],
+  soundtrack: ["image-to-video", "text-to-video", "lip-sync"],
+  audioReferences: ["extend-video", "reference-to-video"],
+  references: ["reference-to-video", "insert-video", "recast", "3d-to-video"],
+  referenceVideos: ["reference-to-video", "insert-video"],
+  camera: ["camera-controls"],
+  insertAt: ["insert-video"],
+  resumeAt: ["insert-video"],
+  colorMatch: ["insert-video"],
+  transcribe: ["lip-sync"],
+  enhanceRealism: ["recast"],
+  subjectConsent: ["recast"],
+  lighting: ["relight"],
+  generatedReferences: ["3d-to-video"],
+  style: ["style"],
+  damage: ["style"],
+  aspectRatio: ["text-to-video", "extend-video", "reference-to-video", "relight", "style"],
+  promptExpansion: ["image-to-video", "text-to-video", "extend-video", "reference-to-video", "camera-controls", "insert-video"],
+  seed: ALL.filter((w) => w !== "3d-to-video"),
+  extendOutput: ["extend-video"]
+};
+var NEEDS = {
+  "lip-sync": ["reference", "soundtrack"],
+  "camera-controls": ["reference", "camera"],
+  "insert-video": ["source", "insertAt", "resumeAt"],
+  recast: ["source", "references", "subjectConsent"],
+  relight: ["source", "lighting"],
+  "3d-to-video": ["source"],
+  style: ["style"]
+};
+var LABELS = {
+  reference: "a starting image",
+  endReference: "an ending image",
+  middleReference: "a middle image",
+  middleSeconds: "middleSeconds",
+  source: "a saved video",
+  soundtrack: "a soundtrack",
+  audioReferences: "audio references",
+  references: "reference images",
+  referenceVideos: "reference videos",
+  camera: "camera keyframes",
+  insertAt: "insertAt",
+  resumeAt: "resumeAt",
+  colorMatch: "colorMatch",
+  transcribe: "transcribe",
+  enhanceRealism: "enhanceRealism",
+  lighting: "a lighting image",
+  subjectConsent: "subjectConsent: true, confirming that each person in the photos agreed to appear in the video",
+  generatedReferences: "generatedReferences",
+  style: "a style",
+  damage: "damage",
+  aspectRatio: "an aspect ratio",
+  promptExpansion: "prompt rewriting",
+  seed: "a seed",
+  extendOutput: "extendOutput"
+};
+var STUDIO_MESSAGES = {
+  reference: "Only image-to-video starts from an image.",
+  endReference: "Only image-to-video ends on an image.",
+  source: "Only an extension starts from a saved video.",
+  audioReferences: "Only an extension takes audio references.",
+  extendOutput: "Only an extension can return the new footage alone."
+};
+var PROMPT = { "camera-controls": "optional", "insert-video": "optional", recast: "optional", "3d-to-video": "optional", "lip-sync": "none", relight: "none" };
+var given = (value) => value !== void 0 && !(Array.isArray(value) && !value.length);
+function videoChecks(p, ctx) {
   const model = spriteVideoModel(p.model);
   const issue2 = (path, message) => ctx.addIssue({ code: "custom", message, path: [path] });
   if (!model.workflows.includes(p.workflow)) return issue2("workflow", "Choose a way of making video supported by the video model.");
-  const extend2 = p.workflow === "extend-video";
-  if (p.seconds < model.seconds.min || p.seconds > model.seconds.max) issue2("seconds", "Choose a duration supported by the video model.");
-  if (!videoResolutions(model, p.workflow).includes(p.resolution)) issue2("resolution", "Choose a resolution supported by the video model.");
-  if (!model.modes.includes(p.mode)) issue2("mode", "Choose a mode supported by the video model.");
-  if (p.workflow === "image-to-video") {
+  const w = p.workflow;
+  const extend2 = w === "extend-video";
+  const range = videoSeconds(model, w);
+  const seconds2 = p.seconds ?? defaultSeconds(model, w);
+  const resolution = p.resolution ?? videoResolutions(model, w)[0];
+  const prompt = PROMPT[w];
+  if (prompt === "none" && p.prompt) issue2("prompt", `${w} takes no prompt; leave it out.`);
+  if (!prompt && p.prompt.length < 3) issue2("prompt", "Describe the video in at least 3 characters.");
+  if ((w === "recast" || w === "3d-to-video") && p.prompt.length > 2e3) issue2("prompt", `${w} takes a prompt of at most 2,000 characters.`);
+  if (!lengthFromMedia(w) && (seconds2 < range.min || seconds2 > range.max || !range.fractional && !Number.isInteger(seconds2))) issue2("seconds", "Choose a duration supported by the video model.");
+  if (!videoResolutions(model, w).includes(resolution)) issue2("resolution", "Choose a resolution supported by the video model.");
+  if (p.mode && !model.modes.includes(p.mode)) issue2("mode", "Choose a mode supported by the video model.");
+  for (const [field, workflows] of Object.entries(TAKES)) {
+    if (!given(p[field]) || workflows.includes(w)) continue;
+    if (field === "promptExpansion" && p.promptExpansion === "disabled" || field === "extendOutput" && p.extendOutput === "extended") continue;
+    const studio = w === "image-to-video" || w === "text-to-video" || extend2;
+    if (field === "aspectRatio" && w === "image-to-video") issue2(field, "A video made from an image keeps the image's shape.");
+    else if (field === "soundtrack" && extend2) issue2(field, "An extension keeps its source's soundtrack; add audio references instead.");
+    else if (studio && STUDIO_MESSAGES[field]) issue2(field, STUDIO_MESSAGES[field]);
+    else issue2(field, `${w} doesn't take ${LABELS[field] ?? field}.`);
+  }
+  for (const field of NEEDS[w] ?? []) if (!given(p[field])) issue2(field, `${w} needs ${LABELS[field] ?? field}.`);
+  if (w === "image-to-video") {
     if (!p.reference && !(p.endReference && model.endFrameOnly)) issue2("reference", "Choose a starting image.");
     if (p.endReference && !model.lastFrame) issue2("endReference", "This video model can't end on a chosen image.");
-  } else {
-    if (p.reference) issue2("reference", "Only image-to-video starts from an image.");
-    if (p.endReference) issue2("endReference", "Only image-to-video ends on an image.");
-  }
-  if (extend2 !== Boolean(p.source)) issue2("source", extend2 ? "Choose a saved video to extend." : "Only an extension starts from a saved video.");
-  if (p.aspectRatio && p.workflow === "image-to-video") issue2("aspectRatio", "A video made from an image keeps the image's shape.");
-  if (p.aspectRatio === "auto" && p.workflow === "text-to-video") issue2("aspectRatio", "Choose an aspect ratio for a video written from text.");
-  if (p.soundtrack && (!model.audio || extend2)) issue2("soundtrack", extend2 ? "An extension keeps its source's soundtrack; add audio references instead." : "This video model can't use a soundtrack.");
-  if (p.soundtrack && p.seconds < 2) issue2("seconds", "A video with a soundtrack must be at least 2 seconds long.");
-  if (p.audioReferences.length && (!model.audio || !extend2)) issue2("audioReferences", "Only an extension takes audio references.");
+  }
+  if (extend2 && !p.source) issue2("source", "Choose a saved video to extend.");
+  if (p.aspectRatio === "auto" && (w === "text-to-video" || w === "style")) issue2("aspectRatio", "Choose an aspect ratio for a video written from text.");
+  if (w === "style" && p.aspectRatio && p.reference) issue2("aspectRatio", "A styled video made from an image keeps the image's shape.");
+  if (p.damage && p.style !== "vhs") issue2("damage", "Only the VHS style takes tape damage.");
+  if (p.soundtrack && !model.audio) issue2("soundtrack", "This video model can't use a soundtrack.");
+  if (p.soundtrack && w !== "lip-sync" && seconds2 < 2) issue2("seconds", "A video with a soundtrack must be at least 2 seconds long.");
+  if (p.audioReferences.length && !model.audio) issue2("audioReferences", "Only an extension takes audio references.");
   if (p.promptExpansion !== "disabled" && !model.promptExpansion?.includes(p.promptExpansion)) issue2("promptExpansion", "This video model doesn't rewrite prompts.");
   if (p.seed !== void 0 && !model.seed) issue2("seed", "This video model doesn't take a seed.");
-  if (p.extendOutput !== "extended" && !extend2) issue2("extendOutput", "Only an extension can return the new footage alone.");
-});
+  if (p.seed !== void 0 && p.seed >= 2 ** 31 && (w === "lip-sync" || w === "insert-video")) issue2("seed", `${w} takes a seed below 2,147,483,648.`);
+  const references = p.references ?? [];
+  const unique = (shas2) => new Set(shas2).size === shas2.length;
+  if (!unique(references) || !unique(p.referenceVideos ?? []) || !unique(p.audioReferences)) issue2("references", "Choose each reference once.");
+  if (w === "reference-to-video") {
+    if (references.length + (p.referenceVideos?.length ?? 0) + p.audioReferences.length > MAX_REFERENCE_FILES) issue2("references", `reference-to-video takes at most ${MAX_REFERENCE_FILES} reference files in all.`);
+    if (!references.length && !p.referenceVideos?.length && !p.audioReferences.length && !p.reference && !p.endReference) issue2("references", "reference-to-video needs reference images, videos or audio, or a first or last frame.");
+    if (Boolean(p.middleReference) !== (p.middleSeconds !== void 0)) issue2("middleSeconds", "A middle image needs middleSeconds, and middleSeconds a middle image.");
+    if (p.middleReference && (!p.reference || !p.endReference)) issue2("middleReference", "A middle image needs the starting and ending images too.");
+    if (p.middleReference && !["480p", "768p"].includes(resolution)) issue2("middleReference", "A middle image needs 480p or 768p.");
+    if (p.middleSeconds !== void 0 && p.middleSeconds >= seconds2) issue2("middleSeconds", "Put the middle image before the end of the clip.");
+  }
+  if (w === "recast" && references.length > MAX_RECAST_PEOPLE) issue2("references", `recast takes at most ${MAX_RECAST_PEOPLE} photos, one per person.`);
+  if (w === "3d-to-video" && references.length > MAX_3D_REFERENCES) issue2("references", `3d-to-video takes at most ${MAX_3D_REFERENCES} reference images.`);
+  if (w === "3d-to-video" && references.length && p.generatedReferences !== void 0) issue2("generatedReferences", "3d-to-video only draws its own references when you give none.");
+  if (w === "insert-video" && p.insertAt !== void 0 && p.resumeAt !== void 0 && p.resumeAt < p.insertAt) issue2("resumeAt", "Resume the source at or after the point where the new scene starts.");
+  if (p.camera) {
+    const times = p.camera.map((k) => k.time);
+    if (times.some((t, i2) => i2 && t <= times[i2 - 1])) issue2("camera", "Order the camera keyframes by time, each later than the one before.");
+    const travel = p.camera.slice(1).reduce((sum, k, i2) => sum + Math.abs(k.azimuth - p.camera[i2].azimuth), 0);
+    if (travel > 360 * MAX_CAMERA_TURNS) issue2("camera", `The camera may travel at most ${MAX_CAMERA_TURNS} full turns around the subject.`);
+  }
+}
+var defaultSeconds = (model, workflow) => {
+  const r = videoSeconds(model, workflow);
+  return Math.min(r.max, Math.max(r.min, 5));
+};
+var videoDefaults = (p) => {
+  const model = spriteVideoModel(p.model);
+  return { ...p, seconds: p.seconds ?? defaultSeconds(model, p.workflow), resolution: p.resolution ?? videoResolutions(model, p.workflow)[0], mode: p.mode ?? model.modes[0] };
+};
 var IMAGE_ASPECT_RATIOS = ["1:1", "3:2", "2:3", "16:9", "9:16"];
 var MAX_IMAGE_REFERENCES = 4;
 var MAX_MASK_REGIONS = 8;
@@ -46416,7 +46626,7 @@ var imageChecks = (p, ctx) => {
 };
 var assetRequest = external_exports.discriminatedUnion("type", [
   imageAsset.superRefine(imageChecks),
-  videoAsset,
+  videoAsset.superRefine(videoChecks).transform(videoDefaults),
   external_exports.object({ ...base, type: external_exports.literal("music"), model: external_exports.literal("lyria-3.5").default("lyria-3.5") }),
   external_exports.object({ ...base, type: external_exports.literal("speech"), model: external_exports.enum(["gemini-3.8-flash-tts", "gemini-3.8-flash-lite-tts", ...ELEVENLABS_SPEECH_MODEL_IDS]).default("gemini-3.8-flash-lite-tts"), voice: external_exports.string().trim().max(80).default(""), delivery: external_exports.string().trim().max(600).default("") }).superRefine((p, ctx) => {
     if (p.voice && (isElevenLabsSpeech(p.model) ? !/^[a-zA-Z0-9]{20}$/.test(p.voice) : !SPEECH_VOICES.includes(p.voice))) ctx.addIssue({ code: "custom", message: "Choose a voice supported by the speech provider.", path: ["voice"] });
@@ -46432,9 +46642,18 @@ var uploadedMedia = external_exports.object({ name: base.name, prompt: external_
 var savedAssetOptions = external_exports.union([assetRequest, libraryAudio, uploadedMedia]);
 var speechCharacters = (text2) => Array.from(text2).length;
 var imageEstimate = (p) => Math.ceil((130 + 40 * p.references.length) * spriteImageModel(p.model).relCost);
+function videoExtras(p, facts = {}) {
+  const w = p.workflow;
+  if (w !== "reference-to-video" && w !== "insert-video" && w !== "3d-to-video") return {};
+  const images = (p.references ?? []).reduce((sum, sha2) => sum + imageReferenceTokens(facts.size?.(sha2)), 0);
+  if (w === "3d-to-video") return { referenceTokens: images + clipReferenceTokens(p.seconds, p.resolution), generatedReferences: p.references?.length ? 0 : p.generatedReferences ?? DEFAULT_GENERATED_REFERENCES };
+  const clips = Math.min(15, (p.referenceVideos ?? []).reduce((sum, sha2) => sum + Math.min(p.seconds, facts.seconds?.(sha2) ?? p.seconds), 0));
+  const audio = Math.min(15, p.audioReferences.reduce((sum, sha2) => sum + (facts.seconds?.(sha2) ?? 15), 0));
+  return { referenceTokens: images + clipReferenceTokens(clips, p.resolution) + (w === "reference-to-video" ? audioReferenceTokens(audio) : 0) };
+}
 function assetEstimate(p, now = Date.now()) {
   if (p.type === "image") return imageEstimate(p);
-  if (p.type === "video") return spriteVideoEstimate(spriteVideoModel(p.model), p);
+  if (p.type === "video") return spriteVideoEstimate(spriteVideoModel(p.model), p, videoExtras(p));
   if (p.type === "music") return 80;
   const units = (credits) => Math.max(1, Math.ceil(credits * UNITS_PER_CREDIT));
   if (p.type === "sfx") return units(Math.max(0, p.seconds) * 0.2);
@@ -47608,7 +47827,42 @@ async function changeVideoSubtitles(client, id2, options) {
 import { mkdir as mkdir8, readFile as readFile9, stat as stat4, writeFile as writeFile8 } from "node:fs/promises";
 import { dirname as dirname7, join as join10, resolve as resolve10 } from "node:path";
 import { setTimeout as delay3 } from "node:timers/promises";
-var extras = { image: ["aspect-ratio", "transparent", "references", "mask"], video: ["workflow", "reference", "end-reference", "source", "soundtrack", "audio-references", "seconds", "resolution", "mode", "aspect-ratio", "prompt-expansion", "seed", "extend-output"], music: [], speech: ["voice", "delivery"], sfx: ["seconds", "loop", "prompt-influence"] };
+var extras = {
+  image: ["aspect-ratio", "transparent", "references", "mask"],
+  video: [
+    "workflow",
+    "reference",
+    "end-reference",
+    "source",
+    "soundtrack",
+    "audio-references",
+    "seconds",
+    "resolution",
+    "mode",
+    "aspect-ratio",
+    "prompt-expansion",
+    "seed",
+    "extend-output",
+    "references",
+    "reference-videos",
+    "middle-reference",
+    "middle-seconds",
+    "camera",
+    "insert-at",
+    "resume-at",
+    "color-match",
+    "transcribe",
+    "enhance-realism",
+    "subject-consent",
+    "lighting",
+    "generated-references",
+    "style",
+    "damage"
+  ],
+  music: [],
+  speech: ["voice", "delivery"],
+  sfx: ["seconds", "loop", "prompt-influence"]
+};
 var list2 = (items) => items.length < 2 ? items.join("") : `${items.slice(0, -1).join(", ")} and ${items.at(-1)}`;
 function accepted(type) {
   if (type === "music") return "Music accepts only --name, --prompt and --model; the model chooses the length, so fit it during the edit.";
@@ -47628,17 +47882,21 @@ var regions = (value) => value?.split(";").filter((region) => region.trim()).map
   if (rest.length || [x2, y, width, height].some((n) => !Number.isFinite(n))) throw new Error(`--mask regions are x,y,width,height in fractions of Image 1, separated by semicolons; "${region.trim()}" is not.`);
   return { x: x2, y, width, height };
 });
+var keyframes = (value) => value?.split(";").filter((frame) => frame.trim()).map((frame) => {
+  const [time3, azimuth, elevation, distance, ...rest] = frame.split(",").map((n) => n.trim() ? Number(n) : NaN);
+  if (rest.length || [time3, azimuth, elevation, distance].some((n) => !Number.isFinite(n))) throw new Error(`--camera keyframes are time,azimuth,elevation,distance (time 0\u20131, angles in degrees), separated by semicolons; "${frame.trim()}" is not.`);
+  return { time: time3, azimuth, elevation, distance };
+});
 function assetFromFlags(flags) {
   if (flags.type === "image" && flags.model) throw new Error("Image models are managed by staff. Omit --model.");
   for (const name2 of Object.values(extras).flat()) {
     const value = flags[name2];
     if (value !== void 0 && value !== false && !extras[flags.type]?.includes(name2)) throw new Error(`--${name2} is not an option for ${flags.type} assets. ${accepted(flags.type)}`.trim());
   }
+  if (flags.type !== "video" && flags.prompt === void 0) throw new Error(`--prompt is required for ${flags.type} assets.`);
   const base2 = { type: flags.type, name: flags.name, prompt: flags.prompt, model: flags.model };
   if (flags.type === "image") return parseAsset({ ...base2, aspectRatio: flags["aspect-ratio"], transparent: flags.transparent, references: shas(flags.references), mask: regions(flags.mask) });
   if (flags.type === "video") {
-    const model = spriteVideoModel(flags.model);
-    const workflow = flags.workflow ?? "image-to-video";
     return parseAsset({
       ...base2,
       workflow: flags.workflow,
@@ -47647,9 +47905,24 @@ function assetFromFlags(flags) {
       source: flags.source,
       soundtrack: flags.soundtrack,
       audioReferences: shas(flags["audio-references"]),
-      seconds: flags.seconds ?? Math.max(5, model.seconds.min),
-      resolution: flags.resolution ?? videoResolutions(model, workflow)[0],
-      mode: flags.mode ?? model.modes[0],
+      references: shas(flags.references),
+      referenceVideos: shas(flags["reference-videos"]),
+      middleReference: flags["middle-reference"],
+      middleSeconds: flags["middle-seconds"],
+      camera: keyframes(flags.camera),
+      insertAt: flags["insert-at"],
+      resumeAt: flags["resume-at"],
+      colorMatch: flags["color-match"],
+      transcribe: flags.transcribe,
+      enhanceRealism: flags["enhance-realism"],
+      subjectConsent: flags["subject-consent"] || void 0,
+      lighting: flags.lighting,
+      generatedReferences: flags["generated-references"],
+      style: flags.style,
+      damage: flags.damage,
+      seconds: flags.seconds,
+      resolution: flags.resolution,
+      mode: flags.mode,
       aspectRatio: flags["aspect-ratio"],
       promptExpansion: flags["prompt-expansion"],
       seed: flags.seed,
@@ -47703,8 +47976,13 @@ async function assetsFromBatchFile(file2, model) {
 ${errors.join("\n")}`);
   return requests;
 }
+var measured = (body) => body.type === "video" && (lengthFromMedia(body.workflow) || ["reference-to-video", "insert-video", "3d-to-video"].includes(body.workflow));
+async function estimateAsset(client, project, body) {
+  if (measured(body)) return client.request(`${assetsPath(project)}/estimate`, { method: "POST", body });
+  return { dryRun: true, request: body, estimatedCredits: toCredits(assetEstimate(body)) };
+}
 async function submitAsset(client, project, body, options) {
-  if (options["dry-run"]) return { dryRun: true, request: body, estimatedCredits: toCredits(assetEstimate(body)) };
+  if (options["dry-run"]) return estimateAsset(client, project, body);
   if (!options.yes) throw new Error("Pass --yes to authorize spending credits, or --dry-run to validate and estimate without generation.");
   return client.request(`/api/v1/sprites/${encodeURIComponent(project)}/assets`, { method: "POST", body });
 }
@@ -47800,8 +48078,12 @@ async function generateAsset(client, project, body, options, signal) {
 var sumCredits = (amounts) => toCredits(amounts.reduce((total, credits) => total + (typeof credits === "number" ? toUnits(credits) : 0), 0));
 async function submitAssetBatch(client, project, requests, options, signal) {
   if (options["dry-run"]) {
-    const items2 = requests.map((request2) => ({ name: request2.name, type: request2.type, model: request2.model, estimatedCredits: toCredits(assetEstimate(request2)) }));
-    return { dryRun: true, items: items2, estimatedCredits: toCredits(requests.reduce((total2, request2) => total2 + assetEstimate(request2), 0)) };
+    const items2 = [];
+    for (const request2 of requests) {
+      const { request: checked3, estimatedCredits } = await estimateAsset(client, project, request2);
+      items2.push({ name: checked3.name, type: checked3.type, model: checked3.model, estimatedCredits });
+    }
+    return { dryRun: true, items: items2, estimatedCredits: sumCredits(items2.map((item) => item.estimatedCredits)) };
   }
   if (!options.yes) throw new Error("Pass --yes to authorize spending credits, or --dry-run to validate and estimate without generation.");
   const waiting = Boolean(options.wait || options.download);
@@ -49567,21 +49849,35 @@ Confirm code: ${device.user_code}`);
   })))).command("assets", (assets) => assets.add(defineCommand("list", { description: "List saved assets, their blob hashes, and configured generation models" }, (command) => command.flags({ name: "url", type: "string", default: "https://animaguru.com", env: { name: "ANIMAGURU_URL" } }).args(id).action(async ({ args, flags, stdout, signal }) => out(stdout, await new Client(flags.url, signal).request(`${projectPath(args.id)}/assets`))))).add(defineCommand("generate", { description: "Generate an image, video, music, speech or sound-effect asset; --yes authorizes credits" }, (command) => command.flags({ name: "url", type: "string", default: "https://animaguru.com", env: { name: "ANIMAGURU_URL" } }).args(id).flags(
     { name: "type", type: "string", required: true, choices: ASSET_TYPES },
     { name: "name", type: "string", required: true },
-    { name: "prompt", type: "string", required: true, description: "Description to generate, or verbatim transcript for speech" },
+    { name: "prompt", type: "string", description: "Description to generate, or verbatim transcript for speech; video lip-sync and relight take none, and camera-controls, insert-video, recast and 3d-to-video may leave it out" },
     { name: "model", type: "string", choices: assetModelIds, description: "Model for the chosen asset type" },
-    { name: "aspect-ratio", type: "string", choices: [.../* @__PURE__ */ new Set([...IMAGE_ASPECT_RATIOS, "auto", ...VIDEO_ASPECT_RATIOS])], description: "Image: 1:1 (default), 3:2, 2:3, 16:9 or 9:16; a masked edit keeps Image 1's shape. Video from text: 21:9\u20139:16 (default 16:9). Extension: auto (default, the source's) or a ratio to crop to" },
+    { name: "aspect-ratio", type: "string", choices: [.../* @__PURE__ */ new Set([...IMAGE_ASPECT_RATIOS, "auto", ...VIDEO_ASPECT_RATIOS])], description: "Image: 1:1 (default), 3:2, 2:3, 16:9 or 9:16; a masked edit keeps Image 1's shape. Video from text or a style without --reference: 21:9\u20139:16 (default 16:9). Extension, reference-to-video and relight: auto (default, the inputs' shape) or a ratio to crop to" },
     { name: "transparent", type: "boolean", description: "Image: transparent background" },
-    { name: "references", type: "string", description: "Image: up to 4 comma-separated blob SHAs of this project's images or sprite art to follow, such as a character sheet; refer to them as Image 1, Image 2\u2026 in the prompt" },
+    { name: "references", type: "string", description: "Comma-separated blob SHAs of this project's images or sprite art, named Image 1, Image 2\u2026 in the prompt. Image: up to 4 to follow, such as a character sheet. Video: subjects or looks to keep (reference-to-video and insert-video up to 9, 3d-to-video up to 8), or recast's new people, one photo each (up to 4)" },
     { name: "mask", type: "string", description: "Image: edit only these rectangles of Image 1 (the first --references image), as x,y,width,height fractions of its size from the top left, up to 8 separated by semicolons; the rest is kept" },
-    { name: "workflow", type: "string", choices: VIDEO_WORKFLOWS, description: "Video: image-to-video (default), text-to-video or extend-video, as the model's videoProfiles allow" },
-    { name: "reference", type: "string", description: "Video: starting image blob SHA from this project's assets or sprites" },
+    { name: "workflow", type: "string", choices: VIDEO_WORKFLOWS, description: "Video: image-to-video (default), text-to-video or extend-video; H3 Max also reference-to-video, lip-sync, camera-controls, insert-video, recast, relight, 3d-to-video and style, as the model's videoProfiles allow" },
+    { name: "reference", type: "string", description: "Video: starting image blob SHA from this project's assets or sprites; the speaking face for lip-sync, the image the camera moves around for camera-controls" },
     { name: "end-reference", type: "string", description: "Video: ending image blob SHA; models with endFrameOnly accept it without --reference" },
-    { name: "source", type: "string", description: "Extension: blob SHA of a video asset in this project to extend" },
-    { name: "soundtrack", type: "string", description: "Video from an image or text: blob SHA of a music, speech or SFX asset pinned as the soundtrack (2 s or longer)" },
-    { name: "audio-references", type: "string", description: "Extension: up to 3 comma-separated audio asset blob SHAs (2\u201315 s each, 15 s total) guiding the new sound; refer to them as Audio 1, Audio 2\u2026 in the prompt" },
-    { name: "seconds", type: "number", description: "Video or SFX duration in seconds (default 5); extensions add this many seconds; SFX supports 0.5\u201330" },
-    { name: "resolution", type: "string", choices: VIDEO_RESOLUTIONS, description: "Video resolution supported by the selected model and workflow (2k for extensions)" },
-    { name: "mode", type: "string", choices: ["cost", "speed", "quality"], description: "Video generation mode supported by the selected model" },
+    { name: "middle-reference", type: "string", description: "Reference-to-video: image blob SHA reached at --middle-seconds; needs --reference and --end-reference, 480p or 768p" },
+    { name: "middle-seconds", type: "number", description: "Reference-to-video: when the middle image is reached, in seconds" },
+    { name: "source", type: "string", description: "Blob SHA of a video asset in this project: the clip to extend, insert a scene into, recast or relight, or the 3D render 3d-to-video turns into footage" },
+    { name: "soundtrack", type: "string", description: "Video from an image or text: blob SHA of a music, speech or SFX asset pinned as the soundtrack (2 s or longer). Lip-sync: the speech to say (5 s\u201315 min), which sets the length" },
+    { name: "audio-references", type: "string", description: "Extension or reference-to-video: up to 3 comma-separated audio asset blob SHAs (2\u201315 s each, 15 s total) guiding the sound; refer to them as Audio 1, Audio 2\u2026 in the prompt" },
+    { name: "reference-videos", type: "string", description: "Reference-to-video or insert-video: up to 3 comma-separated video asset blob SHAs (2\u201315 s each, 15 s total) guiding motion, named Video 1, Video 2\u2026 in the prompt" },
+    { name: "camera", type: "string", description: 'Camera-controls: 2\u201312 keyframes time,azimuth,elevation,distance (time 0\u20131, angles in degrees, elevation \u221290\u201390) separated by semicolons, e.g. "0,0,0,1;1,90,15,1.2"' },
+    { name: "insert-at", type: "number", description: "Insert-video: seconds into --source where the new scene starts (1.625\u201360)" },
+    { name: "resume-at", type: "number", description: "Insert-video: seconds into --source where it resumes after the scene" },
+    { name: "color-match", type: "boolean", description: "Insert-video: match the scene's colors to the source (default on; --no-color-match turns it off)" },
+    { name: "transcribe", type: "boolean", description: "Lip-sync: transcribe the speech to guide the mouth" },
+    { name: "enhance-realism", type: "boolean", description: "Recast: more natural skin and blending of the new people" },
+    { name: "subject-consent", type: "boolean", description: "Recast: confirm that each person in the --references photos agreed to appear in the video" },
+    { name: "lighting", type: "string", description: "Relight: blob SHA of an image of a sphere lit as the video should be" },
+    { name: "generated-references", type: "number", description: "3d-to-video without --references: how many reference images it may draw, 1\u20138 (default 2)" },
+    { name: "style", type: "string", choices: VIDEO_STYLES, description: "Style workflow: the preset look, at 768p for 5\u201315 whole seconds" },
+    { name: "damage", type: "string", choices: VHS_DAMAGE_LEVELS, description: "VHS style: tape damage (fal's default medium)" },
+    { name: "seconds", type: "number", description: "Video or SFX duration in seconds (default 5); H3 takes fractions (6.5); extensions add this many seconds, insert-video's scene is 5\u201313; lip-sync, recast, relight and 3d-to-video take their input's length; SFX supports 0.5\u201330" },
+    { name: "resolution", type: "string", choices: VIDEO_RESOLUTIONS, description: "Video resolution supported by the selected model and workflow (default its first)" },
+    { name: "mode", type: "string", choices: ["cost", "speed", "quality"], description: "Video generation mode supported by the selected model (default its first)" },
     { name: "prompt-expansion", type: "string", choices: PROMPT_EXPANSION_MODES, description: "Video: how much the model may rewrite the prompt (default disabled); extensions treat any other value as on" },
     { name: "seed", type: "number", description: "Video: seed for repeatable results, where the model takes one" },
     { name: "extend-output", type: "string", choices: EXTEND_OUTPUTS, description: "Extension: extended (default, source plus new footage) or continuation (a 1.625 s overlap, then the new footage)" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docyrus/animaguru",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Agent-friendly AnimaGuru CLI built with CrustJS",
   "type": "module",
   "bin": {

package/skills/animaguru/SKILL.md

@@ -61,7 +61,7 @@ animaguru assets generate PROJECT_ID --type speech --name "Welcome" \
   --prompt "Welcome, traveler." --voice Kore --delivery "Warm and welcoming" --yes
 ```
 
-Images use the staff-managed route automatically. Use `--model` to select a model for video, music, speech or sound effects; discover the choices with `catalog` and the server's configured subset with `assets list`. Asset defaults are per type, independently of sprite project defaults. Image backgrounds are retained unless `--transparent` is supplied. CLI 0.17.0 adds `--references`, `--mask` and the 16:9 and 9:16 image shapes. `--references SHA,SHA` (up to four) makes an image follow this project's saved images, uploads or sprite art. To keep a recurring character consistent, generate a character sheet once and reference its `file` SHA in every later image; refer to references in the prompt as Image 1, Image 2 and so on, and say what to take from each. `--aspect-ratio` is 1:1, 3:2, 2:3, 16:9 or 9:16; use 16:9 or 9:16 for video scenes. `--mask x,y,width,height[;…]` (up to eight rectangles, in fractions of Image 1 from the top left) edits only those parts of Image 1, the first reference, and keeps the rest and Image 1's shape. Look at the image before choosing the rectangles. Videos require an image asset's `file` SHA from `assets list`, or a character's `art` SHA from `projects get`, in the same project. Validate video options against the selected model's `videoProfiles` in `catalog`; omitted video settings use five seconds and that provider's first resolution/mode. MiniMax H3 Max and H3 Max Turbo (`fal/minimax-h3-max`, `fal/minimax-h3-max-turbo`) also take `--workflow text-to-video` (with `--aspect-ratio`) and `--workflow extend-video` (with `--source VIDEO_SHA`, 2K resolution, `--extend-output`, and up to three comma-separated `--audio-references`). From images, they accept `--end-reference` with or without `--reference` and a `--soundtrack AUDIO_SHA`. All workflows take `--prompt-expansion` and `--seed`. These need CLI 0.8.0 or newer. For Gemini speech, `--prompt` is spoken verbatim and `--delivery` is a separate instruction. Music uses Lyria; the Gemini TTS models are for speech.
+Images use the staff-managed route automatically. Use `--model` to select a model for video, music, speech or sound effects; discover the choices with `catalog` and the server's configured subset with `assets list`. Asset defaults are per type, independently of sprite project defaults. Image backgrounds are retained unless `--transparent` is supplied. CLI 0.17.0 adds `--references`, `--mask` and the 16:9 and 9:16 image shapes. `--references SHA,SHA` (up to four) makes an image follow this project's saved images, uploads or sprite art. To keep a recurring character consistent, generate a character sheet once and reference its `file` SHA in every later image; refer to references in the prompt as Image 1, Image 2 and so on, and say what to take from each. `--aspect-ratio` is 1:1, 3:2, 2:3, 16:9 or 9:16; use 16:9 or 9:16 for video scenes. `--mask x,y,width,height[;…]` (up to eight rectangles, in fractions of Image 1 from the top left) edits only those parts of Image 1, the first reference, and keeps the rest and Image 1's shape. Look at the image before choosing the rectangles. Videos require an image asset's `file` SHA from `assets list`, or a character's `art` SHA from `projects get`, in the same project. Validate video options against the selected model's `videoProfiles` in `catalog`; omitted video settings use five seconds and that provider's first resolution/mode. MiniMax H3 Max and H3 Max Turbo (`fal/minimax-h3-max`, `fal/minimax-h3-max-turbo`) also take `--workflow text-to-video` (with `--aspect-ratio`) and `--workflow extend-video` (with `--source VIDEO_SHA`, 2K resolution, `--extend-output`, and up to three comma-separated `--audio-references`). From images, they accept `--end-reference` with or without `--reference` and a `--soundtrack AUDIO_SHA`. All workflows take `--prompt-expansion` and `--seed`. These need CLI 0.8.0 or newer. CLI 0.18.0 adds H3 Max's (not Turbo's) `--workflow reference-to-video` (keep a character across clips from up to nine `--references`, three `--reference-videos` and three `--audio-references`, named Image 1, Video 1, Audio 1 in the prompt; optional `--reference`, `--end-reference`, `--middle-reference` with `--middle-seconds`), `lip-sync` (the face in `--reference` says `--soundtrack` speech of 5 s–15 min; no `--prompt`; `--transcribe`), `camera-controls` (`--camera "time,azimuth,elevation,distance;…"`, 2–12 keyframes around `--reference`; without a prompt only the camera moves), `insert-video` (a 5–13 s scene inside `--source` from `--insert-at` to `--resume-at`, guided by `--references`/`--reference-videos`), `recast` (people in `--references` replace those in `--source`; pass `--subject-consent` only after each person agreed), `relight` (`--source` relit from a `--lighting` sphere image; no prompt), `3d-to-video` (a 3D render `--source` into footage, from `--references` or `--generated-references`) and `style` (`--style vhs|retro-toon-70s|low-poly|hand-drawn|16bit-pixel`, `--damage` for VHS, 768p, 5–15 whole seconds). Lip-sync, recast, relight and 3d-to-video take their input's length; their dry runs, like reference-to-video's and insert-video's, are server estimates because the price depends on the files. H3 takes fractional `--seconds` (6.5). For Gemini speech, `--prompt` is spoken verbatim and `--delivery` is a separate instruction. Music uses Lyria; the Gemini TTS models are for speech.
 
 For ElevenLabs speech, choose `eleven_v4` or `eleven_v4_turbo`, pass an ElevenLabs voice ID with `--voice` (George is the default), and put audio tags in `--prompt` rather than using `--delivery`. For sound effects, use `--type sfx`; the only model is `eleven_text_to_sound_v2`. SFX supports `--seconds` from 0.5 to 30 (default 5), `--loop`, and `--prompt-influence` from 0 to 1 (default 0.3). These additions require CLI 0.5.0 or newer; check `catalog` before using them with an installed CLI.