Skip to content

moonlight-lupin/agent-skills / creative/clips-studio

clips-studio

Verified

Use when the user wants to "make a video/clip", "generate a video from text", "animate this image/photo", "create a marketing reel / social video / teaser", "do a 3D / parallax move", "pan/zoom/orbit a shot", or mentions fal.ai, Kling, Veo or Seedance for video. Staged fal.ai workflow — brainstorm, draft cheaply, produce the final at quality. Three modes: text-to-video, animate (still to motion), camera-move (push-in/pan/orbit). Not for still images (image-studio), slide decks, or charts. Honesty discipline: never depict real identifiable subjects via text-to-video.

FileKindSize
README.mdmarkdown1.9 KB
SKILL.mdskill md23.5 KB
examples/example-run.mdmarkdown8.1 KB
references/fal-video-models.mdmarkdown11.9 KB
references/motion-honesty-guide.mdmarkdown11.4 KB
references/video-prompting-techniques.mdmarkdown3.4 KB
scripts/falvid.pyscript34.5 KB
tests/__init__.pyscript0 B
tests/test_falvid.pyscript31.3 KB

scripts/falvid.py

View on GitHub
#!/usr/bin/env python3
"""falvid.py — fal.ai video helper for Clips Studio.

Supports text-to-video (`generate`), image-to-video (`animate`), camera moves over a
still (`camera`), cost summaries, and `--dry-run` preflight. Dry-run prints the
model, arguments and estimated cost without requiring FAL_KEY, uploading images,
calling fal.ai, writing logs, or spending credits.
"""

from __future__ import annotations

import argparse
import json
import os
import re
import sys
import time
from pathlib import Path

FAL_API = "https://api.fal.ai/v1"
DEFAULT_COST_LOG = "_falvid-costs.jsonl"

DEFAULT_MODELS = {
    "generate": "blackforestlabs/flux-3/text-to-video/draft",
    "animate": "blackforestlabs/flux-3/image-to-video/draft",
    "camera": "fal-ai/bytedance/seedance/v1.5/pro/image-to-video",
    "generate_full": "blackforestlabs/flux-3/text-to-video",
    "animate_full": "blackforestlabs/flux-3/image-to-video",
}

