embed-video
Image-to-video craft on the skilyst platform — animate a locked still (first-frame anchor) into a 4-15s clip that keeps the identity of that still, and cut several such clips together without a visibl
SKILL.mdskills/official/embed-video/SKILL.md
GitHubImage-to-video: lock the still, animate the change
When to use
The user has a locked image (or approves generating one) and wants motion from it: a character shot, a product beat, a shot that must match a neighbouring shot. Deliverable = one playable video URL per shot, plus the still that anchors it.
Not this skill: a clip with no source image (skilyst/video-15s) or a shot whose
motion is driven by a voice track (skilyst/lipsync-audio-refs).
Rule 1 — pick ONE mode per job, never mix (this is the expensive one)
Two modes exist on the video nodes, and they cannot coexist inside one job:
| mode | how it is declared | what the model does |
|---|---|---|
| frame mode | image_roles[0] = first_frame (optionally last_frame) |
animates from the locked still(s) toward the described end state |
| reference mode | image_roles = [reference_image, …] (optionally + video_refs / audio_refs) |
treats the image(s) as style/identity reference while generating freely |
Mixing them is rejected upstream with "first/last frame content cannot be mixed
with reference image, video, or audio". That is not a theoretical risk: the
platform's own 30-day failed-node distribution carried 17 jobs killed by exactly
this message, our lane's first i2v attempt was rejected the same way (then a
plain first_frame run succeeded for $0.414 at 6s/768P), and the audio-driven
route hits it again (see skilyst/lipsync-audio-refs).
The implicit form counts too: a frame role anywhere makes every other image a
reference (un-roled images get no role and the upstream reads them as
reference_image). So images=[still, style_ref] with
image_roles=[first_frame] is the same forbidden mix — N images need N frame
roles or the job will be refused. The runtime validator
(internal/api/validation/seedance_mode.go) enforces this at submission time for
the seedance family, so the failure is caught before money is spent; do not
"try it and see".
The runtime side of the same rule: video_refs and audio_refs are mapped
unconditionally to the reference roles (reference_video / reference_audio) —
"video / audio refs are always reference mode" (internal/provider/minimax_h3/runner.go)
— which is why they can never be combined with a frame role in the first place.
Rule 2 — the first frame carries identity, so build it before you animate
Because frame mode forbids a reference_image, identity has to be baked into the
still before the animation step: generate the still from the character anchor
(or the approved asset), inspect it, then animate it. Why: in reference mode a
picture alone is read as a style image — the lane measured identity drift on
batches that handed over an image with no written lock; the fix is either the
frame-mode chain below, or the five-part reference-lock syntax documented in
skilyst/prompt-craft.
When the user has no still yet, generate it with the declared optional image
node (generate:nb2-image, fallbacks generate:nb2-lite-image,
generate:gpt-image-2) and get it approved before animating — an animation of a
still nobody approved is a wasted render.
Rule 3 — write only the change (I2V prompts are not T2V prompts)
The still already says who/what/where. The prompt spends its budget on motion:
- 15-40 words; camera move + subject motion + environmental micro-motion only; never re-describe what is already visible.
- One primary action per shot; environmental motion (steam, drifting mist, background passers-by) supports it and must not compete with it.
- Always give the end state —
…then settles back into place,…comes to rest. Why: without an end state the shot stalls or keeps drifting at the tail of the clip; the tail is exactly where a splice lands.
Rule 4 — duration and resolution are mode-dependent
| node | duration | resolution | note |
|---|---|---|---|
generate:minimax-h3 |
4-15 s integer | 768P (ratio 1.0) / 2K (×1.6) |
primary node; no auto length; 768P at 14 s ≈ $0.97, 6 s ≈ $0.41 |
generate:byteplus-seedance-2.0 |
4-15 s in text/image/frame modes; 4-30 s only when video_refs is present (r2v); -1 = auto |
480p / 720p / 1080p / 4k |
declared fallback; pricing is per second, resolution and model multipliers stack |
A single job cannot exceed the frame-mode cap, so anything longer than 15 s is
several jobs spliced in post. Do not reach for video_refs just to unlock 30 s:
that switches the job into reference mode (Rule 1) and changes the price.
Rule 5 — splice craft for multi-shot sequences
Independently generated clips cut together read as different people unless the chain is built and verified:
- Derive the next shot's still from the previous shot's tail frame (or a frame of it), so the chain is continuous.
- In frame mode that tail frame becomes the next shot's
first_frame. In reference mode the same craft is expressed asreference_image— never carry it asreference_imagewhile a frame role is present (Rule 1). - QA the splice on three elements — shoulder line, camera pitch, light ratio — and regenerate the later shot when any of them mismatches. This is a measured cost decision: the lane's three-clip trailer had to specify these three at the splice or the cut was visible.
Rule 6 — identity QA thresholds differ for i2v
Sampled frames of an i2v output score lower than a static image, purely from motion blur and intermediate-frame warping. Measured across 8 shots × 7 frames (min distribution 0.47-0.75, ±0.03 within a shot, no visible drift): use PASS ≥ 0.60, GRAY 0.50-0.60, regenerate below 0.50 on animated frames, and keep the stricter 0.70 for the still image itself. Applying the static threshold to i2v frames manufactures false failures.
Call contract
Bound through the tool named in the manifest
(requires.nodes[].binding.tool = beehive_submit_job):
| argument | value |
|---|---|
node_id |
generate:minimax-h3 |
prompt |
motion-only prompt (Rule 3) |
images |
[<locked still URL>] |
image_roles |
["first_frame"] (or ["reference_image", …] in reference mode — not both) |
duration |
integer 4-15 |
resolution |
768P unless a higher tier was approved |
ratio |
9:16 / 16:9 as delivered |
Runtime support (A1 phase-2)
beehive_submit_job forwards every argument this binding declares, under the node
field the manifest names: prompt, images, image_roles, duration,
resolution, ratio (for the still: prompt, images, ratio → the node's
aspect_ratio). An argument that is not declared here is refused with the declared
list rather than dropped — a dropped image would silently turn an i2v render into a
text-to-video render, at the same price. images and image_roles are validated as
positionally paired before submission, so the frame/reference mix that the platform
rejects is caught before the job is paid for.
Hand-off
Report dest_video_url verbatim plus the job id, and name the still that anchored
the shot (path or URL) so the sequence can be rebuilt. Report platform errors
verbatim; never substitute a neighbouring take.