create-video-seedance-fal

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

# Single creator + product, 5s 9:16 720p
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

# Product-only with world plate, 5s, fast tier
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:

1. Loads the FAL key via fal_helpers.load_fal_key().
2. Uploads every --ref-image / --ref-video / --ref-audio to FAL storage; collects URLs.
3. Builds the request: {prompt, image_urls, video_urls, audio_urls, resolution, duration, aspect_ratio, generate_audio, seed}.
4. Routes to bytedance/seedance-2.0/reference-to-video (or …/fast/… if --tier fast).
5. Calls fal_client.subscribe(model, payload) via fal_helpers.subscribe.
6. Downloads the resulting MP4 to --output.
7. 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.