VIDEO_PRICING = {
    # ── FLUX 3 (Black Forest Labs) — native audio included free ──
    "blackforestlabs/flux-3/text-to-video": {"kind": "per_second", "rate": 0.17, "fhd_rate": 0.29},
    "blackforestlabs/flux-3/image-to-video": {"kind": "per_second", "rate": 0.17, "fhd_rate": 0.29},
    "blackforestlabs/flux-3/first-last-frame-to-video": {"kind": "per_second", "rate": 0.17, "fhd_rate": 0.29},
    "blackforestlabs/flux-3/keyframes-to-video": {"kind": "per_second", "rate": 0.17, "fhd_rate": 0.29},
    "blackforestlabs/flux-3/extend-video": {"kind": "per_second", "rate": 0.41, "fhd_rate": 0.53},
    "blackforestlabs/flux-3/text-to-video/draft": {"kind": "per_second", "rate": 0.06, "note": "HD only; ~1/3 of full render cost"},
    "blackforestlabs/flux-3/image-to-video/draft": {"kind": "per_second", "rate": 0.06, "note": "HD only; ~1/3 of full render cost"},
    # ── Seedance 2.5 (ByteDance) — token-based, native 30s, expensive ──
    "fal-ai/bytedance/seedance-2.5/image-to-video": {"kind": "per_second", "rate": 0.473, "note": "720p with audio; token-based ~$0.0214/1k tokens; ~$2.31 for 5s/720p/16:9"},
    "fal-ai/bytedance/seedance-2.5/text-to-video": {"kind": "per_second", "rate": 0.473, "note": "720p with audio; same token formula as i2v"},
    "fal-ai/bytedance/seedance-2.5/reference-to-video": {"kind": "per_second", "rate": 0.473, "note": "720p with audio; up to 50 multimodal refs"},
    # ── Seedance 2.0 (ByteDance) — token-based, 15s, 1080p, audio free ──
    "fal-ai/bytedance/seedance-2.0/image-to-video": {"kind": "per_second", "rate": 0.3024, "note": "720p with audio; 1080p ~$0.682/s; token-based $0.014/1k tokens"},
    "fal-ai/bytedance/seedance-2.0/text-to-video": {"kind": "per_second", "rate": 0.3024, "note": "720p with audio; same token formula"},
    "fal-ai/bytedance/seedance-2.0/reference-to-video": {"kind": "per_second", "rate": 0.3024, "note": "720p with audio; up to 9 images + 3 videos + 3 audio refs"},
    "fal-ai/bytedance/seedance-2.0/fast/image-to-video": {"kind": "per_second", "rate": 0.2419, "note": "Fast tier; 720p only; lower latency"},
    "fal-ai/bytedance/seedance-2.0/fast/text-to-video": {"kind": "per_second", "rate": 0.2419, "note": "Fast tier; 720p only; lower latency"},
    "fal-ai/bytedance/seedance-2.0/fast/reference-to-video": {"kind": "per_second", "rate": 0.2419, "note": "Fast tier; 720p only; up to 9 refs"},
    # ── Kling ──
    "fal-ai/kling-video/v2.5-turbo/pro/image-to-video": {"kind": "per_second", "rate": 0.07},
    "fal-ai/kling-video/v3/pro/image-to-video": {"kind": "per_second", "rate": 0.15},
    "fal-ai/kling-video/v3/4k/image-to-video": {"kind": "per_second", "rate": 0.42},
    "fal-ai/veo3.1/image-to-video": {"kind": "per_second", "rate": 0.20, "audio_rate": 0.40, "k4_mult": 2.0},
    "fal-ai/veo3.1/fast/image-to-video": {"kind": "per_second", "rate": 0.10, "audio_rate": 0.20, "k4_mult": 2.0},
    "fal-ai/bytedance/seedance/v1.5/pro/image-to-video": {"kind": "per_clip", "rate": 0.26, "base_secs": 5, "note": "~720p; scales roughly with tokens"},
    "fal-ai/minimax/hailuo-2.3/pro/image-to-video": {"kind": "per_clip", "rate": 0.49, "base_secs": 5},
    "fal-ai/wan/v2.2-a14b/text-to-video": {"kind": "per_second", "rate": 0.10},
    "fal-ai/veo3.1": {"kind": "per_second", "rate": 0.20, "audio_rate": 0.40, "k4_mult": 2.0},
    "fal-ai/kling-video/v2.5-turbo/pro/text-to-video": {"kind": "per_second", "rate": 0.224, "audio_rate": 0.28},
    "fal-ai/kling-video/v3/pro/text-to-video": {"kind": "per_second", "rate": 0.224, "audio_rate": 0.336},
    "fal-ai/bytedance/seedance/v1.5/pro/text-to-video": {"kind": "per_clip", "rate": 0.26, "base_secs": 5},
    "fal-ai/minimax/hailuo-2.3/pro/text-to-video": {"kind": "per_clip", "rate": 0.49, "base_secs": 5},
    "fal-ai/wan-pro": {"kind": "per_second", "rate": 0.10},
    # Corrected: LTX-2 is estimated on output-frame megapixels, not one still frame.
    # 5s at 1080p and 24fps ≈ 248.8 MP; at $0.0018/MP this is ≈ $0.448.
    "fal-ai/ltx-2-19b/text-to-video": {"kind": "per_megapixel", "rate": 0.0018, "note": "~$0.0018/output-frame MP; 5s 1080p@24fps ≈ 248.8 MP → ~$0.448"},
}

START_IMAGE_MODELS = ("kling-video/v3",)
AUDIO_MODELS = ("veo3.1", "kling-video/v3", "seedance/v1.5", "flux-3", "seedance-2.5", "seedance-2.0")
CAMERA_FIXED_MODELS = ("seedance",)
DEFAULT_RESOLUTION = {"fal-ai/bytedance/seedance/v1.5/pro/image-to-video": "720p"}
MAX_DURATION = {
    "kling-video/v2.5-turbo": 10,
    "kling-video/v3": 15,
    "seedance/v1.5": 12,
    "seedance-2.0": 15,
    "seedance-2.5": 30,
    "veo3.1": 8,
    "hailuo-2.3": 5,
    "wan/v2.2": 5,
    "ltx-2": 10,
    "flux-3": 20,
}
URL_ARGUMENT_KEYS = {"image_url", "start_image_url", "end_image_url", "tail_image_url"}
CAMERA_MOVES = {
    "push-in": "slow, gentle dolly push-in toward the subject; smooth and steady",
    "pull-out": "slow dolly pull-out revealing a little more of the existing space; smooth and steady",
    "pan-left": "slow pan to the left across the scene; smooth and steady",
    "pan-right": "slow pan to the right across the scene; smooth and steady",
    "tilt-up": "slow tilt upward; smooth and steady",
    "tilt-down": "slow tilt downward; smooth and steady",
    "orbit": "slow, shallow orbit around the subject; subtle, smooth and steady",
    "crane-up": "slow crane/pedestal up; smooth and steady",
}


def _money(x, currency="USD"):
    return f"${x:,.4f}" if currency == "USD" else f"{x:,.4f} {currency}"


def _model_has(model, needles):
    return any(n in model for n in needles)


def _check_duration(model, duration):
    for needle, max_s in MAX_DURATION.items():
        if needle in model and duration > max_s:
            sys.exit(f"ERROR: --duration {duration}s exceeds the {max_s}s maximum for {model}.")


