videodraft 0.13.2 → 0.14.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "videodraft",
-  "version": "0.13.2",
-  "description": "Official VideoDraft CLI \u2014 create AI videos, images and audio from your terminal. Agent-friendly: --json everywhere, stable exit codes, async job polling.",
+  "version": "0.14.0",
+  "description": "Official VideoDraft CLI — create AI videos, images and audio from your terminal. Agent-friendly: --json everywhere, stable exit codes, async job polling.",
   "license": "MIT",
   "type": "module",
   "homepage": "https://videodraft.ai/cli",

package/skills/index.json

@@ -17,18 +17,18 @@
         },
         {
           "path": "references/models.md",
-          "sha256": "af6162e85424272cd091639fc2232330993c4af55a72dadc8bd402a7d2b23cc9",
-          "bytes": 28436
+          "sha256": "b0ebca952f20b049753cb3c9c047eaa891e205f6df44d0aabf053094ce64065d",
+          "bytes": 30406
         },
         {
           "path": "references/pipeline.md",
-          "sha256": "7bc003b8189544f0da43bcb6ac47650e754ef719d96cd79953712c9d314fd35b",
-          "bytes": 11613
+          "sha256": "87b880b09c953cc08ab9d2859a01059984cc3a20c09d1f391ec489712d16c57a",
+          "bytes": 12870
         },
         {
           "path": "SKILL.md",
-          "sha256": "de4737b2e3e87f3eca323d287c5e44ad58564677f6f3544973c5a07d0f2ea3c7",
-          "bytes": 26059
+          "sha256": "f4191bd53e7cb0341b6f2f88a2f9a8fef5c05c19980dfcd64980178f49f21fa6",
+          "bytes": 28600
         }
       ]
     }

package/skills/videodraft/SKILL.md

@@ -50,6 +50,16 @@ If you are reading this skill through `videodraft skills show skill`, run `video
 
 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.
 
+### Seedance 2.x real-person rule
+
+Seedance 2.0 and 2.5 require an explicit, higher-priced routing choice for real-person likenesses:
+
+- Enable real-person support on the first request when supplied visual input media visibly contains a real identifiable person. This includes a start frame, end frame, reference image, or reference video. Keep the lower-priced Byteplus default for text-only requests, non-people, anime, and clearly synthetic or stylized characters that are not identifiable real people. For MCP use `allow_real_people: true`. For the CLI use `--allow-real-people`. Pass the same value to `get_model_costs` or `videodraft costs` so the estimate matches the charge.
+- The default is false. It uses the lower Byteplus-priced path, and a Byteplus likeness-policy refusal does not fall back to Fal. Enabling the option keeps Byteplus first but permits a submit-time fallback to Fal, which allows real-person likenesses. The request is charged at Fal's higher tier-specific rate even if Byteplus serves it.
+- If a request made without the option 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 enabled. 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.
+- Do not loop if the option was already enabled. 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.
+- For hosted AI Production, the same choice applies to every Seedance scene segment. Use `produce_project` with `mode: "full_video", allow_real_people: true`, or `videodraft produce <project> --mode full_video --allow-real-people`. If an earlier run partially submitted and returns the opt-in code, rerun that same project once with the option. 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.
+
 Every `videodraft models image|video|audio --json` response carries a top-level `recommended` array (best first) and stamps `recommended` / `recommended_for` on each entry. That is the authoritative preference order and it beats this page when they disagree. Preferred today: images `nano-banana-2`, `nano-banana-pro`, `gpt-image-2`; videos `gemini-omni-flash`, `seedance-2.5`, `seedance-2`, `kling-3.0`, `kling-v3-turbo`, `kling-o3`; video edits `gemini-omni-flash`; talking heads `veed-fabric`; motion transfer `kling-v3-motion-control`; audio ElevenLabs for anything with a voice and Lyria for instrumental music. Preference applies only when the user did not name a model.
 
 **Images:**

package/skills/videodraft/references/models.md

@@ -64,6 +64,8 @@ Routing rules:
 - Kling V3 voice control costs 16 cr/s for Standard and 20 cr/s for Pro.
 - 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`.
 - 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.
