Fal Provider: Image, Video, and Music Generation in OpenClaw

OpenClaw includes a built-in fal provider that handles hosted generation of images, videos, and music.

Getting started

Set the API key

openclaw onboard --auth-choice fal-api-key

For non-interactive environments, pass --fal-api-key <key> or set the FAL_KEY environment variable. During onboarding, fal/fal-ai/flux/dev gets configured as the default image model when no other is specified.

Set a default image model

{
  agents: {
    defaults: {
      mediaModels: {
        image: {
          primary: "fal/fal-ai/flux/dev",
        },
      },
    },
  },
}

Image generation

Out of the box, the bundled fal image-generation provider uses fal/fal-ai/flux/dev as its default.

Edit operations, which take reference images through the shared image / images parameters, are sent to a dedicated per-model edit endpoint, each with its own reference image cap:

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 relies on fal's own Krea payload format. Instead of the standard image_size / edit-endpoint structure Flux uses, OpenClaw transmits aspect_ratio, creativity, and image_style_references. Here are the model references:

• fal/krea/v2/medium/text-to-image
• fal/krea/v2/large/text-to-image

For quicker expressive illustration, anime, painting, and artistic styles, go with Medium. For slower photoreal, raw texture, film grain, and detailed looks, pick Large. Krea's default is fal.creativity: "medium"; the accepted values are raw, low, medium, and high.

Krea 2 uses aspect ratio rather than image_size within fal's request schema. aspectRatio is the preferred choice; OpenClaw converts size into the nearest supported Krea aspect ratio, and for Krea it rejects resolution outright instead of silently discarding it.

When you need PNG output from fal models that offer output_format, use outputFormat: "png". Since OpenClaw doesn't declare an explicit transparent-background control in fal, background: "transparent" gets flagged as an ignored override for fal models. Krea 2 endpoints don't provide an output_format request field through fal, so OpenClaw refuses outputFormat overrides on Krea requests.

To get started with Krea 2 Medium:

{
  agents: {
    defaults: {
      mediaModels: {
        image: {
          primary: "fal/krea/v2/medium/text-to-image",
        },
      },
    },
  },
}

Video generation

The included fal video-generation provider comes set to fal/fal-ai/minimax/video-01-live by default.

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 carry only the prompt plus an optional single reference image; all other overrides are left out. Seedance models accept aspectRatio, size, resolution, durations spanning 4-15 seconds, and an audio toggle.

Seedance 2.0 config example

{
  agents: {
    defaults: {
      mediaModels: {
        video: {
          primary: "fal/bytedance/seedance-2.0/fast/text-to-video",
        },
      },
    },
  },
}

Seedance 2.0 reference-to-video config example

{
  agents: {
    defaults: {
      mediaModels: {
        video: {
          primary: "fal/bytedance/seedance-2.0/fast/reference-to-video",
        },
      },
    },
  },
}

Reference-to-video handles up to 9 images, 3 videos, and 3 audio references through the shared video_generate images, videos, and audioRefs parameters, capping total reference files at 12. Audio references demand at least one image or video reference within the same request.

HeyGen video-agent config example

{
  agents: {
    defaults: {
      mediaModels: {
        video: {
          primary: "fal/fal-ai/heygen/v2/video-agent",
        },
      },
    },
  },
}

Music generation

The bundled fal plugin also sets up a music-generation provider for the shared music_generate tool.

To make fal the default music provider:

{
  agents: {
    defaults: {
      mediaModels: {
        music: {
          primary: "fal/fal-ai/minimax-music/v2.6",
        },
      },
    },
  },
}

fal-ai/minimax-music/v2.6 allows explicit lyrics and instrumental mode, but never both within a single request. ACE-Step and Stable Audio are prompt-to-audio endpoints; pick them via the model override when those model families are what you need. ACE-Step turns down explicit lyrics; Stable Audio turns down both lyrics and instrumental mode.

Tip

The model families that the bundled fal provider handles specially are covered by the tables and accordions above. Other fal image endpoint ids remain selectable as the image model; they behave like Flux (generic image_size payload, one reference image via /image-to-image).

Related

• Image generation, Provider choice and shared image tool parameters.

• Video generation, Provider choice and shared video tool parameters.

• Music generation, Provider choice and shared music tool parameters.

• Configuration reference, Agent defaults for image, video, and music model selection.