def _video_cost(model, duration, arguments):
    arguments = arguments or {}
    spec = VIDEO_PRICING.get(model)
    if not spec:
        return None, f"no rate on file for {model} — see references/fal-video-models.md / fal dashboard", False
    if spec["kind"] == "per_second":
        rate = spec["rate"]
        notes = []
        if arguments.get("generate_audio") and spec.get("audio_rate"):
            rate = spec["audio_rate"]
            notes.append("audio")
        if str(arguments.get("resolution", "")).upper() in ("4K", "FHD", "1080P") and spec.get("k4_mult"):
            rate *= spec["k4_mult"]
            notes.append("4K" if "4K" in str(arguments.get("resolution", "")).upper() else "FHD")
        elif str(arguments.get("resolution", "")).upper() in ("FHD", "1080P") and spec.get("fhd_rate"):
            rate = spec["fhd_rate"]
            notes.append("FHD")
        secs = int(duration) if duration else 5
        tag = f" ({', '.join(notes)})" if notes else ""
        return rate * secs, f"{secs}s x ${rate}/s{tag}", False
    if spec["kind"] == "per_megapixel":
        secs = int(duration) if duration else 5
        mp_per_frame = 1920 * 1080 / 1_000_000
        fps = 24
        total_mp = mp_per_frame * fps * secs
        extra = f" — {spec['note']}" if spec.get("note") else ""
        return spec["rate"] * total_mp, f"{secs}s @ ~${spec['rate']}/MP, ~{total_mp:.1f} output-frame MP (1080p×{fps}fps){extra}", False
    base = spec.get("base_secs", 5)
    secs = int(duration) if duration else base
    extra = f" — {spec['note']}" if spec.get("note") else ""
    return spec["rate"] * (secs / base), f"${spec['rate']} base clip × {secs}/{base}s{extra}", False


def _parse_scalar(v):
    stripped = v.strip()
    if stripped[:1] in ("{", "[", '"') or stripped in ("true", "false", "null"):
        try:
            return json.loads(stripped)
        except json.JSONDecodeError as e:
            sys.exit(f"ERROR: invalid JSON value for --arg: {v}\n  {e}")
    lv = stripped.lower()
    if lv in ("true", "false"):
        return lv == "true"
    try:
        return int(stripped)
    except ValueError:
        try:
            return float(stripped)
        except ValueError:
            return v


def _parse_extra_args(pairs, json_blobs=None):
    out = {}
    for blob in json_blobs or []:
        try:
            parsed = json.loads(blob)
        except json.JSONDecodeError as e:
            sys.exit(f"ERROR: --arg-json must be a JSON object, got invalid JSON:\n  {e}")
        if not isinstance(parsed, dict):
            sys.exit('ERROR: --arg-json must parse to a JSON object, e.g. --arg-json \'{"negative_prompt":"blurry"}\'')
        out.update(parsed)
    for pair in pairs or []:
        if "=" not in pair:
            sys.exit(f"ERROR: --arg must be key=value, got: {pair}")
        k, v = pair.split("=", 1)
        k = k.strip()
        if not k:
            sys.exit(f"ERROR: --arg key is empty in: {pair}")
        out[k] = _parse_scalar(v)
    return out


def _redact_url_arguments(arguments):
    return {k: ("[omitted from log; see input_images]" if k in URL_ARGUMENT_KEYS else v) for k, v in arguments.items()}


def _cost_log_path(explicit):
    return Path(explicit).expanduser() if explicit else Path.cwd() / DEFAULT_COST_LOG


def _read_cost_log(path):
    entries = []
    if path.is_file():
        for line in path.read_text(encoding="utf-8").splitlines():
            try:
                entries.append(json.loads(line))
            except Exception:
                pass
    return entries


def _log_cost(path, entry):
    with path.open("a", encoding="utf-8") as f:
        f.write(json.dumps(entry, ensure_ascii=False) + "\n")


def _append_run_log(run_log, entry):
    """Append a human-readable markdown audit block for one call."""
    path = Path(run_log).expanduser()
    path.parent.mkdir(parents=True, exist_ok=True)
    args = entry.get("arguments") or {}
    lines = [f"## {entry.get('time')} — {entry.get('command') or 'run'}", ""]
    lines.append(f"- **Model:** `{entry.get('model')}`")
    inputs = entry.get("input_images") or []
    if inputs:
        lines.append("- **Input image(s):** " + ", ".join(f"`{p}`" for p in inputs))
    for o in entry.get("outputs") or []:
        lines.append(f"- **Output:** `{o.get('path')}`")
    if "prompt" in args:
        lines.append(f"- **Prompt:** {args.get('prompt')}")
    if args.get("seed") is not None:
        lines.append(f"- **Seed (input):** {args.get('seed')}")
    if entry.get("seed") is not None:
        lines.append(f"- **Seed (output):** {entry.get('seed')}  (use with `enhance --seed {entry.get('seed')}` to re-render at full quality)")
    other = {k: v for k, v in args.items() if k not in ("prompt", "seed")}
    if other:
        lines.append(f"- **Arguments:** `{json.dumps(other, ensure_ascii=False)}`")
    if entry.get("duration") is not None:
        lines.append(f"- **Duration:** {entry.get('duration')}s")
    cost = entry.get("cost")
    cost_str = ("~" + _money(cost, entry.get("currency", "USD"))) if cost is not None else (entry.get("basis") or "unknown")
    lines.append(f"- **Cost:** {cost_str} ({entry.get('basis')})")
    lines.append("")
    with path.open("a", encoding="utf-8") as f:
        f.write("\n".join(lines) + "\n")


