| name | create-video-seedance-fal |
| description | Generate a reference-driven video clip with ByteDance Seedance 2.0 via fal.ai's direct API. Use when you have 1-9 reference images (a locked character, a product still, a world plate) and you want the output clip to faithfully reproduce them inside a motion shot. Pay-per-second pricing ($0.30/s at 720p, $0.18/s with video ref). Cheaper alternative to Higgsfield-routed Seedance, and the right tool when product accuracy + character identity must persist across all frames. |
create-video-seedance-fal
Purpose
Generate one Seedance 2.0 reference-to-video clip via the direct fal.ai endpoint (bytedance/seedance-2.0/reference-to-video), not the Higgsfield MCP. Pay-per-second billing makes this the workhorse for any DIBS / beauty / CPG project that needs the product or the locked creator visible inside a moving shot.
Use this atom when:
- You have a product photograph that must appear pixel-faithfully in the output clip (Seedance reference is much more accurate than text prompts at preserving product geometry, color, labeling).
- You have a locked character anchor and need a short talking-frame or action clip with that exact face.
- You need 1-9 reference images composited into one motion shot — multi-SKU product reveals, character + product, character + world.
- You want native synced audio generated alongside the video (
generate_audio=true, default).
- You want to skip Higgsfield's flat-rate billing for short clips.
Use the sibling create-video-seedance (Higgsfield-routed) instead if you need Higgsfield's job-queue infrastructure, you already have your product registered in Marketing Studio, or you want Higgsfield's auto-fallback chain.
Pricing (as of 2026-05)
| Tier | Without video ref | With video ref (0.6×) |
|---|
| Standard 720p | $0.3024/sec | $0.1814/sec |
| Fast 720p | $0.2419/sec | $0.1452/sec |
1080p costs ~1.7× more; 480p costs ~0.6× less. Auto-duration billed at actual clip length. Source: fal.ai/models/bytedance/seedance-2.0/reference-to-video.
Example: a 5s 720p clip from one reference image = $1.51 standard, $1.21 fast.
Inputs
Required:
--prompt — text prompt. Reference media is addressed inline as @Image1, @Image2, ..., @Video1, @Audio1. Example: "@Image1 is held up to the cheek of @Image2, who swipes the product across her cheekbone. soft window light from left, gentle push-in."--output — local MP4 destination.--ref-image — one or more reference image paths. Repeat the flag for multiple. Max 9 images total (30 MB each, JPEG/PNG/WebP).
Optional:
--ref-video — reference video paths (1-3, combined 2-15s, 480p-720p, max 50 MB total). Triggers the 0.6× pricing discount.--ref-audio — reference audio paths (1-3, combined ≤15s, max 15 MB each). Drives pacing/lipsync.--aspect-ratio — auto | 21:9 | 16:9 | 4:3 | 1:1 | 3:4 | 9:16 (default 9:16 for DIBS / vertical social).--resolution — 480p | 720p | 1080p (default 720p).--duration — auto | 4-15 seconds (default 5).--tier — standard | fast (default standard).--no-audio — disable native audio generation (default is generate_audio=true).--seed — integer for reproducibility.--with-logs — stream fal queue logs to stderr.
Credentials:
FAL_API_KEY (or FAL_KEY) in .env or env.
Preflight
test -n "$FAL_API_KEY" || test -n "$FAL_KEY" || { echo "Missing FAL_API_KEY"; exit 1; }
python3 -c "import fal_client" || pip3 install fal_client
Workflow
python3 skills/atoms/video-generation/create-video-seedance-fal/scripts/generate.py \
--prompt "@Image1 (a woman with warm-blonde hair) holds @Image2 (a glossy pink cream-stick) up near her cheek, then swipes it diagonally across her cheekbone. soft warm window light from camera-left. subtle push-in. authentic UGC selfie feel." \
--ref-image dibsbeauty/concept-2-30-second-face/assets/characters/creator-anchor.png \
--ref-image dibsbeauty/concept-2-30-second-face/assets/keyframes/swipe-on-cheek.png \
--output dibsbeauty/concept-2-30-second-face/working/clips/scene-02-swipe.mp4 \
--aspect-ratio 9:16 --resolution 720p --duration 5
python3 .../generate.py \
--prompt "@Image1 (a pink DIBS cream-stick barrel) slides into the empty marble-vanity world of @Image2 from camera-right, settling at center frame. soft golden-hour shadow. slow elegant push-in. no audio." \
--ref-image dibsbeauty/concept-8-pink-is-personality-hypermotion/assets/keyframes/did-on-marble.png \
--ref-image dibsbeauty/concept-8-pink-is-personality-hypermotion/assets/worlds/marble-vanity.png \
--output dibsbeauty/concept-8-pink-is-personality-hypermotion/working/clips/seg-1-did-arrival.mp4 \
--aspect-ratio 9:16 --resolution 720p --duration 5 --tier fast --no-audio
The script:
- Loads the FAL key via
fal_helpers.load_fal_key().
- Uploads every
--ref-image / --ref-video / --ref-audio to FAL storage; collects URLs.
- Builds the request:
{prompt, image_urls, video_urls, audio_urls, resolution, duration, aspect_ratio, generate_audio, seed}.
- Routes to
bytedance/seedance-2.0/reference-to-video (or …/fast/… if --tier fast).
- Calls
fal_client.subscribe(model, payload) via fal_helpers.subscribe.
- Downloads the resulting MP4 to
--output.
- Writes
<output>.meta.json with model id, ref-counts, request, result url, duration, and estimated cost.
Prompting guidance — DIBS-tested patterns
- Always reference each image by
@ImageN inline so Seedance binds the prompt to the right reference. "@Image1 is held up by @Image2" works; "the woman holds the product" does not.
- Lead with the subject + action verb, not the camera. ("@Image1 swipes the cream-stick across her cheek; slow push-in." NOT: "slow push-in on a woman swiping a cream-stick.") — same rule as Higgsfield Seedance (see
_shared/MODEL_BEHAVIORS.md).
- Cap motion ambition. Seedance reference-to-video preserves products best when the camera move is slow (slight push-in, subtle parallax, soft drift). Aggressive moves (orbit, jib) start to "imagine" away from the reference.
- For product clips, use
--no-audio — Seedance's native audio is generic ambient that conflicts with a music bed added in post.
- For talking-frame clips of a locked creator, leave audio on so micro-mouth-movements stay synced with subtle ambient breathing.
- Duration sweet spot is 4-6s. Above 8s the reference fidelity starts to drift on the back half.
Output
<output_path> — MP4 at requested resolution + aspect-ratio + duration.<output_path>.meta.json — request payload, result URL, cost estimate, model id.
Quality Checks
- Output file exists, plays end-to-end, duration within ±0.5s of requested.
- ffprobe: video stream present, audio stream present (unless
--no-audio).
- Visually inspect first/middle/last frame against the reference images: product geometry intact, character identity intact.
meta.json includes gateway: "fal", model id, image_count, video_count, audio_count, and est_cost_usd.
Failure Modes
| Symptom | Likely cause | Fix |
|---|
| 404 / "model not found" | Wrong model ID. Fal sometimes renames. | Pass --model-id override (TODO if/when needed). |
| 422 / "image too large" | A ref image > 30 MB. | Downscale to ≤ 1920px wide before passing. |
| 422 / "too many reference items" | > 9 images, > 3 videos, > 3 audios, or > 12 total. | Drop refs; pick the most-load-bearing. |
| Output product looks "almost right" but slightly off-spec | Prompt didn't reference @Image1 directly. | Add @Image1 inline; redo. |
| First 1s is fine but the last 2s drifts | Duration too long for this composition. | Re-run at 4-5s. |
| Audio output is generic ambient noise | generate_audio=true + no audio_url. | Use --no-audio for product clips. |
Composed by
Used directly by:
dibsbeauty/concept-2-30-second-face/HOW_TO.md (locked-creator talking + macro clips)dibsbeauty/concept-4-out-the-door-diary/HOW_TO.md (multi-location diary clips)dibsbeauty/concept-5-glassy-matte-grwm/HOW_TO.md (step-application clips)dibsbeauty/concept-6-faq-podcast/HOW_TO.md (host talking-frame + product b-roll)dibsbeauty/concept-7-put-it-on-me-music/HOW_TO.md (product macro + creator swipe cuts)dibsbeauty/concept-8-pink-is-personality-hypermotion/HOW_TO.md (product-only arrival + moment clips)
Why this atom exists (vs the Higgsfield-routed sibling)
The Higgsfield-routed create-video-seedance is best when:
- You're already on Higgsfield's job queue for parallel batches.
- You need Higgsfield's auto-fallback (Seedance → Veo on content-filter rejection).
- You're producing a Marketing Studio multi-SKU ad and the product is already registered there.
This Fal-direct atom is best when:
- You're producing standalone clips and want per-second billing visibility.
- You're inside a beauty / CPG project where the same atom needs to run dozens of times with different ref-image combos.
- You want to skip Higgsfield's per-clip overhead and price floor.
For DIBS specifically, every clip uses one or two reference images and runs 4-6s. Fal-direct billing of $1.20-$1.80 per clip beats Higgsfield's effective $10-25 per Hyper Motion clip by an order of magnitude. That's why this atom was created.
