/create-video-seedance-2-fal

name: create-video-seedance-2-fal
description: Generate a single 4-15s vertical video clip with ByteDance Seedance 2.0 reference-to-video via fal.ai, for shots with no realistic face (a product hero, a product in motion, an empty set). Multi-image reference (product + setting), ambient audio, internal multi-cut handling within one render, 720p by default. Routes through the GooseWorks FAL proxy (charged to your GooseWorks credits). Seedance refuses photoreal faces, so talking heads and creators go to creator-h3 / video-h3max.
status: superseded
version: "2.0.5"
superseded_by: video-seedance-2@1.3.0

> **Superseded** in the video kit by the video-seedance-2 part (1.3.0, 720p by default; scripted lines use creator-h3). This atom still runs, unchanged, for skills outside the kit.

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 none exists, take one from the brand's assets, existing ads or product page; clean an occluded one with a gpt-image-2 edit first.

Purpose

Wraps the FAL endpoint `bytedance/seedance-2.0/reference-to-video`. Pass 1-N image references (product + optional empty setting, **never a photoreal face**) + a structured prompt → get back a 4-15s clip with ambient audio, at 720p by default.

**Seedance refuses photoreal faces, whatever model made them** (a fresh Seedream v5 Pro face too, 2026-09-29), and a refused submit still bills. Talking heads and any shot with a realistic face go to `creator-h3` / `video-h3max` (H3). In a GooseWorks custom video Seedance always needs the customer's new yes to its price, saved in the approved review; send that call's `--query` (below).

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 shot has no realistic face: a product hero, a product in motion, an empty set
• It needs hard camera motion or an exact product the cheaper H3 route can't hold
• Length 4-15s, vertical 9:16 (or other aspect ratios)
• Multi-image conditioning (product + setting, or several products for a hook scene)

**Do NOT use** for:

• Any shot with a realistic face (a talking head, a creator, a stranger) → `creator-h3` or `video-h3max`
• > 15s clips → split across multiple calls and stitch (`assembly/stitch-videos-ffmpeg`)
• Pure cinematic camera moves without an on-screen person → Veo through `create-video-fal` is often better
• Product-only B-roll with no person → text-to-video Seedance, or another model through `create-video-fal`
• 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.
• `--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 each local ref with MCP `file_url`: call it with `mode: "upload"` and a `path`, PUT the file to the returned `url`, then call it again with `mode: "download"` and the same `path`, and pass that `url` (set `expires_in_seconds` up to `3600` so it outlives the render).

Optional:

• `--resolution` — `480p` | `720p` (default) | `1080p`. No video above 720p unless the customer asks (16 Oct 2026): pass `1080p` only then.
• `--query` — the call's GooseWorks query as JSON. In a custom video the shot first needs the customer's yes to its Seedance price, saved as a `shot_overrides` `{scene, seedance: true, user_quote}` in the approved review; then send `{"shot_scene": <scene number>}` at 720p. Only 1080p also adds `"upgrade_reason": "customer_asked", "upgrade_quote": "<their words>"`.
• `--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).
• `--input-digest` — a stable id of the WHOLE request: `media_proxy.input_digest(model, payload)` over the full payload (prompt, resolution, duration, aspect ratio, audio, seed) with each ref URL replaced by its file's sha256 or ingredient key. Pass it when refs are re-hosted between runs: a recorded rejection then still matches, and the proxy re-attaches to a running job instead of paying twice. **It becomes a permanent refusal key after a policy rejection**, so it must cover every input: leave the prompt or an image out and a run that changed only that input is refused.

Credentials:

• **No FAL key.** Routes through the GooseWorks FAL proxy (`media_proxy.py`, bundled) and is charged to your GooseWorks credits, 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

> **Read these with the face rule.** Rules 0, 0a, 0d and 3 (identity, wardrobe, seed continuity for a person) were learned on avatar runs before Seedance began refusing photoreal faces whatever model made them (2026-09-29). For a face-free shot keep the scene structure, setting and product rules; skip the identity and wardrobe parts. A shot with a person goes