def _session_total(path):
    entries = _read_cost_log(path)
    total, currency, priced = 0.0, "USD", 0
    for e in entries:
        if e.get("cost") is not None:
            total += float(e["cost"])
            currency = e.get("currency", currency)
            priced += 1
    return total, currency, len(entries), priced


FAL_KEY_RE = re.compile(
    r"[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}:[0-9a-fA-F]{16,}"
)


def _extract_fal_key(text, name_hinted=False):
    """Pull a fal key out of file text: a `FAL_KEY=`/`FAL_KEY:` assignment, a bare `id:secret` token
    anywhere, or — for a file whose NAME hints fal/key — a whole-file single `id:secret` token."""
    m = re.search(r"FAL_KEY\s*[=:]\s*[\"']?([^\s\"']+)", text)
    if m:
        return m.group(1)
    m = FAL_KEY_RE.search(text)
    if m:
        return m.group(0)
    if name_hinted:
        s = text.strip()
        if s and "\n" not in s and " " not in s and ":" in s and 20 <= len(s) <= 200:
            return s
    return None


def _autoload_fal_keys():
    """If FAL_KEY isn't in the environment, find it in a local text file the user saved — WORKING
    FOLDER first, then the home dir — so a non-technical user isn't asked for a key they've already
    dropped in a file. The filename does NOT matter (users rarely use `.env`): the key is detected by
    CONTENT — a `FAL_KEY=…` line or the `id:secret` pattern. Local-only; nothing fetched or sent;
    existing env vars always win."""
    if os.environ.get("FAL_KEY"):
        return
    exts = {".txt", ".env", ".cfg", ".ini", ".text", ""}
    for d in (Path.cwd(), Path.home()):
        try:
            files = [p for p in sorted(d.iterdir()) if p.is_file()]
        except OSError:
            continue
        hinted = [p for p in files if re.search(r"fal|key|api|\.env", p.name, re.I)]
        pool = hinted if d == Path.home() else hinted + [p for p in files if p not in hinted and p.suffix.lower() in exts]
        for p in pool:
            try:
                if p.stat().st_size > 100_000:
                    continue
                text = p.read_text(encoding="utf-8", errors="ignore")
            except OSError:
                continue
            key = _extract_fal_key(text, name_hinted=(p in hinted))
            if key:
                os.environ["FAL_KEY"] = key
                am = re.search(r"FAL_ADMIN_KEY\s*[=:]\s*[\"']?([^\s\"']+)", text)
                if am and not os.environ.get("FAL_ADMIN_KEY"):
                    os.environ["FAL_ADMIN_KEY"] = am.group(1)
                print(f"  using FAL_KEY found in {p}", file=sys.stderr)
                return


def _require_fal_key():
    _autoload_fal_keys()
    if not os.environ.get("FAL_KEY"):
        sys.exit(
            "ERROR: FAL_KEY is not set, and no key file was found in this folder or your home dir.\n"
            "Set the env var, or save it in a text file in this folder (any name) containing a line\n"
            "FAL_KEY=your-key or the raw id:secret key. No video was generated (no data left this machine)."
        )


def _import_deps():
    try:
        import fal_client  # noqa: F401
        import requests  # noqa: F401
    except ImportError as e:
        sys.exit(f"ERROR: missing dependency ({e.name}). Install with: pip install fal-client requests")
    import fal_client
    import requests
    return fal_client, requests


def _resolve_image(ref, fal_client):
    if ref.startswith(("http://", "https://", "data:")):
        return ref
    p = Path(ref).expanduser()
    if not p.is_file():
        sys.exit(f"ERROR: --image not found locally and not a URL: {ref}")
    print(f"  uploading {p.name} to fal storage…", file=sys.stderr)
    return fal_client.upload_file(str(p))


def _balance(requests):
    admin = os.environ.get("FAL_ADMIN_KEY")
    if not admin:
        return None, "set FAL_ADMIN_KEY (a fal Admin key) to show balance"
    try:
        r = requests.get(f"{FAL_API}/account/billing", params={"expand": "credits"}, headers={"Authorization": f"Key {admin}"}, timeout=20)
        if r.status_code == 403:
            return None, "FAL_ADMIN_KEY is not an Admin key (billing returned 403)"
        if r.status_code != 200:
            return None, f"billing HTTP {r.status_code}"
        credits = r.json().get("credits") or {}
        bal = credits.get("current_balance")
        if bal is None:
            return None, "no balance in billing response"
        return (float(bal), credits.get("currency", "USD")), None
    except Exception as e:
        return None, f"balance check failed: {e}"


