Fal Provider Setup for Image, Video, and Music Generation

A hosted image, video, and music generation provider comes bundled with OpenClaw under the fal name.

Getting started

Get an API key

Generate a key at fal.ai/dashboard/keys.

Set the API key

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

For non-interactive setups, either pass --fal-api-key <key> or export FAL_KEY. When no image model is configured, onboarding will also set fal/fal-ai/flux/dev as the default.

Set a default image model

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

Image generation

The default for the bundled fal image-generation provider is fal/fal-ai/flux/dev.

Edit requests (reference images supplied through the shared image / images parameters) are sent to a per-model edit endpoint, and each model enforces its own reference limits:

Warning

aspectRatio overrides are not accepted by Flux image-to-image requests. Requests that edit images through GPT Image and Nano Banana 2 go to fal's /edit endpoint, which does take aspect-ratio hints. Extra-native wide and tall ratios, among them 4:1, 1:4, 8:1, and 1:8, are also accepted by Nano Banana 2; Krea 2 checks against its own narrower set of aspect ratios. Grok Imagine keeps a separate ratio list (which includes 2:1, 20:9, 19.5:9, and their inverses) and takes only 1K/2K resolutions; resolution overrides are rejected by legacy Nano Banana and by Nano Banana 2 Lite.

GPT Image 2.5

Pick one of the two variants:

• fal/openai/gpt-image-2.5/flare/text-to-image
• fal/openai/gpt-image-2.5/sunburst/text-to-image

When references are used, the sibling /edit endpoint is selected. Naming fal/openai/gpt-image-2.5/flare/edit or fal/openai/gpt-image-2.5/sunburst/edit explicitly works as well.

quality: "low", "medium", "high", "xhigh", "max", and "auto" are all accepted by both variants, and high is the fal default. Either background: "transparent", "opaque", or "auto" may be supplied. Transparency comes from outputFormat: "png" or "webp". None of these controls affect older fal models.

Specify size: "auto", or give explicit dimensions such as 1536x864. Each dimension has to be a multiple of 16, and no edge may exceed 3840 pixels. The pixel total must fall between 655,360 and 8,294,400, and the aspect ratio must stay within 1:3 to 3:1. Aspect-ratio hints are converted by OpenClaw into valid dimensions. As an example, aspectRatio: "3:2" yields 1536x1024. To pin exact dimensions, use size; OpenClaw refuses explicit sizes that are invalid. resolution overrides are not accepted by these models. If an edit carries no geometry hints, fal's automatic size selection is left in place.

openclaw infer image generate \
  --model fal/openai/gpt-image-2.5/flare/text-to-image \
  --prompt "A simple red circle sticker" \
  --quality low --size 1024x1024 --json

openclaw infer image edit \
  --model fal/openai/gpt-image-2.5/sunburst/edit \
  --file /path/to/reference.png \
  --prompt "Keep the shape and change the color to blue" \
  --quality low --size auto --json

Krea 2

The native Krea payload schema from fal is what Krea 2 models rely on. Rather than the generic image_size / edit-endpoint payload that Flux uses, OpenClaw transmits aspect_ratio, creativity, and image_style_references. The model refs are:

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

Choose Medium when you want faster, more expressive illustration, anime, painting, and artistic styles. Choose Large for slower photoreal work, raw texture, film grain, and detailed looks. fal.creativity: "medium" is the Krea default; the supported values are raw, low, medium, and high.

In fal's request schema, Krea 2 exposes aspect ratio rather than image_size. aspectRatio is the preferred option; when you pass size, OpenClaw maps it to the nearest Krea aspect ratio it supports, and resolution on Krea is rejected instead of being dropped.

Reach for outputFormat: "png" if you need PNG output from fal models that expose output_format. Apart from GPT Image 2.5, no fal model declares a transparent-background control in OpenClaw. Such models report background as an override that gets ignored. An output_format request field is not exposed by Krea 2 endpoints through fal, so outputFormat overrides on Krea requests are rejected by OpenClaw.

To use Krea 2 Medium:

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

Video generation

By default, the video-generation provider that ships with fal uses 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

Requests to MiniMax Live and HeyGen carry the prompt and, optionally, one reference image. Nothing else is passed along. For Seedance models, the accepted inputs are aspectRatio, size, resolution, clip lengths from 4 to 15 seconds, and a toggle for audio.

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",
        },
      },
    },
  },
}

Through the shared video_generate images, videos, and audioRefs parameters, reference-to-video takes as many as 9 images, 3 videos, and 3 audio references, capped at 12 reference files in total. If a request includes audio references, it must also include at least one image or video reference.

HeyGen video-agent config example

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

Music generation

A music-generation provider for the shared music_generate tool is registered as well by the bundled fal plugin.

To make fal your default music provider:

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

fal-ai/minimax-music/v2.6 handles explicit lyrics and instrumental mode, though not together in one request. ACE-Step and Stable Audio are prompt-to-audio endpoints, so pick them through the model override if those model families are what you need. Explicit lyrics are rejected by ACE-Step, while Stable Audio turns down both lyrics and instrumental mode.

Tip

Model families that the bundled fal provider gives special handling to appear in the tables and accordions above. Any other fal image endpoint id is still selectable as the image model, and gets the same treatment as Flux: a generic image_size payload plus a single reference image supplied through /image-to-image.

Related

• Image generation, Parameters shared by the image tool, plus how the provider is selected.

• Video generation, Parameters shared by the video tool, plus how the provider is selected.

• Music generation, Parameters shared by the music tool, plus how the provider is selected.

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