| name | video-generation |
| description | MUST use when the user wants to RENDER or GENERATE an actual video / MP4 from a description, or ANIMATE a local image. Triggers on "render a video", "generate video", "make a video", "create a video", "animate this", "animate this image", "bring this to life". Builds the motion prompt from what the user types (subject-agnostic, no built-in persona), optionally pulls a saved reference from the Library System, supports text-to-video and image-to-video, confirms cost (video is expensive), then calls the Seedance API (async submit/poll/download) and saves an MP4. |
Video Generation System — Render descriptions into real MP4 video
Overview
This skill renders an actual video by calling the Seedance API (BytePlus ModelArk) through an async
submit → poll → download flow. It is the motion companion to the Image Generation System. It is
subject-agnostic: it builds the prompt from whatever the user types and has no built-in
character, persona, or stored identity. Whatever the user describes is what gets animated.
Video is expensive — a single clip can cost ~$1–$3.50. The cost-confirmation gate (Step 5) is
mandatory and non-negotiable.
Protocol
-
Extract motion intent from user input. Read the typed description and pull out: subject,
scene/setting, camera movement (static / slow push-in / orbit / handheld / dolly / crane),
pacing (calm drift vs energetic), and mood. The prompt is built from their words only —
never from a stored character profile, an "appearance" file, or any baked-in identity.
-
(Optional) Consult the Library System. IF the Library System feature is installed AND the user
references a saved entry (e.g. "use my noir style"), read that user-authored entry and fold it
into the prompt. This is the only persisted source the skill reads, and it is 100% user-owned
content — never a shipped persona.
-
(Optional) Image-to-video. IF the user wants to animate a local still (e.g. one produced by
the Image Generation System), pass it to the helper as -FirstFrame (opening frame),
-LastFrame (closing frame), or -ReferenceImages (style/subject anchors). The helper base64's
local files automatically — no hosting needed. URLs are also accepted.
-
Resolve the output path.
- Default folder:
media-generation/video-generation/ inside the user's memory root (created at
install; its path is recorded in master-memory.md).
- Honor an explicit
to [path] override.
- Sanitize the filename (strip
< > : " / \ | ? *, lowercase, hyphenate whitespace) and append a
-YYYYMMDD-HHmmss.mp4 timestamp suffix.
-
MANDATORY cost-confirmation gate. Run the helper with -WhatIfCost (no API call) to get the
estimate for the chosen resolution/duration. Present it clearly, emphasizing video is pricey,
and get an explicit go-ahead. NEVER auto-fire a paid render.
-
Invoke the render helper (async submit → poll → download) and report the result.
- PowerShell:
& Invoke-VideoGen.ps1 -Prompt "<final prompt>" -OutFile "<resolved path>" -Resolution "<480p|720p|1080p>" -Duration <seconds> -AspectRatio "16:9" [-FirstFrame "<path|url>"]
- Bash:
invoke-video-gen.sh --prompt "<final prompt>" --outfile "<resolved path>" --resolution "<res>" --duration <seconds> [--first-frame "<path|url>"]
- Report back the
saved_path, the cost estimate, elapsed time, and task_id.
Resolution & Duration Reference
| Resolution | Indicative cost/sec (USD) | Notes |
|---|
480p | ~$0.05 | cheapest — good for drafts/smoke tests |
720p | ~$0.10 | balanced |
1080p | ~$0.23 | highest quality, highest cost |
Cost ≈ rate × duration. Default to a short duration unless the user asks otherwise. Verify current
pricing at BytePlus ModelArk — these are indicative only.
Mandatory Rules
- Build prompts only from user input (plus optional user-owned Library entries). The feature is
subject-agnostic — no baked-in character, persona, or appearance.
- Always confirm the cost via
-WhatIfCost before a paid render (Step 5). No silent paid calls.
Video is expensive — never skip this.
- Always save into
media-generation/video-generation/ unless the user overrides with a path.
- Never commit
.env, never print the API key, never include the key in any output.
- Surface sanitized errors (the scripts strip
ark-/sk- patterns). Never auto-retry a failed
render — API errors (moderation, quota, malformed) need human diagnosis.
- The helper is canonical — never inline the HTTP submit/poll/download logic in conversation;
always call the script.