def _download(videos, out_dir, name, requests):
    out = Path(out_dir).expanduser()
    out.mkdir(parents=True, exist_ok=True)
    saved = []
    multiple = len(videos) > 1
    for i, vid in enumerate(videos, 1):
        url = vid.get("url") if isinstance(vid, dict) else None
        if not url:
            continue
        ext = ".webm" if "webm" in (vid.get("content_type", "") if isinstance(vid, dict) else "") else ".mp4"
        dest = out / (f"{name}_{i}{ext}" if multiple else f"{name}{ext}")
        resp = requests.get(url, timeout=600)
        resp.raise_for_status()
        dest.write_bytes(resp.content)
        saved.append({"path": dest, "bytes": dest.stat().st_size})
    return saved


def _run(model, arguments, duration, out_dir, name, cost_log=None, run_log=None, verbose=False, metadata=None):
    fal_client, requests = _import_deps()
    _require_fal_key()
    try:
        result = fal_client.subscribe(model, arguments=arguments, with_logs=verbose)
    except Exception as e:
        sys.exit(f"ERROR: the fal.ai call failed:\n  {e}\n\nNo video was generated.")
    videos = []
    if isinstance(result, dict):
        videos = result.get("videos") or ([result["video"]] if result.get("video") else [])
    if not videos:
        sys.exit("ERROR: no video returned.")
    saved = _download(videos, out_dir, name, requests)
    for o in saved:
        print(f"Saved: {o['path']}")
    # Capture seed from the API result if present
    result_seed = None
    if isinstance(result, dict):
        result_seed = result.get("seed")
    if result_seed is not None:
        print(f"Seed: {result_seed}  (save this to re-render with 'enhance --seed {result_seed}')")
    cost, basis, exact = _video_cost(model, duration, arguments)
    logp = _cost_log_path(cost_log)
    entry = {
        "time": time.strftime("%Y-%m-%d %H:%M:%S"),
        "command": (metadata or {}).get("command"),
        "model": model,
        "arguments": _redact_url_arguments(arguments),
        "input_images": (metadata or {}).get("input_images", []),
        "outputs": [{"path": str(o["path"]), "bytes": o.get("bytes")} for o in saved],
        "duration": duration,
        "seed": result_seed,
        "cost": round(cost, 4) if cost is not None else None,
        "currency": "USD",
        "basis": basis,
        "exact": exact,
    }
    _log_cost(logp, entry)
    if run_log:
        _append_run_log(run_log, entry)
    if cost is None:
        print(f"Est. cost this clip: not on file — {basis}")
    else:
        print(f"Est. cost this clip: ~{_money(cost)} [{basis}] (estimate — dashboard is authoritative)")
    total, tcur, _, n_priced = _session_total(logp)
    print(f"Session total ({n_priced} estimated call(s)): ~{_money(total, tcur)} · log: {logp}")
    bal, why = _balance(requests)
    if bal is not None:
        print(f"Account balance: {_money(bal[0], bal[1])}")
    elif why:
        print(f"(balance not shown — {why})")
    return saved


def _extra_args(a):
    return _parse_extra_args(a.arg, getattr(a, "arg_json", None))


def _dry_run(command, model, arguments, duration, *, input_images=None, out_dir="_workings", name="vid"):
    cost, basis, _ = _video_cost(model, duration, arguments)
    print("DRY RUN — no fal.ai call, no upload, no download, no charge, no log write.")
    print(f"Command:  {command}")
    print(f"Model:    {model}")
    print(f"Duration: {duration}s")
    if input_images:
        print("Input image(s):")
        for img in input_images:
            print(f"  - {img}")
    print("Arguments:")
    print(json.dumps(_redact_url_arguments(arguments), ensure_ascii=False, indent=2))
    if cost is None:
        print(f"Estimated cost: unknown [{basis}]")
    else:
        print(f"Estimated cost: ~{_money(cost)} [{basis}] (estimate; dashboard is authoritative)")
    print("Planned output base:", str(Path(out_dir) / name))


def _build_video_args(a, model, prompt, fal_client=None, dry_run=False):
    img_key = "start_image_url" if _model_has(model, START_IMAGE_MODELS) else "image_url"
    url = "[uploaded image URL]" if dry_run else _resolve_image(a.image, fal_client)
    args = {"prompt": prompt, img_key: url, "duration": str(a.duration) if "kling-video" in model else a.duration}
    res = a.resolution or DEFAULT_RESOLUTION.get(model)
    if res:
        args["resolution"] = res
    if a.aspect:
        args["aspect_ratio"] = a.aspect
    if _model_has(model, AUDIO_MODELS):
        # FLUX 3 includes native audio free — default ON unless --no-audio.
        # Other audio-capable models: opt-in via --audio.
        if _model_has(model, ("flux-3",)):
            args["generate_audio"] = not getattr(a, "no_audio", False)
        else:
            args["generate_audio"] = bool(a.audio)
    if a.seed is not None:
        args["seed"] = a.seed
    args.update(_extra_args(a))
    return url, args, a.duration


