seedance

# Seedance — Seedance 2.0 Motion Graphics Skill Generate cinematic motion graphics videos using ByteDance's Seedance 2.0 model via Fal AI. Turn app screenshots into glossy liquid glass promo videos controlled from Claude Code. ## What This Skill Does - Generate **image-to-video** animations from a single image (with optional end frame control) - Generate **reference-to-video** motion graphics from multiple app screenshots - Generate **text-to-video** motion graphics from pure prompts - Scrape **App Store screenshots** automatically for any iOS app - Upload reference images to get **public URLs** for the API - Apply proven **liquid glass prompting patterns** that produce Apple-keynote-quality output ## Setup ### 1. Get a Fal AI API Key Sign up at [fal.ai](https://fal.ai) and create an API key from your dashboard. ### 2. Store the Key Add to your `.env` file: ``` FAL_KEY=your-fal-ai-key-here ``` ### 3. File Upload (Included) Seedance needs **publicly accessible URLs** for reference images. Fal AI includes its own CDN upload — no extra accounts or keys needed. Your `FAL_KEY` handles both generation and file upload. > **Want a full Generations tab with gallery, styles panel, and multi-model support (Kling, Veo, GPT Image, Nano Banana)?** Check out the Rubric dashboard at [robonuggets.com](https://robonuggets.com). --- ## Endpoints Seedance 2.0 has 5 endpoints on Fal AI. **Default to Pro** — it's only ~25% more expensive but noticeably better quality. | Type | Tier | Endpoint | $/sec (720p) | |------|------|----------|-------------| | **Image-to-video** | **Pro** | `fal.run/bytedance/seedance-2.0/image-to-video` | $0.30 | | Reference-to-video | **Pro (default)** | `fal.run/bytedance/seedance-2.0/reference-to-video` | $0.30 | | Reference-to-video | Fast (testing) | `fal.run/bytedance/seedance-2.0/fast/reference-to-video` | $0.24 | | Text-to-video | **Pro (default)** | `fal.run/bytedance/seedance-2.0/text-to-video` | $0.30 | | Text-to-video | Fast (testing) | `fal.run/bytedance/seedance-2.0/fast/text-to-video` | $0.24 | ### When to Use Which - **Image-to-video** — you have a single image and want to animate it with motion. Supports start + end frame control for precise transitions. Best for: animating a hero image, creating A→B transitions between two states, lip-sync animations. - **Reference-to-video** — you have multiple screenshots, logos, or visual assets to blend into a motion graphics piece. This is the primary mode for promo videos. - **Text-to-video** — no visual references available (e.g. GitHub repos, docs pages, abstract concepts). Pure prompt-driven. --- ## Parameters | Param | Required | Options | Default | |-------|----------|---------|---------| | `prompt` | Yes | string | — | | `image_urls` | No | array of public URLs, up to 9 | — | | `video_urls` | No | array of public URLs, up to 3 | — | | `audio_urls` | No | array of public URLs, up to 3 | — | | `resolution` | No | `"480p"`, `"720p"` | `"720p"` | | `duration` | No | `"auto"`, `"4"` – `"15"` | `"auto"` | | `aspect_ratio` | No | `"auto"`, `"21:9"`, `"16:9"`, `"4:3"`, `"1:1"`, `"3:4"`, `"9:16"` | `"auto"` | | `generate_audio` | No | boolean | `true` | | `seed` | No | integer | random | - **Total files across all modalities must not exceed 12** - Reference images in prompts: `@Image1`, `@Image2`, ... `@Image9` - Reference videos: `@Video1`, `@Video2`, `@Video3` - Reference audio: `@Audio1`, `@Audio2`, `@Audio3` - Max resolution is **720p** — there is no 1080p option ### Cost Reference (Pro, 720p) | Duration | Cost | |----------|------| | 4s | $1.21 | | 5s | $1.51 | | 8s | $2.42 | | 10s | $3.03 | | 12s | $3.63 | | 15s | $4.54 | Fast tier is ~20% cheaper. Use for quick tests before committing to Pro. --- ## Sweet Spot (Tested) These are the proven ratios from extensive testing: | Refs | Duration | Use Case | Cost (Pro 720p) | |------|----------|----------|-----------------| | 1 ref | 4s | Quick test, single screenshot | $1.21 | | 3 refs | 4–6s | Fast promo test | $1.21–$1.81 | | **5 refs** | **10s** | **Production promo (best results)** | **$3.03** | | 3 refs | 4s 480p | Cheapest possible test | ~$0.81 | **The golden rule: 1 reference image per 2 seconds of video.** - Fewer refs = model focuses better on each one - More refs (6-7+) = model blends too loosely, loses clarity - Always describe each image's role in the prompt --- ## Prompting Guide ### Rule 1: Logo References First (CRITICAL) **NEVER describe logos or brand elements in the prompt text.** Seedance mangles text rendering — wrong shapes, wrong colors, hallucinated details. Before writing ANY prompt: 1. Ask for or find the app/brand logo image 2. Save it locally 3. Upload it to get a public URL 4. Pass it as one of the `@Image` references If you don't have the logo: **STOP and ask.** Never proceed without it. **Recommended approach:** Generate the motion graphics without text/logos in the video at all, then overlay the logo in post-production (Premiere, After Effects, etc). This produces the cleanest results. ### Rule 2: The Liquid Glass Prompt Template This is the proven prompt structure that produces Apple-keynote-quality motion graphics: ``` Design a motion-graphics style ad using glossy liquid glass design language. Pure black background. @Image1 is [describe what it shows]. @Image2 is [describe]. @Image3 is [describe]. The [element] from Image 1 becomes translucent glass [describe transformation]. [Element] from Image 2 [describe]. [Continue for each image]. Multiple camera angles: close-up on glass reflections, pull back to reveal the full scene. No text, no logos, no words. Style: liquid glass morphism, Apple Vision Pro aesthetic, premium 3D depth, self-luminous forms on absolute black, [accent color] accent lighting. ``` **Key rules:** - Describe each `@Image` by number and what it contains - Describe how each element transforms into glass - End with a style line including the brand's accent color - `"Multiple camera angles"` keeps it dynamic - `"No text, no logos, no words"` prevents garbled text - Keep under ~200 words — the model ignores long prompts ### Rule 3: Device Framing For product shots, specify the device in the prompt: **Floating desktop screens (best results):** ``` Show the desktop screens floating in 3D space on a pure black background, tilted at slight angles like a MacBook product shot. The UI elements on screen become translucent glass with reflections and refractions. ``` **iPad:** ``` An iPad Pro floating in empty black space, tilted at a cinematic angle like an Apple product shot. The iPad has visible black bezels and a physical frame — only the screen content has the glass effect. ``` **MacBook:** ``` A MacBook Pro floating in empty black space, open at a cinematic angle. The MacBook screen displays the dashboard. Light catches the aluminium edges. ``` **Floating in black void** produces better results than placing devices in environments (offices, desks). Keep it pure black. ### Rule 4: Audio - `generate_audio: true` adds ambient SFX and music - May trigger **content policy violations** on abstract visuals — if it fails, retry with `generate_audio: false` - Audio costs the same whether enabled or not - When it works, the generated audio adds real production value ### Rule 5: Negative Guidance Add constraints to prevent common issues: - `"No text, no logos, no words"` — prevents garbled text - `"No cuts"` — keeps it as one continuous shot - `"No camera shake"` — keeps it stable - `"Pure visual motion only"` — reinforces no text --- ## The Full Pipeline ### Step 1: Get Screenshots **Option A — Screenshot a website:** ```python from playwright.sync_api import sync_playwright with sync_playwright() as p: browser = p.chromium.launch(headless=True) page = browser.new_page(viewport={"width": 1920, "height": 1080}) page.goto("https://example.com", wait_until="networkidle", timeout=30000) page.wait_for_timeout(2000) page.screenshot(path="screenshot.png") browser.close() ``` **Option B — Scrape App Store screenshots:** ```python import json, urllib.request # Step 1: Find the app ID search_url = "https://itunes.apple.com/search?term=APP_NAME&entity=software&limit=3" data = json.loads(urllib.request.urlopen(search_url).read()) app_url = data["results"][0]["trackViewUrl"] # Step 2: Scrape screenshot URLs from the page using Playwright # Look for <source> elements with srcset containing "mzstatic.com" # The URLs use format like /460x996bb.webp — swap to /1290x2796bb.jpg for full res ``` **Option C — Manual screenshots** — take them yourself, save locally. ### Step 2: Upload for Public URL Seedance needs publicly accessible URLs for reference images. Use Fal AI's built-in CDN upload (default) — no extra accounts needed. **Fal AI CDN (default — uses your existing FAL_KEY):** ```bash # Step 1: Initiate upload INIT=$(curl -s -X POST "https://rest.alpha.fal.ai/storage/upload/initiate" \ -H "Authorization: Key $FAL_KEY" \ -H "Content-Type: application/json" \ -d '{"file_name":"my-screenshot.png","content_type":"image/png"}') # Extract URLs from response FILE_URL=$(echo "$INIT" | python -c "import sys,json; print(json.load(sys.stdin)['file_url'])") UPLOAD_URL=$(echo "$INIT" | python -c "import sys,json; print(json.load(sys.stdin)['upload_url'])") # Step 2: Upload the file curl -s -X PUT "$UPLOAD_URL" \ -H "Content-Type: image/png" \ --data-binary @/path/to/screenshot.png ``` Use `FILE_URL` as the public URL in your Seedance API calls. Hosted on `v3b.fal.media` with long-lived caching. Included with your Fal AI account — no extra cost. **Alternative: Kie AI (if you have a key):** ```bash curl -s -X POST "https://kieai.redpandaai.co/api/file-stream-upload" \ -H "Authorization: Bearer $KIE_API_KEY" \ -F "file=@/path/to/screenshot.png" \ -F "uploadPath=generations" \ -F "fileName=my-screenshot.png" ``` Returns `downloadUrl`. Files expire after 3 days. **Alternative: Litterbox (no account needed):** ```bash curl -s -F "reqtype=fileupload" -F "time=1h" \ -F "fileToUpload=@/path/to/screenshot.png" \ https://litterbox.catbox.moe/resources/internals/api.php ``` Returns a direct URL. Expires after 1 hour. ### Step 3: Generate the Video **Always use a temp JSON file** to avoid shell escaping issues: ```bash cat > /tmp/seedance_body.json << 'ENDJSON' { "prompt": "Design a motion-graphics style ad using glossy liquid glass design language. Pure black background. @Image1 is [describe]. @Image2 is [describe]. @Image3 is [describe]. The elements become translucent glass with reflections and refractions. Multiple camera angles. No text, no logos, no words. Style: liquid glass morphism, Apple Vision Pro aesthetic, premium 3D depth, self-luminous forms on absolute black.", "image_urls": [ "https://your-upload-url/screenshot1.png", "https://your-upload-url/screenshot2.png", "https://your-upload-url/screenshot3.png" ], "resolution": "720p", "duration": "4", "aspect_ratio": "16:9", "generate_audio": false } ENDJSON curl -s -X POST "https://fal.run/bytedance/seedance-2.0/reference-to-video" \ -H "Authorization: Key $FAL_KEY" \ -H "Content-Type: application/json" \ -d @/tmp/seedance_body.json ``` ### Step 4: Download the Result The response contains a video URL: ```json { "video": { "url": "https://v3b.fal.media/files/.../video.mp4" }, "seed": 42 } ``` **Download immediately** — URLs may expire. ```bash curl -sL -o "output_video.mp4" "THE_VIDEO_URL" ```