videodraft 0.26.0 → 0.27.1
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 +12 -11
- package/dist/client.js +1 -9
- package/dist/index.js +168 -92
- package/package.json +1 -1
- package/skills/index.json +11 -11
- package/skills/videodraft/SKILL.md +28 -28
- package/skills/videodraft/references/3d.md +1 -1
- package/skills/videodraft/references/editor.md +2 -1
- package/skills/videodraft/references/examples.md +1 -1
- package/skills/videodraft/references/models.md +64 -51
- package/skills/videodraft/references/pipeline.md +2 -2
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "videodraft",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.27.1",
|
|
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
|
@@ -7,33 +7,33 @@
|
|
|
7
7
|
"files": [
|
|
8
8
|
{
|
|
9
9
|
"path": "references/3d.md",
|
|
10
|
-
"sha256": "
|
|
11
|
-
"bytes":
|
|
10
|
+
"sha256": "12a542bc0d902ae15e520b8d18b553bc5ff5229e97df60d0f799ba0c5387d334",
|
|
11
|
+
"bytes": 5431
|
|
12
12
|
},
|
|
13
13
|
{
|
|
14
14
|
"path": "references/editor.md",
|
|
15
|
-
"sha256": "
|
|
16
|
-
"bytes":
|
|
15
|
+
"sha256": "98ad6ded7a7f13aa8c6a59e8b778f3aac4d24094dc767fa0c978e81c33ac2902",
|
|
16
|
+
"bytes": 24349
|
|
17
17
|
},
|
|
18
18
|
{
|
|
19
19
|
"path": "references/examples.md",
|
|
20
|
-
"sha256": "
|
|
20
|
+
"sha256": "7bea9a261ca4e258089af48f35e51f00c1ec877726559581efc7ecbd7aaeb696",
|
|
21
21
|
"bytes": 10103
|
|
22
22
|
},
|
|
23
23
|
{
|
|
24
24
|
"path": "references/models.md",
|
|
25
|
-
"sha256": "
|
|
26
|
-
"bytes":
|
|
25
|
+
"sha256": "6b1e4dac4e4469c01ee61dd9fce07788f2f1c4da75fdcaf4488d2442abdd4000",
|
|
26
|
+
"bytes": 46051
|
|
27
27
|
},
|
|
28
28
|
{
|
|
29
29
|
"path": "references/pipeline.md",
|
|
30
|
-
"sha256": "
|
|
31
|
-
"bytes":
|
|
30
|
+
"sha256": "2178cf9d8d800614f7881ffc68ce12a0700e1eb1877c7392aef22bce129d27b2",
|
|
31
|
+
"bytes": 14213
|
|
32
32
|
},
|
|
33
33
|
{
|
|
34
34
|
"path": "SKILL.md",
|
|
35
|
-
"sha256": "
|
|
36
|
-
"bytes":
|
|
35
|
+
"sha256": "e35a1c86039e1fda2fae67518aa7799fefb50f5722893f212d5dbabbe147432e",
|
|
36
|
+
"bytes": 46450
|
|
37
37
|
}
|
|
38
38
|
]
|
|
39
39
|
}
|
|
@@ -9,7 +9,7 @@ VideoDraft is an AI video creation platform where asset generation is the priori
|
|
|
9
9
|
|
|
10
10
|
- **Asset generation**: standalone images, video clips, Seed Audio, voiceovers, music, sound effects, dialogue, voice-changed audio, dubbed media, upscales, and image descriptions. This is the fastest and most important lane. Treat these as complete deliverables when the user asks for assets.
|
|
11
11
|
- **Asset I/O**: upload local files, download outputs, auto-upload local references, and save generated media where the user can see it.
|
|
12
|
-
- **3D assets**: standalone Meshy 7 and Tripo H3.1 meshes, multi-view generation, complete artifact downloads, and Meshy humanoid rigging through MCP/CLI. Read [references/3d.md](references/3d.md), or `videodraft skills show 3d`. These assets have their own saved library and do not require an AI Studio session or web viewer.
|
|
12
|
+
- **3D assets**: standalone Meshy 7.1 and Tripo H3.1 meshes, multi-view generation, complete artifact downloads, and Meshy humanoid rigging through MCP/CLI. Read [references/3d.md](references/3d.md), or `videodraft skills show 3d`. These assets have their own saved library and do not require an AI Studio session or web viewer.
|
|
13
13
|
- **Native editing**: local `.vdproject` timelines, cuts, layouts, captions, effects, audio, and exports through the headless VideoDraft Editor. Inside VideoDraft ADE, this is the default production and export lane whenever `videodraft_editor` is available.
|
|
14
14
|
- **Hosted project production**: idea → script → storyboard → hosted production timeline → exported MP4. Use the early stages for scripts, storyboards, and generated assets when useful. Treat hosted production and export as a fallback when the native editor is unavailable, or as an explicit destination when the user asks for an editable web project or hosted workflow.
|
|
15
15
|
|
|
@@ -64,15 +64,9 @@ If you are reading this skill through `videodraft skills show skill`, run `video
|
|
|
64
64
|
|
|
65
65
|
If the user names a model, use it when compatible. If it cannot handle the request, explain why and recommend alternatives instead of silently switching. Otherwise inspect the inputs, duration, audio, quality, speed, and cost, check the live catalog, and pass an explicit model.
|
|
66
66
|
|
|
67
|
-
### Seedance 2.x
|
|
67
|
+
### Seedance 2.x pricing
|
|
68
68
|
|
|
69
|
-
Seedance 2.0 and 2.5
|
|
70
|
-
|
|
71
|
-
- The default is true. Generation tries Byteplus first and can fall back to Fal, which allows real-person likenesses, so a person in the prompt, a start frame, end frame, reference image, or reference video does not hard-fail. The request is charged at Fal's higher tier-specific rate even if Byteplus serves it.
|
|
72
|
-
- Turn it off for the cheapest run, only when the user wants that and nothing in the job is a real identifiable person (text-only requests, non-people, anime, clearly synthetic or stylized characters). For MCP use `allow_real_people: false`. For the CLI use `--no-allow-real-people`. That pins the job to the lower-priced Byteplus path, and a Byteplus likeness-policy refusal does not fall back to Fal. Pass the same value to `get_model_costs` or `videodraft costs` so the estimate matches the charge.
|
|
73
|
-
- If a request made with the option off fails with code `SEEDANCE_REAL_PERSON_OPT_IN_REQUIRED`, estimate the higher rate, follow the user's spend-confirmation preference, and retry exactly once with the option on. The structured recovery fields are `retryable: true`, `retry_with: { allow_real_people: true }`, `cli_flag: "--allow-real-people"`, and `retry_policy: "once"`. CLI `--json` submit errors expose them under `details`; `status` and `wait` include them on the failed job result. Do not treat an unrelated moderation or provider error as that signal.
|
|
74
|
-
- Do not loop when the option was on. Byteplus can accept a task and reject its generated output later. VideoDraft refunds that failed generation, but the late asynchronous failure cannot be rerouted to Fal. Rephrase the prompt or use different references before trying again.
|
|
75
|
-
- For hosted AI Production, the same default applies to every Seedance scene segment: `produce_project` with `mode: "full_video"` and `videodraft produce <project> --mode full_video` allow real people unless you pass `allow_real_people: false` or `--no-allow-real-people`. If an earlier run with the option off partially submitted and returns the opt-in code, rerun that same project once with an explicit `allow_real_people: true` / `--allow-real-people`. The server reconciles asynchronous results first, preserves running/completed jobs, and resubmits only failed scene-video placeholders carrying the exact opt-in signal. Keep the native-first VideoDraft ADE routing rule above: hosted full-video production is still explicit/fallback-only when the local editor is available.
|
|
69
|
+
Seedance 2.0 and 2.5 have no real-people option, including for hosted `full_video` production. A video that can't be made at the listed rate, usually one showing a real person, costs a higher rate; the difference is charged before it starts. When a real person is involved, quote both prices (`get_model_costs` returns `cost` and `higher_rate_cost`). Don't name providers to the user.
|
|
76
70
|
|
|
77
71
|
**How to pick a model. Follow this order every time:**
|
|
78
72
|
|
|
@@ -82,7 +76,7 @@ Seedance 2.0 and 2.5 allow real people by default, the same as AI Studio:
|
|
|
82
76
|
|
|
83
77
|
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.
|
|
84
78
|
|
|
85
|
-
Tier 2 is every other catalog model (`wan-3.0`, `flux-3`, `minimax-h3`, `kling-v3-turbo`, `kling-2.6-pro`, `grok-imagine-video-1.5`, `happy-horse`, Veo 3.1,
|
|
79
|
+
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`).
|
|
86
80
|
|
|
87
81
|
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
82
|
|
|
@@ -96,26 +90,26 @@ Every `videodraft models image|video|audio --json` entry carries `tier` (1 or 2)
|
|
|
96
90
|
|
|
97
91
|
**Videos:**
|
|
98
92
|
|
|
99
|
-
- `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
|
|
93
|
+
- `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.
|
|
100
94
|
- `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.
|
|
101
|
-
- `minimax-h3` (Tier 2): 480p/768p/2K/4K (
|
|
102
|
-
- `minimax-h3-max`: 480p/768p
|
|
103
|
-
- `wan-3.0` (Tier 2): unified 2-30s text, first/last-frame, or ordered mixed-reference generation at 480p/720p/1080p
|
|
104
|
-
- `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
|
|
105
|
-
- `seedance-2`: 11-15s, video/audio/mixed references, wider ratios, selectable audio, or first/last frames. `
|
|
95
|
+
- `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.
|
|
96
|
+
- `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.
|
|
97
|
+
- `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`.
|
|
98
|
+
- `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.
|
|
99
|
+
- `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).
|
|
106
100
|
- `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.
|
|
107
101
|
- `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>>>`).
|
|
108
102
|
- Existing-video edits use `videodraft edit video`, not generic generation. `gemini-omni-1.1-flash` is the preferred edit model and is chosen automatically when you omit `--model`: source up to 10s, up to 10 reference images, 360p/720p/1080p/4K with audio. Creative `--ref-video` inputs are NOT accepted on an edit, because an edit takes exactly one input video; use `generate video --video-task generate` to guide a new clip with video references instead. Omitting `--model` on a longer or unmeasurable source spends nothing and prints a priced menu (what each model edits, what it drops, what it costs) so you can put the choice to the user. **Truncation:** only Gemini refuses an over-length source. Happy Horse silently edits just the first 15s, Kling O3 the first 10s, and Grok the first 8s. The command warns you when that will happen; always relay it to the user. Gemini regenerates the audio track, so use Happy Horse or Kling O3 with `--preserve-audio` when the source audio must survive. Choose Grok for the cheapest prompt-only edit, Happy Horse for up to 5 image references, or Kling O3 for controlled reference-image edits.
|
|
109
103
|
- To edit a source longer than 10s without losing its tail, cut it into <=10s pieces in the native editor, edit each with Gemini, and reassemble. VideoDraft has no server-side split/concat, so this path needs `videodraft_editor`.
|
|
110
104
|
- Kling O3 also has a reference-generation mode. Use `videodraft generate video --model kling-o3-video-ref-edit` with exactly one `--ref-video` to generate a new guided clip; use `videodraft edit video` when changing the source itself. For new mixed-reference generation use Seedance 2 / 2.5.
|
|
111
105
|
- Motion transfer uses `videodraft edit motion` with Kling V3 by default, or Kling 2.6 when explicitly requested or lower cost matters. It requires a subject image and a motion-reference video.
|
|
112
|
-
- Veo 3.1,
|
|
106
|
+
- Veo 3.1, Grok Video 1.5, Happy Horse and the other Tier 2 video models: only when explicitly requested or when no Tier 1 model fits.
|
|
113
107
|
|
|
114
108
|
**Audio and utilities:**
|
|
115
109
|
|
|
116
|
-
- Use Seed Audio 1.0 for open-ended text-to-audio, speech/music/sound synthesis, voice conditioning, or prompt-driven editing with up to three audio references or one image. Use `videodraft generate audio`. Reference clips are `@Audio1`, `@Audio2`, and `@Audio3` in array order. There is no duration input. Output is up to two minutes and
|
|
117
|
-
- 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,
|
|
118
|
-
- ElevenLabs voiceover runs on Eleven v4 in two modes. Standard is the default and the best quality
|
|
110
|
+
- Use Seed Audio 1.0 for open-ended text-to-audio, speech/music/sound synthesis, voice conditioning, or prompt-driven editing with up to three audio references or one image. Use `videodraft generate audio`. Reference clips are `@Audio1`, `@Audio2`, and `@Audio3` in array order. There is no duration input. Output is up to two minutes and is billed per actual output minute; the two-minute maximum is reserved during generation and the unused part refunded. The CLI automatically retries transient responses with one operation key. To recover after the CLI process itself is interrupted, set `--idempotency-key <uuid>` on the original command and reuse it.
|
|
111
|
+
- 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.
|
|
112
|
+
- 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.
|
|
119
113
|
- 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.
|
|
120
114
|
- A character who needs to TALK:
|
|
121
115
|
- **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.
|
|
@@ -125,15 +119,21 @@ Every `videodraft models image|video|audio --json` entry carries `tier` (1 or 2)
|
|
|
125
119
|
|
|
126
120
|
See [references/models.md](references/models.md) for the detailed routing table and exact capability limits.
|
|
127
121
|
|
|
128
|
-
Provider routing uses a maintained local price catalog, with exact setting compatibility and account rules. Platform requests prefer Google's direct image/video APIs and BytePlus for Seedance 2.0/2.5 before comparing public prices.
|
|
122
|
+
Provider routing uses a maintained local price catalog, with exact setting compatibility and account rules. Platform requests prefer Google's direct image/video APIs and BytePlus for Seedance 2.0/2.5 before comparing public prices. Other models retain their supported provider routing. Agents should keep using normal model IDs and `get_model_costs` / `--estimate` for customer credits. Do not choose a vendor from a marketing starting price or retry an accepted generation to chase a lower price. Unknown or expired comparable costs retain the existing route; a selected personal provider key stays exclusive and overrides platform-account preferences.
|
|
129
123
|
|
|
130
124
|
Temporary provider promotions are excluded from routing prices. With an Atlas personal key, H3 Max supports text or first/last-frame generation at 480P/768P only with `prompt_expansion_mode: "disabled"` and no seed. Balanced/quality expansion, reference generation and H3 Max Lip Sync require the existing Fal path. Atlas H3 Max is not selected automatically while its published price units remain inconsistent.
|
|
131
125
|
|
|
126
|
+
The live catalogs show discoverable models. Historical IDs remain valid for explicit requests and recreating saved generations, subject to provider availability. Do not pick a hidden model unless the user explicitly requests it.
|
|
127
|
+
|
|
132
128
|
## Matching AI Studio controls
|
|
133
129
|
|
|
130
|
+
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.
|
|
131
|
+
|
|
132
|
+
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.
|
|
133
|
+
|
|
134
134
|
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.
|
|
135
135
|
|
|
136
|
-
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.
|
|
136
|
+
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`.
|
|
137
137
|
|
|
138
138
|
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`.
|
|
139
139
|
|
|
@@ -149,17 +149,17 @@ Pure text-to-image or text-to-video is fine for a generic one-off asset. When a
|
|
|
149
149
|
|
|
150
150
|
Do not call `videodraft credits` before routine generations. Paid endpoints validate and deduct atomically; if the balance is insufficient, the request is rejected before the provider job starts (CLI exit code 4). Check the balance only when the user asks, gives a credit budget, or a large workflow needs budget planning.
|
|
151
151
|
|
|
152
|
-
|
|
152
|
+
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 or from older notes. For expensive work, estimate first, state the selected model/settings/cost, and get a go-ahead. This matters most for shot-image batches, long or high-resolution video, AI Production, and paid audio batches. Honor the user's confirmation preference for the session.
|
|
153
153
|
|
|
154
|
-
Kling voice creation
|
|
154
|
+
Kling voice creation has a small charge on the platform Fal account and is free with Fal BYOK. Preview it with `videodraft kling-voices create <sample> --name <name> --estimate`; the estimate does not create a voice or require consent confirmation. Actual creation requires `--confirm-consent`.
|
|
155
155
|
|
|
156
|
-
MiniMax H3
|
|
156
|
+
MiniMax H3 is billed per output second by resolution (768p by default). In reference mode the first 5 images are included and each additional image adds a charge. Reference video and reference audio are NOT billed.
|
|
157
157
|
|
|
158
|
-
MiniMax H3 Max
|
|
158
|
+
MiniMax H3 Max is billed per output second at 480p or 768p (default), plus pooled reference tokens in reference mode: a free allowance, then a charge per 1,000 tokens, where an image is `(width x height) / 1024` tokens, a reference video is 2,886 tokens per second at 480p or 7,459 at 768p, and reference audio is about 2,121 per second. Use `--prompt-expansion-mode disabled|balanced|quality`; balanced is the default. Fal's provider safety checker is OFF by default and is not exposed in the app — only pass `--safety-checker true` if the user explicitly asks for it.
|
|
159
159
|
|
|
160
|
-
Wan 3.0
|
|
160
|
+
Wan 3.0 is billed per output second by resolution. Auto duration reserves the 30-second maximum and refunds the unused reserve after the provider reports the actual whole-second output length. Fal BYOK runs on the connected user key and charges zero VideoDraft credits.
|
|
161
161
|
|
|
162
|
-
Grok Imagine Video 1.5
|
|
162
|
+
Grok Imagine Video 1.5 is billed per output second by resolution, plus a small charge for each first-frame or reference image. Native audio is always generated.
|
|
163
163
|
|
|
164
164
|
`videodraft models image|video` lists the live image and video catalogs with supported inputs. Video entries are grouped as `generation`, `video_edit`, `motion_control`, `avatar_lipsync`, and `upscale`, and each reports the exact tool. Use `videodraft models video --category video_edit` to narrow the list. `videodraft models audio` lists Seed Audio, Google Lyria, and ElevenLabs audio/media tools, while `videodraft models voices` helps discover TTS voices. Consult them for capabilities; a supplied ElevenLabs voice ID does not need to appear in the voice catalog.
|
|
165
165
|
|
|
@@ -13,7 +13,7 @@ videodraft rig 3d --estimate
|
|
|
13
13
|
|
|
14
14
|
MCP tools: `get_3d_models`, `estimate_3d`, `generate_3d`, `rig_3d`, `check_generation_status`, `list_3d_assets`, `get_3d_asset`, `create_3d_upload`, and `finalize_3d_upload`.
|
|
15
15
|
|
|
16
|
-
The generator catalog is deliberately limited to `meshy-7` and `tripo-h3.1`. Both expose text/image/multi-image modes; use the live schemas for option availability, view order, limits, topology, texture/PBR, and pose controls. Do not invent common provider option names. Server defaults prioritize quality. Rigging is a separate Meshy operation for compatible textured humanoid GLBs; it is not an arbitrary creature or facial rig service.
|
|
16
|
+
The generator catalog is deliberately limited to `meshy-7` (Meshy 7.1; the CLI also accepts `meshy-7.1`) and `tripo-h3.1`. Both expose text/image/multi-image modes; use the live schemas for option availability, view order, limits, topology, texture/PBR, and pose controls. Do not invent common provider option names. Server defaults prioritize quality. Meshy's `geometry_resolution` sets geometry detail: text/image default to `2k` and also take `standard` or `4k` (4k costs more than 2k); multi-image takes `standard` (default) or `2k`. `ultra_mode` is a deprecated alias for 2k. Rigging is a separate Meshy operation for compatible textured humanoid GLBs; it is not an arbitrary creature or facial rig service.
|
|
17
17
|
|
|
18
18
|
Every option is accessible through `--options` JSON (`@path.json` supported), plus repeatable `--option key=value` overrides. Values parse as JSON when valid. Options and explicit input mode affect pricing, so obtain a fresh quote for the exact recipe. Estimates perform no file upload or provider generation. VideoDraft bills whole credits at 100 credits per dollar using the server's rounding rules. BYOK costs zero VideoDraft credits and runs on the connected user Fal key. Do not infer the user's Fal-account charges from a zero VideoDraft-credit quote.
|
|
19
19
|
|
|
@@ -104,6 +104,7 @@ An MCP session can begin without a project selected. Project selection belongs t
|
|
|
104
104
|
3. Create only when the user wants a new local edit. `action: "create"` accepts optional `name`, `fps`, `aspectRatio`, and `quality`.
|
|
105
105
|
4. Treat `isActive` as this session's target and `isVisible` as the project shown in the UI. Headless editing only needs the session target.
|
|
106
106
|
5. Use `action: "close"` only when closing is part of the task. It saves first and never deletes the project. Afterwards other calls answer `no_project` until you open or create a project again.
|
|
107
|
+
6. Your session edits its own project even while another project's window is in front. If the user says "this clip" or "here" and `edit_snapshot` has no `selection`, or `selection.visible` is false, they are looking at something else: ask before editing. An older editor may instead refuse the write because another project is in front; tell the user rather than taking the front yourself. Never change which project is in front with Computer Use or other UI automation.
|
|
107
108
|
|
|
108
109
|
Other `project_manage` operations: `create_timeline` and `select_timeline` for additional timelines, and `configure` for project settings (a frame-rate change applies to every timeline).
|
|
109
110
|
|
|
@@ -119,7 +120,7 @@ Do not substitute a hosted project ID for a native project. A hosted project can
|
|
|
119
120
|
- Send writes serially. Parallel writes against one project race each other's context.
|
|
120
121
|
- A refused call answers `status: "rejected"`: nothing changed, so fix what the message names and send it again. A service write that answers `failed` may have applied before a save or connection failed; inspect before repeating it.
|
|
121
122
|
- Use `inspect` for detail and verification: `timeline` for exact clip and track properties, `frame` for rendered frames of the composited result, `media` before describing source content, `color` for scopes, and `transcript` to locate spoken words.
|
|
122
|
-
-
|
|
123
|
+
- Clip `volume` is linear gain: `0` is silent, `1` plays the clip as recorded, and up to `5.62` (+15 dB) boosts it. Volume keyframes stay `0` to `1`. Boost sparingly and read the export check, which reports clipping.
|
|
123
124
|
|
|
124
125
|
## Edit with recipes
|
|
125
126
|
|
|
@@ -82,7 +82,7 @@ videodraft generate image \
|
|
|
82
82
|
|
|
83
83
|
SCRIPT=$(videodraft avatar script "why our espresso subscription saves you money" --style ad-style --json | jq -r .script)
|
|
84
84
|
AVATAR=$(videodraft avatar create ./media/avatar.png --script "$SCRIPT" --voice elevenlabs-kPzsL2i3teMYv0FxEYQ6 --ar 9:16 --json | jq -r .avatar_video_id)
|
|
85
|
-
videodraft avatar render "$AVATAR" --resolution 720p # VEED Fabric paid step;
|
|
85
|
+
videodraft avatar render "$AVATAR" --resolution 720p # VEED Fabric paid step; check the cost first with --estimate
|
|
86
86
|
```
|
|
87
87
|
|
|
88
88
|
`avatar script` and `avatar create` (including speech) are bundled/free. In this example only the optional portrait generation and Fabric render spend credits.
|
|
@@ -30,8 +30,22 @@ Tier 1 is the rows marked **T1** below. Every other catalog model is Tier 2 and
|
|
|
30
30
|
| 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 |
|
|
31
31
|
| T1: Complex multi-image composition, precise editing, or a strong alternate interpretation | `gpt-image-2.5-sunburst` | More fidelity/detail; 16 references, quality through max |
|
|
32
32
|
| T1: Vector / SVG output (logos, icons, illustrations that must scale) | `recraft-v4` | Recraft V4.1 text-to-vector; SVG only, no reference images |
|
|
33
|
-
| T2:
|
|
34
|
-
|
|
33
|
+
| T2: xAI at 2K or with a quality tier, up to 3 edit references | `grok-imagine-2.0` | 1K/2K, low/medium quality, small charge per reference image |
|
|
34
|
+
|
|
35
|
+
Ideogram 4.5 (`ideogram-v4.5`) replaces 4.0 in the same Tier 2 position. Text-to-image: `--quality low|medium|high` (medium default), `--resolution 1K|2K`, `--ar`, `--num 1..8`, `--seed`, `--prompt-expansion true|false`. Editing: `--source-image <url|file>` plus up to four `--ref` images; without a source flag the first `--ref` is the source. `--edit-precision regular|high`; regular edits also support `--quality very_low`. `--mask <url|file>` uses black for edits, white for preserved regions and must match source dimensions; masked edits allow three additional references. Precise/masked edits require `--ar auto` with no resolution or custom dimensions. `--image-width` and `--image-height` select exact supported generation sizes or 32px-grid regular-edit sizes (min 256px, max 4MP, within 6:1). Expansion is text-to-image only. Reference/mask/precision do not add a separate surcharge.
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
videodraft generate image 'A poster with the exact title "SUMMER"' --model ideogram-v4.5 --quality high --resolution 2K --num 2 --estimate
|
|
39
|
+
videodraft generate image 'Replace the sign text with "OPEN"' --model ideogram-v4.5 --source-image source.png --ref lettering.png --mask mask.png --edit-precision high --ar auto --quality medium
|
|
40
|
+
videodraft costs ideogram-v4.5 --type image --quality very_low --ref-images 1 --num 2
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
FLUX 3 image (`flux-3-image`, not the `flux-3` video model) 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.
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
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
|
|
47
|
+
videodraft generate image 'Place the mug from image 1 on the desk in image 2, keep the lighting of image 2' --model flux-3-image --ref mug.png --ref desk.png --num 2
|
|
48
|
+
```
|
|
35
49
|
|
|
36
50
|
GPT Image 2.5 has two IDs: `gpt-image-2.5-flare` replaces the former GPT Image 2 recommendation; `gpt-image-2.5-sunburst` is the precision/detail alternative. Other model recommendations are unchanged. Explicit `gpt-image-2` selections continue to use the previous model.
|
|
37
51
|
|
|
@@ -46,24 +60,24 @@ videodraft generate image 'A blue glass bird' --model gpt-image-2.5-flare --ar 1
|
|
|
46
60
|
|
|
47
61
|
### Videos
|
|
48
62
|
|
|
49
|
-
| Need | Choose | Important limits
|
|
50
|
-
| -------------------------------------------------------------------------------------------------------------- | ------------------------ |
|
|
51
|
-
| T1: Most generation, first/last-frame, mixed-reference, source-edit, or extension requests | `gemini-omni-1.1-flash` | 3-10s output; 360p/720p/1080p/4K
|
|
52
|
-
| 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
|
|
53
|
-
| T2: Document or webpage reference generation; by name otherwise | `wan-3.0` | 2-30s or auto; 480p/720p/1080p
|
|
54
|
-
| T2: 480p/768p/2K/4K with native stereo audio, first/last frames, or mixed image/video/audio references | `minimax-h3` | 5-15s;
|
|
55
|
-
| T1: Text, first/last-frame, or mixed-reference video with native audio and stronger prompt adherence | `minimax-h3-max` | 5-15s;
|
|
56
|
-
| 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
|
|
57
|
-
| 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
|
|
58
|
-
| 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
|
|
59
|
-
| 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
|
|
60
|
-
| T1: Cinematic 3-15s with reference images, image/video elements, first+last frame, audio, or 4K | `kling-o3` | 7 combined image refs/elements, reduced to 4 with a video element; Standard/Pro/4K
|
|
61
|
-
| T1: Kling 3-15s image-to-video with first+last frame, image/video elements, multi-prompt, audio, or 4K | `kling-3.0` | Elements require a start image; image or video elements can bind voice_id; Standard/Pro/4K
|
|
62
|
-
| T2: User explicitly requests Veo, or the selected workflow specifically needs Veo | `google-veo3.1` | Good fallback, but not the preferred general model
|
|
63
|
+
| Need | Choose | Important limits |
|
|
64
|
+
| -------------------------------------------------------------------------------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
65
|
+
| T1: Most generation, first/last-frame, mixed-reference, source-edit, or extension requests | `gemini-omni-1.1-flash` | 3-10s output; 360p/720p/1080p/4K; audio always; up to 10 image inputs, and 3 reference videos <=3s on generate only; edit source <=10s; continuation or 3-10s extension of a 1-30s source, 40s total reachable only by extending from <=30s |
|
|
66
|
+
| 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 |
|
|
67
|
+
| 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 |
|
|
68
|
+
| 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 |
|
|
69
|
+
| 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 |
|
|
70
|
+
| 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 |
|
|
71
|
+
| 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 |
|
|
72
|
+
| 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 |
|
|
73
|
+
| 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 |
|
|
74
|
+
| T1: Cinematic 3-15s with reference images, image/video elements, first+last frame, audio, or 4K | `kling-o3` | 7 combined image refs/elements, reduced to 4 with a video element; Standard/Pro/4K |
|
|
75
|
+
| T1: Kling 3-15s image-to-video with first+last frame, image/video elements, multi-prompt, audio, or 4K | `kling-3.0` | Elements require a start image; image or video elements can bind voice_id; Standard/Pro/4K |
|
|
76
|
+
| T2: User explicitly requests Veo, or the selected workflow specifically needs Veo | `google-veo3.1` | Good fallback, but not the preferred general model |
|
|
63
77
|
|
|
64
78
|
Routing rules:
|
|
65
79
|
|
|
66
|
-
- Inexpensive pass or draft at 480p/768p with native audio: use MiniMax H3 Max
|
|
80
|
+
- Inexpensive pass or draft at 480p/768p with native audio: use MiniMax H3 Max.
|
|
67
81
|
- Grok 1.5 reference mode accepts 1-7 images only. Address them in array order as `<IMAGE_0>` through `<IMAGE_6>`. Do not combine reference images with `--start-image`, `--end-image`, `--ref-video`, or `--ref-audio`.
|
|
68
82
|
- Grok 1.5 first-frame mode accepts one `--start-image`, derives the output aspect ratio from that image, and does not support `--end-image`. Text and first-frame modes support 480p, 720p, or 1080p. Reference mode supports 480p or 720p.
|
|
69
83
|
- Grok 1.5 always generates native audio. Do not pass `--no-audio`, `--seed`, `--negative`, or `--quality`.
|
|
@@ -78,12 +92,11 @@ Routing rules:
|
|
|
78
92
|
- Seedance reference mode and first-plus-last-frame mode are separate. Do not promise reference video/audio plus a last frame in one generation.
|
|
79
93
|
- Multi-prompt sequencing: use Kling 3.0 Turbo, Kling O3, or Kling 3.0.
|
|
80
94
|
- Kling 3.0 image-to-video and Kling O3 reference-to-video accept repeatable structured `--element` JSON. Each element is image-backed (`frontal_image_url` plus 1-3 `reference_image_urls`) or video-backed (`video_url`). Either form may include `voice_id`. Keep the voice ID inside the same element so the association is preserved. Reference them as `@Element1`, `@Element2`. Kling V3 Turbo rejects elements.
|
|
81
|
-
- Kling 2.6 Pro image-to-video accepts one or two repeatable `--voice-id` values. Cite them as `<<<voice_1>>>` and `<<<voice_2>>>` in the prompt. Voice control costs
|
|
82
|
-
- Kling V3 voice control
|
|
95
|
+
- Kling 2.6 Pro image-to-video accepts one or two repeatable `--voice-id` values. Cite them as `<<<voice_1>>>` and `<<<voice_2>>>` in the prompt. Voice control costs more per second. Use `videodraft kling-voices list|create|delete` to manage the separate Kling video-control voice library. Creating a voice requires a clean 5-30 second, up-to-50MB single-speaker `.mp3`, `.wav`, `.mp4`, or `.mov` sample plus `--confirm-consent`. Creation has a small charge on the platform Fal account and is free with Fal BYOK; use the create command's `--estimate` flag to check without creating.
|
|
96
|
+
- Kling V3 voice control (Standard and Pro) also costs more per second than plain generation.
|
|
83
97
|
- Seedance quality: `mini` for the lowest cost, `fast` for speed, `standard` for maximum quality and for 1080p/4K. Seedance 2.5 has a single tier and ignores `--quality`.
|
|
84
98
|
- Longer than 15 seconds, or more than 9 image / 3 video / 3 audio references: use Seedance 2.5. It reaches 30s and 30/10/10 references (50 files total) at 480p/720p/1080p, but has no 4K.
|
|
85
|
-
- Seedance 2.x
|
|
86
|
-
- If a Seedance request made with the option off fails with `SEEDANCE_REAL_PERSON_OPT_IN_REQUIRED`, estimate the higher rate, follow the user's spend policy, and retry once with the option on. The response also carries `retry_with: { allow_real_people: true }`, `cli_flag: "--allow-real-people"`, and `retry_policy: "once"`. If the option was already on, do not repeat the same request. Byteplus may accept a task and reject the output later. VideoDraft refunds that failed generation, but it cannot reroute the asynchronous failure to Fal. Rephrase or change the references instead.
|
|
99
|
+
- Seedance 2.x has no real-people option. A video that can't be made at the listed rate, usually one showing a real person, costs a higher rate, charged before it starts.
|
|
87
100
|
|
|
88
101
|
### Video edit and motion-control categories
|
|
89
102
|
|
|
@@ -93,7 +106,7 @@ Use `videodraft models video --category video_edit` for existing-video transform
|
|
|
93
106
|
| ------------------------------------------ | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
94
107
|
| Most edits of a source up to 10s (DEFAULT) | `videodraft edit video <video> "..."` (auto-selects `gemini-omni-1.1-flash`) | Source <=10s or it REFUSES; up to 10 image refs and 3 creative video refs <=3s each; 360p/720p/1080p/4K; audio always regenerated (no `--preserve-audio`) |
|
|
95
108
|
| Cheapest simple prompt edit | `videodraft edit video <video> "..." --model grok-imagine-video-edit` | No image refs; source silently truncated to 8s; auto/480p/720p |
|
|
96
|
-
| Edit with several image references | `--model happy-horse-video-edit --ref ...` | Up to 5 refs; 720p/1080p; source silently truncated to 15s; highest rate
|
|
109
|
+
| Edit with several image references | `--model happy-horse-video-edit --ref ...` | Up to 5 refs; 720p/1080p; source silently truncated to 15s; highest rate |
|
|
97
110
|
| Controlled Kling edit | `--model kling-o3-video-ref-edit --ref ...` | Up to 4 refs; Standard/Pro; source silently clamped to 3-10s |
|
|
98
111
|
| Transfer reference motion to an image | `videodraft edit motion <image> [direction] --motion-video <video>` | Prompt/direction is optional; Kling V3 default; optional one image-only `--element`; element requires video orientation |
|
|
99
112
|
|
|
@@ -162,13 +175,13 @@ The managed renderer is VEED Fabric Fast (`veed/fabric-1.0/fast`). Direct Fabric
|
|
|
162
175
|
|
|
163
176
|
The portrait is passed as the avatar's character image, not as a generic video's start frame. Prefer rendering directly at 720p. Use 480p only when the user prioritizes lower cost. Avatar script generation and `avatar create` (including speech) are bundled/free. Confirm the Fabric render cost, plus portrait generation or upscaling when needed.
|
|
164
177
|
|
|
165
|
-
Direct Fabric text/audio, H3 Max Lip Sync, and Sync Labs do not use the managed avatar record. The CLI uploads local portrait, video, and audio files automatically. `avatar fabric --speed fast` applies only to audio mode. `avatar h3-lipsync` takes no prompt: pick `--resolution 480P|768P|1080P|2K` (default 768P), an optional `--seed`, `--no-transcription` to sync without transcribing the audio (transcription is on by default), and `--safety-checker` only when the user asks for Fal's checker. The portrait's width / height must be 0.4-2.5, and audio shorter than 5 seconds is refused before any charge. Sync
|
|
178
|
+
Direct Fabric text/audio, H3 Max Lip Sync, and Sync Labs do not use the managed avatar record. The CLI uploads local portrait, video, and audio files automatically. `avatar fabric --speed fast` applies only to audio mode. `avatar h3-lipsync` takes no prompt: pick `--resolution 480P|768P|1080P|2K` (default 768P), an optional `--seed`, `--no-transcription` to sync without transcribing the audio (transcription is on by default), and `--safety-checker` only when the user asks for Fal's checker. The portrait's width / height must be 0.4-2.5, and audio shorter than 5 seconds is refused before any charge. Sync is billed per verified audio second; under Fal BYOK, `sync_mode` remains available but `temperature` and `active_speaker` are ignored by the provider.
|
|
166
179
|
|
|
167
180
|
### Upscaling / enhancement
|
|
168
181
|
|
|
169
|
-
- **Images**: Topaz via `videodraft upscale image <url-or-file> --scale 1x|2x|4x [--mode precision|generative|creative] [--model <name>]`. Modes: `generative` (default; Wonder 3.5, Topaz's recommended model for AI-generated images; `Redefine` takes `--prompt`, `--creativity 1-6`, `--texture 1-5`), `precision` (faithful and cheapest; Standard V2, High Fidelity V3, Low Resolution V2, CGI, Text Refine; use for clean real photos), `creative` (Bloom 2; artistic, `--prompt`, `--creativity 1-9`). Extra knobs: `--no-face-enhance`, `--face-strength`, `--sharpen`, `--denoise`, `--fix-compression`, `--format png`. Use 1x for light enhancement without enlargement, 2x as the general default, and 4x only when the source quality and target size justify it. The server must verify dimensions from a readable image of at most 50 MB; `--width` and `--height` are compatibility hints and cannot bypass a failed probe. The result may be immediate or queued; the CLI waits by default. Use `--no-wait` for an async job ID, and poll it with `status` or `wait`. Cost:
|
|
170
|
-
- **Videos**: Topaz via `videodraft upscale video <url-or-file> --resolution 720p|1080p|4k` (preferred) or `--scale 2x`, plus `--mode precision|generative|creative` and `--model <name>`. `generative` (default; Starlight Precise 2.6, Topaz's recommended model for AI-generated footage; Starlight Fast 2 at half price)
|
|
171
|
-
- **Frame interpolation / slow motion**: `videodraft interpolate <url-or-file> --fps 60 [--model Apollo|Chronos|Aion] [--slowdown 1-8]` (MCP `interpolate_video`). Resolution is unchanged. Apollo (default) for smooth general conversion, Chronos for natural slow motion, Aion for extreme slow motion. Apollo/Chronos
|
|
182
|
+
- **Images**: Topaz via `videodraft upscale image <url-or-file> --scale 1x|2x|4x [--mode precision|generative|creative] [--model <name>]`. Modes: `generative` (default; Wonder 3.5, Topaz's recommended model for AI-generated images; `Redefine` takes `--prompt`, `--creativity 1-6`, `--texture 1-5`), `precision` (faithful and cheapest; Standard V2, High Fidelity V3, Low Resolution V2, CGI, Text Refine; use for clean real photos), `creative` (Bloom 2; artistic, `--prompt`, `--creativity 1-9`). Extra knobs: `--no-face-enhance`, `--face-strength`, `--sharpen`, `--denoise`, `--fix-compression`, `--format png`. Use 1x for light enhancement without enlargement, 2x as the general default, and 4x only when the source quality and target size justify it. The server must verify dimensions from a readable image of at most 50 MB; `--width` and `--height` are compatibility hints and cannot bypass a failed probe. The result may be immediate or queued; the CLI waits by default. Use `--no-wait` for an async job ID, and poll it with `status` or `wait`. Cost: per started block of output megapixels; precision is cheapest, then generative, then creative.
|
|
183
|
+
- **Videos**: Topaz via `videodraft upscale video <url-or-file> --resolution 720p|1080p|4k` (preferred) or `--scale 2x`, plus `--mode precision|generative|creative` and `--model <name>`. `generative` (default; Starlight Precise 2.6, Topaz's recommended model for AI-generated footage; Starlight Fast 2 at half price) is billed per second, more at 4K. `precision` (Proteus, Proteus Natural, Iris, Gaia 2 for animation, Rhea, Theia, Artemis, Dione) is much cheaper, billed per second by output resolution; use it for real footage or when cost matters. `creative` (Astra 2, `--prompt`, `--creativity`, `--realism`, `--sharp`) always renders 4K and costs the most. `--fps 60` delivers 60fps on the same pass; any output above 30fps (including a 50/60fps source) doubles every rate; the server must verify duration, dimensions, and frame rate from an MP4/MOV source of at most 100 MB. `--duration`, `--width`, `--height`, and `--source-fps` are compatibility hints and cannot override billing or bypass a failed probe. The same source-verification requirement applies to frame interpolation. `--scale` also accepts intermediate factors such as `1.5x`. Max source length 5 minutes. The job is asynchronous; the CLI waits by default, while MCP callers poll `check_generation_status`. MCP video input must be VideoDraft-hosted, so upload local or external sources first.
|
|
184
|
+
- **Frame interpolation / slow motion**: `videodraft interpolate <url-or-file> --fps 60 [--model Apollo|Chronos|Aion] [--slowdown 1-8]` (MCP `interpolate_video`). Resolution is unchanged. Apollo (default) for smooth general conversion, Chronos for natural slow motion, Aion for extreme slow motion. Apollo/Chronos are billed per output second (more at 4K); Aion costs more. These rates cover targets up to 60fps; above 60fps multiply by target FPS / 60 (120fps doubles the rate). Output seconds = source seconds × slowdown. The final charge rounds up to a whole credit.
|
|
172
185
|
- Use upscaling to preserve the image/video while improving detail, resolution, or cleanup. It cannot fix the wrong subject, misspelled text, bad framing, unwanted objects, broken continuity, or incorrect motion. Use an edit or regeneration for those problems. Keep `generative` for AI-generated sources; switch to `precision` for clean real photos/footage or a cheap pass, and `creative` only when the user wants an artistic reinterpretation.
|
|
173
186
|
- For a new Fabric avatar, render directly at 720p instead of rendering at 480p and then upscaling. Upscale the source portrait first only when the portrait itself is low quality.
|
|
174
187
|
|
|
@@ -176,34 +189,35 @@ Direct Fabric text/audio, H3 Max Lip Sync, and Sync Labs do not use the managed
|
|
|
176
189
|
|
|
177
190
|
- 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.
|
|
178
191
|
- Most video models support only 16:9 / 9:16 / 1:1. A 3:4 request hard-fails on most.
|
|
179
|
-
- `--seed` reproduces a specific output on models that support it (e.g.
|
|
180
|
-
- `--rendering-speed`
|
|
181
|
-
- `seedream-v5-pro` supports unified text-to-image and reference-image editing with up to 10 image references. Use `--resolution 1K`
|
|
192
|
+
- `--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
|
+
- `--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.
|
|
194
|
+
- `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).
|
|
182
195
|
- 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.
|
|
183
196
|
- The top-level prompt is OPTIONAL for Gemini Omni 1.1 Flash media-input or continuation calls, Wan 3.0 frame/reference modes, `generate video` with multi-prompt models, and Kling 3.0 Turbo (`--model kling-v3-turbo`) image-to-video. Text-only Gemini and Wan calls still require a prompt unless their live schema says otherwise.
|
|
184
|
-
- Hosted AI Production fallback: `videodraft produce <project> --mode full_video` generates one Seedance 2 video per scene
|
|
197
|
+
- Hosted AI Production fallback: `videodraft produce <project> --mode full_video` generates one Seedance 2 video per scene. The MCP equivalent is `produce_project` with `mode: "full_video"`. Poll with `videodraft generations`, then `videodraft finalize <project>` swaps them into the hosted timeline before `export`. In VideoDraft ADE, do not choose this path while `videodraft_editor` is available unless the user explicitly requests hosted production. Generate or download the scene assets, import them, and assemble/export with the native editor instead. If the user explicitly requests another compatible video model for a hosted production, do not use this fixed Seedance path; generate the project shots manually with the requested model and attach them to the hosted timeline.
|
|
185
198
|
|
|
186
199
|
## Cost model
|
|
187
200
|
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
-
|
|
191
|
-
-
|
|
192
|
-
-
|
|
193
|
-
-
|
|
194
|
-
-
|
|
195
|
-
-
|
|
201
|
+
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:
|
|
202
|
+
|
|
203
|
+
- 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).
|
|
204
|
+
- Video: per output second; the rate depends on model, resolution, quality and native audio on/off.
|
|
205
|
+
- 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.
|
|
206
|
+
- 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.
|
|
207
|
+
- MiniMax H3 Max: per output second at 480p or 768p (default), plus pooled reference tokens: a free allowance, then a charge per 1,000 tokens. An image is `(width x height) / 1024` tokens; a reference video is 2,886 tokens per second at 480p or 7,459 at 768p; reference audio is about 2,121 per second. Pass `--ref-audio-seconds` for an exact estimate with audio references. The server measures each reference image, so a quote that assumes 1024x1024 is a floor.
|
|
208
|
+
- Wan 3.0: per output second by resolution. Auto duration reserves 30 seconds and reconciles unused credits from the provider-reported output duration. Fal BYOK charges zero VideoDraft credits.
|
|
209
|
+
- Grok Imagine Video 1.5: per output second by resolution, plus a small charge for each first-frame or reference image. Native generated audio is part of every output.
|
|
210
|
+
- Kling: per output second by tier and audio; voice control costs more.
|
|
211
|
+
- Seedance 2.0 / 2.5: per output second by tier and resolution. A video that can't be made at the base rate, usually one showing a real person, costs a higher rate; the difference is charged before it starts. `get_model_costs` returns both (`cost` and `higher_rate_cost`). Reference videos bill input seconds alongside output.
|
|
196
212
|
- Shot-image batches: one image per shot (+1 grid image per scene in `--grid` mode) — the largest single spend in the pipeline.
|
|
197
|
-
- VEED Fabric avatar renders:
|
|
198
|
-
- Direct VEED Fabric:
|
|
199
|
-
- MiniMax H3 Max Lip Sync:
|
|
200
|
-
- Sync Labs Lipsync 2:
|
|
201
|
-
- Voiceover TTS:
|
|
202
|
-
- Lyria music: flat per track
|
|
203
|
-
- Seed Audio 1.0:
|
|
204
|
-
- ElevenLabs audio: sound effects are per second, dialogue is per character, music/voice-changer/dubbing are per started minute
|
|
205
|
-
- Seedance 2.0 / 2.5 real people: allowed by default, which keeps Byteplus first, permits a submit-time Fal fallback, and prices at Fal's rate for that tier: 2.0 Mini 8/16 cr/s, Fast 11/25, Standard 14/31/69/156, 2.5 23/48/114 for 480p/720p/1080p. `--no-allow-real-people` uses the Byteplus-priced path instead (2.0 Mini 4/8, Fast 6/13, Standard 7/16/38/78, 2.5 11/24/57); Byteplus refuses real-person likenesses, so a likeness-policy failure then does not fall back. The gap is roughly 2x but not exactly: the Seedance 2.0 1080p pair is 38/69, or about 1.82x. If Byteplus accepts the task and later rejects the generated output, VideoDraft refunds the failure but does not resubmit it to Fal. Turn the option off only for the cheapest run when nothing in the job is a real identifiable person.
|
|
206
|
-
- Grok Imagine images: `grok-imagine` is a flat 2 cr (3 with a reference). `grok-imagine-2.0` is a separate, newer model priced by resolution and quality: 1K 4 (low) / 6 (medium), 2K 6 / 8, plus 1 cr per reference image (up to 3). v1 is NOT superseded — pick it when cost matters more than 2K.
|
|
213
|
+
- VEED Fabric avatar renders: per second by resolution. Avatar creation and its speech are bundled/free; only optional portrait generation/upscaling adds cost before the render.
|
|
214
|
+
- Direct VEED Fabric: per second by resolution; fast audio costs more than text or normal audio.
|
|
215
|
+
- MiniMax H3 Max Lip Sync: per output second by resolution (768P default). The video runs as long as the audio (at least 5s; only the first 14.8s is used), billed on the server-measured length rounded up, so at most 15 seconds. Use MP3, WAV, M4A (AAC), or AAC audio; other formats run only on the user's own Fal key.
|
|
216
|
+
- Sync Labs Lipsync 2: per verified audio second.
|
|
217
|
+
- Voiceover TTS: per character. ElevenLabs Turbo (Eleven v4 Turbo) costs less than Standard (Eleven v4), and cloned `custom-*` voices cost more; this applies to standalone voiceovers AND per-scene narration during `produce`. Quote Turbo with model id `voiceover-turbo` (CLI: `costs voiceover --mode turbo`) and cloned voices with `voiceover-cloned`. Silent tracks are free. Voice cloning itself is a flat fee per clone.
|
|
218
|
+
- Lyria music: one flat price per track (Clip, 3.5 and legacy Pro differ). Fal BYOK uses zero VideoDraft credits.
|
|
219
|
+
- Seed Audio 1.0: per actual output minute, prorated and rounded up to a whole credit. VideoDraft reserves the 120-second maximum and refunds the unused portion after generation. Fal BYOK is free.
|
|
220
|
+
- ElevenLabs audio: sound effects are per second, dialogue is per character, music/voice-changer/dubbing are per started minute (Music v2.5 and v1 cost the same); estimate a composition plan with its total length. Voice changer and dubbing reject source media above 300s in the current synchronous flow.
|
|
207
221
|
- xAI bills refused requests, so failed Grok generations are not refunded.
|
|
208
222
|
- Upscales: priced by output size, mode, and (video) duration/fps; see the Upscaling section above.
|
|
209
223
|
|
|
@@ -219,12 +233,11 @@ videodraft costs minimax-h3-max --type video --duration 10 --resolution 768p --r
|
|
|
219
233
|
videodraft costs grok-imagine-video-1.5 --type video --duration 8 --resolution 720p --ref-images 4
|
|
220
234
|
videodraft costs seedance-2 --type video --duration 15 --resolution 720p --quality standard --audio
|
|
221
235
|
videodraft costs grok-imagine-2.0 --type image --resolution 2K --quality medium --num 2
|
|
222
|
-
videodraft costs seedance-2 --type video --duration 15 --resolution 720p --quality standard --audio --no-allow-real-people # lower Byteplus-only rate
|
|
223
236
|
videodraft costs elevenlabs-dubbing --type audio --duration 60
|
|
224
237
|
videodraft costs seed-audio-1.0 --type audio --duration 60 # scenario only; model controls actual length
|
|
225
238
|
videodraft costs elevenlabs-dialogue --type audio --chars 350
|
|
226
|
-
videodraft costs voiceover --type audio --chars 800 # TTS
|
|
227
|
-
videodraft costs voiceover --type audio --chars 800 --mode turbo # ElevenLabs Turbo
|
|
239
|
+
videodraft costs voiceover --type audio --chars 800 # TTS, per character
|
|
240
|
+
videodraft costs voiceover --type audio --chars 800 --mode turbo # ElevenLabs Turbo, cheaper per character
|
|
228
241
|
videodraft generate video "..." --model gemini-omni-1.1-flash --estimate # same quote, inline
|
|
229
242
|
videodraft generate video "..." --model minimax-h3-max --duration 8 --resolution 768p --prompt-expansion-mode balanced
|
|
230
243
|
```
|
|
@@ -46,8 +46,8 @@ Use direct asset tools for standalone images, clips, audio, upscales, and descri
|
|
|
46
46
|
- **The storyboard is generated FROM the script**, never from the raw idea. `videodraft create` runs the whole chain correctly. Don't call `generate_storyboard_scenes` with a raw idea as the "script".
|
|
47
47
|
- **Visual consistency**: never generate a storyboard shot in isolation. Shot prompts carry `[[asset:Name]]` / `[[shot:X-Y]]` tags that `generate_shot_images` resolves against the project's visual assets and prior shots. When generating a single shot whose prompt has no tags, pass `--ref` images yourself (the project's visual assets and/or the previous shot's image; `projects get` exposes both). For scenes with multiple shots or recurring characters, prefer `videodraft shots <project> --model <selected-image-model> --grid`: preserve an explicitly requested compatible image model, otherwise use `nano-banana-2`. It creates one coherent scene grid, then decodes it into individual shot images.
|
|
48
48
|
- **Reference-first video**: when identity, styling, or composition matters, do not generate each motion clip from text alone. Generate or select the shot still first, then pass the decoded shot image as `--start-image` or `--ref` to the selected video model. AI Production already composes scene grids and sends them to Seedance as references. If the user explicitly requests another compatible video model, bypass fixed Seedance full-video mode and generate the per-shot clips with the requested model, using the individual decoded shot images as anchors.
|
|
49
|
-
- **Seedance full-video
|
|
50
|
-
- **Narration voice mode**: ElevenLabs narration runs on Eleven v4. Standard is the default and the best quality
|
|
49
|
+
- **Seedance full-video pricing**: hosted `full_video` has no real-people option. A scene video that can't be made at the listed rate, usually one showing a real person, costs a higher rate, charged before it starts.
|
|
50
|
+
- **Narration voice mode**: ElevenLabs narration runs on Eleven v4. Standard is the default and the best quality. `videodraft produce <project> --voice-mode turbo` (MCP `produce_project` with `voice_mode: "turbo"`) uses Eleven v4 Turbo, which is faster and cheaper. For one scene, `videodraft generate voiceover --project <id> --scene N --mode turbo` (MCP `generate_voiceover` with `mode: "turbo"`) does the same. Google, OpenAI and cloned `custom-*` voices ignore the mode.
|
|
51
51
|
- **Hold off generating shot images while the user is still iterating** on storyboard structure.
|
|
52
52
|
- **produce → export ordering**: `export` requires a produced project where every production scene has timeline media. If `produce` returns `generating_shot_images`, poll the job ids it returns, then re-run produce.
|
|
53
53
|
- **Do not attach motion clips before production exists**: run `produce` successfully first, then attach finished motion clips to the production timeline. Attaching before `production_data` exists cannot place them in the final timeline.
|