Fal provider for image, video, and music generation in OpenClaw

OpenClaw includes a bundled fal provider for hosted image, video, and music generation.

Getting started

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.

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.

Edit requests (reference images via the shared image / images parameters) route to a per-model edit endpoint with per-model reference limits:

Warning

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.

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-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.

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.

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.

Tip

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

• 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.