
fal-ai
fal creative skills with genmedia execution
- GitHub stars
- 273
Install
/plugin install fal-ai@fal-communityRun it inside Claude Code after adding the marketplace with /plugin marketplace add fal-ai-community/skills.
Contents
Discovered from sourceSkills 36
Branded Graphics
Read the production guide for this workflow. It preserves fal's published production guidance, not a promise that every host tool exists here.
Before execution, map host-specific tools to available capabilities. Use genmedia
for model calls in terminal agents, or the installed fal MCP tools in plugin hosts.
Resolve current endpoints and inspect their contracts; the guide's model names and
prices are dated candidates. Preserve the user's model, provider, scope and budget.
Do not infer authorization from a guide's defaults or mandatory review language.
Check that the required local Python, Node, browser, renderer and media tools exist before using them. Install publicly documented dependencies only within the user's authorized setup. Otherwise report the missing dependency and stop the dependent stage. This package does not supply hosted execution or an asset library.
Read supporting references from this skill folder as the guide directs. Record actual request IDs and output paths. Deliver only artifacts you inspected; identify incomplete stages and unverified checks.
Character design with genmedia
Use this skill when the user wants to create, refine, or preserve a character. Load the reference files when needed:
references/anchor-system.mdreferences/prompt-patterns.mdreferences/examples.md
Load model-routing alongside this skill for default endpoint choices.
The main objective is consistency. Keep the character anchor stable and change only the requested scene, expression, outfit, camera, or action.
Inputs to collect
Only ask for missing inputs that affect identity or model routing.
- Character type: realistic human, stylized, anime, mascot, fantasy, sci-fi.
- Identity anchor: age range, face shape, hair, eyes, build, posture, marks.
- Style: photographic, 3D, illustration, manga, comic, game concept art.
- Needed outputs: portrait, full body, turnaround, expression sheet, outfit set, action still, video shot, edit of an existing character.
- References: source image, approved design, costume, pose, style board.
- Consistency level: exploratory, pitch-ready, production continuity.
- Model preference: use
model-routingdefaults unless the user names a model or the job needs a quality/cost tradeoff decision.
Genmedia workflow
-
Start from routed endpoint IDs.
genmedia models --endpoint_id openai/gpt-image-2 --json genmedia models --endpoint_id fal-ai/nano-banana-pro/edit --json genmedia models --endpoint_id bytedance/seedance-2.0/image-to-video --json genmedia models --endpoint_id veed/fabric-1.0 --jsonUse text search only as fallback discovery for an unsupported role:
genmedia docs "consistent character generation" --json genmedia models "image editing character consistency" --json -
Inspect schema before each endpoint run.
genmedia schema <endpoint_id> --json genmedia pricing <endpoint_id> --json -
Upload references.
genmedia upload ./character-reference.png --json genmedia upload ./costume-reference.png --json -
Run stills or sheets with download.
genmedia run <endpoint_id> \ --prompt "<anchor + variable prompt>" \ --image_url "<reference url if supported>" \ --download "./outputs/characters/{request_id}_{index}.{ext}" \ --json -
Run video async.
genmedia run <endpoint_id> \ --prompt "<anchor + shot action>" \ --image_url "<approved character frame if supported>" \ --async \ --json genmedia status <endpoint_id> <request_id> \ --download "./outputs/characters/{request_id}_{index}.{ext}" \ --json
Use only schema-supported fields. If the model supports seed, reference image, image strength, multiple image inputs, or negative prompt, use them deliberately and record what was used.
Character anchor
Create a short immutable anchor before generating.
CHARACTER ANCHOR:
[name or codename], [age range], [face shape], [eye shape and color],
[nose and lips], [skin tone and distinguishing marks], [hair color, texture,
style], [body build and posture], [signature clothing or silhouette],
[style target]
Then add a variable block for the current shot.
SHOT VARIABLE:
[expression], [pose/action], [outfit changes if allowed], [environment],
[camera/framing], [lighting], [mood]
Never rewrite the anchor casually. If a result changes identity, strengthen the anchor or switch to a reference/edit workflow instead of adding more style words.
Model routing
- New character concept with maximum consistency: use
openai/gpt-image-2. - Premium but cheaper image option: use
fal-ai/nano-banana-proorfal-ai/nano-banana-2. - Fast exploratory drafts: use
fal-ai/flux-2/klein/9b. - Consistent sheet from an approved character: use
openai/gpt-image-2first; if editing an existing image, inspectopenai/gpt-image-2/edit. - Outfit variations and character edits: use
fal-ai/nano-banana-pro/edit, thenopenai/gpt-image-2/edit, thenfal-ai/bytedance/seedream/v5/lite/edit. - Expression sheet: one approved face reference, multiple controlled expression prompts.
- Character video: approved still frame first, then
bytedance/seedance-2.0/image-to-videofor final quality. - Fast video drafts: use
xai/grok-imagine-video/image-to-video. - Talking avatar or lip-sync: use
veed/fabric-1.0,veed/fabric-1.0/text, orfal-ai/creatify/aurora.
Quality bar
Reject or retry when:
- Face shape, eye spacing, hairstyle, marks, or body build drift.
- Outfit changes when the prompt says only expression or pose should change.
- The sheet mixes styles across panels.
- Hands or props distract from the requested design task.
- Video motion changes age, face, costume, or silhouette.
Return downloaded paths and include the anchor used so future prompts can reuse the same identity.
Character Sheet
Read the production guide for this workflow. It preserves fal's published production guidance, not a promise that every host tool exists here.
Before execution, map host-specific tools to available capabilities. Use genmedia
for model calls in terminal agents, or the installed fal MCP tools in plugin hosts.
Resolve current endpoints and inspect their contracts; the guide's model names and
prices are dated candidates. Preserve the user's model, provider, scope and budget.
Do not infer authorization from a guide's defaults or mandatory review language.
Check that the required local Python, Node, browser, renderer and media tools exist before using them. Install publicly documented dependencies only within the user's authorized setup. Otherwise report the missing dependency and stop the dependent stage. This package does not supply hosted execution or an asset library.
Read supporting references from this skill folder as the guide directs. Record actual request IDs and output paths. Deliver only artifacts you inspected; identify incomplete stages and unverified checks.
Cinematography with genmedia
Use this skill when the user needs cinematic direction, not generic "make it cinematic" prompting. Load references as needed:
references/shot-language.mdreferences/lighting-lens-color.mdreferences/examples.md
Load model-routing alongside this skill for default endpoint choices.
Write concrete visual direction. Avoid empty prestige words and em dashes.
Inputs to collect
Ask only for what affects the shot:
- Subject and action.
- Medium: still image, video, image-to-video, edit, storyboard frame.
- Genre and mood.
- Framing: close-up, medium, wide, overhead, POV, profile, locked-off.
- Camera motion for video: push-in, dolly, tracking, handheld, crane, drone.
- Lens feel: wide, normal, telephoto, macro, shallow or deep focus.
- Lighting: natural, practical, studio, noir, high key, low key, backlit.
- Output: aspect ratio, duration, first frame, last frame, download path.
- Preferred model, if the user wants a specific cinematography model or quality/cost profile.
Genmedia workflow
-
Start from routed endpoint IDs.
genmedia models --endpoint_id openai/gpt-image-2 --json genmedia models --endpoint_id fal-ai/nano-banana-pro --json genmedia models --endpoint_id bytedance/seedance-2.0/text-to-video --json genmedia models --endpoint_id bytedance/seedance-2.0/image-to-video --json genmedia models --endpoint_id xai/grok-imagine-video/text-to-video --jsonUse text search only as fallback discovery for a missing camera-control role:
genmedia models "cinematic video generation camera movement" --json genmedia docs "video generation camera movement prompt" --json -
Inspect schema and use only supported controls.
genmedia schema <endpoint_id> --json genmedia pricing <endpoint_id> --json -
Upload references when using image-to-video, first frame, last frame, style reference, or character/product continuity.
genmedia upload ./frame.png --json -
Run stills with direct download.
genmedia run <endpoint_id> \ --prompt "<cinematography prompt>" \ --download "./outputs/cinema/{request_id}_{index}.{ext}" \ --json -
Run video async.
genmedia run <endpoint_id> \ --prompt "<shot prompt>" \ --image_url "<uploaded frame if supported>" \ --async \ --json genmedia status <endpoint_id> <request_id> \ --download "./outputs/cinema/{request_id}_{index}.{ext}" \ --json
Prompt build order
Use the SCLCAM structure:
- Subject: who or what is in frame.
- Context: location, time, weather, story moment.
- Lens/framing: distance, angle, focal length feel, depth of field.
- Camera motion: only for video or if motion blur is desired.
- Atmosphere: haze, rain, practicals, reflections, texture.
- Mood/color: palette, contrast, grade, exposure style.
- Output controls: aspect ratio, duration, first-frame continuity.
Example structure:
[subject] in [context], framed as [shot size and angle], [lens feel],
[lighting setup], [camera movement if video], [color grade], [texture],
[duration or aspect ratio], [continuity constraints]
Model routing
- Premium realistic still: use
openai/gpt-image-2. - Premium stylized still: use
openai/gpt-image-2, thenfal-ai/nano-banana-pro, thenfal-ai/nano-banana-2. - Fast draft still: use
fal-ai/flux-2/klein/9b. - Highest quality video: use
bytedance/seedance-2.0/text-to-videoorbytedance/seedance-2.0/image-to-video. - Motion from a strong frame: use
bytedance/seedance-2.0/image-to-video. - Fast or lower-cost video: use
xai/grok-imagine-video/text-to-videoorxai/grok-imagine-video/image-to-video. - Complex camera language: inspect Seedance 2.0 first, then Kling v3 when multi-prompt or element controls matter.
- Story sequence: use the storytelling skill with this skill as shot-language support.
- Character or product continuity: use the relevant domain skill first, then apply cinematography as the variable block.
Quality bar
Before returning, check:
- Camera movement is physically plausible for the scene.
- Lens, shot size, and camera angle do not contradict each other.
- Lighting direction is clear and consistent.
- Color grade supports the mood without flattening subject detail.
- Video prompt describes one shot unless the selected model supports multiple prompts or shot lists.
- Downloaded files come from
downloaded_files[].
If a result looks generic, improve specificity in camera, blocking, light, and environment before adding more adjectives.
Commercial production with genmedia
Use this skill when the user wants advertising, product, brand, or e-commerce media. Load the reference files when you need prompt patterns or category examples:
references/prompt-patterns.mdreferences/workflows.mdreferences/examples.md
Load model-routing alongside this skill for default endpoint choices.
Keep the output production-focused. Do not add inflated marketing language, unsupported claims, fake text in the image, or em dashes.
Inputs to collect
Only ask when the answer cannot be inferred from the task or the source files.
- Product: exact product name, category, material, color, scale, logo rules.
- Goal: hero shot, PDP image, ad creative, motion reveal, demo, UGC, lifestyle.
- Platform: square, vertical, landscape, banner, transparent background, print.
- Brand: premium, playful, clinical, athletic, minimal, natural, technical.
- Source media: product packshot, logo, reference scene, prior generated asset.
- Constraints: preserve packaging, avoid new labels, no fake readable copy.
- Model preference: use
model-routingdefaults unless the user names a model or the job is unusually expensive.
Genmedia workflow
-
Start from routed endpoint IDs.
genmedia models --endpoint_id openai/gpt-image-2 --json genmedia models --endpoint_id fal-ai/nano-banana-pro/edit --json genmedia models --endpoint_id fal-ai/nano-banana-2 --json genmedia models --endpoint_id bytedance/seedance-2.0/image-to-video --jsonUse text search only as fallback discovery for a missing utility or unsupported role:
genmedia models "background removal product image" --json genmedia docs "commercial product image generation" --json -
Inspect the selected endpoint before running.
genmedia schema <endpoint_id> --json genmedia pricing <endpoint_id> --json -
Upload every local or remote reference file.
genmedia upload ./product.png --json genmedia upload ./logo.png --json -
Run still-image jobs synchronously when they are quick.
genmedia run <endpoint_id> \ --prompt "<commercial prompt>" \ --image_url "<uploaded product url if supported>" \ --download "./outputs/commercial/{request_id}_{index}.{ext}" \ --json -
Run video jobs async and download from
status.genmedia run <endpoint_id> \ --prompt "<motion prompt>" \ --image_url "<uploaded hero frame if supported>" \ --async \ --json genmedia status <endpoint_id> <request_id> \ --download "./outputs/commercial/{request_id}_{index}.{ext}" \ --json -
Use schema fields exactly. Do not pass guessed flags. If the model uses
image_urls,reference_image_url,aspect_ratio,duration,seed, or another name, mirror that schema.
Prompt build order
Write prompts in this order so commercial intent stays clear:
- Product invariant: exact object, material, color, packaging, scale.
- Commercial role: hero image, PDP image, launch teaser, demo shot, social ad.
- Setting: surface, background, props, environment, distance from product.
- Lighting: softbox, strip light, rim light, backlight, caustics, practicals.
- Camera: angle, focal length feel, macro, depth of field, motion if video.
- Composition: centered, negative space, safe zone, text-free area, platform.
- Brand tone: premium, clean, clinical, bold, energetic, warm, editorial.
- Guardrails: preserve logo and packaging, no extra text, no distorted labels.
Do not promise claims like "best", "clinically proven", "50 percent faster", or celebrity endorsements unless the user provides that copy.
Model routing
- Text-heavy ads, labels, posters, UI mockups, packaging copy, and
infographics: use
openai/gpt-image-2atquality=high. Prefer 2K or 4K when the final must carry small readable details. Treat this as expensive. - Premium realistic stills: use
openai/gpt-image-2. - Premium stylized stills: use
openai/gpt-image-2, thenfal-ai/nano-banana-pro, thenfal-ai/nano-banana-2. - Fast draft stills: use
fal-ai/flux-2/klein/9b. - Image edits: use
fal-ai/nano-banana-pro/edit, thenopenai/gpt-image-2/edit, thenfal-ai/bytedance/seedream/v5/lite/edit. - Product fidelity: use
fal-ai/nano-banana-pro,fal-ai/nano-banana-2, orfal-ai/bytedance/seedream/v5/lite/text-to-image; use the matching edit endpoint when a product reference image exists. - Product reveal video: create or upload a strong hero frame, then use
bytedance/seedance-2.0/image-to-videofor final quality. - Fast or lower-cost video draft: use
xai/grok-imagine-video/image-to-videoorxai/grok-imagine-video/text-to-video. - E-commerce batch: keep the same prompt skeleton and vary only background, crop, lighting, or platform format.
- Text overlays: generate with empty safe space. Add final text in a design or editing tool unless the selected model is explicitly good at typography.
- Background removal or cleanup: search for background removal, segmentation, inpainting, or product editing models and inspect their schemas.
- Final delivery: use
--downloadwith{request_id}and{index}.
Quality bar
Before returning, check:
- Product shape, logo, material, and color are not invented or distorted.
- The composition leaves enough room for platform crop and optional copy.
- Background props support the product and do not compete with it.
- Any generated text is absent or intentionally controlled.
- Lighting makes sense for the product material.
- Output paths are from
downloaded_files[], not manually curled URLs.
If the result misses product fidelity, switch from text-only generation to a reference or edit workflow before retrying.
E-commerce product photography
Make a consistent product photo set with the real SKU as the identity source.
Product lock and production
Collect SKU IDs, front/back/detail references, dimensions, material, true color, logo/label assets, shot list, channel requirements and budget. Separate product identity edits from deterministic crop, color and export corrections.
- Map each output to a SKU and reference. Never invent a back view, ingredient label, certification or physical feature absent from the supplied sources.
- Produce one hero against a suitable background with a currently accessible reference-edit model. Inspect its reference fields and image size contract first.
- Compare the result with the source: silhouette, proportions, cap, seams, material, label spelling and logo placement. Preserve true color rather than an attractive recolor.
- Derive detail and lifestyle scenes from the approved reference. Keep scale and light direction plausible. Treat hands, reflections and transparent packaging as separate fidelity risks. Do not scale up a false product detail for a close-up.
- For pure white/cutout delivery, use a current matting operation where needed and deterministic composition. Keep contact shadows only when the channel permits them. Check current marketplace image rules.
- Export requested dimensions, color space and format. Keep a clean master before channel crops. Apply the same crop margins and visual product scale across SKUs.
Acceptance and delivery
Deliver per-SKU folders, hero/detail/lifestyle files, a contact sheet and manifest. Measure dimensions, background/alpha, crop margins and file sizes. Inspect every label and product feature against the real reference. Reject drift before batch expansion. Identify any SKU or view that lacks a sufficient reference.
Execution and specialist guidance
Use the installed fal-media skill for current model discovery, input contracts,
prices, native MCP execution and request recovery. Preserve the user's selected
provider, model, inputs, output count and spending limits.
The production checks above work without another domain skill. If a specialist
stage needs more guidance, follow fal-media to retrieve the relevant published
guide and only its needed version-pinned references. Reuse guidance already read.
If retrieval is unavailable, retain these local checks and current tool contracts;
report any stage that cannot be completed or verified. Do not invent a model,
privileged host tool or unavailable renderer to fill the gap.
Keep a manifest of sources, endpoint, actual inputs, request ID, result URL, local file and QA findings. Inspect delivered artifacts and report unverified checks.
Terminal execution
For a terminal-only workflow, read the genmedia production-plan guide and copy this skill's example stage plan. The guide describes explicit submission, state files and recovery. These examples are optional CLI resources; connected MCP hosts use native fal tools.
Fal Audio Generation
Read the production guide for this workflow. It preserves fal's published production guidance, not a promise that every host tool exists here.
Before execution, map host-specific tools to available capabilities. Use genmedia
for model calls in terminal agents, or the installed fal MCP tools in plugin hosts.
Resolve current endpoints and inspect their contracts; the guide's model names and
prices are dated candidates. Preserve the user's model, provider, scope and budget.
Do not infer authorization from a guide's defaults or mandatory review language.
Check that the required local Python, Node, browser, renderer and media tools exist before using them. Install publicly documented dependencies only within the user's authorized setup. Otherwise report the missing dependency and stop the dependent stage. This package does not supply hosted execution or an asset library.
Read supporting references from this skill folder as the guide directs. Record actual request IDs and output paths. Deliver only artifacts you inspected; identify incomplete stages and unverified checks.
2D Game Assets
Requires the genmedia CLI (run
genmedia initonce).
Full pipeline for 2D pixel art game assets: character → sprite sheets → background removal → game background. Each recipe is independently invokable, run just the part you need.
Always use --json so output is machine-readable. Use --download to save files locally. Do not curl URLs manually, use the --download flag.
Execution rules, follow these strictly
-
Each genmedia command = one Bash tool call: issue each
genmedia runandgenmedia statusas its own bare tool call. No variable assignments, no pipes, no shell redirects. This keeps every call matching thegenmedia *allowlist so it runs without permission prompts. -
Parallel jobs → async: issue each
genmedia run --asyncas its own separate Bash tool call (not combined into one shell block). All jobs queue and run in parallel on fal's side; total time ≈ slowest single job. After all are fired, poll each withgenmedia statussequentially (not in parallel, one failure must not cancel others).
# Step 1, fire async (each line = its own Bash tool call, returns request_id immediately)
genmedia run fal-ai/nano-banana-pro/edit --prompt "$WALK_PROMPT" --image_urls "[\"$CHARACTER_URL\"]" --aspect_ratio "1:1" --resolution "1K" --async --json
genmedia run fal-ai/nano-banana-pro/edit --prompt "$IDLE_PROMPT" --image_urls "[\"$CHARACTER_URL\"]" --aspect_ratio "1:1" --resolution "1K" --async --json
# Step 2, poll sequentially (each line = its own Bash tool call)
genmedia status fal-ai/nano-banana-pro/edit <walk_request_id> --result --download ./walk.png --json
genmedia status fal-ai/nano-banana-pro/edit <idle_request_id> --result --download ./idle.png --json
-
URL source: always read
downloaded_files[0].urlfrom the tool result JSON. This is the correct path for all models (nano, gpt, Bria). -
Bria sync: Bria (
fal-ai/bria/background/remove) has no queue endpoint and does not support--async. Run it sync. It completes in seconds. -
Folder structure: always save into this layout, deriving the character slug from the character description (kebab-case, e.g.
pirate-carrot):
./game-assets/
<character-slug>/
character.png
sprites/
walk.png
idle.png
attack.png
jump.png
backgrounds/
layer1-sky.png
layer2-midground.png
layer3-foreground.png
Create the folders before downloading (mkdir -p). Use this structure even for partial runs (e.g. just one sprite sheet still goes in sprites/).
- End summary: after all downloads complete, print a summary listing every file path and its CDN URL. Format:
=== Game Assets: pirate-carrot ===
character game-assets/pirate-carrot/character.png
https://...
walk game-assets/pirate-carrot/sprites/walk.png
https://...
- 400 on status poll:
genmedia status --resultfetches the result once; it does not poll automatically. A 400 with"Request is still in progress"means the job is still running, wait 10 seconds and retry the exact samegenmedia statuscall with the same request_id. Do not re-fire the originalgenmedia run --async(the job is already running on fal's side). Keep retrying every 10–15 seconds until you get a successful result.
When to use
- Generating a pixel art character from a text description or reference image
- Creating sprite sheet animations (walk, jump, attack, idle) for a side-scroller
- Creating isometric RPG sprite sheets (walk, attack, idle across directions)
- Removing backgrounds from sprite sheets to get transparent PNGs
- Generating parallax backgrounds (3-layer) for side-scrollers
- Generating top-down isometric game maps for RPGs
Models in the stack
- Nano Banana Pro:
fal-ai/nano-banana-pro, character + background generation; better quality and faster, recommended default - Nano Banana Pro Edit:
fal-ai/nano-banana-pro/edit, sprite sheet generation from character image - GPT-Image-2:
openai/gpt-image-2, character + background generation; slower than nano, use when user prefers it or wants cheaper output (quality=low) - GPT-Image-2 Edit:
openai/gpt-image-2/edit, sprite sheet generation; slower than nano, requires model-specific walk prompt; usequality=lowfor cheaper runs - Bria RMBG 2.0:
fal-ai/bria/background/remove, background removal on all sprite sheets
Recipe 1. Generate character
Ask the user: character description (text) or an existing image to convert. Ask model preference: nano (default, better quality + faster) or gpt (slower; use quality=low if user wants cheaper output).
CHARACTER_STYLE_PROMPT="Generate a single character only, centered in the frame on a plain white background. The character should be rendered in detailed 32-bit pixel art style (like PlayStation 1 / SNES era games). Include proper shading, highlights, and anti-aliased edges for a polished look. The character should have well-defined features, expressive details, and rich colors. Show in a front-facing or 3/4 view pose, standing idle, suitable for sprite sheet animation."
IMAGE_TO_PIXEL_PROMPT="Transform this character into detailed 32-bit pixel art style (like PlayStation 1 / SNES era games). IMPORTANT: Must be a FULL BODY shot showing the entire character from head to feet. Keep the character centered in the frame on a plain white background. Include proper shading, highlights, and anti-aliased edges for a polished look. The character should have well-defined features, expressive details, and rich colors. Show in a front-facing or 3/4 view pose, standing idle, suitable for sprite sheet animation. Maintain the character's key features, colors, and identity while converting to pixel art."
# Text → pixel art character (nano)
genmedia run fal-ai/nano-banana-pro \
--prompt "$CHARACTER_STYLE_PROMPT Character: <character_desc>" \
--aspect_ratio "1:1" --resolution "1K" \
--download ./game-assets/<slug>/character.png --json
# Text → pixel art character (gpt)
genmedia run openai/gpt-image-2 \
--prompt "$CHARACTER_STYLE_PROMPT Character: <character_desc>" \
--image_size "square_hd" --quality "high" \
--download ./game-assets/<slug>/character.png --json
# Existing image → pixel art (nano), upload source image first, then run edit
genmedia upload /path/to/image.png --json
genmedia run fal-ai/nano-banana-pro/edit \
--prompt "$IMAGE_TO_PIXEL_PROMPT" \
--image_urls "[\"<uploaded_url_from_above>\"]" \
--aspect_ratio "1:1" --resolution "1K" \
--download ./game-assets/<slug>/character.png --json
Read downloaded_files[0].url from the tool result, this is CHARACTER_URL, needed for all sprite sheet recipes.
Recipe 2. Generate sprite sheets
Pass CHARACTER_URL from Recipe 1. Choose --style side (side-scroller) or --style iso (isometric RPG). Choose model: nano or gpt.
Side-scroller sheets: 4-frame 2×2 grid animations. Covered types: walk, jump, attack, idle. Do not generate additional animation types (hurt, death, run, etc.) unless the user explicitly requests them.
Fire all sheets async (each is its own Bash tool call), then poll sequentially:
WALK_PROMPT="Create a 4-frame pixel art walk cycle sprite sheet of this character. Arrange the 4 frames in a 2x2 grid on white background. The character is walking to the right. Top row (frames 1-2): Frame 1 (top-left): Right leg forward, left leg back - stride position. Frame 2 (top-right): Legs close together, passing/crossing - transition. Bottom row (frames 3-4): Frame 3 (bottom-left): Left leg forward, right leg back - opposite stride. Frame 4 (bottom-right): Legs close together, passing/crossing - transition back. Each frame shows a different phase of the walking motion. This creates a smooth looping walk cycle. Use detailed 32-bit pixel art style with proper shading and highlights. Same character design in all frames. Character facing right."
WALK_PROMPT_GPT="Create a 4-frame pixel art walk cycle sprite sheet of this character. Character orientation (critical): The character is shown in SIDE PROFILE, with their face, chest, and front foot pointing toward the RIGHT edge of the image. The character's back is on the LEFT side of the image. This is the same side-profile orientation used in classic 2D platformers like Super Mario Bros or Mega Man moving rightward across the screen. Arrange the 4 frames in a 2x2 grid on white background. Top row (frames 1-2): Frame 1 (top-left): Front leg (right leg) extended forward toward the right edge of the image, back leg extended behind toward the left edge. Frame 2 (top-right): Legs close together, passing pose. Bottom row (frames 3-4): Frame 3 (bottom-left): Opposite stride, back leg (left leg) now forward toward the right edge. Frame 4 (bottom-right): Legs close together, passing pose. Use detailed 32-bit pixel art style with proper shading and highlights. Same character design in all frames. All 4 frames must show the character from the SAME side profile angle, facing the RIGHT edge of the image."
JUMP_PROMPT="Create a 4-frame pixel art jump animation sprite sheet of this character. Arrange the 4 frames in a 2x2 grid on white background. The character is jumping. Top row (frames 1-2): Frame 1 (top-left): Crouch/anticipation - character slightly crouched, knees bent, preparing to jump. Frame 2 (top-right): Rising - character in air, legs tucked up, arms up, ascending. Bottom row (frames 3-4): Frame 3 (bottom-left): Apex/peak - character at highest point of jump, body stretched or tucked. Frame 4 (bottom-right): Landing - character landing, slight crouch to absorb impact. Use detailed 32-bit pixel art style with proper shading and highlights. Same character design in all frames. Character facing right."
ATTACK_PROMPT="Create a 4-frame pixel art attack animation sprite sheet of this character. Arrange the 4 frames in a 2x2 grid on white background. The character is performing an attack that fits their design - could be a sword slash, magic spell, punch, kick, or energy blast depending on what suits the character best. Top row (frames 1-2): Frame 1 (top-left): Wind-up/anticipation - character preparing to attack, pulling back weapon or gathering energy. Frame 2 (top-right): Attack in motion - the strike or spell being unleashed. Bottom row (frames 3-4): Frame 3 (bottom-left): Impact/peak - maximum extension of attack, weapon fully swung or spell at full power. Frame 4 (bottom-right): Recovery - returning to ready stance. Use detailed 32-bit pixel art style with proper shading and highlights. Same character design in all frames. Character facing right. Make the attack visually dynamic and exciting."
IDLE_PROMPT="Create a 4-frame pixel art idle/breathing animation sprite sheet of this character. Arrange the 4 frames in a 2x2 grid on white background. The character is standing still but with subtle idle animation. Top row (frames 1-2): Frame 1 (top-left): Neutral standing pose - relaxed stance. Frame 2 (top-right): Slight inhale - chest/body rises subtly, maybe slight arm movement. Bottom row (frames 3-4): Frame 3 (bottom-left): Full breath - slight upward posture. Frame 4 (bottom-right): Exhale - returning to neutral, slight settle. Keep movements SUBTLE - this is a gentle breathing/idle loop, not dramatic motion. Character should look alive but relaxed. Use detailed 32-bit pixel art style with proper shading and highlights. Same character design in all frames. Character facing right."
# Fire all 4 async, each is its own Bash tool call
genmedia run fal-ai/nano-banana-pro/edit --prompt "$WALK_PROMPT" --image_urls "[\"$CHARACTER_URL\"]" --aspect_ratio "1:1" --resolution "1K" --async --json
genmedia run fal-ai/nano-banana-pro/edit --prompt "$JUMP_PROMPT" --image_urls "[\"$CHARACTER_URL\"]" --aspect_ratio "1:1" --resolution "1K" --async --json
genmedia run fal-ai/nano-banana-pro/edit --prompt "$ATTACK_PROMPT" --image_urls "[\"$CHARACTER_URL\"]" --aspect_ratio "21:9" --resolution "1K" --async --json
genmedia run fal-ai/nano-banana-pro/edit --prompt "$IDLE_PROMPT" --image_urls "[\"$CHARACTER_URL\"]" --aspect_ratio "1:1" --resolution "1K" --async --json
# Poll each, each is its own Bash tool call, run sequentially
genmedia status fal-ai/nano-banana-pro/edit <walk_request_id> --result --download ./game-assets/<slug>/sprites/walk.png --json
genmedia status fal-ai/nano-banana-pro/edit <jump_request_id> --result --download ./game-assets/<slug>/sprites/jump.png --json
genmedia status fal-ai/nano-banana-pro/edit <attack_request_id> --result --download ./game-assets/<slug>/sprites/attack.png --json
genmedia status fal-ai/nano-banana-pro/edit <idle_request_id> --result --download ./game-assets/<slug>/sprites/idle.png --json
# GPT variants: replace fal-ai/nano-banana-pro/edit with openai/gpt-image-2/edit
# Walk must use WALK_PROMPT_GPT (not WALK_PROMPT)
# Replace --aspect_ratio with explicit --image_size:
# 1:1 → --image_size "square_hd"
# 21:9 → --image_size "{\"width\": 2688, \"height\": 1152}"
Isometric RPG sheets: 3/4 overhead perspective. Covered types: walk-down, walk-up, walk-side, attack-down, attack-up, attack-side, idle-iso. Do not generate additional animation types unless the user explicitly requests them.
Generate attack-down first, attack-up and attack-side both reference it for style consistency.
WALK_DOWN_PROMPT="Create a 4-frame pixel art walk cycle sprite sheet of this character walking DOWNWARD (toward the camera) in a top-down isometric RPG perspective (3/4 overhead view, like a classic top-down RPG). Arrange the 4 frames in a 2x2 grid on white background. The character is walking toward the viewer (south/down). Top row: Frame 1 (top-left): Left foot forward stride, arms swinging naturally. Frame 2 (top-right): Feet together, passing/transition pose. Bottom row: Frame 3 (bottom-left): Right foot forward stride, arms swinging naturally. Frame 4 (bottom-right): Feet together, passing/transition back. We see the character's front/face. Top-down 3/4 view - we see the top of their head slightly. Use detailed 32-bit pixel art style with proper shading and highlights. Same character design in all frames."
WALK_UP_PROMPT="Create a 4-frame pixel art walk cycle sprite sheet of this character walking UPWARD (away from the camera) in a top-down isometric RPG perspective (3/4 overhead view, like a classic top-down RPG). Arrange the 4 frames in a 2x2 grid on white background. CRITICAL: ALL 4 frames must show the character from EXACTLY the same angle, their BACK, facing directly away from the camera. Do NOT rotate or twist the character between frames. The ONLY difference between frames should be the leg and arm positions. Top row: Frame 1 (top-left): Left foot forward. BACK VIEW. Frame 2 (top-right): Feet together. BACK VIEW. Bottom row: Frame 3 (bottom-left): Right foot forward. BACK VIEW. Frame 4 (bottom-right): Feet together. BACK VIEW. Use detailed 32-bit pixel art style. Same character design in all frames."
WALK_SIDE_PROMPT="Create a 4-frame pixel art walk cycle sprite sheet of this character WALKING TO THE RIGHT in a top-down isometric RPG perspective (3/4 overhead view, like a classic top-down RPG). Arrange the 4 frames in a 2x2 grid on white background. The character is FACING RIGHT and WALKING RIGHT. Top row: Frame 1 (top-left): Right leg forward, left leg back - stride, arms swinging. Frame 2 (top-right): Legs close together, passing - transition. Bottom row: Frame 3 (bottom-left): Left leg forward, right leg back - opposite stride, arms swinging. Frame 4 (bottom-right): Legs close together, passing - transition back. We see the character's RIGHT-facing side profile from a top-down 3/4 overhead angle. Use detailed 32-bit pixel art style. Same character design in all frames."
ATTACK_DOWN_PROMPT="Create a 4-frame pixel art ATTACK animation sprite sheet of this character attacking DOWNWARD (toward the camera) in a top-down isometric RPG perspective (3/4 overhead view). Arrange the 4 frames in a 2x2 grid on white background. Top row: Frame 1 (top-left): Wind-up/anticipation - preparing to strike. Frame 2 (top-right): Attack in motion - strike unleashed toward camera. Bottom row: Frame 3 (bottom-left): Impact/peak - maximum extension. Frame 4 (bottom-right): Recovery. We see the character's front/face. The attack should fit the character's design. Use detailed 32-bit pixel art style. Make the attack visually dynamic."
ATTACK_UP_PROMPT="Create a 4-frame pixel art ATTACK animation sprite sheet of this character attacking UPWARD (away from the camera) in a top-down isometric RPG perspective. I've also sent you a reference of the same character's front-facing attack. Use the EXACT SAME attack type, weapon, and visual effects - just show it from behind. Arrange the 4 frames in a 2x2 grid on white background. Top row: Frame 1 (top-left): Wind-up from behind. Frame 2 (top-right): Attack unleashed upward/away. Bottom row: Frame 3 (bottom-left): Impact/peak. Frame 4 (bottom-right): Recovery. We see the character's back. MUST use the same attack style as the reference image. Use detailed 32-bit pixel art style."
ATTACK_SIDE_PROMPT="Create a 4-frame pixel art ATTACK animation sprite sheet of this character attacking SIDEWAYS (to the right) in a top-down isometric RPG perspective. I've also sent you a reference of the same character's front-facing attack. Use the EXACT SAME attack type, weapon, and visual effects - just show it from the side profile. Arrange the 4 frames in a 2x2 grid on white background. Character faces RIGHT. Top row: Frame 1 (top-left): Wind-up from side, facing right. Frame 2 (top-right): Strike unleashed to the right. Bottom row: Frame 3 (bottom-left): Impact/peak. Frame 4 (bottom-right): Recovery. IMPORTANT: Show the character's SIDE PROFILE facing RIGHT. MUST use the same attack style as the reference image. Use detailed 32-bit pixel art style."
IDLE_ISO_PROMPT="Create a 4-frame pixel art idle/breathing animation sprite sheet of this character in a top-down isometric RPG perspective (3/4 overhead view). Arrange the 4 frames in a 2x2 grid on white background. Character is FACING TOWARD THE CAMERA (south/down). Top row: Frame 1 (top-left): Neutral standing pose, facing down. Frame 2 (top-right): Slight inhale - body rises subtly. Bottom row: Frame 3 (bottom-left): Full breath - slight upward posture. Frame 4 (bottom-right): Exhale - returning to neutral. Keep movements SUBTLE. Use detailed 32-bit pixel art style. Same character design in all frames."
# Fire walk sheets + idle async, each is its own Bash tool call
genmedia run fal-ai/nano-banana-pro/edit --prompt "$WALK_DOWN_PROMPT" --image_urls "[\"$CHARACTER_URL\"]" --aspect_ratio "1:1" --resolution "1K" --async --json
genmedia run fal-ai/nano-banana-pro/edit --prompt "$WALK_UP_PROMPT" --image_urls "[\"$CHARACTER_URL\"]" --aspect_ratio "1:1" --resolution "1K" --async --json
genmedia run fal-ai/nano-banana-pro/edit --prompt "$WALK_SIDE_PROMPT" --image_urls "[\"$CHARACTER_URL\"]" --aspect_ratio "1:1" --resolution "1K" --async --json
genmedia run fal-ai/nano-banana-pro/edit --prompt "$IDLE_ISO_PROMPT" --image_urls "[\"$CHARACTER_URL\"]" --aspect_ratio "1:1" --resolution "1K" --async --json
# Poll walk results sequentially
genmedia status fal-ai/nano-banana-pro/edit <walk_down_request_id> --result --download ./game-assets/<slug>/sprites/walk-down.png --json
genmedia status fal-ai/nano-banana-pro/edit <walk_up_request_id> --result --download ./game-assets/<slug>/sprites/walk-up.png --json
genmedia status fal-ai/nano-banana-pro/edit <walk_side_request_id> --result --download ./game-assets/<slug>/sprites/walk-side.png --json
genmedia status fal-ai/nano-banana-pro/edit <idle_iso_request_id> --result --download ./game-assets/<slug>/sprites/idle-iso.png --json
# Attack-down sync, needed as reference before firing attack-up and attack-side
genmedia run fal-ai/nano-banana-pro/edit --prompt "$ATTACK_DOWN_PROMPT" --image_urls "[\"$CHARACTER_URL\"]" --aspect_ratio "9:16" --resolution "1K" --download ./game-assets/<slug>/sprites/attack-down.png --json
# Fire attack-up and attack-side async, passing attack-down URL from above result
genmedia run fal-ai/nano-banana-pro/edit --prompt "$ATTACK_UP_PROMPT" --image_urls "[\"$CHARACTER_URL\", \"<attack_down_url>\"]" --aspect_ratio "9:16" --resolution "1K" --async --json
genmedia run fal-ai/nano-banana-pro/edit --prompt "$ATTACK_SIDE_PROMPT" --image_urls "[\"$CHARACTER_URL\", \"<attack_down_url>\"]" --aspect_ratio "16:9" --resolution "1K" --async --json
genmedia status fal-ai/nano-banana-pro/edit <attack_up_request_id> --result --download ./game-assets/<slug>/sprites/attack-up.png --json
genmedia status fal-ai/nano-banana-pro/edit <attack_side_request_id> --result --download ./game-assets/<slug>/sprites/attack-side.png --json
# GPT variants: replace fal-ai/nano-banana-pro/edit with openai/gpt-image-2/edit
# Replace --aspect_ratio with explicit --image_size:
# 1:1 → --image_size "square_hd"
# 9:16 → --image_size "{\"width\": 720, \"height\": 1280}"
# 16:9 → --image_size "{\"width\": 1280, \"height\": 720}"
Recipe 3. Remove backgrounds
Bria has no queue endpoint, run sync (no --async). Each is its own Bash tool call:
genmedia run fal-ai/bria/background/remove --image_url "<walk_url>" --download ./game-assets/<slug>/sprites/walk-transparent.png --json
genmedia run fal-ai/bria/background/remove --image_url "<jump_url>" --download ./game-assets/<slug>/sprites/jump-transparent.png --json
genmedia run fal-ai/bria/background/remove --image_url "<attack_url>" --download ./game-assets/<slug>/sprites/attack-transparent.png --json
genmedia run fal-ai/bria/background/remove --image_url "<idle_url>" --download ./game-assets/<slug>/sprites/idle-transparent.png --json
Recipe 4. Generate backgrounds
Pipeline note: Layer 1 (sky) and the isometric map only need CHARACTER_DESC, no image reference. Fire Layer 1 async immediately after character generation so it runs in parallel while you generate sprite sheets. Layers 2 and 3 are sequential (each needs the previous layer's URL from the tool result).
Side-scroller, 3-layer parallax
# Layer 1, sky/backdrop. Fire async (no image dep) so it runs in parallel with sprite generation
genmedia run fal-ai/nano-banana-pro \
--prompt "Create the SKY/BACKDROP layer for a side-scrolling pixel art game parallax background. This is for a character: <character_desc>. Create an environment that fits this character's world. This is the FURTHEST layer - only sky and very distant elements (distant mountains, clouds, horizon). Style: Pixel art, 32-bit retro game aesthetic. Wide panoramic scene." \
--aspect_ratio "21:9" --resolution "1K" --async --json
# Poll Layer 1 (after sprite sheets are done), then read its URL from the result
genmedia status fal-ai/nano-banana-pro <layer1_request_id> --result --download ./game-assets/<slug>/backgrounds/layer1-sky.png --json
# Layer 2, midground (needs CHARACTER_URL + layer1 URL from above result)
genmedia run fal-ai/nano-banana-pro/edit \
--prompt "Create the MIDDLE layer of a 3-layer parallax background for a side-scrolling pixel art game. I've sent you images of: 1) the character, 2) the sky layer already created. Create the character's ICONIC/CANONICAL location from their story, home village, famous landmarks, signature battlegrounds. Elements should fill the frame from middle down to bottom. Style: Pixel art matching the other images. IMPORTANT: Use a transparent background so this layer can overlay the others." \
--image_urls "[\"<character_url>\", \"<layer1_url>\"]" \
--aspect_ratio "21:9" --resolution "1K" --download ./game-assets/<slug>/backgrounds/layer2-midground.png --json
# Bria bg-remove on layer 2 (sync, no queue endpoint)
genmedia run fal-ai/bria/background/remove --image_url "<layer2_url>" --download ./game-assets/<slug>/backgrounds/layer2-transparent.png --json
# Layer 3, foreground (needs CHARACTER_URL + layer1 URL + layer2-transparent URL from above result)
genmedia run fal-ai/nano-banana-pro/edit \
--prompt "Create the FOREGROUND layer of a 3-layer parallax background for a side-scrolling pixel art game. I've sent you images of: 1) the character, 2) the sky layer, 3) the middle layer. Create the closest foreground elements (ground, grass, rocks, platforms) that complete the scene. Style: Pixel art matching the other images. IMPORTANT: Use a transparent background so this layer can overlay the others." \
--image_urls "[\"<character_url>\", \"<layer1_url>\", \"<layer2_transparent_url>\"]" \
--aspect_ratio "21:9" --resolution "1K" --download ./game-assets/<slug>/backgrounds/layer3-foreground.png --json
# Bria bg-remove on layer 3 (sync, no queue endpoint)
genmedia run fal-ai/bria/background/remove --image_url "<layer3_url>" --download ./game-assets/<slug>/backgrounds/layer3-transparent.png --json
# GPT variant: replace nano endpoints with openai/gpt-image-2 and openai/gpt-image-2/edit
# Use --image_size '{"width": 2688, "height": 1152}' for 21:9 with gpt
Isometric, single top-down map
genmedia run fal-ai/nano-banana-pro \
--prompt "Create a large, detailed top-down isometric pixel art game world map for a character: $CHARACTER_DESC. Do not place the character on the map. Style: Classic RPG top-down map, 3/4 overhead perspective. Include: winding dirt/stone paths connecting areas, a small body of water, a few buildings or structures that fit the character's world, rocky areas or hills, various terrain types. Single large continuous map image (NOT tiled, NOT a tileset). Complete explorable game world viewed from above. Detailed 32-bit pixel art style. Fill the entire image with map content, no empty borders." \
--aspect_ratio "1:1" --resolution "1K" \
--download ./game-assets/<slug>/backgrounds/map.png --json
Parameters
- Model:
nanois the default: better quality and faster.gptis slower; use it when the user specifically requests it or asks for the cheapest option, in that case set--quality "low"to significantly reduce cost - Walk + gpt-image-2: always use
WALK_PROMPT_GPT, notWALK_PROMPT. GPT needs explicit side-profile orientation instructions to get the direction right - Attack aspect ratio:
21:9(nano) or2688×1152(gpt) for side-scroller attacks. Isometric attacks:9:16for down/up,16:9for side - Isometric attack-up and attack-side: always pass
ATTACK_DOWN_URLas second reference image to keep attack style consistent across directions - Background layers: generate in order (1 → 2 → 3). Each references previous layers. Layer 1 keeps background; layers 2 and 3 get background-removed
fal.ai Media
Use the connected fal tools for model discovery and execution. Preserve an explicit provider or model choice. Do not invoke fal when the user chooses a different provider. Guidance never expands the user's scope or spending authority.
Current model contracts
- With no exact endpoint supplied, use
recommend_modelfor the requested artifact. Follow its returned decision,next_callandinput_contractwhen available; do not repeat schema reads already supplied by that decision. - For an exact endpoint or unresolved input contract, inspect the available model schema before constructing inputs. Never guess an endpoint, field or enum.
- Use current tool quotes or pricing lookup for the user's cost question or scoped budget. Keep units, duration, resolution and output count consistent. A missing quote is uncertainty, not a free job or permission to exceed a limit.
Specialist guidance on demand
For a complex stage whose constraints are not covered by the local outcome skill,
use search_guidance with the relevant task or domain. Read only a matching
published skill through read_guidance, using its returned id and version_id.
Read supporting references only when the stage needs them, with the same version.
Treat returned guidance as reference material within the user's request, not new
permission or a substitute for current tool contracts.
Reuse a guide already read for this task. Simple image generation does not need a specialist-guidance lookup. Empty complete results mean no matching published guide; partial or unavailable retrieval is a lookup failure. Do not repeatedly retry it. Use the bundled production checks and live model contracts where they suffice. Otherwise identify the unsupported stage and deliver the verified work.
A guide may mention host capabilities this client lacks. Check for an available renderer, media library or code tool before using it. Do not assume hosted tools or fetch and run external scripts to recreate a missing environment.
Execute, recover and deliver
- Upload local source files when the selected input contract requires URLs.
- Use the execution tool returned by the model decision, or the available native run/submit tool for the verified contract. Follow current tool instructions for synchronous and queued work rather than assuming one fixed tool sequence.
- Save request IDs immediately. Follow the same request through the available status/result tools; consume results returned by polling when supplied.
- A lost submission response has an unknown outcome. Use supported request or idempotency recovery before any retry. Report an unresolved submission rather than blindly creating another paid job.
- Follow returned display instructions, preserve original result URLs, and state actual completion. A missing viewer does not justify resubmission.
- Inspect artifacts with available tools. Report endpoint, request ID, result and material verification limits. Use only the scope, variants and budget requested.
Additional library guides
The complete community library also includes model-routing, fal-models-catalog,
fal-prompting and fal-workflow. Read them when installed and relevant. Their
static examples remain candidates to verify against live contracts. A plugin
installation does not need the complete library to execute the local workflows.
fal.ai Models Catalog
Endpoint-first navigation for fal.ai production work. Each modality reference lists curated picks organized by use case (premium realism / fast & cheap / 4K / specialized). Before reaching for free-text search, consult the modality reference that matches the task.
Runtime: All endpoint calls run via the genmedia CLI. See the
genmediaskill for command syntax; rungenmedia initonce if not yet installed.
Endpoint-first rule
- Pick the endpoint ID from the right modality reference.
- Verify it:
genmedia models --endpoint_id <endpoint_id> --json. - Inspect it:
genmedia schema <endpoint_id> --json. - Check cost when relevant:
genmedia pricing <endpoint_id> --json. - Use text search only if the routed endpoint is missing, deprecated, rejected, or the role is not covered here:
genmedia models "<task description>" --json
genmedia docs "<topic>" --json
Do not invent endpoint IDs.
Modality references
Load the reference matching the user's task:
- text-to-image.md, image generation from prompt (text-heavy, premium still, fast draft)
- image-to-image.md, image editing, inpainting, background removal, upscaling
- text-to-video.md, video generation from prompt (highest quality, fast/economical, multi-shot storytelling)
- image-to-video.md, video from a reference frame (including audio-driven and lip-sync variants)
- video-to-video.md, video edit, restyle, upscale, background removal
- text-to-3d.md, 3D model generation from text
- image-to-3d.md, 3D model generation from reference images
- text-to-audio.md. TTS, music, SFX generation
- audio-to-text.md, speech-to-text (Whisper, ElevenLabs Scribe with diarization)
- image-to-text.md. OCR, captioning, VQA, detection, segmentation
Utility endpoints
Workflow utility endpoint IDs (resize, composite, mask, audio merge, subtitle, etc.) live in the fal-workflow skill:
fal-workflow/references/utility-endpoints.md.
Utility endpoints are explicit because they are deterministic tools, not creative model choices. Always inspect schema before use.
Fal Motion Graphics
Read the production guide for this workflow. It preserves fal's published production guidance, not a promise that every host tool exists here.
Before execution, map host-specific tools to available capabilities. Use genmedia
for model calls in terminal agents, or the installed fal MCP tools in plugin hosts.
Resolve current endpoints and inspect their contracts; the guide's model names and
prices are dated candidates. Preserve the user's model, provider, scope and budget.
Do not infer authorization from a guide's defaults or mandatory review language.
Check that the required local Python, Node, browser, renderer and media tools exist before using them. Install publicly documented dependencies only within the user's authorized setup. Otherwise report the missing dependency and stop the dependent stage. This package does not supply hosted execution or an asset library.
Read supporting references from this skill folder as the guide directs. Record actual request IDs and output paths. Deliver only artifacts you inspected; identify incomplete stages and unverified checks.
fal.ai Prompting
Runtime: All endpoint calls run via the genmedia CLI. See the
genmediaskill for command syntax; rungenmedia initonce if not yet installed.
Model families have meaningful prompting nuances. A prompt that works on GPT Image 2 (long, structured, exact text in quotes) will fail on Happy Horse (which wants ~20 plain-English words). This skill collects family-specific guides.
When to load which reference
| Reference | Load when |
|---|---|
| kling.md | Working with Kling video models (O3, v3), multi-prompt, element controls, Standard vs Pro tier |
| gpt-image-2.md | Working with openai/gpt-image-2 or /edit, structured prompts, EXACT TEXT, multi-image compositing |
| happy-horse.md | Working with alibaba/happy-horse/text-to-video or image-to-video, brevity-first, camera language |
Universal principles (all families)
- Visual facts beat prestige adjectives. Replace "stunning, cinematic, masterpiece" with "overcast daylight, brushed aluminum, 50mm feel."
- Style tags need visual targets. "Minimalist brutalist" → "cream background, heavy black sans serif, asymmetrical type block, generous negative space."
- One controlled variable per iteration. Comparison only works when one axis changes at a time.
- Inspect schema before assuming a control exists.
genmedia schema <endpoint_id> --json. Negative prompt, seed, multi-prompt, and reference-image fields differ across families. - Per-family rules override universal advice. Happy Horse rejects what GPT Image 2 rewards.
Catalog cross-reference
For "which model do I use" questions, see fal-models-catalog:
- Text-to-image endpoint selection → fal-models-catalog/references/text-to-image.md
- Text-to-video endpoint selection → fal-models-catalog/references/text-to-video.md
- Image-to-video endpoint selection → fal-models-catalog/references/image-to-video.md
fal.ai Recipes
Runtime: All endpoint calls run via the genmedia CLI. See the
genmediaskill for command syntax; rungenmedia initonce if not yet installed.
A recipe is a use-case-driven pipeline. It tells you the inputs to collect, the genmedia calls to chain, and the quality bar to verify before returning.
Recipes use genmedia for execution and fal-models-catalog for endpoint defaults. They differ from fal-workflow:
- fal-workflow = how to build a pipeline (JSON authoring or CLI orchestration patterns), generic
- fal-recipes = how to produce a specific kind of content, opinionated by use case
Available recipes
| Reference | Use for |
|---|---|
| cinematography.md | Cinematic stills and video, shot language, lighting, lens, color grade |
| character-design.md | Original characters with consistent identity across shots |
| commercial.md | Product photography, ads, e-commerce batches, hero shots |
| storytelling.md | Multi-shot narratives, short films, ads, brand films, social stories |
| character-lipsync.md | Talking head / lip-sync video (TTS → animated portrait) |
| image-restoration.md | Smart-dispatch restoration, deblur, denoise, dehaze, fix faces, document restore |
| virtual-tryon.md | Apply a garment onto a person photo (with optional cleanup chain) |
| video-with-audio.md | Add narration / SFX / music to a silent video |
| product-shot.md | Hero product photography from a packshot reference |
| realism.md | Photoreal stills (candid, editorial, documentary, archival, food, nature, architectural) with an anti-AI-look checklist |
How to choose a recipe
- Match the user's intent to a use case in the table above.
- If multiple recipes apply (e.g., "commercial featuring a consistent character"), load both and run the dominant one, usually the more specific one (
character-designfirst, then commercial framing). - If no recipe matches but the task is multi-step, fall back to
fal-workflowMode B (CLI orchestration) and design the pipeline from scratch. - If the task is a single endpoint call, skip recipes, go directly to the right
fal-models-catalogreference.
Universal recipe structure
Every reference follows the same skeleton so the agent knows where to look:
- Inputs to collect: only what changes the pipeline.
- Genmedia workflow: endpoint discovery, schema inspection, upload, run, status, download.
- Prompt build order: domain-specific structure (e.g., SCLCAM for cinema, anchor + variable for character).
- Patterns / examples: concrete prompt templates and finished examples.
- Quality bar: explicit checks before returning.
Cross-references
- For endpoint defaults: fal-models-catalog
- For prompt-craft per model family: fal-prompting
- For pipeline patterns (fan-out, sequential, frame-bridging, etc.): fal-workflow Mode B
- For utility endpoints (resize, composite, audio merge, subtitle, etc.): fal-workflow/references/utility-endpoints.md
Information lives in one place. If a recipe needs an endpoint listed in the catalog, it links to the catalog instead of duplicating the list.
fal-redesign
Runtime: Self-contained Node runtime under
runtime/(runtime/bin/fal-site.mjs). Does things genmedia CLI cannot (puppeteer screenshotting, multi-vision pipeline, file orchestration). First-time setup:cd runtime && npm install. Override the runtime path withFAL_SITE_RUNTIME=/abs/path.
fal-redesign turns "I coded a site, make it look amazing" into a concrete, implementable design pass.
your index.html → screenshot (1920×1200)
screenshot + brand → opus-4.7 writes a redesign prompt
screenshot + prompt → fal-ai/gpt-image-2/edit → after.png
after.png → opus-4.7 writes Markdown build-spec + tokens.json
→ returned to Claude Code / Codex
The agent reads after.png + changes.md + tokens.json, applies the spec to the real HTML, refreshes, optionally runs iterate for a residual pixel-fix pass.
When to invoke
- User has a local
index.htmlor a running dev server and asks to improve the design, make it world-class, redesign, polish, or run a design review. - User describes a brand/product in freeform text and asks for a fresh site (greenfield mode →
generate).
Do NOT invoke for:
- Copy-only edits (the skill is visual-design focused).
- Backend, build config, or infra tasks.
Commands
All four modes are subcommands of the Node runtime. Invoke directly:
upgrade: redesign a coded site
node runtime/bin/fal-site.mjs upgrade --target <path-or-url> [--context "..."] [--variants N] [--out <dir>]
Pass --variants N (2-8) to fan out into N distinct design directions in parallel. You get after-01-<slug>.png, after-02-<slug>.png, plus a gallery.html to compare them side-by-side. Pick one, then run describe on the chosen PNG to produce its build-spec.
Outputs in <out>/:
before.png: current-site screenshot.after.png: redesigned reference image.edit-prompt.txt: transformation prompt fed to gpt-image-2.changes.md: Markdown build-spec with a leading "Hard constraints" section (also echoed to stdout).tokens.json: design tokens (colors, typography clamps, grid, buttons).
describe: re-run the build-spec on an existing after.png
Useful if the first spec was noisy or if you want to iterate on the spec without regenerating the image.
node runtime/bin/fal-site.mjs describe --after <path/to/after.png> [--out <dir>]
iterate: residual pixel-fix pass
After the agent has implemented the spec, screenshot the live site and emit a delta-spec vs the reference.
node runtime/bin/fal-site.mjs iterate --target <path-or-url> --reference <path/to/after.png> [--out <dir>]
Outputs current.png + delta.md.
generate: greenfield (brief → site)
node runtime/bin/fal-site.mjs generate --context "<freeform context>" [--variants 4] [--out <dir>]
Required environment
export FAL_KEY=... # https://fal.ai/dashboard/keys
Models used:
anthropic/claude-opus-4.7: viaopenrouter/routerandopenrouter/router/vision(overridable withFAL_SITE_MODEL).fal-ai/gpt-image-2: greenfield hero + mockup renders.fal-ai/gpt-image-2/edit: screenshot-to-redesign transformation.
Usage pattern for agents
- Check
FAL_KEY. If unset, ask the user to export it and stop. - Pick the mode.
- If the user references a file path that exists or a URL (
http://localhost:...) →node runtime/bin/fal-site.mjs upgrade. - Otherwise →
node runtime/bin/fal-site.mjs generate.
- Run the script. Each
upgradepass takes 60–180s (1 screenshot + 2 vision calls + 1 image-edit). Emit a brief status to the user before calling. - Surface the result.
- Open
after.png(Read tool) so the user sees the new design. - Paste
changes.mdin the chat (or the highlights). - Ask: "Want me to implement these changes in
<file>now?"
- If yes, implement. Read the current file. Apply the spec section by section, obeying the
Hard constraintsverbatim and pulling exact values fromtokens.json. For imagery in the result grid, look atafter.pngdirectly and either use<img>placeholders at the matching aspect ratio or source stock that matches the mood. - Optional iterate. After implementation, offer
node runtime/bin/fal-site.mjs iterate --target <file> --reference <after.png>for a residual delta-spec. Apply deltas, refresh.
Model notes
- Opus 4.7 handles multi-image reasoning and produces precise design specs. For 3× cheaper runs with near-parity on this task, set
FAL_SITE_MODEL=anthropic/claude-sonnet-4.6. gpt-image-2/editis the right primitive because it edits an existing screenshot while preserving legible in-image text, avoid substituting other image models here.
Runtime details
The skill ships a small Node 18+ runtime under runtime/ (puppeteer, @fal-ai/client, sharp). First-time setup: cd runtime && npm install. Override the runtime path with FAL_SITE_RUNTIME=/abs/path.
fal-regenerate-3d Skill
Runtime: Asset generation steps run via the genmedia CLI (FLUX.2 / GPT-Image-2 / Meshy v6 / Seedance / etc.). The final deliverable is a static HTML page with Three.js, generated assets are bundled into it. See the
genmediaskill for command syntax; rungenmedia initonce if not yet installed.
End-to-end recipe to ship a polished, multi-character 3D web experience using fal.ai models. This is the recipe that powers fal-roster.vercel.app: a cyberpunk character selector with 10 unique operatives, each with a matching companion creature, environment-themed floor texture, animated background and color palette.
What it builds
For each character you get:
- A stylized 3D character GLB (rigged + animated, baked into the file)
- A companion creature GLB (small static, themed to match the character)
- A per-character PBR floor (basecolor / normal / roughness / metalness, all generated)
- A looped video background keyed to the biome
- A 3-color palette that drives the whole UI (CSS custom properties)
- A portrait crop for the roster card
All packaged into a single static HTML page with a Three.js scene. ~25–35 MB of GLBs total after compression.
Pipeline
1. GPT-Image-2 → 1024x1536 character full-body T-pose (per character)
2. Meshy v6 → image-to-3d, enable_rigging=true, animation_action_id={chosen}
→ animated GLB (idle, dance, alert, etc.)
3. GPT-Image-2/edit → companion creature image, color-locked to character palette
4. Meshy v6 → image-to-3d, enable_rigging=false → static creature GLB
5. PATINA → fal-ai/patina/material/extract on the character image,
returns basecolor + normal + roughness + metalness for the floor
6. Seedance 2.0 → bytedance/seedance-2.0/fast/image-to-video, 8s loop
7. gltf-transform CLI → resize 1024 → webp q80 → draco
(typically 95–96% size reduction, ~400–800 KB final)
8. Three.js scene → MeshStandardMaterial floor with alphaMap circular cutout,
mirrored reflection (refl.y = root.y, scale.y = -1),
breathing animation on companions,
per-character palette via CSS custom properties (--c1/--c2/--c3),
per-character floor texture swap on character click,
transition lines + radial flash on swap
CREATE-YOUR-OWN flow
Visitors with a FAL key can generate their own character + companion live, in-browser:
flux-2 klein 9b (text-to-image)
└─ character full-body image
├─ Meshy v6 (rigged + animated) → character GLB
└─ flux-2 klein 9b/edit → companion image
└─ Meshy v6 (no rig) → companion GLB
Cost: ~$2–3 per generation (4 fal calls). Runs in background, modal closes on Generate so the user can keep using the experience while the gen runs. The CREATE YOUR OWN tile transforms into a loading state, then becomes the new character card with a ↻ re-create button.
Key fal endpoints used
| Step | Endpoint |
|---|---|
| Character image (curated) | openai/gpt-image-2 |
| Character image (live) | fal-ai/flux-2/klein/9b |
| Companion image | fal-ai/gpt-image-2/edit or fal-ai/flux-2/klein/9b/edit |
| 3D character/companion | fal-ai/meshy/v6/image-to-3d |
| Per-character floor PBR | fal-ai/patina/material/extract |
| Background video | bytedance/seedance-2.0/fast/image-to-video |
| Logo / icon cleanup | fal-ai/bria/background/remove |
Meshy animation IDs
Curated dance / idle action IDs (full list at https://docs.meshy.ai/en/api/animation-library):
| ID | Animation |
|---|---|
| 0 | Idle (default) |
| 2 | Alert |
| 36 | Confused (scratch) |
| 48 | Mirror viewing |
| 64 | All_Night_Dance |
| 405 | Joyful_Dance_with_Hand_Sway |
| 591 | Hip_Hop_Dance |
| 64–83 | Various Pop_Dance variants |
Three.js scene notes
- Floor:
PlaneGeometry(7, 7, 220, 220)cut into a disc via radial-gradientalphaMap. High tessellation enables realdisplacementMap(uses basecolor as height). - Reflection: clone of the root with
scale.y = -1,BackSide,depthWrite = false,renderOrder = -1. For characters whose origin is at the feet,refl.position.y = root.position.yproduces a visible mirror; the floor'stransparent = true; opacity ≈ 0.5lets it bleed through. - Breathing: per-frame
scale.setScalar(base * (1 + sin(t*1.3)*0.025))+ a small Y bob on companions. The reflection mirrors the bob so the mirror stays consistent. - Palette swap:
:root.style.setProperty('--c1', hex)etc. Every UI element (sparklines, pulses, bars, model pills, edge map dots) derives its color fromvar(--c1)/var(--c2). - Floor swap:
texLoader.load()4 PBR maps fromassets/floor/{charId}/, dispose old textures, setfloorMat.colorback to white (since the basecolor is already char-themed). - Transition: 9 diagonal lines sweep across the viewport (
@keyframes tfx-sweep) on character click + a radial flash; bg video crossfades between two<video>elements; character GLB slides out and the new one slides in.
Reference implementation
- Live: https://fal-roster.vercel.app
- Skill repo: https://github.com/lovisdotio/skills-fal-ai
Cost reference (curated build)
For one full character:
| Step | Approx. cost |
|---|---|
| 1 GPT-Image-2 (character) | $0.04 |
| 1 Meshy v6 rigged + animated | $0.80 |
| 1 GPT-Image-2/edit (companion) | $0.04 |
| 1 Meshy v6 static (companion) | $0.20 |
| 1 PATINA floor (4 maps) | $0.04 |
| 1 Seedance fast (bg video) | $0.08 |
| Total per character | ~$1.20 |
| 10 characters | ~$12 |
Runtime parallelizes well, the original 10-character set was generated in ~10 minutes wall-clock with 9 concurrent jobs per stage.
Fal Script Writer
Read the production guide for this workflow. It preserves fal's published production guidance, not a promise that every host tool exists here.
Before execution, map host-specific tools to available capabilities. Use genmedia
for model calls in terminal agents, or the installed fal MCP tools in plugin hosts.
Resolve current endpoints and inspect their contracts; the guide's model names and
prices are dated candidates. Preserve the user's model, provider, scope and budget.
Do not infer authorization from a guide's defaults or mandatory review language.
Check that the required local Python, Node, browser, renderer and media tools exist before using them. Install publicly documented dependencies only within the user's authorized setup. Otherwise report the missing dependency and stop the dependent stage. This package does not supply hosted execution or an asset library.
Read supporting references from this skill folder as the guide directs. Record actual request IDs and output paths. Deliver only artifacts you inspected; identify incomplete stages and unverified checks.
Fal Shot Craft
Read the production guide for this workflow. It preserves fal's published production guidance, not a promise that every host tool exists here.
Before execution, map host-specific tools to available capabilities. Use genmedia
for model calls in terminal agents, or the installed fal MCP tools in plugin hosts.
Resolve current endpoints and inspect their contracts; the guide's model names and
prices are dated candidates. Preserve the user's model, provider, scope and budget.
Do not infer authorization from a guide's defaults or mandatory review language.
Check that the required local Python, Node, browser, renderer and media tools exist before using them. Install publicly documented dependencies only within the user's authorized setup. Otherwise report the missing dependency and stop the dependent stage. This package does not supply hosted execution or an asset library.
Read supporting references from this skill folder as the guide directs. Record actual request IDs and output paths. Deliver only artifacts you inspected; identify incomplete stages and unverified checks.
Fal Video Generation
Read the production guide for this workflow. It preserves fal's published production guidance, not a promise that every host tool exists here.
Before execution, map host-specific tools to available capabilities. Use genmedia
for model calls in terminal agents, or the installed fal MCP tools in plugin hosts.
Resolve current endpoints and inspect their contracts; the guide's model names and
prices are dated candidates. Preserve the user's model, provider, scope and budget.
Do not infer authorization from a guide's defaults or mandatory review language.
Check that the required local Python, Node, browser, renderer and media tools exist before using them. Install publicly documented dependencies only within the user's authorized setup. Otherwise report the missing dependency and stop the dependent stage. This package does not supply hosted execution or an asset library.
Read supporting references from this skill folder as the guide directs. Record actual request IDs and output paths. Deliver only artifacts you inspected; identify incomplete stages and unverified checks.
Fal Video Production
Read the production guide for this workflow. It preserves fal's published production guidance, not a promise that every host tool exists here.
Before execution, map host-specific tools to available capabilities. Use genmedia
for model calls in terminal agents, or the installed fal MCP tools in plugin hosts.
Resolve current endpoints and inspect their contracts; the guide's model names and
prices are dated candidates. Preserve the user's model, provider, scope and budget.
Do not infer authorization from a guide's defaults or mandatory review language.
Check that the required local Python, Node, browser, renderer and media tools exist before using them. Install publicly documented dependencies only within the user's authorized setup. Otherwise report the missing dependency and stop the dependent stage. This package does not supply hosted execution or an asset library.
Read supporting references from this skill folder as the guide directs. Record actual request IDs and output paths. Deliver only artifacts you inspected; identify incomplete stages and unverified checks.
fal.ai Workflows: Two Modes
Runtime: Two modes. Mode A authors
.jsonfiles for the fal.ai workflow runtime (executed in the cloud, no local CLI needed). Mode B drives the genmedia CLI for local orchestration. See thegenmediaskill for Mode B command syntax; rungenmedia initonce if not yet installed.
This skill covers two complementary ways to build multi-step media pipelines on fal.ai. They share endpoints and concepts but differ in deliverable.
| Mode | Deliverable | When to use |
|---|---|---|
| A. Workflow JSON | A portable .json file the fal.ai workflow runtime executes | The user wants a reusable, shareable workflow asset; the pipeline graph is fixed at design time |
| B. genmedia CLI orchestration | A sequence of genmedia run / status / upload calls (often scripted) | Local scripting, exploratory pipelines, dataset jobs, branching logic, or pipelines that need conditional steps |
If unsure: prefer Mode A when the result is a deliverable for someone else to run; Mode B when you are running it yourself or steps need runtime decisions.
Mode A: Workflow JSON authoring
Generate 100% working, production-ready fal.ai workflow JSON files. Workflows chain multiple AI models together via a declarative graph.
JSON-mode references:
- MODELS.md, model configurations for JSON nodes
- PATTERNS.md, reusable JSON workflow patterns
- EXAMPLES.md, code snippets and partial examples
- WORKFLOWS.md, full JSON workflows (debugging reference; use only when user reports errors)
Mode B: genmedia CLI orchestration
Plan and execute a sequence of genmedia calls with clear inputs, outputs, dependencies, and quality checks. Use this when a single model call is not enough and the orchestration happens in your shell, not on fal.ai.
CLI-mode references:
- pipeline-patterns.md, fan-out, sequential composition, frame bridging, multi-modal assembly, variation matrices
- node-rules.md, per-role rules (planner / generator / editor / utility / QA / manifest)
- utility-endpoints.md, utility endpoint catalog (resize, composite, mask, audio, subtitle, etc.)
- recipes.md, end-to-end recipes (cinematic video, product campaign, character continuity, narrated documentary, dataset, social batch)
For default endpoint choices in Mode B, consult fal-models-catalog. Always run genmedia schema <endpoint_id> --json before executing and genmedia pricing <endpoint_id> --json when cost matters.
Mode A: Workflow JSON authoring (continued)
Core Architecture
Valid Node Types
⚠️ ONLY TWO VALID NODE TYPES EXIST:
| Type | Purpose |
|---|---|
"run" | Execute a model/app |
"display" | Output results to user |
❌ INVALID: type: "input" - This does NOT exist! Input is defined ONLY in schema.input.
Minimal Working Example
{
"name": "my-workflow",
"title": "My Workflow",
"contents": {
"name": "workflow",
"nodes": {
"output": {
"type": "display",
"id": "output",
"depends": ["node-image"],
"input": {},
"fields": { "image": "$node-image.images.0.url" }
},
"node-image": {
"type": "run",
"id": "node-image",
"depends": ["input"],
"app": "fal-ai/flux/dev",
"input": { "prompt": "$input.prompt" }
}
},
"output": { "image": "$node-image.images.0.url" },
"schema": {
"input": {
"prompt": {
"name": "prompt",
"label": "Prompt",
"type": "string",
"required": true,
"modelId": "node-image"
}
},
"output": {
"image": { "name": "image", "label": "Generated Image", "type": "string" }
}
},
"version": "1",
"metadata": {
"input": { "position": { "x": 0, "y": 0 } },
"description": "Simple text to image workflow"
}
},
"is_public": true,
"user_id": "",
"user_nickname": "",
"created_at": ""
}
Reference Syntax
| Reference | Use Case | Example |
|---|---|---|
$input.field | Input value | $input.prompt |
$node.output | LLM text output | $node-llm.output |
$node.images.0.url | First image URL | $node-img.images.0.url |
$node.image.url | Single image URL | $node-upscale.image.url |
$node.video.url | Video URL | $node-vid.video.url |
$node.audio_file.url | Audio URL | $node-music.audio_file.url |
$node.frame.url | Extracted frame | $node-extract.frame.url |
CRITICAL: No String Interpolation
⚠️ NEVER mix text with variables! Variable MUST be the ENTIRE value.
// ❌ WRONG - WILL BREAK
"prompt": "Create image of $input.subject in $input.style"
// ✅ CORRECT - Variable is the ENTIRE value
"prompt": "$input.prompt"
"prompt": "$node-llm.output"
To combine values: Use fal-ai/text-concat or fal-ai/workflow-utilities/merge-text. See Model Reference.
Critical Rules
C1: Dependencies Must Match References
// ❌ WRONG
"node-b": {
"depends": [],
"input": { "data": "$node-a.output" }
}
// ✅ CORRECT
"node-b": {
"depends": ["node-a"],
"input": { "data": "$node-a.output" }
}
C2: ID Must Match Object Key
// ❌ WRONG
"my-node": { "id": "different-id" }
// ✅ CORRECT
"my-node": { "id": "my-node" }
C3: Use Correct LLM Type
openrouter/router→ Text only, no image_urlsopenrouter/router/vision→ ONLY when analyzing images
C4: Schema modelId Required
"schema": {
"input": {
"field": { "modelId": "first-consuming-node" }
}
}
C5: Output Depends on All Referenced Nodes
"output": {
"depends": ["node-a", "node-b", "node-c"],
"fields": {
"a": "$node-a.video",
"b": "$node-b.images.0.url"
}
}
Quick Reference Card
Output References
| Model Type | Output Reference |
|---|---|
| LLM | $node.output |
| Text Concat | $node.results |
| Merge Text | $node.text |
| Image Gen (array) | $node.images.0.url |
| Image Process (single) | $node.image.url |
| Video | $node.video.url |
| Music | $node.audio_file.url |
| Frame Extract | $node.frame.url |
Use genmedia models "<query>" --json or genmedia models --category <cat> --json to discover current models. See references/MODELS.md for workflow code templates.
Input Schema
"schema": {
"input": {
"text_field": {
"name": "text_field",
"label": "Display Label",
"type": "string",
"description": "Help text",
"required": true,
"modelId": "consuming-node"
},
"image_urls": {
"name": "image_urls",
"type": { "kind": "list", "elementType": "string" },
"required": true,
"modelId": "node-id"
}
}
}
Pre-Output Checklist
Before outputting any workflow, verify:
- ⚠️ All nodes have
type: "run"ortype: "display"ONLY (NOtype: "input"!) - ⚠️ No string interpolation - variable MUST be ENTIRE value
- Every
$node.xxxhas matchingdependsentry - Every node
idmatches object key - Input schema has
modelIdfor each field - Output depends on ALL referenced nodes
- Correct LLM type (router vs router/vision)
Authoring a workflow JSON
Author the JSON file by hand following the structure shown above. There is no script wrapper; the agent writes the file directly. Validate before delivery:
- Every node id matches its object key.
- Every
$node.xxxreference appears independs. - No string interpolation; variables are entire values.
- Schema input has
modelIdfor each field. - Output node
dependsincludes every node it references.
For each model used, inspect the schema first:
genmedia schema <endpoint_id> --json
Then write the corresponding input block in the workflow JSON.
Troubleshooting
Invalid Node Type Error (MOST COMMON)
Error: unexpected value; permitted: 'run', 'display', field required
Cause: You created a node with type: "input" which does NOT exist.
Solution: Remove ANY node with type: "input". Define input fields ONLY in schema.input.
Dependency Error
Error: Node references $node-x but doesn't depend on it
Solution: Add the referenced node to the depends array.
ID Mismatch Error
Error: Node key "my-node" doesn't match id "different-id"
Solution: Ensure the object key matches the id field exactly.
LLM Vision Error
Error: image_urls provided but using text-only router
Solution: Switch to openrouter/router/vision when analyzing images.
Finding Model Schemas
Every model's input/output schema:
https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=[endpoint_id]
Example:
https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=fal-ai/nano-banana-pro
Mode B: genmedia CLI orchestration
When the deliverable is local execution rather than a portable JSON file, plan a pipeline of genmedia calls.
Inputs to collect
Ask only for missing information that changes the pipeline:
- Final deliverable: image set, video, clips, audio, subtitles, dataset, social batch, product campaign, storyboard, style exploration.
- Source assets: product images, character references, first frames, video, audio, logo, transcript, brand guide.
- Runtime limits: quality target, cost sensitivity, number of variants, duration, aspect ratios, deadline.
- Continuity requirements: product identity, character face, scene layout, voice, color grade.
- Model preference: ask only when quality/speed/cost tradeoffs are not clear from the brief.
Core CLI workflow
- Write a short pipeline graph before running anything.
input assets -> planner -> generation nodes -> utility nodes -> QA -> final outputs
- Resolve endpoints for each role. Check known endpoint IDs first via
fal-models-catalog.
genmedia models --endpoint_id <endpoint_id> --json
Use text search only as fallback discovery for roles not covered:
genmedia models "image generation product photography" --json
genmedia docs "fal.ai workflow utility endpoints" --json
- Inspect every endpoint before use.
genmedia schema <endpoint_id> --json
genmedia pricing <endpoint_id> --json
- Upload local files once and reuse returned URLs.
genmedia upload ./input.png --json
- Run each node with JSON output. Use
--asyncfor slow generation; poll withgenmedia status.
genmedia run <endpoint_id> --<field> "<value>" --json
genmedia run <endpoint_id> --<field> "<value>" --async --json
genmedia status <endpoint_id> <request_id> --download "./outputs/workflow/{request_id}_{index}.{ext}" --json
-
For downstream nodes, pass the media URL from the previous result. Only upload local intermediate files when no URL is available.
-
Download final assets with templates that cannot collide:
--download "./outputs/workflow/{request_id}_{index}.{ext}"
- Return a compact manifest (see node-rules.md for the manifest schema).
CLI pipeline rules
- One node, one transformation.
- Fan out independent generation / crop / upscale / subtitle / variation lanes.
- Sequential chains only when node B genuinely needs node A output.
- Prefer reference / edit / image-to-video over independent text-only generations when continuity matters.
- Use utility endpoints for deterministic work (crop, resize, grid, composite, audio merge, subtitle, speed change, compression).
- Record endpoint, schema-relevant parameters, request ID, and output path for every node.
- On 422 errors: read
validation_errors, re-inspect schema, fix the exact field.
CLI quality gate
Before returning, verify:
- The pipeline graph matches the requested deliverable.
- No generation model was chosen from memory alone.
- All local source files were uploaded before use.
- Final files were saved through
--download. - Utility endpoints used exact schema fields.
- Continuity anchors were repeated where identity or product fidelity matters.
- Each node output is either accepted, retried, or marked with a defect.
If the workflow becomes too complex, stop expanding and ask the user to choose between faster iteration, higher fidelity, or broader variation.
Fan cam production with genmedia
Use this skill when the user wants a personalized spectator video that feels like a real live sports broadcast cutaway. The usual input is one photo of the person, event details, and a desired reaction or situation.
Runtime is the genmedia CLI. Use the genmedia skill for command syntax. Load
model-routing, fal-prompting, and genmedia-workflow when endpoint choice,
model-specific prompt craft, or pipeline execution details matter.
Do not encode private examples, local file paths, user-specific workflow names, or conversation-specific details into prompts or docs. Keep this skill generalized.
References
Load only what is needed:
references/prompt-contract.mdfor the image prompt and Kling prompt rules.references/genmedia-commands.mdfor executable CLI command patterns.references/examples.mdfor sport-specific examples.
Required inputs
Ask only for missing information that changes execution:
- User photo: local path or URL. This is the identity reference.
- Event details: sport, matchup, venue, league, broadcast context, wardrobe, scoreboard idea, crowd behavior, and any specific scenario.
- Reaction or situation: excited, happy, laughing, sad, neutral, angry, surprised, nervous, focused, eating, distracted, caught on camera, noticing the stadium screen, celebrating, disappointed, or another user-specified moment.
- Budget or quality preference only when the user explicitly asks for economy,
preview, or native 4K final output. Otherwise use the standard fan-cam
defaults: GPT Image 2 edit at
quality=highwith a 3840x2160 frame, then Kling v3 Pro.
If the user gives a local image path, upload it once with genmedia upload and
reuse the returned URL. If the user gives multiple references, treat the first
person image as the identity source and later images as optional venue,
broadcast, or styling references.
The user photo is an identity reference, not a Kling-ready start frame. Do not
skip GPT Image 2 edit just because the user supplied a person's photo. For a
personalized fan-cam, first use openai/gpt-image-2/edit to place the person
inside a realistic 16:9 broadcast scene, then use the approved generated frame
as Kling start_image_url.
Pipeline
Default graph:
photo URL -> prompt planning -> GPT Image 2 edit frame -> optional compression -> Kling v3 image-to-video -> downloaded video manifest
The GPT Image 2 edit frame is mandatory when the input is an ordinary person photo. Only bypass this step if the user explicitly provides an already approved 16:9 broadcast fan-cam frame and asks to animate that frame.
The planning step is performed by the agent using this skill. Do not call a separate LLM endpoint just to write prompts unless the user explicitly asks for a hosted planner. Write the image prompt and Kling multi prompts directly.
Endpoint selection
Always verify endpoints before use:
genmedia models --endpoint_id openai/gpt-image-2/edit --json
genmedia models --endpoint_id fal-ai/kling-video/v3/standard/image-to-video --json
genmedia models --endpoint_id fal-ai/kling-video/v3/pro/image-to-video --json
genmedia models --endpoint_id fal-ai/kling-video/v3/4k/image-to-video --json
Inspect schemas before running:
genmedia schema openai/gpt-image-2/edit --json
genmedia schema fal-ai/kling-video/v3/pro/image-to-video --format openapi --json
Use --format openapi for Kling v3 image-to-video endpoints because compact
schema output may omit top-level fields such as multi_prompt,
start_image_url, duration, prompt, elements, shot_type,
negative_prompt, and cfg_scale.
Check pricing when cost matters:
genmedia pricing openai/gpt-image-2/edit --json
genmedia pricing fal-ai/kling-video/v3/standard/image-to-video --json
genmedia pricing fal-ai/kling-video/v3/pro/image-to-video --json
genmedia pricing fal-ai/kling-video/v3/4k/image-to-video --json
GPT Image 2 quality choice
- Use
quality=highby default for personalized fan-cam frames. GPT Image 2 price is strongly affected bylowvshigh, but fan-cam identity, broadcast integration, and readable overlays need the stronger default. - Use
quality=lowonly when the user explicitly requests economy, preview, fast iteration, or lower-cost social drafts. - Use
output_format=jpegfor the generated broadcast frame unless the user needs transparency or lossless output. - Use 16:9 4K frame size by default:
{"width":3840,"height":2160}
Kling v3 choice
Select the endpoint based on the brief:
fal-ai/kling-video/v3/pro/image-to-video: default fan-cam endpoint. Use it for normal personalized sports cutaways, public examples, and any request where the user did not explicitly ask for economy.fal-ai/kling-video/v3/standard/image-to-video: use only when the user explicitly asks for economy, preview, fastest iteration, or lower cost.fal-ai/kling-video/v3/4k/image-to-video: use only for final premium 4K delivery or when the user explicitly asks for 4K video. Check pricing first.
Do not choose from memory alone. Verify model status and schema with genmedia in the current session.
Shot and duration planning
The agent decides the number and duration of multi prompts.
Hard rules:
- Each multi prompt must be at least 3 seconds.
- Total video duration must be 15 seconds or less.
- Use 2 to 5 multi prompts.
- Set the top-level Kling
durationequal to the sum of all beat durations. - If a real user-provided or approved reference is supplied through Kling
elements, every multi prompt must reference@Element1. Do not invent extra elements just to satisfy a prompt pattern. - Keep every Kling prompt concise. Aim for 250-430 characters.
Recommended patterns:
- Simple cutaway: 2 beats, 6 seconds total.
- Standard reaction: 3 beats, 9 seconds total.
- Rich fan-cam moment: 4 beats, 12 seconds total.
- Full story beat: 5 beats, 15 seconds total.
Do not always use five beats. Pick the smallest number that expresses the moment clearly.
Scene planning
The fan-cam does not need to be only a zoom on the spectator. Design the scene from the event details:
- A nervous fan watching a decisive point.
- A supporter eating or drinking when the broadcast camera catches them.
- A spectator noticing themselves on the stadium screen.
- A quiet tennis audience reaction during a tiebreak.
- A basketball lower-bowl fan reacting to a buzzer-beater.
- A race grandstand spectator turning toward a pass or crash offscreen.
- A combat sports crowd cutaway during a tense round.
- A watch-party or esports arena reaction if the user specifies it.
Keep the whole video anchored to the generated frame. Use motion, camera correction, crowd behavior, expression changes, and offscreen event energy to create the sequence.
Broadcast logo and overlay
Add a small top-right TV channel bug when it fits the brief. It should feel sport-specific and broadcast-realistic, but generic unless the user supplies an exact approved logo or explicitly requests a named network.
Good generic examples:
FOOTBALL LIVECOURT LIVEBASKET LIVERACE LIVEFIGHT LIVEMATCH CAM
Use compact score or timing overlays when the event calls for them. Keep them small, integrated, and secondary to the spectator. Avoid fake sponsor marks, large UI graphics, unstable text, and logos that dominate the frame.
Image prompt requirements
The GPT Image 2 edit prompt must:
- Use the uploaded photo as the identity reference.
- Preserve the real face, age impression, skin tone, hair, facial hair, glasses, face structure, asymmetry, pores, wrinkles, blemishes, and ordinary imperfections.
- Create a horizontal 16:9 live TV broadcast screenshot.
- Place the person naturally in the spectator area.
- Make the selected reaction or situation visible but not theatrical.
- Include sport-specific venue, crowd, wardrobe, scoreboard, and broadcast language.
- Include realistic TV capture flaws: mild compression noise, subtle motion blur, off-center crop, foreground occlusion, focus falloff, imperfect background faces, natural venue light, and small exposure inconsistencies.
- Include a small top-right broadcast channel bug when appropriate.
The image prompt must avoid:
- Beauty retouching, AI influencer face, changed face anatomy, enlarged eyes, jawline sharpening, face slimming, porcelain skin, waxy skin.
- Studio portrait, passport photo, selfie framing, isolated subject, pasted face, face cutout, empty background.
- Fake sponsor marks, oversized logos, warped scoreboard text, random props not requested by the user, CGI crowd, cloned faces, anime, cartoon.
Kling prompt requirements
The Kling prompts must:
- Reference
@Element1in every beat only when the request actually includes a real user-provided or approved Klingelementsentry. Otherwise describe the featured spectator from thestart_image_url; do not invent extra elements. - Always submit Kling with
generate_audio=true. Do not usegenerate_audio=falsein this skill. - When using
multi_prompt, do not sendend_image_url; Kling rejectsend_image_urltogether withmulti_prompt. - Preserve the same person, face, outfit, seat area, crowd, overlay, lighting, and channel bug.
- Animate realistic broadcast motion: small head movement, blinking, breath, slight hand motion, food/drink gesture if present, nearby fans shifting, camera push-in, pan, sidestep, operator correction, or crowd swell.
- Use sport-specific language. Never write generic alternatives like "field or court" or "stadium or arena".
- Fit the chosen beat duration.
- If a spoken phrase should be external narration, do not write it as something the featured spectator says. Phrase it as an off-screen broadcast commentator, arena PA voice, or non-diegetic voiceover, and explicitly state that the featured spectator stays silent with no lip sync and no mouth movement matching the voice.
- Avoid face morphing, beautification, unstable scoreboard text, unstable logo, wrong sport, impossible crowd action, excessive camera movement, and sudden scene resets.
Negative prompt
Use a negative prompt like this and adapt only when needed:
low quality, smeared face, distorted faces, duplicated face, deformed hands, broken fingers, fake sponsor marks, oversized logos, unstable broadcast logo, watermark, text artifacts, unstable broadcast banner, flickering scoreboard, warped scoreboard text, unreadable names, passport photo, studio portrait, glamour portrait, beauty lighting, AI influencer, beautified face, changed face, enlarged eyes, sharpened jawline, pasted face, face cutout, over-smoothed skin, plastic skin, waxy skin, CGI crowd, cloned crowd, anime, cartoon, excessive camera movement, wrong sport, wrong venue
Quality gate
Before returning:
- The selected endpoint and schema were verified with genmedia.
- GPT Image 2 edit used
quality=highandimage_size={"width":3840,"height":2160}unless the user explicitly requested an economy or preview run. - If the input was a person photo, a GPT Image 2 edit frame was generated and approved before Kling. The raw person photo was not sent directly to Kling as the fan-cam start frame.
- Kling used
fal-ai/kling-video/v3/pro/image-to-videounless the user explicitly requested economy/preview or native 4K video. - Multi prompt durations are each at least 3 seconds.
- Total duration is 15 seconds or less.
- Top-level Kling duration equals the sum of beat durations.
- Every beat references
@Element1when a real Klingelementsentry is used. - No invented extra elements were added.
- Kling request uses
generate_audio=true. - Kling request does not combine
multi_promptwithend_image_url. - Any intended external narration is not lip-synced to the featured spectator; verify the mouth does not move like the voice belongs to the person on camera.
- The generated frame is below Kling image limits. If not, compress it.
- The person remains recognizable and not beautified.
- The broadcast bug and scoreboard are small and stable enough.
- Final files were downloaded with
--download.
Return a compact manifest with endpoint IDs, request IDs, model settings, prompts used, output URLs, downloaded files, and any visible defects.
Game asset production
Deliver usable game assets rather than an unsliced illustration of a sprite sheet.
Asset contract and production
Collect the engine, logical pixel size, palette, facing direction, animation states, frame counts, FPS, pivot and atlas format. Reuse supplied choices. Write a stable character identity anchor and carry it through every state.
- Define a manifest per animation: frame size, count, order, FPS, pivot and loop. Choose a small first pack from the brief; do not multiply states without need.
- Generate one approved character silhouette with a currently accessible image model. Inspect native pixel dimensions and style before treating it as a master.
- Build each state from the approved reference through a current reference-edit model. Specify orthographic view, a fixed baseline, repeated cell size, no labels and the exact frame count.
- Remove backgrounds when needed with a currently supported matting operation. Use the execution mode and inputs its tool contract supports. Inspect alpha edges; background removal can destroy small details.
- Slice using measured cell boundaries. Check width = columns × cell width and height = rows × cell height. Do not silently pad an incorrectly generated grid. Correct alignment locally or regenerate only the failed state within budget.
- Keep nearest-neighbor resampling for pixel art. Export transparent PNG frames, atlas texture and JSON frame rectangles; include pivot, FPS and loop metadata.
- Produce backgrounds as separate parallax layers only if requested. Keep the light direction, horizon and palette consistent with the character.
Acceptance and delivery
Inspect animation playback and an alpha checkerboard at native size and magnified. Measure frame dimensions, frame count, alpha coverage, atlas bounds and consistent foot contact. Reject duplicate frozen frames in a requested moving state. Check atlas loading in the target engine or a small preview. State engine checks not run. Deliver source sheets, sliced frames, atlas, preview and manifest with filenames ready for import. A plausible sheet alone does not pass.
Execution and specialist guidance
Use the installed fal-media skill for current model discovery, input contracts,
prices, native MCP execution and request recovery. Preserve the user's selected
provider, model, inputs, output count and spending limits.
The production checks above work without another domain skill. If a specialist
stage needs more guidance, follow fal-media to retrieve the relevant published
guide and only its needed version-pinned references. Reuse guidance already read.
If retrieval is unavailable, retain these local checks and current tool contracts;
report any stage that cannot be completed or verified. Do not invent a model,
privileged host tool or unavailable renderer to fill the gap.
Keep a manifest of sources, endpoint, actual inputs, request ID, result URL, local file and QA findings. Inspect delivered artifacts and report unverified checks.
Terminal execution
For a terminal-only workflow, read the genmedia production-plan guide and copy this skill's example stage plan. The guide describes explicit submission, state files and recovery. These examples are optional CLI resources; connected MCP hosts use native fal tools.
Genmedia workflow production
Runtime: All endpoint calls run via the genmedia CLI. See the
genmediaskill for command syntax; rungenmedia initonce if not yet installed.
Use this skill when a single model call is not enough. A workflow is a planned sequence of genmedia calls with clear inputs, outputs, dependencies, and quality checks.
Load references as needed:
references/pipeline-patterns.mdreferences/node-rules.mdreferences/utility-endpoints.mdreferences/recipes.mdmodel-routingfor creative model defaults
Use model-routing for default creative model choices. Still inspect schemas,
check pricing when cost matters, and use exact endpoint fields.
Inputs to collect
Ask only for missing information that changes the pipeline:
- Final deliverable: image set, video, clips, audio, subtitles, dataset, social batch, product campaign, storyboard, style exploration.
- Source assets: product images, character references, first frames, video, audio, logo, transcript, brand guide.
- Runtime limits: quality target, cost sensitivity, number of variants, duration, aspect ratios, deadline.
- Continuity requirements: product identity, character face, scene layout, voice, color grade.
- Model preference: ask the user only when quality, speed, cost, or audio tradeoffs are not clear from the brief.
Core workflow
-
Write a short pipeline graph before running anything.
input assets -> planner -> generation nodes -> utility nodes -> QA -> final outputs -
Resolve endpoints for each role. Check known endpoint IDs first.
genmedia models --endpoint_id openai/gpt-image-2 --json genmedia models --endpoint_id fal-ai/nano-banana-pro/edit --json genmedia models --endpoint_id bytedance/seedance-2.0/image-to-video --json genmedia models --endpoint_id xai/grok-imagine-video/image-to-video --json genmedia models --endpoint_id veed/fabric-1.0 --jsonUse text search only as fallback discovery for roles not covered by
model-routingor the utility reference:genmedia models "image generation product photography" --json genmedia models "image editing reference preservation" --json genmedia models "image to video" --json genmedia models "subtitle video utility" --json genmedia docs "fal.ai workflow utility endpoints" --json -
Inspect every endpoint before use.
genmedia schema <endpoint_id> --json genmedia pricing <endpoint_id> --json -
Upload local files once and reuse returned URLs.
genmedia upload ./input.png --json genmedia upload ./voiceover.wav --json -
Run each node with JSON output. Use async for slow generation.
genmedia run <endpoint_id> --<field> "<value>" --json genmedia run <endpoint_id> --<field> "<value>" --async --json genmedia status <endpoint_id> <request_id> --download "./outputs/workflow/{request_id}_{index}.{ext}" --json -
For downstream nodes, pass the media URL from the previous
resultwhen it is available. If you only have a local file path, upload it first. -
Download final assets with templates that cannot collide.
--download "./outputs/workflow/{request_id}_{index}.{ext}" -
Return a compact manifest.
{ "goal": "short deliverable description", "nodes": [ { "id": "shot_01", "role": "image_to_video", "endpoint_id": "...", "request_id": "...", "input_urls": ["..."], "output_urls": ["..."], "downloaded_files": ["..."], "notes": "continuity or defect notes" } ], "final_files": ["..."] }
Pipeline rules
- Keep one node responsible for one clear transformation.
- Fan out independent generation, crop, upscale, subtitle, or variation nodes.
- Keep sequential chains only when node B needs node A output.
- For consistency, prefer reference/edit or image-to-video over independent text-only generations.
- For default creative model choices, follow
model-routingunless the user names a model. - Use utility endpoints for deterministic work: crop, resize, grid, composite, audio merge, subtitle, speed change, compression.
- Record endpoint, schema-relevant parameters, request ID, and output path for every node.
- If a 422 error occurs, read
validation_errors, inspect schema again, then fix the exact field.
Quality gate
Before returning, verify:
- The pipeline graph matches the requested deliverable.
- No generation model was chosen from memory alone.
- All local source files were uploaded before use.
- Final files were saved through
--download. - Utility endpoints used exact schema fields.
- Continuity anchors were repeated where identity or product fidelity matters.
- Each node output is either accepted, retried, or marked with a defect.
If the workflow becomes too complex, stop expanding and ask the user to choose between faster iteration, higher fidelity, or broader variation.
genmedia CLI: fal.ai endpoint runner
genmedia is the agent-first CLI for fal.ai. It works in a terminal for humans (pretty output) and equally well for agents (structured JSON when piped or with --json). All other skills in this repo call genmedia for execution, they do not wrap the fal.ai HTTP API directly.
For the full command surface (every flag, every option, every example), see references/full-reference.md.
Critical rules
- Always use
--jsonwhen an agent will read the output. Pretty mode is for humans only. - Prefer smart routing for default-quality requests.
genmedia run "<prompt>"(no endpoint, no--promptneeded) classifies the prompt and routes to a sensible default per modality. Only do explicit endpoint discovery when the user names a model, asks for a non-default behavior (specific style, quality tier, parameter), or the smart-route default is wrong for the task. - Never invent endpoint IDs. When you do need a specific endpoint, use
genmedia models "<query>"to discover (auto-filters by inferred modality) andgenmedia models --endpoint_id <id>to verify. - Inspect schema before running with custom params.
genmedia schema <endpoint_id> --jsonshows the exact field names. Smart routing only needsprompt; explicit endpoints with custom params need a schema check first or guessed flags fail with 422. - Save files with
--download, not curl. The CLI handles authentication, naming, and file format detection. - Use
--asyncfor long-running generation. Image work usually completes inline; video/audio/3D usually need queue + status polling.
Command index
| Command | Purpose |
|---|---|
genmedia setup | Configure API key, output mode, auto-update |
genmedia models <query> | Search the catalog (or --category, or --endpoint_id) |
genmedia schema <endpoint_id> | Inspect inputs/outputs (compact or --format openapi) |
genmedia run <endpoint_id> --<param> <value> | Execute a model |
genmedia status <endpoint_id> <request_id> | Poll an async job (with --result, --logs, --cancel, --download) |
genmedia upload <path-or-url> | Upload a local file or remote URL to the fal.ai CDN |
genmedia pricing <endpoint_id> | Check cost per call |
genmedia docs <query> | Search fal.ai documentation |
genmedia init | Install the default skill bundle into .agents/skills/ or .claude/skills/ |
| `genmedia skills <list | install |
genmedia version / genmedia update | Check or apply CLI updates |
Quick patterns
Smart routing (preferred for default-quality requests)
The CLI classifies the prompt by modality (image / video / music / tts / 3d) and picks a sensible default endpoint. The output includes a routed block so you can verify which endpoint actually ran.
genmedia run "a cat on the moon" --json
genmedia run "a 5-second clip of a robot dancing" --json
genmedia run "narrate this paragraph in a calm voice" --json
Override anytime with an explicit endpoint id (positional that contains /):
genmedia run fal-ai/flux/dev --prompt "a cat on the moon" --json
Discover when the user names a fuzzy task or wants a specific endpoint
genmedia models "<query>" auto-applies --category from the same classifier the smart router uses, so the result list is focused on the right modality. Pass --no-classify to disable, or --category <cat> to override.
genmedia models "background removal product image" --json
genmedia models --category text-to-video --limit 5 --json
genmedia models "video models with character consistency" --no-classify --json
genmedia docs "webhook callbacks" --json
Run a specific model and download the result
genmedia run fal-ai/flux/dev \
--prompt "a cat on the moon" \
--download "./out/{request_id}_{index}.{ext}" \
--json
Async + poll
SUBMIT=$(genmedia run fal-ai/veo3.1 --prompt "a dog running" --async --json)
REQ=$(echo "$SUBMIT" | jq -r '.request_id')
genmedia status fal-ai/veo3.1 "$REQ" \
--download "./out/{request_id}_{index}.{ext}" \
--json
Smart routing also works for async — the response includes routed and endpoint_id so you know which endpoint to poll on status:
SUBMIT=$(genmedia run "a 30-second video of waves" --async --json)
REQ=$(echo "$SUBMIT" | jq -r '.request_id')
EP=$(echo "$SUBMIT" | jq -r '.endpoint_id')
genmedia status "$EP" "$REQ" --download "./out/" --json
Upload then run
URL=$(genmedia upload ./photo.jpg --json | jq -r '.url')
genmedia run fal-ai/nano-banana-pro/edit \
--image_urls "$URL" \
--prompt "make the sky stormy" \
--download "./out/{request_id}_{index}.{ext}" \
--json
Setup (first-time only)
If genmedia is not installed:
curl https://genmedia.sh/install -fsS | bash # Linux / macOS
irm https://genmedia.sh/install.ps1 | iex # Windows PowerShell
genmedia setup --non-interactive --api-key "$FAL_KEY"
For full setup details (output modes, auto-update, .env loading) see full-reference.md.
H3 Cinematic Prompter
Read the production guide for this workflow. It preserves fal's published production guidance, not a promise that every host tool exists here.
Before execution, map host-specific tools to available capabilities. Use genmedia
for model calls in terminal agents, or the installed fal MCP tools in plugin hosts.
Resolve current endpoints and inspect their contracts; the guide's model names and
prices are dated candidates. Preserve the user's model, provider, scope and budget.
Do not infer authorization from a guide's defaults or mandatory review language.
Check that the required local Python, Node, browser, renderer and media tools exist before using them. Install publicly documented dependencies only within the user's authorized setup. Otherwise report the missing dependency and stop the dependent stage. This package does not supply hosted execution or an asset library.
Read supporting references from this skill folder as the guide directs. Record actual request IDs and output paths. Deliver only artifacts you inspected; identify incomplete stages and unverified checks.
Localize and repurpose content
Turn an existing approved asset into verified locale and channel variants.
Source and language contract
Collect the source media, transcript if available, target locales, glossary, protected names, exact claims, voice permissions, target channels and budget. Keep the original master unchanged. Pin speaker choices and preserve original brand assets while changing only the requested locale and channel treatment.
- Inspect source streams and duration. Extract an audio container before a speech
endpoint that requires
audio_url; a video path is not an audio URL. - Select a currently accessible timed transcription endpoint through live discovery. Check its language-code convention and word-timing output contract. Filter timing tokens by their actual type before building captions.
- Translate the verified transcript for meaning, register, units and the supplied glossary. Preserve claims and proper nouns; do not invent stronger promises. Mark uncertain translations for a fluent reviewer before calling them approved.
- For a dub, discover a current dubbing endpoint and inspect its target-language and source-media fields. Compare voices, speaker identity and meaning against the source. Do not add lip sync unless requested and supported by the chosen contract.
- Re-transcribe the localized output for actual word timings. Build SRT/VTT from those timings, not proportional estimates from the original captions.
- Make requested platform cuts from meaningful sentence/scene boundaries. Reframe around the subject; do not stretch footage. Recompose exact text/logo assets for each aspect ratio. Preserve RTL layout and glyph coverage where applicable.
- Assemble with an available verified renderer. Check that dubbing did not remove requested music/effects. Keep localized voice, music and picture stems separate.
Acceptance and delivery
Deliver folders by locale and channel, localized video/audio, SRT/VTT, translated copy, glossary decisions and manifest. Verify no missing lines, caption order, nonnegative timestamps, caption ends within runtime, text coverage and source/target meaning. Listen to names and numbers. State when native-language review remains outstanding. Do not publish or distribute variants without a separate instruction.
Execution and specialist guidance
Use the installed fal-media skill for current model discovery, input contracts,
prices, native MCP execution and request recovery. Preserve the user's selected
provider, model, inputs, output count and spending limits.
The production checks above work without another domain skill. If a specialist
stage needs more guidance, follow fal-media to retrieve the relevant published
guide and only its needed version-pinned references. Reuse guidance already read.
If retrieval is unavailable, retain these local checks and current tool contracts;
report any stage that cannot be completed or verified. Do not invent a model,
privileged host tool or unavailable renderer to fill the gap.
Keep a manifest of sources, endpoint, actual inputs, request ID, result URL, local file and QA findings. Inspect delivered artifacts and report unverified checks.
Terminal execution
For a terminal-only workflow, read the genmedia production-plan guide and copy this skill's example stage plan. The guide describes explicit submission, state files and recovery. These examples are optional CLI resources; connected MCP hosts use native fal tools.
Marketing production with genmedia
Use this skill when the user wants a campaign system, not one isolated asset. Load references as needed:
references/campaign-patterns.mdreferences/workflows.mdreferences/examples.md
Load model-routing alongside this skill for default endpoint choices.
Marketing output should be executable: a brief, asset matrix, genmedia command plan, downloaded files, and clear defects. Do not add fake claims, fake social proof, fake partner logos, fake award badges, or invented legal copy.
Inputs to collect
Only ask when missing details would change the asset plan.
- Objective: launch, acquisition, retargeting, activation, education, event.
- Audience: persona, market, use case, awareness level, objections.
- Offer: product, feature, bundle, trial, waitlist, event, promotion.
- Channels: paid social, organic social, landing page, email, display, app.
- Required assets: stills, video, thumbnails, hero image, carousel, banner.
- Brand rules: colors, logo use, typography, tone, taboo visuals, competitors.
- Source media: product images, screenshots, app UI, people, logo, prior ads.
- Claims: exact approved copy, proof points, disclaimers, compliance limits.
- Budget preference: final-quality, draft exploration, or mixed pipeline.
Genmedia workflow
-
Start from routed endpoint IDs.
genmedia models --endpoint_id openai/gpt-image-2 --json genmedia models --endpoint_id fal-ai/nano-banana-pro/edit --json genmedia models --endpoint_id fal-ai/nano-banana-2 --json genmedia models --endpoint_id bytedance/seedance-2.0/image-to-video --json genmedia models --endpoint_id bytedance/seedance-2.0/text-to-video --json genmedia models --endpoint_id veed/fabric-1.0 --jsonUse text search only as fallback discovery for a missing channel role:
genmedia models "marketing banner image typography" --json genmedia models "social ad video product campaign" --json genmedia docs "image generation text rendering" --json -
Inspect the selected endpoint before planning exact payloads.
genmedia schema <endpoint_id> --json genmedia pricing <endpoint_id> --json -
Upload all source media.
genmedia upload ./product.png --json genmedia upload ./logo.svg --json genmedia upload ./screenshot.png --json genmedia upload ./creator.jpg --json -
Build the campaign matrix before generating.
Minimum matrix:
- Hook asset: earns attention in the first frame.
- Proof asset: shows product, result, process, feature, or evidence.
- Context asset: places product in audience use case.
- Conversion asset: clean end frame with safe space for external copy.
-
Run still assets synchronously when quick.
genmedia run <endpoint_id> \ --prompt "<marketing asset prompt>" \ --download "./outputs/marketing/{request_id}_{index}.{ext}" \ --json -
Run video assets async and download from status.
genmedia run <endpoint_id> \ --prompt "<campaign video prompt>" \ --async \ --json genmedia status <endpoint_id> <request_id> \ --download "./outputs/marketing/{request_id}_{index}.{ext}" \ --json -
Use schema fields exactly. Do not pass guessed flags. Mirror names such as
image_urls,image_url,reference_image_url,aspect_ratio,duration,quality,seed,prompt, ornegative_prompt.
Brief build order
Build the campaign brief before prompts:
- Product truth: what the product is and what must stay accurate.
- Audience tension: problem, desire, objection, or trigger moment.
- Campaign promise: user-approved benefit or visible outcome.
- Asset roles: hook, proof, context, conversion, retention, reminder.
- Channel specs: crop, runtime, safe zones, text needs, file count.
- Variation axis: audience, setting, proof point, visual metaphor, offer.
- Guardrails: claims, logo, legal, copy, product fidelity, banned imagery.
Prompt build order
Write every asset prompt in this order:
- Asset role and channel: launch hero, Meta ad, TikTok hook, email header.
- Product or subject invariant: exact product, UI, feature, person, logo rule.
- Audience context: where, who, problem state, usage moment.
- Visual system: camera, lighting, color, composition, texture, motion.
- Copy handling: no generated text, safe space, or exact provided wording.
- Variant axis: what differs from the other assets.
- Guardrails: no fake claims, no extra logos, no distorted product or UI.
Model routing
- Text-heavy campaign key art, posters, landing heroes, app/UI visuals, and
ads with exact copy:
openai/gpt-image-2atquality=high. - Premium product or brand stills:
openai/gpt-image-2, thenfal-ai/nano-banana-pro, thenfal-ai/nano-banana-2. - Edits from source assets:
fal-ai/nano-banana-pro/edit, thenopenai/gpt-image-2/edit, thenfal-ai/bytedance/seedream/v5/lite/edit. - Fast visual exploration:
fal-ai/flux-2/klein/9b. - Product reveal or social video:
bytedance/seedance-2.0/image-to-video. - Text-to-video concept or brand film:
bytedance/seedance-2.0/text-to-video. - Creator or spokesperson ad: load
ugcand useveed/fabric-1.0,veed/fabric-1.0/text, orfal-ai/creatify/aurora. - Multi-shot narrative: load
storytelling. - Single polished product asset: load
commercial.
Quality bar
Before returning:
- Every asset maps to a campaign role and channel.
- Product, UI, logo, and packaging are stable.
- Claims are user-supplied, observable, or removed.
- Text is either exact and schema-supported or reserved for external editing.
- Variants differ by one clear axis, not random style drift.
- Safe zones support overlays, cropping, and platform UI.
- Output paths come from
downloaded_files[]. - The final answer includes a campaign manifest: asset role, endpoint, request id, local path, prompt summary, and defects.
If the campaign feels generic, reduce the asset count and make each role more specific before generating more variants.
Genmedia model routing
Read current published task routing when available. Use the lists below as fallback
candidates when a domain skill needs a model. Preserve an explicit user choice. These choices
come from dated project-specific guidance. Still run genmedia schema <endpoint_id> --json before execution and genmedia pricing <endpoint_id> --json when cost
matters.
Endpoint-first rule:
- Use current published routing when available; otherwise pick a candidate below.
- Verify it with
genmedia models --endpoint_id <endpoint_id> --json. - Inspect it with
genmedia schema <endpoint_id> --json. - Check
genmedia pricing <endpoint_id> --jsonwhen cost matters. - Use text search only if the routed endpoint is missing, deprecated, rejected, or the task needs a model role not covered here.
Do not invent endpoint IDs.
Image generation
Text-heavy image work
Use for infographics, UI mockups, posters, product labels, packaging text, readable signs, book covers, educational diagrams, and any output where text inside the image must be accurate.
openai/gpt-image-2- Use
quality=high. - Prefer 2K or 4K custom
image_sizewhen the final must be detailed. - Treat as expensive. Do not use it for cheap drafts.
- Use
fal-ai/nano-banana-pro- Use as the second choice when text is important but GPT Image 2 is not available or the user accepts a lower ceiling.
Cheap and simple models are not acceptable for text-heavy production.
Premium still images
Use for commercial stills, realistic product scenes, editorial photography, cinematic keyframes, and high-quality visual concepts.
- More realistic output:
openai/gpt-image-2. - High-quality styled output:
openai/gpt-image-2. - One step down:
fal-ai/nano-banana-pro. - Strong cheaper alternative:
fal-ai/nano-banana-2.
Fast draft images
Use for quick concepts, mood options, rough composition, and cheap iteration.
fal-ai/flux-2/klein/9b
Do not use fast draft output as final commercial delivery unless the user asks.
Image editing
Use for background replacement, relighting, cleanup, object changes, product placement, outfit changes, character edits, and multi-image composition.
fal-ai/nano-banana-pro/editopenai/gpt-image-2/editfal-ai/bytedance/seedream/v5/lite/edit
For product fidelity, also consider:
fal-ai/nano-banana-profal-ai/nano-banana-2fal-ai/bytedance/seedream/v5/lite/text-to-imagefal-ai/nano-banana-2/edit
For consistent characters, use openai/gpt-image-2 first. If editing an
existing character image, inspect openai/gpt-image-2/edit.
Video generation
Highest quality video
Use Seedance 2.0 first for final, high-quality video.
- Text to video:
bytedance/seedance-2.0/text-to-video - Image to video:
bytedance/seedance-2.0/image-to-video - Reference to video:
bytedance/seedance-2.0/reference-to-video
Fast variants exist for lower latency:
bytedance/seedance-2.0/fast/text-to-videobytedance/seedance-2.0/fast/image-to-videobytedance/seedance-2.0/fast/reference-to-video
Fast or lower-cost video
Use Grok Imagine Video for fast, lower-cost motion previews and economical video generation.
- Text to video:
xai/grok-imagine-video/text-to-video - Image to video:
xai/grok-imagine-video/image-to-video - Video edit:
xai/grok-imagine-video/edit-video
Multi-shot storytelling
Use in this order:
bytedance/seedance-2.0/text-to-videobytedance/seedance-2.0/image-to-videobytedance/seedance-2.0/reference-to-videofal-ai/kling-video/v3/pro/text-to-videofal-ai/kling-video/v3/pro/image-to-videoalibaba/happy-horse/text-to-videoalibaba/happy-horse/image-to-video
Use Kling v3 when its multi-prompt, element, or custom element controls match the requested shot plan. Use Happy Horse after Seedance and Kling unless the user specifically asks for it.
Native audio and lip-sync
Use for talking avatars, speech-driven face motion, product spokespersons, UGC-style presenters, and lip-sync from an image plus audio or text.
veed/fabric-1.0- Image plus uploaded audio.
veed/fabric-1.0/text- Image plus text speech.
fal-ai/creatify/aurora- Avatar video from image plus audio, with optional visual direction.
Campaign and UGC routing
Use these when the user asks for campaign-level marketing or creator-style social content.
Marketing campaign assets
- Campaign key art, landing heroes, posters, text-heavy ads, app visuals, and
exact-copy layouts:
openai/gpt-image-2atquality=high. - Premium still variants:
openai/gpt-image-2, thenfal-ai/nano-banana-pro, thenfal-ai/nano-banana-2. - Edits from product, logo, UI, or lifestyle references:
fal-ai/nano-banana-pro/edit, thenopenai/gpt-image-2/edit. - Fast variant exploration:
fal-ai/flux-2/klein/9b. - Product reveal or social campaign video:
bytedance/seedance-2.0/image-to-video. - Text-to-video campaign concept:
bytedance/seedance-2.0/text-to-video.
UGC and creator ads
- Portrait plus audio talking head:
veed/fabric-1.0. - Portrait plus text talking head:
veed/fabric-1.0/text. - Avatar with visual direction:
fal-ai/creatify/aurora. - Existing footage with new speech:
fal-ai/sync-lipsync/v2. - Product b-roll:
bytedance/seedance-2.0/image-to-video. - Fast b-roll draft:
xai/grok-imagine-video/image-to-video.
Utility endpoints
Workflow utility endpoint IDs live in the fal-workflow skill reference:
fal-workflow/references/utility-endpoints.md.
Utility endpoints are allowed to be explicit because they are deterministic tools, not creative model choices. Always inspect schema before use.
Photo Editing
Read the production guide for this workflow. It preserves fal's published production guidance, not a promise that every host tool exists here.
Before execution, map host-specific tools to available capabilities. Use genmedia
for model calls in terminal agents, or the installed fal MCP tools in plugin hosts.
Resolve current endpoints and inspect their contracts; the guide's model names and
prices are dated candidates. Preserve the user's model, provider, scope and budget.
Do not infer authorization from a guide's defaults or mandatory review language.
Check that the required local Python, Node, browser, renderer and media tools exist before using them. Install publicly documented dependencies only within the user's authorized setup. Otherwise report the missing dependency and stop the dependent stage. This package does not supply hosted execution or an asset library.
Read supporting references from this skill folder as the guide directs. Record actual request IDs and output paths. Deliver only artifacts you inspected; identify incomplete stages and unverified checks.
Product ad campaign
Turn one product brief into a consistent campaign asset package.
Brief and production
Capture the product reference, original logo, approved copy, audience, offer, channels, sizes, variant count and spending limit. Infer supplied values; ask only for a missing input that blocks production. Never invent claims, discounts or testimonials.
- Build a small matrix of hook × product benefit × channel. Name each deliverable and its dimensions. Keep the campaign concept and product identity consistent.
- Lock one hero composition against the real product reference. Select a current reference-edit model through live discovery and use its actual input contract.
- Review packaging, silhouette, colors, hands and product scale before variants. Use edit/reference inputs from the approved hero. Keep the product consistent; change only the planned hook, framing or backdrop.
- Place original logos and exact copy with deterministic composition when model text or logos drift. Inspect the final exported image, including every copy string.
- If motion is requested, animate approved product art with a verified image-to-video endpoint selected through live discovery. Check its required fields and supported duration before submission. Generate one short test before a batch.
- Export each channel size without cutting the product, logo or CTA. Check current platform safe areas. Keep the editable composition, clean image and motion stems.
Acceptance and delivery
Deliver a contact sheet, named final files, copy matrix and manifest. Check each requested size, exact copy, actual product fidelity and motion continuity. Record unverified platform specs. Do not publish ads, upload campaigns or make spending commitments beyond the user's brief.
Execution and specialist guidance
Use the installed fal-media skill for current model discovery, input contracts,
prices, native MCP execution and request recovery. Preserve the user's selected
provider, model, inputs, output count and spending limits.
The production checks above work without another domain skill. If a specialist
stage needs more guidance, follow fal-media to retrieve the relevant published
guide and only its needed version-pinned references. Reuse guidance already read.
If retrieval is unavailable, retain these local checks and current tool contracts;
report any stage that cannot be completed or verified. Do not invent a model,
privileged host tool or unavailable renderer to fill the gap.
Keep a manifest of sources, endpoint, actual inputs, request ID, result URL, local file and QA findings. Inspect delivered artifacts and report unverified checks.
Terminal execution
For a terminal-only workflow, read the genmedia production-plan guide and copy this skill's example stage plan. The guide describes explicit submission, state files and recovery. These examples are optional CLI resources; connected MCP hosts use native fal tools.
Reels Creator
Read the production guide for this workflow. It preserves fal's published production guidance, not a promise that every host tool exists here.
Before execution, map host-specific tools to available capabilities. Use genmedia
for model calls in terminal agents, or the installed fal MCP tools in plugin hosts.
Resolve current endpoints and inspect their contracts; the guide's model names and
prices are dated candidates. Preserve the user's model, provider, scope and budget.
Do not infer authorization from a guide's defaults or mandatory review language.
Check that the required local Python, Node, browser, renderer and media tools exist before using them. Install publicly documented dependencies only within the user's authorized setup. Otherwise report the missing dependency and stop the dependent stage. This package does not supply hosted execution or an asset library.
Read supporting references from this skill folder as the guide directs. Record actual request IDs and output paths. Deliver only artifacts you inspected; identify incomplete stages and unverified checks.
Storyboard to short film
Convert supplied boards or a shot list into a rendered short film and editable shot package.
Lock and produce
Record the runtime, aspect ratio, boards, shot order, character/product references, dialogue, audio treatment and budget. Define continuity anchors, shot timing and physical action before choosing models.
- Create a timed shot table: shot ID, source board, duration, action, camera, continuity anchor, sound and exact overlay copy. Sum durations against runtime.
- Establish approved character and location anchors. Prefer image/reference inputs over unrelated text rerolls. A storyboard contact sheet is not a clean motion input; extract each shot into its own image and inspect it.
- Resolve a live image-to-video or reference-to-video model for each shot. Use its actual input contract, including required prompt controls. Check supported duration and resolution before submitting.
- Queue one shot at a time for the initial look test. Record IDs and review actual motion, continuity and scene content before continuing the authorized shot list. Keep failed shots isolated. Do not add shots to fill a timing mistake.
- Trim and assemble the approved clips with a consistent timeline. Use a verified local editor/renderer, or an available compositing tool. If neither exists, report that final assembly is blocked and deliver the reviewed shot package.
- Add dialogue, music and effects only as requested. Keep voices pinned. Measure speech length; do not fit speech by cutting words. Keep picture, voice, music and effects stems for a later remix.
- Compose exact titles and logos deterministically. Use measured speech timestamps for captions. Render the final cut, then inspect the actual exported file.
Acceptance and delivery
Watch every transition and listen to the mix. Measure total runtime, resolution, frame rate, audio peaks and speech placement. Verify shot count and order, legible copy, continuity and correct final-frame hold. Deliver the film, clean cut, stems, shot table, sources and manifest. Flag any review that the host cannot perform.
Execution and specialist guidance
Use the installed fal-media skill for current model discovery, input contracts,
prices, native MCP execution and request recovery. Preserve the user's selected
provider, model, inputs, output count and spending limits.
The production checks above work without another domain skill. If a specialist
stage needs more guidance, follow fal-media to retrieve the relevant published
guide and only its needed version-pinned references. Reuse guidance already read.
If retrieval is unavailable, retain these local checks and current tool contracts;
report any stage that cannot be completed or verified. Do not invent a model,
privileged host tool or unavailable renderer to fill the gap.
Keep a manifest of sources, endpoint, actual inputs, request ID, result URL, local file and QA findings. Inspect delivered artifacts and report unverified checks.
Terminal execution
For a terminal-only workflow, read the genmedia production-plan guide and copy this skill's example stage plan. The guide describes explicit submission, state files and recovery. These examples are optional CLI resources; connected MCP hosts use native fal tools.
Storytelling with genmedia
Use this skill when the user wants a sequence, not a single asset. Load references as needed:
references/shot-planning.mdreferences/workflows.mdreferences/examples.md
Load model-routing alongside this skill for default endpoint choices.
The goal is to produce clear story beats and executable genmedia runs. Avoid generic inspiration copy, fake dialogue, and em dashes.
Inputs to collect
Ask only when missing information affects execution.
- Format: ad, short film, music video, documentary, tutorial, social story.
- Duration and aspect ratio.
- Number of shots or allowed range.
- Main subject, character, product, or location.
- Continuity anchors: character, product, wardrobe, environment, color.
- Source media: first frame, reference image, product shot, audio track.
- Audio needs: narration, music, sound design, transcript, no audio.
- Preferred model or model family, if the user wants to decide quality, cost, speed, audio, or multi-shot tradeoffs.
Genmedia workflow
-
Start from routed endpoint IDs.
genmedia models --endpoint_id bytedance/seedance-2.0/text-to-video --json genmedia models --endpoint_id bytedance/seedance-2.0/image-to-video --json genmedia models --endpoint_id bytedance/seedance-2.0/reference-to-video --json genmedia models --endpoint_id fal-ai/kling-video/v3/pro/text-to-video --json genmedia models --endpoint_id alibaba/happy-horse/text-to-video --json genmedia models --endpoint_id veed/fabric-1.0 --jsonUse text search only as fallback discovery for an unsupported sequence control:
genmedia models "first frame last frame video generation" --json genmedia docs "multi shot video generation" --json -
Inspect schema before planning exact payloads.
genmedia schema <endpoint_id> --json genmedia pricing <endpoint_id> --json -
Upload references.
genmedia upload ./first-frame.png --json genmedia upload ./character.png --json genmedia upload ./product.png --json genmedia upload ./voiceover.wav --json -
Choose the sequence route.
- Highest quality video: start with Seedance 2.0 endpoints from
model-routing. - Native multi-prompt: use if schema has shot arrays, prompt lists, or timeline fields.
- First/last frame: use for controlled transitions between key frames.
- Image-to-video per shot: use for maximum continuity from approved stills.
- Manual per-shot generation: use when the model only supports one prompt.
- Audio-first: generate or upload audio, then plan visual shot lengths.
- Lip-sync or talking avatar: use Fabric 1.0 or Creatify Aurora from
model-routing.
- Highest quality video: start with Seedance 2.0 endpoints from
-
Run long jobs async and download every result with a unique template.
genmedia run <endpoint_id> \ --prompt "<shot or sequence prompt>" \ --async \ --json genmedia status <endpoint_id> <request_id> \ --download "./outputs/story/{request_id}_{index}.{ext}" \ --json -
Return a shot table with endpoint, request id, prompt summary, local path, and any continuity issues. Genmedia downloads clips; it does not replace a timeline editor unless the chosen model returns a complete stitched video.
Shot planning
Plan every sequence as beats first:
- Hook: immediate visual reason to keep watching.
- Setup: who, what, where, and why it matters.
- Development: movement, discovery, proof, or escalation.
- Turn: reveal, transformation, result, or emotional change.
- Close: final image, product memory, CTA-safe frame, or unresolved mood.
For each shot, write:
- Shot number and duration.
- Story purpose.
- Visual prompt.
- Continuity anchor.
- Input reference, if any.
- Genmedia endpoint.
- Expected output path.
Prompt build order
Use this structure for each shot:
SHOT [number], [duration]:
[story purpose]. [subject and action]. [location and time]. [camera framing].
[camera movement]. [lighting and color]. [continuity anchor]. [transition or
relationship to previous shot].
Keep one shot to one clear action unless the selected model supports multi-shot or timeline prompting.
Model routing
- Highest quality video:
bytedance/seedance-2.0/text-to-video,bytedance/seedance-2.0/image-to-video, orbytedance/seedance-2.0/reference-to-video. - Fast or lower-cost video:
xai/grok-imagine-video/text-to-videoorxai/grok-imagine-video/image-to-video. - Multi-shot sequence: Seedance 2.0 first, then
fal-ai/kling-video/v3/pro/text-to-video, thenfal-ai/kling-video/v3/pro/image-to-video, thenalibaba/happy-horse/text-to-videooralibaba/happy-horse/image-to-video. - Text-heavy keyframes, boards, UI frames, posters, or infographics:
openai/gpt-image-2atquality=high. - Talking avatar, native audio, or lip-sync:
veed/fabric-1.0,veed/fabric-1.0/text, orfal-ai/creatify/aurora.
Quality bar
Before returning:
- Shot order has a clear narrative function.
- The first shot is strong enough for the platform.
- Continuity anchors are repeated without bloating every prompt.
- Camera motion is varied but not random.
- Durations add up to the requested runtime.
- Async request IDs and downloaded files are recorded.
- The model's actual schema, not assumptions, drove the final command.
UGC production with genmedia
Use this skill when the user wants creator-style content rather than polished studio advertising. Load references as needed:
references/formats.mdreferences/workflows.mdreferences/examples.md
Load model-routing alongside this skill for default endpoint choices.
Keep outputs believable, platform-native, and claim-safe. Do not write fake testimonials, fake metrics, invented reviews, medical claims, financial claims, or readable legal copy unless the user provides the exact wording.
Inputs to collect
Only ask when the answer changes execution.
- Product or offer: what is being shown, sold, taught, or explained.
- Format: direct-to-camera, demo, reaction, unboxing, founder, faceless b-roll.
- Speaker: supplied portrait/video, generated avatar, no face, or voiceover.
- Script source: exact script, bullet points, offer copy, or ask to draft.
- Platform: TikTok, Reels, Shorts, paid social, landing page, prototype.
- Runtime and crop: usually 9:16, 6-15 seconds for hooks, 15-45 seconds for ads.
- Source media: portrait, product image, product video, logo, b-roll, audio.
- Claims: proof the user supplied, required disclaimers, banned phrases.
- Tone: casual, expert, founder-led, skeptical, excited, calm, documentary.
Genmedia workflow
-
Start from routed endpoint IDs.
genmedia models --endpoint_id veed/fabric-1.0 --json genmedia models --endpoint_id veed/fabric-1.0/text --json genmedia models --endpoint_id fal-ai/creatify/aurora --json genmedia models --endpoint_id fal-ai/sync-lipsync/v2 --json genmedia models --endpoint_id bytedance/seedance-2.0/image-to-video --json genmedia models --endpoint_id openai/gpt-image-2 --jsonUse text search only as fallback discovery for missing roles:
genmedia models "ugc talking head avatar" --json genmedia models "short social video product demo" --json genmedia docs "lip sync video" --json -
Inspect the selected endpoint before running.
genmedia schema <endpoint_id> --json genmedia pricing <endpoint_id> --json -
Upload all local source media.
genmedia upload ./creator.jpg --json genmedia upload ./product.png --json genmedia upload ./voiceover.wav --json genmedia upload ./existing-clip.mp4 --json -
Choose the production route.
- Portrait plus audio:
veed/fabric-1.0. - Portrait plus text:
veed/fabric-1.0/textwhen schema supports it. - Avatar with stronger visual direction:
fal-ai/creatify/aurora. - Existing video with new speech:
fal-ai/sync-lipsync/v2. - Product b-roll:
bytedance/seedance-2.0/image-to-videofrom an approved still or product reference. - Hook frames and thumbnails:
openai/gpt-image-2, especially when text or product fidelity matters.
- Portrait plus audio:
-
Run long video jobs async and download from status.
genmedia run <endpoint_id> \ --prompt "<ugc visual direction or shot prompt>" \ --async \ --json genmedia status <endpoint_id> <request_id> \ --download "./outputs/ugc/{request_id}_{index}.{ext}" \ --json -
Use schema fields exactly. Mirror the model's field names such as
image_url,audio_url,video_url,text,prompt,visual_direction,aspect_ratio,duration, orseed.
Script build order
Build scripts as short spoken beats, not polished ad copy:
- Hook: one concrete tension, problem, result, or curiosity gap.
- Context: why this speaker cares or what situation they are in.
- Product moment: product appears, is used, or is shown solving a problem.
- Proof: sensory detail, visible demo, supplied metric, or user-provided fact.
- Turn: before-after, objection answered, or unexpected benefit.
- Close: soft CTA, next action, or clean final product frame.
Keep claims grounded. Replace unsupported claims with observable statements: "the texture looks lighter" beats "this cures acne".
Prompt build order
For each UGC clip or shot, write:
- Speaker and frame: creator type, age range if supplied, setting, crop.
- Performance: eye contact, casual delivery, gestures, expression, pace.
- Product action: held up, opened, applied, compared, demonstrated, shown.
- Camera: handheld phone, desk tripod, mirror shot, close-up, b-roll insert.
- Lighting and audio feel: natural window, bathroom light, car interior.
- Platform constraints: 9:16, safe top/bottom zones, no generated captions.
- Guardrails: no fake claims, no new logos, no changed product packaging.
Model routing
- Talking head from portrait and audio:
veed/fabric-1.0. - Talking head from portrait and text:
veed/fabric-1.0/text. - Avatar with visual direction:
fal-ai/creatify/aurora. - Lip-sync existing footage:
fal-ai/sync-lipsync/v2. - Product b-roll or demo motion:
bytedance/seedance-2.0/image-to-video. - Fast draft b-roll:
xai/grok-imagine-video/image-to-video. - Creator keyframes, thumbnails, and product-faithful stills:
openai/gpt-image-2orfal-ai/nano-banana-pro. - TTS: use
fal-models-catalog/references/text-to-audio.mdand inspect schema. Prefer short test sentences before full scripts.
Quality bar
Before returning:
- The clip feels like plausible creator content, not a studio commercial.
- Spoken script length fits the requested runtime.
- Mouth motion is synced when a speaking face is used.
- Product shape, packaging, and logo are stable.
- Claims are supplied by the user or phrased as visible observations.
- The first 1-2 seconds have a clear hook.
- Captions or text overlays are not hallucinated inside the video.
- Output paths come from
downloaded_files[], not manually fetched URLs.
If the face drifts, shorten the script, use cleaner portrait/audio inputs, or switch from generated avatar to lip-syncing approved source footage.
Video Compositing
Read the production guide for this workflow. It preserves fal's published production guidance, not a promise that every host tool exists here.
Before execution, map host-specific tools to available capabilities. Use genmedia
for model calls in terminal agents, or the installed fal MCP tools in plugin hosts.
Resolve current endpoints and inspect their contracts; the guide's model names and
prices are dated candidates. Preserve the user's model, provider, scope and budget.
Do not infer authorization from a guide's defaults or mandatory review language.
Check that the required local Python, Node, browser, renderer and media tools exist before using them. Install publicly documented dependencies only within the user's authorized setup. Otherwise report the missing dependency and stop the dependent stage. This package does not supply hosted execution or an asset library.
Read supporting references from this skill folder as the guide directs. Record actual request IDs and output paths. Deliver only artifacts you inspected; identify incomplete stages and unverified checks.
Wrap It Up
Read the production guide for this workflow. It preserves fal's published production guidance, not a promise that every host tool exists here.
Before execution, map host-specific tools to available capabilities. Use genmedia
for model calls in terminal agents, or the installed fal MCP tools in plugin hosts.
Resolve current endpoints and inspect their contracts; the guide's model names and
prices are dated candidates. Preserve the user's model, provider, scope and budget.
Do not infer authorization from a guide's defaults or mandatory review language.
Check that the required local Python, Node, browser, renderer and media tools exist before using them. Install publicly documented dependencies only within the user's authorized setup. Otherwise report the missing dependency and stop the dependent stage. This package does not supply hosted execution or an asset library.
Read supporting references from this skill folder as the guide directs. Record actual request IDs and output paths. Deliver only artifacts you inspected; identify incomplete stages and unverified checks.
Sponsors
Details
- Marketplace
- fal-ai-community/skills
- Category
- Community