openclaw/docs/providers/fal.md

summary, title, read_when

summary	title	read_when
fal image, video, and music generation setup in OpenClaw	Fal	You want to use fal image generation in OpenClaw You need the FAL_KEY auth flow You want fal defaults for image_generate, video_generate, or music_generate

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

```bash openclaw onboard --auth-choice fal-api-key ``` ```json5 { 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
Edit mode	Flux: 1 reference image; GPT Image 2: 10; Nano Banana 2: 14
Size overrides	Supported
Aspect ratio	Supported for generate and GPT Image 2/Nano Banana 2 edit
Resolution	Supported
Output format	png or jpeg

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.

Use outputFormat: "png" when you want PNG output. fal does not declare an explicit transparent-background control in OpenClaw, so background: "transparent" is reported as an ignored override for fal models.

To use fal as the default image provider:

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

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

**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`

```json5 { agents: { defaults: { videoGenerationModel: { primary: "fal/bytedance/seedance-2.0/fast/text-to-video", }, }, }, } ``` ```json5 { 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.

```json5 { 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.

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

Related

Shared image tool parameters and provider selection. Shared video tool parameters and provider selection. Shared music tool parameters and provider selection. Agent defaults including image, video, and music model selection.