Providers
Fal
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
Set the API key
openclaw onboard --auth-choice fal-api-keyNon-interactive setups can pass --fal-api-key <key> or export FAL_KEY.
Onboarding also sets fal/fal-ai/flux/dev as the default image model when
none is configured.
Set a default image model
{ 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 |
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-imagefal/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:
{ 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 |
Available video models
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-videofal/fal-ai/wan/v2.2-a14b/text-to-videofal/fal-ai/wan/v2.2-a14b/image-to-video
Seedance 2.0:
fal/bytedance/seedance-2.0/fast/text-to-videofal/bytedance/seedance-2.0/fast/image-to-videofal/bytedance/seedance-2.0/fast/reference-to-videofal/bytedance/seedance-2.0/text-to-videofal/bytedance/seedance-2.0/image-to-videofal/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.
Seedance 2.0 config example
{ agents: { defaults: { videoGenerationModel: { primary: "fal/bytedance/seedance-2.0/fast/text-to-video", }, }, },}Seedance 2.0 reference-to-video config example
{ 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.
HeyGen video-agent config example
{ 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:
{ 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.
