videodraft 0.27.1 → 0.28.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "videodraft",
-  "version": "0.27.1",
+  "version": "0.28.0",
   "description": "Official VideoDraft CLI for AI videos, images, audio and 3D assets. Agent-friendly: --json everywhere, stable exit codes, async job polling.",
   "license": "MIT",
   "type": "module",

package/skills/index.json

@@ -17,13 +17,13 @@
         },
         {
           "path": "references/examples.md",
-          "sha256": "7bea9a261ca4e258089af48f35e51f00c1ec877726559581efc7ecbd7aaeb696",
-          "bytes": 10103
+          "sha256": "a6398c2f1e40b54b9a169680235e712b59f09bef984f56f65df50b6aac4154c1",
+          "bytes": 10105
         },
         {
           "path": "references/models.md",
-          "sha256": "6b1e4dac4e4469c01ee61dd9fce07788f2f1c4da75fdcaf4488d2442abdd4000",
-          "bytes": 46051
+          "sha256": "40ac27fe5f0683d80b3b4825f0a2f501aea2381896bb44ec85a53cf98d07da19",
+          "bytes": 46306
         },
         {
           "path": "references/pipeline.md",
@@ -32,8 +32,8 @@
         },
         {
           "path": "SKILL.md",
-          "sha256": "e35a1c86039e1fda2fae67518aa7799fefb50f5722893f212d5dbabbe147432e",
-          "bytes": 46450
+          "sha256": "782da50f2ec4ad2e9760e4473ad5ebc1e12c5676c663ffce201d1a77fd0108c7",
+          "bytes": 47506
         }
       ]
     }

package/skills/videodraft/SKILL.md

@@ -74,7 +74,7 @@ Seedance 2.0 and 2.5 have no real-people option, including for hosted `full_vide
 2. Otherwise pick a **Tier 1** model.
 3. 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.
 
-Tier 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.
+Tier 1: images `nano-banana-2.1`, `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.
 
 Tier 2 is every other catalog model (`wan-3.0`, `flux-3`, `flux-3-image`, `minimax-h3`, `kling-v3-turbo`, `kling-2.6-pro`, `grok-imagine-video-1.5`, `happy-horse`, Veo 3.1, 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`).
 
@@ -84,7 +84,8 @@ Every `videodraft models image|video|audio --json` entry carries `tier` (1 or 2)
 
 **Images:**
 
-- `nano-banana-2`: general default, editing, consistency, and references.
+- `nano-banana-2.1`: general default, editing, text, consistency, and references. Add `--thinking-level medium` or `high` for complex layouts, infographics or dense text.
+- `nano-banana-2`: the previous default; use it when temperature control is wanted.
 - `nano-banana-pro`: maximum quality. `nano-banana-2-lite`: fast, inexpensive drafts.
 - `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.
 
@@ -111,6 +112,8 @@ Every `videodraft models image|video|audio --json` entry carries `tier` (1 or 2)
 - 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, one flat price per track), 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) and `lyria-3-pro-preview` 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.
 - ElevenLabs voiceover runs on Eleven v4 in two modes. Standard is the default and the best quality. Turbo (Eleven v4 Turbo) is faster and cheaper. Both are billed per character. 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 more per character). v4 has no style or speed settings and no SSML `<break>` tags; audio tags such as `[whispers]` work. Dialogue stays on Eleven v3.
 - 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.
+- Search the dynamic ElevenLabs catalogue with `videodraft models voices --search "warm narrator" --language en --source library --page-size 20 --json`. Repeat the same filters with `--page-token <next_page_token>` for more results. `--accent` and `--gender male|female` are optional. ElevenLabs BYOK defaults to the connected account's voices; `--source library` explores public voices on that key. Descriptions, previews and access scope help choose a voice. Public discovery does not guarantee Fal access; private voices require their owning/shared ElevenLabs account. Existing VideoDraft prices apply on direct platform generation and Fal fallback; BYOK remains zero VideoDraft credits.
+
 - A character who needs to TALK:
   - **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.
   - **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.
@@ -131,7 +134,7 @@ Ideogram 4.5 (`ideogram-v4.5`) replaces 4.0 and remains Tier 2. Quality is low/m
 
 FLUX 3 image (`flux-3-image`, not the `flux-3` video model) is Tier 2. It generates and edits with up to 10 `--ref` images, `--num 1..4`, `--resolution 1K|2K|4K` (default 1K), `--prompt-expansion true|false` (default true) and `--ar` with 14 ratios plus `auto`. Each image is priced by output size (resolution and ratio); `auto` is quoted at the tier's highest price. Without `--ar`, a new image is 16:9 and an edit follows its first reference. No seed.
 
