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

Getting started

1. Set the API key

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

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.

Capability	Value
Max images	4 per request; Krea 2: 1 per request
Edit mode	Flux: 1 reference image; GPT Image 2: 10; Nano Banana 2: 14
Style refs	Krea 2: up to 10 style references via image / images
Size overrides	Supported
Aspect ratio	Supported for generate, Krea 2, and GPT Image 2/Nano Banana 2 edit
Resolution	Supported
Output format	png or jpeg

Warning

Flux image-to-image requests do not support aspectRatio overrides. GPT Image 2 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.

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 fal as the default image provider:

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

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

Available video models

HeyGen video-agent:

• fal/fal-ai/heygen/v2/video-agent

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

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.

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, fal-ai/ace-step/prompt-to-audio, fal-ai/stable-audio-25/text-to-audio
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. ACE-Step and Stable Audio are prompt-to-audio endpoints; choose them with the model override when you want those model families.

Tip

Use openclaw models list --provider fal to see the full list of available fal models, including any recently added entries.

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.