Skip to main content
OpenClaw ships a bundled fal provider for hosted image, video, and music generation.
PropertyValue
Providerfal
AuthFAL_KEY (canonical; FAL_API_KEY also works as a fallback)
APIfal model endpoints (https://fal.run; video jobs use https://queue.fal.run)
Base URLOverride with models.providers.fal.baseUrl

​
Getting started

1

Set the API key

openclaw onboard --auth-choice fal-api-key
Non-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.
2

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.
CapabilityValue
Max images4 per request; Krea 2: 1 per request
Size overrides1024x1024, 1024x1536, 1536x1024, 1024x1792, 1792x1024
Aspect ratioSupported everywhere except Flux image-to-image
Resolution1K, 2K, 4K (per-model limits below)
Output formatpng (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 familyModel ref after fal/Edit endpointMax reference images
Flux and other fal modelsfal-ai/flux/dev (default)/image-to-image1
GPT Imageopenai/gpt-image-*/edit10
Grok Imaginexai/grok-imagine-image/edit3
Nano Banana (legacy)fal-ai/nano-banana/edit3
Nano Banana 2fal-ai/nano-banana-*/edit14
Nano Banana 2 Litegoogle/nano-banana-2-lite/edit14
Krea 2krea/v2/{medium,large}/text-to-imagenone (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: 
{
  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.
CapabilityValue
ModesText-to-video, single-image reference, Seedance reference-to-video
RuntimeQueue-backed submit/status/result flow for long-running jobs
Timeout20 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.
{
  agents: {
    defaults: {
      videoGenerationModel: {
        primary: "fal/bytedance/seedance-2.0/fast/text-to-video",
      },
    },
  },
}

{
  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.
{
  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.
CapabilityValue
Default modelfal/fal-ai/minimax-music/v2.6
Modelsfal-ai/minimax-music/v2.6 (mp3), fal-ai/ace-step/prompt-to-audio (wav), fal-ai/stable-audio-25/text-to-audio (wav)
Max duration240 seconds
RuntimeSynchronous 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.
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).

Image generation

Shared image tool parameters and provider selection.

Video generation

Shared video tool parameters and provider selection.

Music generation

Shared music tool parameters and provider selection.

Configuration reference

Agent defaults including image, video, and music model selection.