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.

## Decision Rules

**0. Prefer FEWER, LONGER calls with internal multi-scene prompting over many short calls.** Every new Seedance call drifts character, wardrobe, lighting, and background slightly — even with the same portrait reference. 5 short calls = 5 drift points the viewer registers as continuity breaks. Use the proven multi-scene template inside ONE 10-15s call to get internal hard-feeling cuts from a single render:

```
SCENE 1 (0-3s) — WIDE HOOK [framing + action + dialogue]
SCENE 2 (3-7s) — PRODUCT HERO [framing + camera move + dialogue]
SCENE 3 (7-11s) — SIDESTEP / PROOF [framing + action + dialogue]
SCENE 4 (11-15s) — REACTION + CTA [framing + action + dialogue]
```

**Setting CAN vary across internal sub-scenes within one Seedance call.** Character identity is locked by the portrait reference image, not by the setting. Validated reference (ref-01 Bristle UGC, 26s) shows the same creator across 5+ different room/background settings within a single multi-scene render. Don't artificially split into multiple calls just to change rooms — bake the setting changes INTO the SCENE N (X-Ys) sub-scene structure of a single call. Distribute calls based on STORY ARC and the 15s max-duration cap, not setting count. See `prompt-example.md` for the validated template. Memory: `feedback_seedance_long_calls_not_short.md`.

**0a. WARDROBE must be FULLY specified — top + bottom + hair + accessories.** Validated 2026-05-23 (Bristle): if only the top is specified ("cream sweatshirt"), Seedance hallucinates the bottom (denim shorts appeared from nowhere). Every prompt must lock all of:
- Top (with negations)
- Bottom (with negations) — "light denim cuffed shorts, mid-thigh, NOT jeans, NOT pajama shorts"
- Hair (specific styling — "loose low ponytail at the nape with face-framing strands" works better than vague "bun")
- Accessories (e.g. "thin gold hoop earrings, nothing else")

For confessional / single-sitting UGC, wardrobe should be IDENTICAL across all calls of the same ad (validated user preference + ref-01 + ad-03 patterns). Vary wardrobe across calls ONLY for GRWM / transformation / multi-day formats. Memory: `feedback_seedance_long_calls_not_short.md`.

**0b. PASS A BACKGROUND REFERENCE IMAGE as `image_urls[2]` for locked settings.** Validated 2026-05-23 (Bristle). Text-only setting description yields generic-rental aesthetic — Seedance fills with its own room prior. A background hero image (generated via NB2