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 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. 720p by default; 1080p only when the customer asks (16 Oct 2026). On a phone, after the platform recompresses it, the difference barely shows, and 1080p costs about twice as much. Seedance is only for shots with no face: it refuses photoreal faces, whatever model made them.

Workflow

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

The script:

1. Routes through the bundled media_proxy.py (GooseWorks FAL proxy) — no FAL key; charged to your GooseWorks credits 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)

Resolution	Duration	Cost per call
720p std	15s	~$4.54
1080p std	15s	~$10.20
1080p std	8s	~$5.44
1080p std	4s	~$2.72

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

Prompt template

History, not a recipe for faces. This template was written for a creator face as @Image1, which Seedance now refuses (2026-09-29). For a face-free shot, @Image1 is the product and @Image2 the empty set: keep the scene beats, the camera and the product lock, and drop the IDENTITY, WARDROBE, skin and lip blocks.

The prompt is the single biggest quality lever. Use this proven template structure:

📱 UGC INFLUENCER [PRODUCT] REVIEW REEL (SELFIE-STYLE, NOT A COMMERCIAL)

[BLOCK 0 — anti-pattern opener]
This is NOT a cinematic commercial, NOT a [category] ad, NOT an editorial campaign.
This is a real Instagram Reel filmed by a 20-something [demographic] creator on her
iPhone front camera, talking directly to her followers in a relaxed, confiding tone...

[IMAGE REF ASSIGNMENTS]
Use @Image1 as the influencer's face/identity. Use @Image2 as the exact [product]
she is reviewing — it is a [VISUAL DESCRIPTION]. It is NOT a [common confusion].
The product and label MUST be clearly identifiable.

[FORMAT block]
- Vertical 9:16 phone-shot selfie aesthetic, slight handheld micro-shake
- WARDROBE (STRICT): [wardrobe]. ABSOLUTELY NOT [list of negations].
- Setting: [setting]
- Lighting: [lighting]
- Real, slightly imperfect skin (natural barely-any makeup), light golden tan

[IDENTITY block]
Same young woman as @Image1 — [age range, hair, eyes, skin tone]

[DYNAMIC FRAMING block]
The video must vary its framing across scenes like a real Reel — do NOT stay
on one focal length the whole time. Mix wide / medium / close-ups.

[SCENE 1 (0-3s)] WIDE HOOK — [script line] + [emotion + action]
[SCENE 2 (3-7s)] PRODUCT HERO with rotation — [script line] + [emotion + action]
[SCENE 3 (7-11s)] SIDESTEP application or smell-test — [script line] + [emotion + action]
[SCENE 4 (11-15s)] REACTION + recommendation — [script line] + [emotion + action]

[AUDIO DIRECTION]
[Voice character: tone, accent, pace per DELIVERY_STYLES.md]
NO music in the audio (we add music in post).

[GLOBAL RULES]
- Wardrobe identical across the scene
- Product stays identical and clearly visible in her hand
- Lips remain CLOSED between dialogue beats
- [NSFW sidestep negations if relevant]

[STRICT REALISM RULES — Block F]
- Tiny natural imperfections, subtle peach fuzz, faint fine lines
- NOT plastic, NOT airbrushed, NOT doll-like, NOT porcelain
- Skin highlights ONLY on nose tip, cheekbones, cupid's bow
- Hair: individual flyaway strands, slight frizz
- Image grain matches iPhone front camera

Full template reference: prompt-example.md.

Quality Checks

• Output MP4 exists, plays end-to-end, duration within ±0.5s of --duration.
• Aspect ratio and resolution match the request.
• No realistic face was sent or rendered (Seedance refuses them; a person goes to creator-h3).
• Product label readable in the hero sub-scene (zoom in on the t=mid frame).
• The product matches its reference photo (shape, label, colour).
• No NSFW visual leaked (no water/lather/body-application unless explicitly approved).
• meta.json records gateway: "fal", model: "bytedance/seedance-2.0/reference-to-video", and the FAL seed.

Failure Modes

