create-video-seedance-2-fal

create-video-seedance-2-fal

⚠️ REQUIRED PREFLIGHT (2026-06-04): every Seedance prompt that names a branded product MUST be paired with a real reference image of that exact product as one of the --image-ref inputs. Text-only product description without a ref invites Seedance to invent geometry that does not match the real SKU. If no reference exists locally, find one via brand-assets → existing-ads → PDP harvest → promote to clients/<brand>/brand-assets/reference-photos/. Optionally clean an occluded ref via a quick GPT-image-2 edit pass first. Always get user review of the reference + final prompt before firing the paid call. See feedback_product_reference_required.md.

Purpose

Wraps the FAL endpoint bytedance/seedance-2.0/reference-to-video. Pass 1-N image references (typically: portrait + product + optional setting) + a structured prompt → get back a 4-15s clip with native lip-synced VO and ambient audio.

Seedance 2.0 renders multiple internal cuts within a single 15s call when the prompt specifies sub-scene structure (e.g. WIDE HOOK / PRODUCT HERO / SIDESTEP / REACTION). This is the architectural win over the older NB2 + i2v multi-keyframe approach — fewer calls, native lip-sync, no Soul ID required.

Use this atom when:

• The clip needs a talking-head avatar reviewing or demonstrating a product
• Native lip-synced dialogue is required (set --generate-audio)
• Identity must hold via image reference, not video reference (see Decision Rule 1)
• Length 4-15s, vertical 9:16 (or other aspect ratios)
• Multi-image conditioning (face + product, or face + multiple products for a hook scene)

Do NOT use for:

• 15s clips → split across multiple calls and stitch (assembly/stitch-videos-ffmpeg)

• Pure cinematic camera moves without an on-screen person → create-video-veo3 is often better
• Product-only B-roll with no person → create-product-videos-higgsfield-ms or text-to-video Seedance
• Clips that need video reference for continuity from a prior AI-gen scene → not supported (content_policy_violation)

Inputs

Required:

• --prompt — structured prompt block (see "Prompt template" below). Long, multi-block. Reference run example: beauty-by-earth/video-01-three-product-grwm/working/fire_seedance_facewash.py.
• --output — local MP4 destination.
• --image-url (alias --image-ref) — at least one PUBLIC reference image URL (repeatable), passed as image_urls. Order matters — first = @Image1 in prompt addressing. The proxy does NOT upload local files: host local refs via MCP get_upload_url → get_download_url and pass the URL (identical to create-video-fal).

Optional:

• --resolution — 480p | 720p | 1080p (default). 1080p meaningfully better for product label fidelity.
• --duration — 4–15 seconds (default 15). Passed as an int (seedance-2.0/reference-to-video enum {auto,4..15}); a string 400s with invalid_request (validated 2026-07-18).
• --aspect-ratio — 9:16 (default), 16:9, 1:1, etc.
• --generate-audio — bool, default true. Set false for silent B-roll where VO is added post.
• --seed — integer for deterministic re-runs (FAL returns a seed; pass it back to reproduce).

Credentials:

• No FAL key. Routes through the GooseWorks FAL proxy (media_proxy.py, bundled) and bills the Ads agent, using ~/.gooseworks/credentials.json (written by the gooseworks CLI). Your cal_/agent token is not a FAL key — the old direct-key path 401'd; that's why this capability was rerouted through the proxy.