def cmd_generate(a):
    if a.duration < 1:
        sys.exit("ERROR: --duration must be at least 1 second")
    model = a.model or DEFAULT_MODELS["generate"]
    _check_duration(model, a.duration)
    args = {"prompt": a.prompt, "duration": str(a.duration) if "kling-video" in model else a.duration, "aspect_ratio": a.aspect or "16:9"}
    res = a.resolution or DEFAULT_RESOLUTION.get(model)
    if res:
        args["resolution"] = res
    if _model_has(model, AUDIO_MODELS):
        # FLUX 3 includes native audio free — default ON unless --no-audio.
        # Other audio-capable models: opt-in via --audio.
        if _model_has(model, ("flux-3",)):
            args["generate_audio"] = not getattr(a, "no_audio", False)
        else:
            args["generate_audio"] = bool(a.audio)
    if a.seed is not None:
        args["seed"] = a.seed
    args.update(_extra_args(a))
    if a.dry_run:
        _dry_run("generate", model, args, a.duration, out_dir=a.out_dir, name=a.name)
        return
    _run(model, args, a.duration, a.out_dir, a.name, a.cost_log, a.run_log, a.verbose, {"command": "generate"})


def cmd_animate(a):
    if a.duration < 1:
        sys.exit("ERROR: --duration must be at least 1 second")
    model = a.model or DEFAULT_MODELS["animate"]
    _check_duration(model, a.duration)
    if a.dry_run:
        _, args, dur = _build_video_args(a, model, a.prompt, dry_run=True)
        _dry_run("animate", model, args, dur, input_images=[a.image], out_dir=a.out_dir, name=a.name)
        return
    fal_client, _ = _import_deps()
    _require_fal_key()
    _, args, dur = _build_video_args(a, model, a.prompt, fal_client=fal_client)
    _run(model, args, dur, a.out_dir, a.name, a.cost_log, a.run_log, a.verbose, {"command": "animate", "input_images": [a.image]})


def cmd_camera(a):
    if a.duration < 1:
        sys.exit("ERROR: --duration must be at least 1 second")
    model = a.model or DEFAULT_MODELS["camera"]
    _check_duration(model, a.duration)
    parts = []
    if a.move:
        if a.move not in CAMERA_MOVES:
            sys.exit(f"ERROR: --move must be one of: {', '.join(CAMERA_MOVES)}")
        parts.append(CAMERA_MOVES[a.move])
    if a.prompt:
        parts.append(a.prompt)
    if not parts:
        sys.exit("ERROR: give a --move and/or a --prompt describing the camera motion.")
    prompt = ". ".join(parts)
    if a.dry_run:
        _, args, dur = _build_video_args(a, model, prompt, dry_run=True)
    else:
        fal_client, _ = _import_deps()
        _require_fal_key()
        _, args, dur = _build_video_args(a, model, prompt, fal_client=fal_client)
    if a.static:
        if _model_has(model, CAMERA_FIXED_MODELS):
            args["camera_fixed"] = True
        else:
            args["prompt"] += ". Static shot, locked-off camera, no camera movement."
    if a.dry_run:
        _dry_run("camera", model, args, dur, input_images=[a.image], out_dir=a.out_dir, name=a.name)
        return
    _run(model, args, dur, a.out_dir, a.name, a.cost_log, a.run_log, a.verbose, {"command": "camera", "input_images": [a.image]})


def cmd_enhance(a):
    """Draft Enhance: re-render a prior FLUX 3 draft at full quality with the same seed.
    The draft's seed is extracted from its cost-log entry or provided explicitly.

    This is a FLUX 3-specific feature — only FLUX 3 has a paired draft/full pipeline where
    the same seed reproduces the same motion at higher fidelity. Other models (Kling, Veo,
    Seedance) don't have this relationship; passing their seeds won't reproduce motion.
    """
    if not a.seed:
        sys.exit("ERROR: --seed is required for enhance. Pass the draft's seed (from the run log or cost log).")
    if not a.image:
        sys.exit("ERROR: --image is required for enhance. Pass the draft clip's first frame or the source image.")
    if a.mode == "generate":
        model = a.model or DEFAULT_MODELS["generate_full"]
    else:
        model = a.model or DEFAULT_MODELS["animate_full"]
    # Guard: warn if a non-FLUX-3 model is passed — seed continuity is a FLUX 3 feature.
    if a.model and "flux-3" not in a.model:
        sys.exit(
            f"ERROR: Draft Enhance is a FLUX 3-specific feature. The model '{a.model}' is not a FLUX 3 "
            f"endpoint — its seed won't reproduce the draft's motion at full quality. Use a fresh full "
            f"render instead (generate/animate with --model {a.model}), or omit --model to use the "
            f"FLUX 3 full default."
        )
    _check_duration(model, a.duration)
    if a.dry_run:
        fal_client = None
    else:
        fal_client, _ = _import_deps()
        _require_fal_key()
    _, args, dur = _build_video_args(a, model, a.prompt, fal_client=fal_client if not a.dry_run else None, dry_run=a.dry_run)
    args["seed"] = a.seed
    if a.dry_run:
        _dry_run("enhance", model, args, dur, input_images=[a.image], out_dir=a.out_dir, name=a.name)
        return
    _run(model, args, dur, a.out_dir, a.name, a.cost_log, a.run_log, a.verbose,
         {"command": "enhance", "input_images": [a.image]})