-Use `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.
+Use `models image --json` / `models video --json` for the accepted options. Nano Banana 2.1 exposes `--thinking-level minimal|medium|high` (default minimal; no extra charge) and `--google-search-grounding true|false`, but no temperature. 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.
 
 Kling 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. Kling O3 reference/edit modes accept image-only `--element` objects, at most four combined with `--ref`.
 
@@ -142,7 +145,7 @@ Topaz image results may be immediate or queued. The CLI waits by default and dow
 Pure 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.
 
 - If the user supplies reference media, preserve and pass it. Never reduce the request to text alone.
-- 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.
+- When continuity matters, generate/select a strong still first with the selected image model (`nano-banana-2.1` by default), wait for its URL, then animate it as a start frame/reference. Confirm the combined image and video cost.
 - 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.
 
 ## Cost and credits

package/skills/videodraft/references/examples.md

@@ -78,7 +78,7 @@ When the user has no portrait, generate a clear front-facing avatar image first.
 ```bash
 videodraft generate image \
   "Front-facing head-and-shoulders portrait of a friendly coffee expert, direct eye contact, natural expression, clean studio background" \
-  --model nano-banana-2 --ar 9:16 --download ./media/avatar.png
+  --model nano-banana-2.1 --ar 9:16 --download ./media/avatar.png
 
 SCRIPT=$(videodraft avatar script "why our espresso subscription saves you money" --style ad-style --json | jq -r .script)
 AVATAR=$(videodraft avatar create ./media/avatar.png --script "$SCRIPT" --voice elevenlabs-kPzsL2i3teMYv0FxEYQ6 --ar 9:16 --json | jq -r .avatar_video_id)

package/skills/videodraft/references/models.md

@@ -24,7 +24,8 @@ Tier 1 is the rows marked **T1** below. Every other catalog model is Tier 2 and
 
 | Need                                                                                       | Choose                   | Why                                                               |
 | ------------------------------------------------------------------------------------------ | ------------------------ | ----------------------------------------------------------------- |
-| T1: Most generation, editing, character consistency, or reference work                     | `nano-banana-2`          | Best general default; 1K/2K/4K and up to 14 reference images      |
+| T1: Most generation, editing, text, character consistency, or reference work               | `nano-banana-2.1`        | Best general default; 1K/2K/4K, 14 references, thinking levels    |
+| T1: Previous default, or when temperature control is wanted                                | `nano-banana-2`          | 1K/2K/4K and up to 14 reference images; temperature 0-2           |
 | T1: Highest-quality complex generation or reasoning                                        | `nano-banana-pro`        | Premium Nano Banana quality and reasoning                         |
 | T1: Fast, inexpensive drafts and iteration                                                 | `nano-banana-2-lite`     | Fastest/cheapest Nano Banana option; 1K only, up to 14 references |
 | 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        |
@@ -124,8 +125,8 @@ Kling O3 is also exposed for reference generation. `videodraft generate video --
 
 - Prefer a start frame or reference image whenever a specific character, product, location, style, composition, or brand identity must stay recognizable.
 - If the user gives a reference, pass it. Never silently replace it with a text description.
-- 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.
-- 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.
+- 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.1. Wait for the image URL, then animate it with the selected video model. Confirm the combined image plus video cost before starting.
+- 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.1`. The grid establishes the scene and characters together, then decodes into individual shot images.
 - 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.
 - Pure text-to-video remains appropriate for generic one-off footage where no subject, composition, or continuity needs to be preserved.
 
@@ -167,7 +168,7 @@ For a presenter, spokesperson or explainer speaking to camera, VEED Fabric is th
 
 The 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.
 
-1. 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.
+1. 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.1`, direct eye contact, a natural expression, and a clean background. Match the intended video aspect ratio when practical.
 2. If the portrait is visibly soft or too small, run Topaz image enhancement/upscaling before animation.
 3. Generate a script only if needed: `videodraft avatar script "<idea>"`.
 4. 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.
@@ -200,7 +201,7 @@ Direct Fabric text/audio, H3 Max Lip Sync, and Sync Labs do not use the managed
 
 This skill lists no prices because they change with provider routing and sales. Get the current price from `videodraft costs <model> [settings]` or the command's `--estimate` flag; both read live prices from the server and spend nothing. Never quote a price from memory. What each kind of job is billed on:
 
-- Images: per image (x `--num`). Matrix-priced models (GPT Image, Nano Banana Pro, Seedream v5 Pro, Ideogram 4.5, Grok Imagine 2.0) vary by resolution and/or quality; Grok Imagine 2.0 also charges per reference image (up to 3).
+- Images: per image (x `--num`). Matrix-priced models (GPT Image, Nano Banana 2.1 and Pro, Seedream v5 Pro, Ideogram 4.5, Grok Imagine 2.0) vary by resolution and/or quality (Nano Banana 2.1 thinking and web search are free); Grok Imagine 2.0 also charges per reference image (up to 3).
 - Video: per output second; the rate depends on model, resolution, quality and native audio on/off.
 - Gemini Omni 1.1 Flash: per output second by resolution (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.
 - MiniMax H3: per output second by resolution (768p default). The first 5 reference images are included, then each additional image adds a charge. Reference video and reference audio are NOT billed.