videodraft 0.26.0 → 0.27.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 +9 -8
- package/dist/client.js +1 -9
- package/dist/index.js +163 -87
- package/package.json +1 -1
- package/skills/index.json +10 -10
- package/skills/videodraft/SKILL.md +14 -14
- package/skills/videodraft/references/3d.md +1 -1
- package/skills/videodraft/references/editor.md +2 -1
- package/skills/videodraft/references/models.md +21 -9
- package/skills/videodraft/references/pipeline.md +1 -1
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "videodraft",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.27.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
|
@@ -7,13 +7,13 @@
|
|
|
7
7
|
"files": [
|
|
8
8
|
{
|
|
9
9
|
"path": "references/3d.md",
|
|
10
|
-
"sha256": "
|
|
11
|
-
"bytes":
|
|
10
|
+
"sha256": "97560d188df8f6fa3e6735fac42b92f14032cd0bbdf4d904f5916196faac2e8b",
|
|
11
|
+
"bytes": 5436
|
|
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",
|
|
@@ -22,18 +22,18 @@
|
|
|
22
22
|
},
|
|
23
23
|
{
|
|
24
24
|
"path": "references/models.md",
|
|
25
|
-
"sha256": "
|
|
26
|
-
"bytes":
|
|
25
|
+
"sha256": "62f33a43f741899683476d66d92ecdf0dc9b978551c4e1ed7a85df53d7a9dcfd",
|
|
26
|
+
"bytes": 46810
|
|
27
27
|
},
|
|
28
28
|
{
|
|
29
29
|
"path": "references/pipeline.md",
|
|
30
|
-
"sha256": "
|
|
31
|
-
"bytes":
|
|
30
|
+
"sha256": "5317a6e661f0c4adf0377c6e6b4ec9833a238c84b5b82a103f96cbdb71797e80",
|
|
31
|
+
"bytes": 14269
|
|
32
32
|
},
|
|
33
33
|
{
|
|
34
34
|
"path": "SKILL.md",
|
|
35
|
-
"sha256": "
|
|
36
|
-
"bytes":
|
|
35
|
+
"sha256": "67b6462dcf5e17834decd3574a55a20614fd0ec93ebb1c6f64612c2187d9fb1a",
|
|
36
|
+
"bytes": 46485
|
|
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 (about twice as much); 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
|
|
|
@@ -102,14 +96,14 @@ Every `videodraft models image|video|audio --json` entry carries `tier` (1 or 2)
|
|
|
102
96
|
- `minimax-h3-max`: 480p/768p pricing (5/8 cr/s, 768p default), native audio, and 5-15s text, first/last-frame, or mixed-reference generation. Reference mode accepts up to 9 images, 3 videos, and 3 audio clips, with at most 12 files total, cited as `Image 1`, `Video 1`, and `Audio 1` in array order. It supports a reproducibility seed and `disabled` / `balanced` / `quality` prompt expansion.
|
|
103
97
|
- `wan-3.0` (Tier 2): unified 2-30s text, first/last-frame, or ordered mixed-reference generation at 480p/720p/1080p (7/14/28 cr/s), with optional native audio. Reference mode accepts up to 10 images, 5 videos, and 5 audio clips, at most 20 media files total; video and audio each total at most 15 seconds. `--auto-duration` reserves 30 seconds and reconciles to the provider-reported output length. Document/web references use `--file-url` or `--web-url` and require `--thinking`.
|
|
104
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 roughly a third of the cost. Auto duration is text/first-frame only.
|
|
105
|
-
- `seedance-2`: 11-15s, video/audio/mixed references, wider ratios, selectable audio, or first/last frames. `
|
|
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
|
|
|
@@ -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 low/medium/high costs 3/6/22 credits per output (default medium); regular edits also offer very_low at 1 credit. 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 costs 5-10 credits at 1K, 20-24 at 2K and 77-82 at 4K, set by the 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
|
|
|
@@ -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 adds 20 credits over 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
|
|
|
@@ -30,9 +30,23 @@ 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: By name, or an explicitly requested xAI look | `grok-imagine` | 2 cr flat (3 with a reference); 1 reference image |
|
|
34
33
|
| T2: xAI at 2K or with a quality tier, up to 3 edit references | `grok-imagine-2.0` | 1K 4 (low) / 6 (medium), 2K 6 / 8, +1 cr per reference image |
|
|
35
34
|
|
|
35
|
+
Ideogram 4.5 (`ideogram-v4.5`) replaces 4.0 in the same Tier 2 position. Text-to-image: `--quality low|medium|high` (3/6/22 credits, 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` (1 credit). `--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 costs 5-10 credits at 1K, 20-24 at 2K and 77-82 at 4K, set by the 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
|
+
```
|
|
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
|
|
|
38
52
|
Use the same basic image controls as GPT Image 2: `--ref`, `--ar`, `--resolution 1K|2K|4K`, `--quality`, and `--num 1..4`. GPT Image 2.5 quality supports auto/low/medium/high/xhigh/max. Auto is priced at Max in customer-credit estimates. The default platform path uses OpenAI; a selected personal connection stays exclusive. A Pika personal connection requires an explicit quality from low/medium/high/xhigh/max because its upstream API has no auto value. Other unsupported connection settings return an error instead of switching payer or changing the request.
|
|
@@ -82,8 +96,7 @@ Routing rules:
|
|
|
82
96
|
- Kling V3 voice control costs 16 cr/s for Standard and 20 cr/s for Pro.
|
|
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
|
|
|
@@ -176,12 +189,12 @@ 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`
|
|
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.
|
|
181
194
|
- `seedream-v5-pro` supports unified text-to-image and reference-image editing with up to 10 image references. Use `--resolution 1K` for 7 credits/image or `--resolution 2K` for 14 credits/image.
|
|
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
|
|
|
@@ -202,8 +215,8 @@ Direct Fabric text/audio, H3 Max Lip Sync, and Sync Labs do not use the managed
|
|
|
202
215
|
- Lyria music: flat per track, 4 credits (Clip) / 10 credits (3.5) / 8 credits (legacy Pro). Fal BYOK uses zero VideoDraft credits.
|
|
203
216
|
- Seed Audio 1.0: 19 credits per actual output minute, prorated and rounded up to a whole credit. VideoDraft reserves the 120-second maximum of 38 credits and refunds the unused portion after generation. Fal BYOK is free.
|
|
204
217
|
- ElevenLabs audio: sound effects are per second, dialogue is per character, music/voice-changer/dubbing are per started minute. ElevenLabs Music v2.5 and v1 both cost 60 credits per started output minute; estimate a composition plan with its total length. Voice changer and dubbing reject source media above 300s in the current synchronous flow.
|
|
205
|
-
- Seedance 2.0 / 2.5
|
|
206
|
-
- Grok Imagine
|
|
218
|
+
- Seedance 2.0 / 2.5: 4/8 cr/s for 2.0 Mini, 6/13 for Fast, 8/16/40/82 for Standard, and 11/25/60 for 2.5, at 480p/720p/1080p/4K where offered. A video that can't be made at these rates, usually one showing a real person, costs the higher rate: 8/16 Mini, 11/25 Fast, 14/31/69/156 Standard, and 23/48/114 for 2.5; the difference is charged before it starts.
|
|
219
|
+
- Grok Imagine 2.0 images are priced by resolution and quality: 1K 4 (low) / 6 (medium), 2K 6 / 8, plus 1 cr per reference image (up to 3).
|
|
207
220
|
- xAI bills refused requests, so failed Grok generations are not refunded.
|
|
208
221
|
- Upscales: priced by output size, mode, and (video) duration/fps; see the Upscaling section above.
|
|
209
222
|
|
|
@@ -219,7 +232,6 @@ videodraft costs minimax-h3-max --type video --duration 10 --resolution 768p --r
|
|
|
219
232
|
videodraft costs grok-imagine-video-1.5 --type video --duration 8 --resolution 720p --ref-images 4
|
|
220
233
|
videodraft costs seedance-2 --type video --duration 15 --resolution 720p --quality standard --audio
|
|
221
234
|
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
235
|
videodraft costs elevenlabs-dubbing --type audio --duration 60
|
|
224
236
|
videodraft costs seed-audio-1.0 --type audio --duration 60 # scenario only; model controls actual length
|
|
225
237
|
videodraft costs elevenlabs-dialogue --type audio --chars 350
|
|
@@ -46,7 +46,7 @@ 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
|
|
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
50
|
- **Narration voice mode**: ElevenLabs narration runs on Eleven v4. Standard is the default and the best quality, at 10 credits per 1000 characters. `videodraft produce <project> --voice-mode turbo` (MCP `produce_project` with `voice_mode: "turbo"`) uses Eleven v4 Turbo, which is faster at 5 credits per 1000 characters. For one scene, `videodraft generate voiceover --project <id> --scene N --mode turbo` (MCP `generate_voiceover` with `mode: "turbo"`) does the same. Google, OpenAI and cloned `custom-*` voices ignore the mode.
|
|
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.
|