def cmd_costs(a):
    logp = _cost_log_path(a.cost_log)
    if a.reset:
        if logp.is_file():
            logp.unlink()
        print(f"Cost log cleared: {logp}")
        return
    entries = _read_cost_log(logp)
    if not entries:
        print(f"No cost log yet at {logp}")
        return
    total, currency = 0.0, "USD"
    print(f"Cost summary — {logp}\n")
    for e in entries:
        c = e.get("cost")
        if c is not None:
            total += float(c)
            currency = e.get("currency", currency)
            cstr = f"~{_money(float(c), currency)}"
        else:
            cstr = "n/a"
        print(f"  {e.get('time', ''):20}  {e.get('command', ''):8}  {e.get('model', ''):48}  {cstr:>12}  [{e.get('basis', '')}]")
    print(f"\n  TOTAL: ~{_money(total, currency)} (estimates — dashboard authoritative)")


def build_parser():
    p = argparse.ArgumentParser(description="fal.ai VIDEO helper — generate / animate / camera.")
    sub = p.add_subparsers(dest="command", required=True)

    def common(sp, default_name, image=True):
        if image:
            sp.add_argument("--image", required=True)
        sp.add_argument("--duration", type=int, default=5)
        sp.add_argument("--resolution")
        sp.add_argument("--aspect")
        sp.add_argument("--audio", action="store_true")
        sp.add_argument("--no-audio", action="store_true", help="Disable audio (FLUX 3 defaults ON)")
        sp.add_argument("--seed", type=int)
        sp.add_argument("--model")
        sp.add_argument("--out-dir", default="_workings")
        sp.add_argument("--name", default=default_name)
        sp.add_argument("--arg", action="append")
        sp.add_argument("--arg-json", action="append")
        sp.add_argument("--cost-log")
        sp.add_argument("--run-log")
        sp.add_argument("--verbose", action="store_true")
        sp.add_argument("--dry-run", action="store_true", help="Print arguments/cost estimate without calling fal.ai or requiring FAL_KEY.")

    gen = sub.add_parser("generate")
    gen.add_argument("--prompt", required=True)
    common(gen, "vid", image=False)
    gen.set_defaults(func=cmd_generate)

    an = sub.add_parser("animate")
    an.add_argument("--prompt", required=True)
    common(an, "vid")
    an.set_defaults(func=cmd_animate)

    cam = sub.add_parser("camera")
    cam.add_argument("--prompt")
    cam.add_argument("--move")
    cam.add_argument("--static", action="store_true")
    common(cam, "vid_camera")
    cam.set_defaults(func=cmd_camera)

    c = sub.add_parser("costs")
    c.add_argument("--cost-log")
    c.add_argument("--reset", action="store_true")
    c.set_defaults(func=cmd_costs)

    en = sub.add_parser("enhance", help="FLUX 3 Draft Enhance: re-render a draft at full quality with the same seed and motion.")
    en.add_argument("--prompt", required=True, help="The same prompt used for the draft.")
    en.add_argument("--image", required=True, help="The source image (for animate) or draft first frame.")
    en.add_argument("--seed", type=int, required=True, help="The draft's seed (from run log or cost log).")
    en.add_argument("--mode", choices=["generate", "animate"], default="animate", help="Draft mode: 'generate' (text-to-video) or 'animate' (image-to-video). Default: animate.")
    en.add_argument("--duration", type=int, default=5)
    en.add_argument("--resolution")
    en.add_argument("--aspect")
    en.add_argument("--audio", action="store_true")
    en.add_argument("--no-audio", action="store_true", help="Disable audio (FLUX 3 defaults ON)")
    en.add_argument("--model")
    en.add_argument("--out-dir", default=".")
    en.add_argument("--name", default="vid_enhanced")
    en.add_argument("--arg", action="append")
    en.add_argument("--arg-json", action="append")
    en.add_argument("--cost-log")
    en.add_argument("--run-log")
    en.add_argument("--verbose", action="store_true")
    en.add_argument("--dry-run", action="store_true")
    en.set_defaults(func=cmd_enhance)

    s = sub.add_parser("search", help="Search the live fal model catalogue by keyword (with pricing).")
    s.add_argument("query", help="Search term, e.g. 'video upscale', 'image to video', 'kling'.")
    s.add_argument("--category", help="Filter by category substring, e.g. text-to-video, image-to-video.")
    s.add_argument("--limit", type=int, default=15, help="Max results (default 15).")
    s.set_defaults(func=cmd_search)

    rec = sub.add_parser("recommend", help="Show the recommended default model per mode, with live pricing.")
    rec.set_defaults(func=cmd_recommend)
    return p


