videodraft 0.28.2 → 0.29.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +5 -1
- package/dist/index.js +30 -6
- package/package.json +1 -1
- package/skills/index.json +4 -4
- package/skills/videodraft/SKILL.md +5 -5
- package/skills/videodraft/references/models.md +7 -4
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "videodraft",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.29.0",
|
|
4
4
|
"description": "Official VideoDraft CLI for AI videos, images, audio and 3D assets. Agent-friendly: --json everywhere, stable exit codes, async job polling.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
package/skills/index.json
CHANGED
|
@@ -22,8 +22,8 @@
|
|
|
22
22
|
},
|
|
23
23
|
{
|
|
24
24
|
"path": "references/models.md",
|
|
25
|
-
"sha256": "
|
|
26
|
-
"bytes":
|
|
25
|
+
"sha256": "db80a37e3a4cea0df38a8ace4b99654e74cc6c4ebd6c768abc1c5c3592511677",
|
|
26
|
+
"bytes": 46719
|
|
27
27
|
},
|
|
28
28
|
{
|
|
29
29
|
"path": "references/pipeline.md",
|
|
@@ -32,8 +32,8 @@
|
|
|
32
32
|
},
|
|
33
33
|
{
|
|
34
34
|
"path": "SKILL.md",
|
|
35
|
-
"sha256": "
|
|
36
|
-
"bytes":
|
|
35
|
+
"sha256": "dfa55654d56a522d7a52c3364de21bbc179689a838abeae30108b8576921dfdd",
|
|
36
|
+
"bytes": 49955
|
|
37
37
|
}
|
|
38
38
|
]
|
|
39
39
|
}
|
|
@@ -80,9 +80,9 @@ Seedance 2.0 and 2.5 have no real-people option, including for hosted `full_vide
|
|
|
80
80
|
2. Otherwise pick a **Tier 1** model.
|
|
81
81
|
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.
|
|
82
82
|
|
|
83
|
-
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.
|
|
83
|
+
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`, `flux-3-max`, `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.
|
|
84
84
|
|
|
85
|
-
Tier 2 is every other catalog model (`wan-3.0`, `flux-3
|
|
85
|
+
Tier 2 is every other catalog model (`wan-3.0`, `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`), re-syncing existing footage (`sync-lipsync-2`).
|
|
86
86
|
|
|
87
87
|
Every `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.
|
|
88
88
|
|
|
@@ -100,9 +100,9 @@ Every `videodraft models image|video|audio --json` entry carries `tier` (1 or 2)
|
|
|
100
100
|
- `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 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.
|
|
101
101
|
- `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.
|
|
102
102
|
- `minimax-h3` (Tier 2): 480p/768p/2K/4K (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.
|
|
103
|
+
- `flux-3-max` (Tier 1, before `minimax-h3-max`): fast 5-20s video at 720p/1080p, 24fps, optional native audio. Text, first frame, first + last frame, or up to 10 timed keyframes (`--keyframe shot.png@2.5`, repeatable). `--reasoning-level high|low` (high default), `--seed`, and explicit whole-second duration (default 5s). No Draft/quality mode or auto duration. Quote current pricing with `videodraft costs flux-3-max --type video --duration 5 --resolution 720p` or `--estimate`. Keep Gemini Omni as the default.
|
|
103
104
|
- `minimax-h3-max`: 480p/768p (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.
|
|
104
105
|
- `wan-3.0` (Tier 2): unified 2-30s text, first/last-frame, or ordered mixed-reference generation at 480p/720p/1080p, 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`.
|
|
105
|
-
- `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 much less. Auto duration is text/first-frame only.
|
|
106
106
|
- `seedance-2`: 11-15s, video/audio/mixed references, wider ratios, selectable audio, or first/last frames. `standard` is the default; use `mini` for a cheaper draft or `fast` for speed (both are 480p/720p only).
|
|
107
107
|
- `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.
|
|
108
108
|
- `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>>>`).
|
|
@@ -138,11 +138,11 @@ The live catalogs show discoverable models. Historical IDs remain valid for expl
|
|
|
138
138
|
|
|
139
139
|
Ideogram 4.5 (`ideogram-v4.5`) replaces 4.0 and remains Tier 2. Quality is low/medium/high (default medium) and is priced per output; regular edits also offer very_low. Supports 1-8 outputs, 1K/2K, seed, and text-only `--prompt-expansion true|false`. Use `--source-image` plus up to four `--ref` images, or source-first `--ref` ordering. `--edit-precision high` and `--mask` require Auto size with no resolution; masks match source dimensions, black edits and white preserves, and reduce additional references to three. See [models](references/models.md) for custom dimensions and examples.
|
|
140
140
|
|
|
141
|
-
FLUX 3 image (`flux-3-image`,
|
|
141
|
+
FLUX 3 image (`flux-3-image`, separate from `flux-3-max` video) 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.
|
|
142
142
|
|
|
143
143
|
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.
|
|
144
144
|
|
|
145
|
-
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,
|
|
145
|
+
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, Gemini Omni generation accept `--auto-duration`; do not combine it with `--duration`. Kling O3 reference/edit modes accept image-only `--element` objects, at most four combined with `--ref`.
|
|
146
146
|
|
|
147
147
|
Topaz 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`.
|
|
148
148
|
|
|
@@ -41,7 +41,7 @@ videodraft generate image 'Replace the sign text with "OPEN"' --model ideogram-v
|
|
|
41
41
|
videodraft costs ideogram-v4.5 --type image --quality very_low --ref-images 1 --num 2
|
|
42
42
|
```
|
|
43
43
|
|
|
44
|
-
FLUX 3 image (`flux-3-image`,
|
|
44
|
+
FLUX 3 image (`flux-3-image`, separate from `flux-3-max` video) is Tier 2: Black Forest Labs' newest image model, on Fal or your Fal key. It generates and edits with up to 10 `--ref` images (call them "image 1", "image 2" in the prompt), `--num 1..4`, `--resolution 1K|2K|4K` (default 1K), `--prompt-expansion true|false` (default true) and `--ar` with 14 ratios (21:9 to 1:2, including 7:5 and 5:7) plus `auto`. Each image is priced by output size (resolution and ratio); `auto` lets the model pick, or follows the first reference, and is quoted at the tier's highest price. Without `--ar`, a new image is 16:9 and an edit is `auto`. No seed. Output is JPEG.
|
|
45
45
|
|
|
46
46
|
```bash
|
|
47
47
|
videodraft generate image 'Studio photo of a ceramic mug on a walnut desk, soft light from the left' --model flux-3-image --ar 4:5 --resolution 2K --estimate
|
|
@@ -67,8 +67,8 @@ videodraft generate image 'A blue glass bird' --model gpt-image-2.5-flare --ar 1
|
|
|
67
67
|
| 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 |
|
|
68
68
|
| T2: Document or webpage reference generation; by name otherwise | `wan-3.0` | 2-30s or auto; 480p/720p/1080p; 10 image, 5 video, 5 audio refs, 20 media files total; document/web refs require thinking |
|
|
69
69
|
| T2: 480p/768p/2K/4K with native stereo audio, first/last frames, or mixed image/video/audio references | `minimax-h3` | 5-15s; up to 9 image, 3 video, 3 audio refs, 12 files total; first 5 reference images included; reference video/audio each total <=15s |
|
|
70
|
+
| T1: Fast video and timed keyframes, before H3 Max | `flux-3-max` | 5-20s, default 5s; 720p/1080p; optional audio; first/last frames or up to 10 keyframes; High/Low reasoning (`--reasoning-level`), `--seed`; no Draft or auto duration |
|
|
70
71
|
| T1: Text, first/last-frame, or mixed-reference video with native audio and stronger prompt adherence | `minimax-h3-max` | 5-15s; 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 |
|
|
71
|
-
| 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 and much cheaper |
|
|
72
72
|
| 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 |
|
|
73
73
|
| 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 |
|
|
74
74
|
| 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 |
|
|
@@ -86,7 +86,7 @@ Routing rules:
|
|
|
86
86
|
- 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.
|
|
87
87
|
- 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.
|
|
88
88
|
- 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.
|
|
89
|
-
- 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.
|
|
89
|
+
- 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, FLUX 3 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.
|
|
90
90
|
- 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.
|
|
91
91
|
- 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`.
|
|
92
92
|
- 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.
|
|
@@ -190,7 +190,7 @@ Direct Fabric text/audio, H3 Max Lip Sync, and Sync Labs do not use the managed
|
|
|
190
190
|
|
|
191
191
|
- 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 — check first, don't trial-and-error paid calls.
|
|
192
192
|
- Most video models support only 16:9 / 9:16 / 1:1. A 3:4 request hard-fails on most.
|
|
193
|
-
- `--seed` reproduces a specific output on models that support it (e.g. Ideogram 4.5). GPT Image 2.5 and FLUX 3 reject any explicit seed; older models may ignore unsupported seeds. You do not need a seed for variation — `--num` already varies.
|
|
193
|
+
- `--seed` reproduces a specific output on models that support it (e.g. Ideogram 4.5). GPT Image 2.5 and FLUX 3 Image reject any explicit seed; older models may ignore unsupported seeds. You do not need a seed for variation — `--num` already varies.
|
|
194
194
|
- `--rendering-speed` remains accepted for explicit legacy image requests and their cost estimates. Current Ideogram models use `--quality`. 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.
|
|
195
195
|
- `seedream-v5-pro` supports unified text-to-image and reference-image editing with up to 10 image references. Use `--resolution 1K` or `--resolution 2K` (2K costs more per image).
|
|
196
196
|
- 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.
|
|
@@ -231,6 +231,7 @@ videodraft costs topaz-upscale --type image --width 2048 --height 2048 --scale 2
|
|
|
231
231
|
videodraft costs topaz-interpolate-video --type video --duration 10 --width 1920 --height 1080 --fps 60 --topaz-model Apollo
|
|
232
232
|
videodraft costs minimax-h3 --type video --duration 10 --resolution 2K --ref-images 7
|
|
233
233
|
videodraft costs minimax-h3-max --type video --duration 10 --resolution 768p --ref-images 2
|
|
234
|
+
videodraft costs flux-3-max --type video --duration 5 --resolution 720p
|
|
234
235
|
videodraft costs grok-imagine-video-1.5 --type video --duration 8 --resolution 720p --ref-images 4
|
|
235
236
|
videodraft costs seedance-2 --type video --duration 15 --resolution 720p --quality standard --audio
|
|
236
237
|
videodraft costs grok-imagine-2.0 --type image --resolution 2K --quality medium --num 2
|
|
@@ -242,3 +243,5 @@ videodraft costs voiceover --type audio --chars 800 --mode turbo # ElevenLabs Tu
|
|
|
242
243
|
videodraft generate video "..." --model gemini-omni-1.1-flash --estimate # same quote, inline
|
|
243
244
|
videodraft generate video "..." --model minimax-h3-max --duration 8 --resolution 768p --prompt-expansion-mode balanced
|
|
244
245
|
```
|
|
246
|
+
|
|
247
|
+
MiniMax H3 Max and FLUX 3 Max are Tier 1; Gemini Omni remains the default. Use `videodraft costs` or `--estimate` for current prices before spending.
|