+- Real identifiable people in Seedance 2.x require an explicit routing and pricing opt-in. Set MCP `allow_real_people: true` or CLI `--allow-real-people` on the first request when supplied visual input media visibly contains one, including a start frame, end frame, reference image, or reference video. Keep the Byteplus default for text-only requests, non-people, anime, and clearly synthetic or stylized characters that are not identifiable real people. This keeps Byteplus first, permits a submit-time Fal fallback, and charges Fal's higher tier-specific rate.
+- If a default-priced Seedance request fails with `SEEDANCE_REAL_PERSON_OPT_IN_REQUIRED`, estimate the higher rate, follow the user's spend policy, and retry once with the option enabled. The response also carries `retry_with: { allow_real_people: true }`, `cli_flag: "--allow-real-people"`, and `retry_policy: "once"`. If the option was already enabled, 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.
 
 ### Video edit and motion-control categories
 
@@ -145,9 +147,9 @@ Direct Fabric text/audio and Sync Labs do not use the managed avatar record. The
 - `--seed` reproduces a specific output on models that support it (e.g. Flux, Ideogram V4); everything else ignores it. You do not need a seed for variation — `--num` already varies.
 - `--rendering-speed` applies to Ideogram (V3: `Default`/`Turbo`/`Quality`; V4: `Turbo`/`Balanced`/`Quality`) and affects image cost — pass it to `videodraft costs ... --rendering-speed <tier>` for an accurate estimate. 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.
 - `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.
-- Reference inputs: `--ref <img>` (images, including up to 7 for Grok 1.5), `--ref-video <v>` (Gemini Omni Flash, MiniMax H3, Seedance 2, Wan 2.7), `--ref-audio <a>` (MiniMax H3, 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, and the server measures the real duration before charging. The CLI uploads local files inside every structured element without flattening the video/voice association. `--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.
+- Reference inputs: `--ref <img>` (images, including up to 7 for Grok 1.5), `--ref-video <v>` (Gemini Omni Flash, MiniMax H3, Seedance 2, Wan 2.7), `--ref-audio <a>` (MiniMax H3, Seedance 2), and `--element '<json>'` or `--element @elements.json` for Kling V3/O3. For an exact Seedance 2.x or Wan 2.7 reference-video `--estimate`, add `--ref-video-seconds <combined-seconds>`; both bill input seconds alongside output, and the server measures the real duration before charging. The combined window is 30s on Seedance 2.5 and 15s on Seedance 2.0 and Wan 2.7. The CLI uploads local files inside every structured element without flattening the video/voice association. `--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.
 - The top-level prompt is OPTIONAL for `generate video` with multi-prompt models and for Kling 3.0 Turbo (`--model kling-v3-turbo`) image-to-video — a `--segment`-only or `--start-image`-only call is valid. Every other model still needs a prompt; the server enforces per-model rules.
-- Hosted AI Production fallback: `videodraft produce <project> --mode full_video` generates one Seedance 2 video per scene; 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.
+- Hosted AI Production fallback: `videodraft produce <project> --mode full_video` generates one Seedance 2 video per scene; add `--allow-real-people` when a scene grid visibly contains a real identifiable person. The MCP equivalent is `produce_project` with `mode: "full_video", allow_real_people: true`. The option applies the higher Fal-tier rate to every submitted scene segment. If a partial run returns `SEEDANCE_REAL_PERSON_OPT_IN_REQUIRED`, rerun the same project once with the option after cost confirmation. The server reconciles asynchronous results first, preserves running/completed jobs, and retries only failed placeholders carrying that exact code. 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.
 
 ## Cost model
 
@@ -164,7 +166,7 @@ Direct Fabric text/audio and Sync Labs do not use the managed avatar record. The
 - Lyria music: flat per track, 10 credits (clip) / 15 credits (pro).
 - 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.
 - ElevenLabs audio: sound effects are per second, dialogue is per character, music/voice-changer/dubbing are per started minute. Voice changer and dubbing reject source media above 300s in the current synchronous flow.
-- Seedance 2.0 / 2.5 real people: every listed Seedance 2.x rate assumes `--allow-real-people` is OFF, which runs the job on Byteplus alone and is priced at Byteplus cost (2.0 Mini 4/8 cr/s, Fast 6/13, Standard 7/16/38/78, 2.5 11/24/57 (480p/720p/1080p)). Byteplus refuses real-person likenesses, so such a job fails with a content-filter error instead of falling back. Passing `--allow-real-people` permits the Fal fallback, which allows them, and prices at FAL's rate for that tier: 2.0 Mini 8/16, Fast 11/25, Standard 14/31/69/156, 2.5 23/48/114. That is roughly 2x but NOT exactly 2x — Byteplus charges more per token at both 1080p tiers (1.82x there). Only pass it when the prompt or the reference images involve a real, identifiable person.
+- Seedance 2.0 / 2.5 real people: every listed Seedance 2.x rate assumes `--allow-real-people` is OFF, which uses the Byteplus-priced path (2.0 Mini 4/8 cr/s, Fast 6/13, Standard 7/16/38/78, 2.5 11/24/57 for 480p/720p/1080p). Byteplus refuses real-person likenesses, so a likeness-policy failure does not fall back by default. Passing `--allow-real-people` keeps Byteplus first but permits a submit-time Fal fallback, which allows them, and prices at Fal's rate for that tier: 2.0 Mini 8/16, Fast 11/25, Standard 14/31/69/156, 2.5 23/48/114. That is roughly 2x but not exactly 2x: 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. Pass the option proactively only when supplied visual input media visibly contains a real identifiable person. Otherwise retry once only after the exact opt-in code.
 - 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.
 - xAI bills refused requests, so failed Grok generations are not refunded.
 - Upscales: priced by scale and source size.
@@ -177,7 +179,7 @@ videodraft costs minimax-h3 --type video --duration 10 --resolution 2K --ref-ima
 videodraft costs grok-imagine-video-1.5 --type video --duration 8 --resolution 720p --ref-images 4
 videodraft costs seedance-2 --type video --duration 15 --resolution 720p --quality standard --audio
 videodraft costs grok-imagine-2.0 --type image --resolution 2K --quality medium --num 2
-videodraft costs seedance-2 --type video --duration 15 --resolution 720p --quality standard --audio --allow-real-people # 2x
+videodraft costs seedance-2 --type video --duration 15 --resolution 720p --quality standard --audio --allow-real-people # Fal-tier rate
 videodraft costs elevenlabs-dubbing --type audio --duration 60
 videodraft costs seed-audio-1.0 --type audio --duration 60 # scenario only; model controls actual length
 videodraft costs elevenlabs-dialogue --type audio --chars 350

package/skills/videodraft/references/pipeline.md

@@ -14,6 +14,7 @@ Use direct asset tools for standalone images, clips, audio, upscales, and descri
 | Batch shot images                       | `videodraft shots <project>`                                                | `generate_shot_images`                     |
 | One shot image                          | `videodraft generate image --project <id> --scene N --shot M`               | `generate_image`                           |
 | Produce (voiceover, captions, timeline) | `videodraft produce <project>`                                              | `produce_project`                          |
+| Seedance full-video production          | `videodraft produce <project> --mode full_video`                            | `produce_project` with `mode: "full_video"` |
 | Per-shot motion prompts                 | `videodraft video-prompts <project>`                                        | `generate_video_prompts`                   |
 | Motion clip for a shot                  | `videodraft generate video --project <id>`                                  | `generate_video`                           |
 | Attach a finished clip to the timeline  | `videodraft attach <project> --scene N --shot M --media <url> --type video` | `attach_media_to_shot`                     |
@@ -40,6 +41,7 @@ Use direct asset tools for standalone images, clips, audio, upscales, and descri
 - **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".
 - **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.
 - **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.
+- **Seedance full-video real people**: when a hosted `full_video` scene grid visibly contains a real identifiable person, enable the option before submitting any scene videos. Keep the Byteplus default for non-people, anime, and clearly synthetic or stylized characters that are not identifiable real people. Use `videodraft produce <project> --mode full_video --allow-real-people`, or MCP `produce_project` with `mode: "full_video", allow_real_people: true`. This applies Fal-tier pricing to every submitted segment and permits the Byteplus-to-Fal fallback. If a partial run without the option returns `SEEDANCE_REAL_PERSON_OPT_IN_REQUIRED`, re-estimate, follow the user's spend-confirmation preference, and rerun the same project once with the option. The server reconciles asynchronous results first, preserves running/completed jobs, and retries only failed placeholders carrying that exact code. Do not loop when it was already enabled. VideoDraft refunds a Byteplus task rejected after asynchronous acceptance, but cannot reroute it; rephrase or change the scene references instead.
 - **Hold off generating shot images while the user is still iterating** on storyboard structure.
 - **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.
 - **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.