---
name: imagen-fal
description: >
The fal.ai worker for the /imagen hub; use directly only to pin the provider.
Triggers: /imagen-fal, explicit mentions of "Kling", "BiRefNet", "fal.ai image",
or "use fal". Skip for non-image tasks, text-in-image prompts (route to
imagen-nanobanana), and ambiguous image requests (those route through the /imagen
hub). Trigger only on explicit fal/Kling/BiRefNet mentions or direct invocation.
---
# imagen-fal
This skill is the fal.ai worker for the `/imagen` hub — invoke it directly only when you need to pin the provider to fal.ai (Kling O1 or another fal-hosted model).
## Models
| Model ID | Notes |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `fal-ai/kling-image/v3/text-to-image` | **Default for text-only prompts.** Kling V3 Standard, pure text-to-image. 1K/2K, $0.028/image. Auto-selected when `--source` is not provided. |
| `fal-ai/kling-image/o1` | **Default for multi-reference prompts.** Kling O1 image-to-image / multi-ref remix (1–10 reference images required). Auto-selected when `--source` is provided. 1K/2K, $0.028/image. |
| `fal-ai/nano-banana-2` | Gemini 3.1 Flash Image via fal. Explicit override only — costs 3–10x more than the direct Google path used by `imagen-nanobanana`. |
| `fal-ai/nano-banana-pro` | Gemini 3 Pro Image via fal. Same cost caveat. |
The script auto-selects between `v3/text-to-image` and `o1` based on whether `--source` is supplied. Override with `--model` when needed.
**Not on fal:** `kling-v3-omni` is not hosted on fal. Calls requiring v3-omni or 4K resolution fall outside what the hub routes today — inform the user and defer.
**Transparency:** `--transparent` invokes BiRefNet v2 (`fal-ai/birefnet/v2`) as a post-processing step after generation. The original Kling PNG is kept; BiRefNet writes a sibling `-alpha.png`. Both files are emitted (`image:` and `alpha:` lines). Cost add: ~$0.001–0.005/image; latency add: ~1–3s. Superior to chroma-key for subjects with hair, fur, and soft edges. Pass `--cutout none` to skip BiRefNet and keep only the raw Kling PNG.
## Invocation
```
doppler run -p claude-code -c std --no-fallback -- \
bun /scripts/imagen-fal.ts "" [flags]
```
Replace `` with this skill's base directory at invocation time. Pass the file path directly — `bun run` is not used because it would interpret the path as a package.json script name.
## Flag reference
| Flag | Description |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--source ` | One or more reference image paths, comma-separated for multi-ref (e.g. `a.png,b.png`). Up to 10. Presence of `--source` auto-switches the default model to `fal-ai/kling-image/o1` (i2i). Each file is uploaded to fal storage and passed as `image_urls`. |
| `--drafts ` | Number of variant images to generate (1–9, default: 1). |
| `--model ` | Model identifier. Default auto-picks `fal-ai/kling-image/v3/text-to-image` for t2i or `fal-ai/kling-image/o1` for i2i. |
| `--aspect ` | Aspect ratio enum, one of `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `3:2`, `2:3`, `21:9`. The `o1` (i2i) endpoint also accepts `auto`. Other ratios are rejected by fal. Default: `auto` for image-to-image (`--source` provided), `1:1` for text-to-image. |
| `--resolution <1k\|2k\|4k>` | Output resolution (default: `2k`). Maps to Kling's `1K`/`2K` enum. fal Kling does not support `4k` — passing it triggers a warning and caps to `2k`. |
| `--name ` | Output filename prefix (default: full prompt slugified, truncated to 40 chars). |
| `--out ` | Output directory (default: `~/Pictures/imagen`). |
| `--transparent` | After generation, run the cutout step (controlled by `--cutout`). The original Kling PNG is kept; BiRefNet result is written to a sibling `-alpha.png`. Both paths are emitted. |
| `--cutout ` | Controls the cutout step when `--transparent` is set. `birefnet` (default): run BiRefNet v2 and write `-alpha.png`. `none`: skip BiRefNet; only the raw Kling PNG is saved. |
| `--dry-run` | Print the resolved request payload as JSON and exit without making an API call. No `FAL_KEY` required. |
## Workflow
```
// Gather
intent = do("understand what the user wants to create or edit")
transparent = do("true if user wants a transparent/cut-out/no-background/alpha result")
// Expand prompt
prompt = do("""
Rewrite the request as a full descriptive paragraph — not a keyword list.
Cover: subject, composition, lighting, colour palette, style, camera angle, mood.
Omit transparency/alpha/checkerboard wording — that is handled by --transparent.
""")
// Choose flags
source_flag = do("--source a.png,b.png for comma-separated reference images")
drafts_flag = do("--drafts 3 or 4 when the user wants options; omit (default 1) otherwise")
model_flag = do("--model only when the user explicitly overrides the default")
aspect_flag = do("--aspect when the user specifies dimensions or orientation")
resolution_flag = do("--resolution 1k or 2k; warn if user requests 4k (not supported on fal Kling); omit to use default 2k")
name_flag = do("--name when the user wants a specific filename prefix")
transparent_flag = do("--transparent when transparent is true")
cutout_flag = do("--cutout none when the user explicitly wants to skip BiRefNet; omit otherwise (default birefnet)")
// Invoke
Bash(doppler run -p claude-code -c std --no-fallback -- \
bun /scripts/imagen-fal.ts "" \
[source_flag] [drafts_flag] [model_flag] [aspect_flag] \
[resolution_flag] [name_flag] [transparent_flag] [cutout_flag])
// Relay output
do("print each 'image: ...' path (raw Kling PNG) and 'alpha: ...' path (BiRefNet result, when cutout ran) so the user can see or copy them")
do("note the log path and cost_estimate if emitted")
// Iterate
if user wants to refine:
do("call the script again with a chosen output as --source and adjusted flags")
```
## Notes
- `FAL_KEY` is injected by `doppler run -p claude-code -c std --no-fallback`. It is never passed on the command line.
- Output images land in `~/Pictures/imagen/` by default. That directory is sandbox-allowlisted. Pointing `--out` outside it requires a matching `home/claude/settings.json` entry.
- fal returns signed CDN URLs (~1h TTL). The script downloads each URL to disk; the CDN URL is not the final path.
- `--transparent` keeps the original Kling PNG and writes BiRefNet output to a sibling `-alpha.png`. Both files persist. The script emits `image: ` and `alpha: ` on stdout.
- The green-plate prompt strategy used by `imagen-nanobanana` is NOT used here. Kling does not render flat chroma-key backgrounds — BiRefNet on the raw Kling output is the cutout path.
- Kling O1 does not render text inside images reliably. Route text-in-image prompts to `imagen-nanobanana`.