def _search_models(query, requests, limit=15, category=None):
    """Live keyword search of the fal model catalogue (GET /v1/models?query=). Read-only, no spend."""
    key = os.environ.get("FAL_KEY", "")
    try:
        r = requests.get(f"{FAL_API}/models", params={"query": query},
                         headers={"Authorization": f"Key {key}"}, timeout=20)
        if r.status_code != 200:
            return []
    except Exception:
        return []
    out = []
    for m in (r.json().get("models") or []):
        md = m.get("metadata") or {}
        if md.get("status") and md.get("status") != "active":
            continue
        if category and category.lower() not in str(md.get("category", "")).lower():
            continue
        out.append({
            "endpoint_id": m.get("endpoint_id", ""),
            "name": md.get("display_name", ""),
            "category": md.get("category", ""),
            "license": md.get("license_type", ""),
            "desc": " ".join(str(md.get("description", "")).split()),
        })
        if len(out) >= limit:
            break
    return out


def _prices_batch(endpoint_ids, requests):
    """Live pricing for several endpoints in one call → {endpoint_id: (unit_price, unit)}."""
    key = os.environ.get("FAL_KEY", "")
    ids = [e for e in dict.fromkeys(endpoint_ids) if e]
    out = {}
    if not ids:
        return out
    try:
        params = [("endpoint_id", e) for e in ids]
        r = requests.get(f"{FAL_API}/models/pricing", params=params,
                         headers={"Authorization": f"Key {key}"}, timeout=20)
        if r.status_code == 200:
            for p in (r.json().get("prices") or []):
                out[p.get("endpoint_id")] = (p.get("unit_price"), str(p.get("unit", "")))
    except Exception:
        pass
    return out


def _price_str(pr):
    return f"${pr[0]}/{pr[1]}" if pr and pr[0] is not None else "price n/a"


def cmd_search(a):
    fal_client, requests = _import_deps()
    _require_fal_key()          # discovery needs the key for the Authorization header (read-only, no spend)
    models = _search_models(a.query, requests, a.limit, a.category)
    if not models:
        print(f"No active models matched '{a.query}'. Browse the full catalogue at https://fal.ai/models")
        return
    prices = _prices_batch([m["endpoint_id"] for m in models], requests)
    print(f"fal models matching '{a.query}' (live):\n")
    for m in models:
        print(f"  {m['endpoint_id']}   [{_price_str(prices.get(m['endpoint_id']))}]")
        meta = "  ·  ".join(x for x in (m["name"], m["category"], m["license"]) if x)
        if meta:
            print(f"      {meta}")
        if m["desc"]:
            print(f"      {m['desc'][:130]}")
    print("\nDefault-first: reach for these only if the tuned defaults fall short (see SKILL.md). "
          "Full catalogue: https://fal.ai/models")


def cmd_recommend(a):
    fal_client, requests = _import_deps()
    _require_fal_key()
    rec_ids = list(DEFAULT_MODELS.values())
    prices = _prices_batch(rec_ids, requests)
    print("Recommended default per mode for this skill (live pricing):\n")
    for mode, mid in DEFAULT_MODELS.items():
        print(f"  {mode:14} → {mid}   [{_price_str(prices.get(mid))}]")
    print("\n  Draft defaults use FLUX 3 Draft (cheap, HD only, native audio).")
    print("  Full defaults use FLUX 3 full render (720p/1080p, native audio free).")
    print("  Camera default: Seedance 1.5 Pro (best camera control + camera_fixed lock).")
    print("\n  Use 'enhance' to re-render a draft at full quality with the same seed + motion.")
    print("\nThese are the tuned, cost-balanced defaults — stick with them unless a result is genuinely")
    print("unsatisfactory. To explore alternatives, search the catalogue with:  search <term>")


def main():
    for stream in (sys.stdout, sys.stderr):
        try:
            stream.reconfigure(encoding="utf-8")
        except (AttributeError, ValueError):
            pass
    args = build_parser().parse_args()
    args.func(args)


if __name__ == "__main__":
    main()
canvas-designanthropics/skillsCreate beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
docxanthropics/skillsUse this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', '.dotx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx or .dotx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
pdfanthropics/skillsUse this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
pptxanthropics/skillsUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates (.potx), layouts, speaker notes, or comments. Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx or .potx filename, regardless of what they plan to do with the content afterward. If a .pptx or .potx file needs to be opened, created, or touched, use this skill.Stars: 198kUpdated Claude CodeCodexVerifiedInstall