---

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 to creator-h3 / video-h3max.

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 Brightbite 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.

0a. WARDROBE must be FULLY specified — top + bottom + hair + accessories. Validated 2026-05-23 (Brightbite): 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.

0b. PASS A BACKGROUND REFERENCE IMAGE as image_urls[2] for locked settings. Validated 2026-05-23 (Brightbite). 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."

0c. PRE-CLEAN PRODUCT REFERENCE IMAGES via NB2 edit if they contain accessories. Validated 2026-05-23 (Brightbite 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.

0d. SEQUENTIAL CALL CONTINUITY — use seed reuse, NOT video_urls. Validated 2026-05-23 (Brightbite 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).

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. Local files go up through the media proxy's fal_upload.
• 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 older belief that it is always refused with content_policy_violation is outdated).

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.

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.

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