Create Video Seedance 2 Fal

Superseded in the video kit by the video-seedance-2 part (1.0.1; 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 (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).
• --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 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 Pro at fal-ai/nano-banana-pro, $0.15/1K, text-to-image with "no bokeh, infinite focus, no people, no faces" directives) LOCKS the room across all sub-scenes. Use the SAME background image across all calls of the same ad — different bg image per call reads as "she moved." Memory: feedback_seedance_long_calls_not_short.md.

0c. PRE-CLEAN PRODUCT REFERENCE IMAGES via NB2 edit if they contain accessories. Validated 2026-05-23 (Bristle hi_res-12 had vials + funnel beside the box; Seedance fused them onto the box face). Inspect source product images at intake. If accessories / secondary products / score badges / lifestyle elements visible, route through fal-ai/nano-banana/edit (quote the current proxy price first) to isolate the hero product before passing to Seedance. Approve the cleanup cost before calling it; compare with the current quoted cost of a Seedance retry. Memory: feedback_nb2_clean_product_refs.md.

0d. SEQUENTIAL CALL CONTINUITY — use seed reuse, NOT video_urls. Validated 2026-05-23 (Bristle Variant A/B test). For Call N>1 in a multi-call ad, pass the prior call's seed (via --seed) with the same image_urls. NEVER pass the prior call's mp4 as video_urls for sequential continuity — it HURTS continuity (model tries to "continue" prior video; wardrobe/product drift more than they otherwise would). video_urls is ONLY for style transfer from a REAL HUMAN reference video (e.g. take a real-creator UGC ad and recreate with AI creator). Memory: feedback_seedance_video_urls_vs_seed.md.

0e. WHEN USING video_urls (style transfer from real reference): set client timeout to 30+ min AND trim reference to ≤15s. Validated 2026-05-23:

• Render time: ~18-20 min (vs ~10 min for image-only). The default fal_client.subscribe() 10-min timeout will fail. Use fal_client.submit() + manual polling.
• Combined video_urls duration cap: 15s. FAL rejects with input_value_error: Combined video duration must not exceed 15.0s. Trim reference videos with ffmpeg -t 15 before upload.
• Combined files cap: 50 MB total. Our fal_helpers.upload_file() cap bumped from 10 MB to 50 MB on 2026-05-23.
• Detect validation errors (input_value_error / "must not exceed") in polling exceptions and bail after 1-2 retries — terminal errors don't surface via status=Failed.
• Video reference transfers MORE than style/pacing — it transfers wardrobe styling, accessories, hair to a non-trivial degree (validated 2026-05-23 Probiotic Recreation: hair flipped to match reference; tablets appeared despite cleaned product image). Text-side overrides are PARTIALLY effective; pick a reference whose visuals already align with your target.
• FAL DOES accept AI-gen video as input (the old "instant content_policy_violation" assumption from BBE 2026-05 early is outdated). Memory: feedback_seedance_video_urls_vs_seed.md.

1. NEVER pass AI-generated video as video_urls. FAL's content-policy validator rejects this with partner_validation_failed. The 60% video-input discount is real but only applies to REAL HUMAN reference video. For AI-avatar continuity across multiple scenes, use the same identity portrait as image_urls in every scene. Validated on BBE.

2. NSFW reject → STOP and surface, do not auto-retry (exit 4). Body-application + female + water/lather hits the classifier reliably. If FAL returns content_policy_violation or status: failed with nsfw reason, do NOT retry the same prompt. Surface to the caller with 3 options: rewrite the application beat as smell-test / fingertips-show, reframe as POV (no face), or skip the scene. Follows the project-wide moderation policy (see memory feedback_hf_moderation_surface.md).

3. duration as an INT. Pass 15, not "15". seedance-2.0/reference-to-video rejects a string duration with invalid_request (validated 2026-07-18; the old "string only" note was the deprecated v1 i2v endpoint).

4. Single product per call (except hook). Multi-product hero scenes within a single Seedance call degrade label fidelity. The exception is the hook/intro scene where all products appear together but no single label is hero.

5. 1080p for hero quality. Skin texture and product label crispness scale noticeably with resolution. Use 720p only for budget/probe calls.

Workflow

python3 scripts/generate.py \
  --prompt "$(cat prompt-scene-1.txt)" \
  --output /path/to/scene-1.mp4 \
  --image-url "https://<hosted>/portrait.png" \
  --image-url "https://<hosted>/product.png" \
  --resolution 1080p \
  --duration 15 \
  --aspect-ratio 9:16 \
  --generate-audio

The script:

1. Routes through the bundled media_proxy.py (GooseWorks FAL proxy) — no FAL key; bills the Ads agent via ~/.gooseworks/credentials.json.
2. Passes the --image-url values straight through as image_urls (they must already be PUBLIC URLs; the orchestrator hosts local refs via MCP).
3. Submits bytedance/seedance-2.0/reference-to-video through the proxy and polls to completion with:

   {
       "prompt": <prompt>,
       "image_urls": [<refs>],
       "resolution": <res>,
       "duration": <dur>,  # int
       "aspect_ratio": <ar>,
       "generate_audio": <bool>,
       "seed": <optional int>,
   }

4. Downloads the result MP4 to --output.
5. Writes <output>.meta.json with prompt, refs, video URL, seed, duration, cost estimate.
6. On a policy rejection: one submit, no retry. Prints the reason, type, request id and charge state, writes <output>.rejection.json, and exits 3 (likeness, content_policy_violation, partner_validation_failed) or 4 (NSFW / safety checker). See "Provider rejection and scene acceptance".

Exit codes: 0 done · 1 other error · 3 policy rejection, or the same request already rejected · 4 NSFW rejection. The MCP relay also exits 3 when it needs the agent to make a call; it prints [mcp-relay] instead of "surface, do not retry".

Output

• <output> — MP4 clip at requested duration, resolution, aspect ratio.
• <output>.meta.json — request + result metadata + seed for reproducibility + cost estimate.
• <output>.rejection.json — only after a policy rejection: reason, kind, type, request id, HTTP status, charge state, exit code. Removed by the next successful render to the same path.

Pricing (2026-05)

Fast tier is ~20% cheaper but caps at 720p.