Failure	Cause	Recovery
FAL 422 content_policy_violation: partner_validation_failed	AI-gen scene passed as video_urls	Remove video_urls. Use image_urls only for identity continuity.
FAL 422 "may contain likenesses of real people" (exit 3)	A photoreal face in image_urls read as a real person	STOP. Surface the reason, request id and charge state. Re-running the same command is refused locally. Offer a permitted route with its cost (see below).
FAL response status: failed, nsfw reason	Body-application + female + water/lather hit classifier	STOP. Surface to caller. Rewrite sidestep beat as smell-test or fingertips-show. NEVER auto-retry.
FAL 404 on endpoint path	Wrong endpoint slug	Use bytedance/seedance-2.0/reference-to-video exactly — no fal-ai/ prefix.
invalid_request on submit	duration sent as a string	Send an int: "duration": 15 (enum {auto,4..15}).
Product label garbled / wrong	Multi-image refs drifted, or a small label at 720p	Ensure the product ref is sharp + correctly cropped, add "label MUST be sharp and clearly readable" to the hero sub-scene, or put the real label on with an overlay. 1080p only when the customer asks for it.
Mouth moving when not speaking	Default Seedance behavior	Add to Global Rules: "Lips remain CLOSED between dialogue beats — no mouth movement when not speaking."
Cinematic slow pacing despite "iPhone selfie" prompt	Seedance prior leans cinematic	Strengthen anti-pattern block: "Casual real-time pace, NOT slow-motion, NOT dolly moves, NOT cinematic." Optionally post-process with ffmpeg setpts=0.66*PTS for 1.5x speed.
Heavy freckles / blotchy skin	Block B language too aggressive	Use v8 soft-skin language. Drop "freckles prominent", "real-person imperfections". Replace with "tiny natural imperfections, subtle peach fuzz, faint fine lines".
FalPollTimeout after a long wait (1080p renders can run past 30 min)	The poller gave up; the paid job is still running	DO NOT re-fire (that pays twice). Re-attach to the same job: see Recovery below.
FAL downstream_service_unavailable after long wait (~30 min)	Seedance backend overloaded / transient infra issue	Not billed (FAL bills on completion). Retry once. If retry also fails, wait 30 min then retry. Don't change prompt — it's infra, not your input.
Brand name mispronounced in native-audio output (validated 2026-06-08 on Veloru A3: rendered "Veloru" as "vel-roo" instead of "veh-LOR-oo")	Seedance picks its own voice + interprets non-English / made-up brand names phonetically without dictionary knowledge	Preflight: use phonetic spelling directly in the dialogue (NOT a parenthetical). E.g. SPOKEN LINE: "Veh-lor-oo does the engineering for you." Avoid Dialogue: "Veloru (pronounced veh-LOR-oo)" — Seedance reads the parenthetical out loud (see next row). Post-render QC: /watch:watch and confirm the Whisper transcript matches expected pronunciation. Recovery: re-roll the affected sub-scene with phonetic spelling baked into the line, OR splice an ElevenLabs reading of the brand-name beat over the Seedance visual.
Prompt metadata leaks into spoken line (validated 2026-06-08 on Veloru A3 v2: rendered "Veloru, pronounced Ve-lo-ru, three syllables, does the engineering for you" — Seedance read the parenthetical voice-coaching out loud as if it were part of the dialogue)	Seedance does not distinguish "spoken text" from "voice coaching" inside a Dialogue: field. Parentheticals, notes, "(pronounced X)", "(softly)", "(stage whisper)" all get verbalized.	Prevention: keep voice-coaching OUTSIDE the dialogue field entirely. Use a separate SPOKEN LINE: heading whose content is the EXACT verbatim utterance, no parens, no notes. Put coaching under NEGATIONS: as "DO NOT say X / DO NOT explain pronunciation". Bake phonetic intent into the dialogue spelling itself (Veh-lor-oo not Veloru).

Recovery — re-attach to a paid job, never re-fire

A Seedance submit is billed as soon as it is accepted. The media proxy saves every submit's request_id (in ~/.gooseworks/pending-fal-jobs/) before it starts polling, so a lost poller or a crashed shell never loses the render.

Use the bundled scripts/media_proxy.py (run from this skill's folder):

1. List what can be resumed: python3 -c "import sys; sys.path.insert(0, 'scripts'); from media_proxy import list_pending; print(list_pending())"
2. Re-attach and download: python3 -c "import sys; sys.path.insert(0, 'scripts'); from media_proxy import resume_fal, download; r = resume_fal('<request_id>'); download(r['video']['url'], '<output>.mp4')". resume_fal never re-submits, so it can't charge twice.
3. Save the seed and request id next to the clip (<output>.mp4.meta.json) so later calls can reuse the seed for continuity.

References

• FAL model page: https://fal.ai/models/bytedance/seedance-2.0/reference-to-video
• Proven prompt template: prompt-example.md
• Sibling atom for avatar and product stills: create-image-fal
• Shared helper: media-proxy's scripts/media_proxy.py (bundled here as scripts/media_proxy.py)

Provider rejection and scene acceptance

generate.py enforces the first part. A rejection in any body shape (fal's detail with msg and/or type, or the GooseWorks provider_validation_failed wrapper) exits 3 after exactly one submit. The reason, request id and charge state go to stderr and <output>.rejection.json. The exact request is recorded (media-proxy's rejected-request ledger), so running the same command again exits 3 without sending anything. Changing the prompt, an image, the seed or the model makes a new request. charged: false means the GooseWorks proxy did not debit the explicit 4xx (read from the proxy code; one paid reproduction is still needed to confirm it).

Preserve the exact rejection reason, request id and charged/uncharged/unknown state. Stop identical rejected submissions; do not batch them or assume a provider switch is a policy bypass. Check which references the selected provider permits and review a permitted original character or non-likeness route, including changed cost, before another paid step. Historical incidents do not establish current universal policy or billing.

Record wearable counts/body locations, holding hands, object contacts and permitted gestures before generation. Review every generated frame against that checklist. Pin a reference per cast member and map speakers to lines. Compare fewer people per shot, shared referenced scenes and separately composed plates. Multi-character success rates and a six-character/two-attempt target remain unmeasured until a separately approved benchmark retains both successes and failures.