fal-video

name	fal-video
description	Use fal.ai for image to video generation, model comparison, queue-based inference, pricing and usage tracking, and portable multi-model experiment workflows with local prompt and cost logs.
metadata	{"short-description":"fal.ai video generation, comparison, and cost-aware experiment tooling."}

fal.ai Video

Use this skill when the user wants to generate media through fal.ai, compare multiple marketplace models, or build repeatable experiment workflows with prompts, inputs, outputs, and costs tracked in a consistent way.

Philosophy: Standardize The Workflow, Not The Model

fal gives you one platform for many models, but it does not give you one truthful schema for all of them. The right abstraction is:

• standardize auth, queueing, file handling, output capture, and cost tracking
• keep model-specific knobs explicit
• compare models on the same task, not by pretending they expose identical controls

Before generating, ask:

• Is this a single run, or a comparison batch?
• What should stay constant across models: prompt, anchor image, duration target, background, camera, or framing?
• Which model-specific controls materially affect fairness and need to be frozen?
• Do we need exact per-run spend, pre-run estimates, or both?

Core principles:

1. Queue-first for video: long-running media generation should use fal’s queue workflow, not fragile synchronous assumptions.
2. Prompt parity beats parameter parity: hold the task steady, then document the model-specific compromises.
3. Tracking is part of the run: a generation is not complete until prompt, request metadata, outputs, and cost signals are recorded.

What This Skill Provides

• A portable, repo-scoped fal workflow with no repo-wide Python packaging requirement.
• A generic image-to-video runner based on fal’s documented queue HTTP endpoints.
• Model presets for:
  • seedance-pro-i2v
  • kling-v3-pro-i2v
  • hailuo-02-standard-i2v
• Platform tooling for:
  • model lookup
  • pricing
  • estimate-cost
  • usage
  • request audit
• A batch runner that executes the same task across multiple fal models and appends a central ledger row per run.

Working With fal In This Repo

Core Execution Pattern

For video jobs, this skill uses fal’s queue API:

• submit: POST https://queue.fal.run/{endpoint_id}
• status: GET https://queue.fal.run/{endpoint_id}/requests/{request_id}/status
• result: GET https://queue.fal.run/{endpoint_id}/requests/{request_id}

Authentication uses:

• Authorization: Key $FAL_KEY
• in this repo, FAL_API_KEY is also accepted by the bundled scripts

Important platform headers for repeatable comparison runs:

• X-Fal-Store-IO: 1
• x-app-fal-disable-fallback: true

The runner also captures response headers such as:

• x-fal-request-id
• x-fal-billable-units

Why This Skill Uses Raw HTTP First

The official fal-client SDK is valid and documented, but this repo’s first requirement is portability inside a Codex skill. The scripts therefore keep a deterministic raw-HTTP queue path and also use fal-client automatically when it is installed.

In this repo's retained live runs, some endpoints were most reliable when invoked with:

• uv run --with fal-client python3 ...

Prompting Guidance For Video Comparison

Prompt like direction, not like marketing copy:

• subject identity
• action
• framing
• background
• motion constraints
• exclusions

For sprite-animation comparison:

• lock the facing
• lock the background
• lock the shot
• keep the action short and readable
• disable audio when the model supports it
• prefer a neutral 1280x720 flat-background anchor plate for walk-cycle image-to-video runs
• avoid checkerboards, grid sheets, or alternating-pixel guides as video start images

Do not overload early comparison runs with cinematic flourishes. The first job is to test motion usefulness and identity preservation.

Sprite Walk-Cycle Start Images

For image-to-video sprite walk cycles, use a direction-specific neutral plate instead of a spritesheet guide:

• approved direction anchor composited onto flat neutral gray
• one character centered, feet visible, no floor or horizon
• fixed camera, fixed framing, locked facing
• no props, effects, scene detail, labels, arrows, or visible grid

Checkerboards and alternating-pixel guides are useful for still-image spritesheet generation, but video models tend to treat them as physical floors or rooms. That can introduce perspective, camera drift, and character rotation.

In retained sprite walk runs, bytedance/seedance-2.0/image-to-video with a minimal payload and generate_audio=false produced useful motion references. Extract raw frames first, build contact sheets/GIFs for curation, and defer background cleanup to selected frames.

Scripts

• scripts/fal_queue_video_run.py
  • one image-to-video run
  • writes request/result JSON
  • downloads output media
  • writes normalized run manifest
• scripts/fal_platform_models.py
  • query fal model metadata and cost surfaces
• scripts/fal_video_experiment_matrix.py
  • run the same task across multiple model presets
  • append central ledger rows

Repo Workflow

Machine-readable tracking:

• experiments/fal/ledger.jsonl
• experiments/fal/ledger.csv
• experiments/fal/<timestamp>-<slug>/batch.json

Human-readable tracking:

• prompts/<timestamp>-...-prompts.md
• learnings/<timestamp>-...-learnings.md

Generated media should still live under the appropriate public/assets/.../concepts/... path for the asset family being tested.

Anti-Patterns To Avoid

❌ Anti-pattern: flattening all fal models into one fake schema Why bad: you lose the knobs that actually matter and comparisons become misleading. Better: use shared runner behavior plus explicit per-model presets.

❌ Anti-pattern: recording only prompts and outputs Why bad: you cannot audit request IDs, retries, or costs later. Better: always save raw JSON, normalized manifests, and ledger rows.

❌ Anti-pattern: comparing models with hidden fallback routing Why bad: you may think you tested one endpoint but actually hit another route. Better: set x-app-fal-disable-fallback: true on strict comparison runs.

❌ Anti-pattern: forcing every model to pretend it supports the same size and duration controls Why bad: it creates fake parity and bad assumptions. Better: normalize the task, then document the actual resolved arguments used per model.

❌ Anti-pattern: waiting until the end to think about spend Why bad: expensive comparison batches get hard to control. Better: estimate before the run and reconcile after the run.

❌ Anti-pattern: using checkerboards as sprite video start backgrounds Why bad: models often convert the guide into a floor, horizon, or scene and stop behaving like a locked sprite reference. Better: use a neutral flat-background anchor plate and keep grids for still-image guide sheets.

References

• Platform notes: references/fal-platform-notes.md
• Queue and inference notes: references/fal-queue-and-inference.md
• Initial video model notes: references/fal-video-models.md
• Model presets: assets/model-presets.json

Remember

A good fal workflow is not just “can it generate.” It is:

• reproducible
• comparable
• cost-visible
• honest about model differences