--- summary: "fal image, video, and music generation setup in OpenClaw" title: "Fal" read_when: - You want to use fal image generation in OpenClaw - You need the FAL_KEY auth flow - You want fal defaults for image_generate, video_generate, or music_generate --- OpenClaw ships a bundled `fal` provider for hosted image, video, and music generation. | Property | Value | | -------- | ------------------------------------------------------------------------------- | | Provider | `fal` | | Auth | `FAL_KEY` (canonical; `FAL_API_KEY` also works as a fallback) | | API | fal model endpoints (`https://fal.run`; video jobs use `https://queue.fal.run`) | | Base URL | Override with `models.providers.fal.baseUrl` | ## Getting started ```bash openclaw onboard --auth-choice fal-api-key ``` Non-interactive setups can pass `--fal-api-key ` or export `FAL_KEY`. Onboarding also sets `fal/fal-ai/flux/dev` as the default image model when none is configured. ```json5 { agents: { defaults: { imageGenerationModel: { primary: "fal/fal-ai/flux/dev", }, }, }, } ``` ## Image generation The bundled `fal` image-generation provider defaults to `fal/fal-ai/flux/dev`. | Capability | Value | | -------------- | ------------------------------------------------------------------ | | Max images | 4 per request; Krea 2: 1 per request | | Size overrides | `1024x1024`, `1024x1536`, `1536x1024`, `1024x1792`, `1792x1024` | | Aspect ratio | Supported everywhere except Flux image-to-image | | Resolution | `1K`, `2K`, `4K` (per-model limits below) | | Output format | `png` (default) or `jpeg`; Krea 2 rejects `outputFormat` overrides | Edit requests (reference images via the shared `image` / `images` parameters) route to a per-model edit endpoint with per-model reference limits: | Model family | Model ref after `fal/` | Edit endpoint | Max reference images | | ------------------------- | -------------------------------------- | ----------------- | -------------------- | | Flux and other fal models | `fal-ai/flux/dev` (default) | `/image-to-image` | 1 | | GPT Image | `openai/gpt-image-*` | `/edit` | 10 | | Grok Imagine | `xai/grok-imagine-image` | `/edit` | 3 | | Nano Banana (legacy) | `fal-ai/nano-banana` | `/edit` | 3 | | Nano Banana 2 | `fal-ai/nano-banana-*` | `/edit` | 14 | | Nano Banana 2 Lite | `google/nano-banana-2-lite` | `/edit` | 14 | | Krea 2 | `krea/v2/{medium,large}/text-to-image` | none (style refs) | 10 style references | Flux image-to-image requests do **not** support `aspectRatio` overrides. GPT Image and Nano Banana 2 edit requests use fal's `/edit` endpoint and accept aspect-ratio hints. Nano Banana 2 also accepts extra-native wide/tall ratios such as `4:1`, `1:4`, `8:1`, and `1:8`; Krea 2 validates its own smaller aspect-ratio subset. Grok Imagine has its own ratio list (including `2:1`, `20:9`, `19.5:9`, and their inverses) and only accepts `1K`/`2K` resolutions; legacy Nano Banana and Nano Banana 2 Lite reject `resolution` overrides. Krea 2 models use fal's native Krea payload schema. OpenClaw sends `aspect_ratio`, `creativity`, and `image_style_references` instead of the generic `image_size` / edit-endpoint payload used by Flux. The model refs are: - `fal/krea/v2/medium/text-to-image` - `fal/krea/v2/large/text-to-image` Use Medium for faster expressive illustration, anime, painting, and artistic styles. Use Large for slower photoreal, raw texture, film grain, and detailed looks. Krea defaults to `fal.creativity: "medium"`; supported values are `raw`, `low`, `medium`, and `high`. Krea 2 exposes aspect ratio, not `image_size`, in fal's request schema. Prefer `aspectRatio`; OpenClaw maps `size` to the closest supported Krea aspect ratio and rejects `resolution` for Krea rather than dropping it. Use `outputFormat: "png"` when you want PNG output from fal models that expose `output_format`. fal does not declare an explicit transparent-background control in OpenClaw, so `background: "transparent"` is reported as an ignored override for fal models. Krea 2 endpoints do not expose an `output_format` request field through fal, so OpenClaw rejects `outputFormat` overrides for Krea requests. To use Krea 2 Medium: ```json5 { agents: { defaults: { imageGenerationModel: { primary: "fal/krea/v2/medium/text-to-image", }, }, }, } ``` ## Video generation The bundled `fal` video-generation provider defaults to `fal/fal-ai/minimax/video-01-live`. | Capability | Value | | ---------- | ------------------------------------------------------------------ | | Modes | Text-to-video, single-image reference, Seedance reference-to-video | | Runtime | Queue-backed submit/status/result flow for long-running jobs | | Timeout | 20 minutes per job by default; status polled every 5 seconds | **MiniMax (default):** - `fal/fal-ai/minimax/video-01-live` **HeyGen video-agent:** - `fal/fal-ai/heygen/v2/video-agent` **Kling and Wan:** - `fal/fal-ai/kling-video/v2.1/master/text-to-video` - `fal/fal-ai/wan/v2.2-a14b/text-to-video` - `fal/fal-ai/wan/v2.2-a14b/image-to-video` **Seedance 2.0:** - `fal/bytedance/seedance-2.0/fast/text-to-video` - `fal/bytedance/seedance-2.0/fast/image-to-video` - `fal/bytedance/seedance-2.0/fast/reference-to-video` - `fal/bytedance/seedance-2.0/text-to-video` - `fal/bytedance/seedance-2.0/image-to-video` - `fal/bytedance/seedance-2.0/reference-to-video` MiniMax Live and HeyGen requests send only the prompt plus an optional single reference image; other overrides are not forwarded. Seedance models accept `aspectRatio`, `size`, `resolution`, durations of 4-15 seconds, and an audio toggle. ```json5 { agents: { defaults: { videoGenerationModel: { primary: "fal/bytedance/seedance-2.0/fast/text-to-video", }, }, }, } ``` ```json5 { agents: { defaults: { videoGenerationModel: { primary: "fal/bytedance/seedance-2.0/fast/reference-to-video", }, }, }, } ``` Reference-to-video accepts up to 9 images, 3 videos, and 3 audio references through the shared `video_generate` `images`, `videos`, and `audioRefs` parameters, with at most 12 total reference files. Audio references require at least one image or video reference in the same request. ```json5 { agents: { defaults: { videoGenerationModel: { primary: "fal/fal-ai/heygen/v2/video-agent", }, }, }, } ``` ## Music generation The bundled `fal` plugin also registers a music-generation provider for the shared `music_generate` tool. | Capability | Value | | ------------- | ------------------------------------------------------------------------------------------------------------------------ | | Default model | `fal/fal-ai/minimax-music/v2.6` | | Models | `fal-ai/minimax-music/v2.6` (mp3), `fal-ai/ace-step/prompt-to-audio` (wav), `fal-ai/stable-audio-25/text-to-audio` (wav) | | Max duration | 240 seconds | | Runtime | Synchronous request plus generated audio download | Use fal as the default music provider: ```json5 { agents: { defaults: { musicGenerationModel: { primary: "fal/fal-ai/minimax-music/v2.6", }, }, }, } ``` `fal-ai/minimax-music/v2.6` supports explicit lyrics and instrumental mode, but not both in the same request. ACE-Step and Stable Audio are prompt-to-audio endpoints; choose them with the `model` override when you want those model families. ACE-Step rejects explicit lyrics; Stable Audio rejects both lyrics and instrumental mode. The tables and accordions above cover the model families the bundled fal provider special-cases. Other fal image endpoint ids can still be selected as the image model; they are treated like Flux (generic `image_size` payload, one reference image via `/image-to-image`). ## Related Shared image tool parameters and provider selection. Shared video tool parameters and provider selection. Shared music tool parameters and provider selection. Agent defaults including image, video, and music model selection.