Model providers

Using fal with OpenClaw

3 min read

Browse more in Model providers.

All model providers guides →

This guide shows you how to wire up fal as an image and video generation provider inside OpenClaw. You will set the fal API key, pick default image and video models, and understand which fal capabilities OpenClaw exposes.

By the end, your agents can call fal for both image and video generation using OpenClaw’s standard tools.

Prerequisites

  • ✓An existing OpenClaw installation with the CLI available so you can run `openclaw` commands.
  • ✓A fal account with an API key that you can expose to OpenClaw via `FAL_KEY` or `FAL_API_KEY`.

Steps

  1. 1

    Set the fal API key with the OpenClaw CLI

    Start by registering your fal API key with OpenClaw so the bundled provider can authenticate against fal model endpoints. The CLI flow handles storing the key under the correct auth choice for you.

    bash
    openclaw onboard --auth-choice fal-api-key
  2. 2

    Configure fal as the default image generation model

    Tell OpenClaw to use fal for image generation by setting the default image model in your agent configuration. This makes every image-generation tool call route to the specified fal model unless you override it per-agent.

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

    Use fal image generation defaults effectively

    OpenClaw’s bundled fal image provider already defaults to `fal/fal-ai/flux/dev`, so you can rely on that or keep the explicit config for clarity. Remember that the fal image edit endpoint does not support `aspectRatio` overrides, even though size, aspect ratio, and resolution overrides work for normal generation.

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

    Set fal as the default video generation model with Seedance 2.0

    To drive text-to-video or image-to-video flows through fal, configure a default video model. 0 fast text-to-video endpoint, which runs through a queue-backed submit/status/result flow for long-running jobs.

    json
    {
  agents: {
    defaults: {
      videoGenerationModel: {
        primary: "fal/bytedance/seedance-2.0/fast/text-to-video",
      },
    },
  },
}
  5. 5

    Switch the default video model to the HeyGen video-agent

    If you prefer the HeyGen video-agent integration, point your default video model at the HeyGen endpoint instead. This keeps your agent code the same while swapping the underlying fal video model.

    json
    {
  agents: {
    defaults: {
      videoGenerationModel: {
        primary: "fal/fal-ai/heygen/v2/video-agent",
      },
    },
  },
}
  6. 6

    List all available fal models from OpenClaw

    Once fal is wired up, inspect the full set of image and video models OpenClaw can see from fal. This helps you discover newly added endpoints and confirm that your provider integration works.

    bash
    openclaw models list --provider fal

Configuration

OptionDescriptionExample
FAL_KEYPrimary environment variable OpenClaw uses to authenticate against fal model endpoints.fal_sk_live_1234567890abcdef
FAL_API_KEYFallback environment variable that also works for fal authentication if FAL_KEY is not set.fal_sk_live_fallback_abcdef123456
agents.defaults.imageGenerationModel.primarySets the default image generation model for all agents, using a fal model identifier.fal/fal-ai/flux/dev
agents.defaults.videoGenerationModel.primarySets the default video generation model for all agents, using a fal video model identifier.fal/bytedance/seedance-2.0/fast/text-to-video

Troubleshooting

Image edit calls ignore the `aspectRatio` you pass in.

The fal image edit endpoint does not support `aspectRatio` overrides. Remove `aspectRatio` from edit requests and rely on the default behavior for edits instead.

fal video generation requests take a long time and you are unsure if they are stuck.

fal video models in OpenClaw run through a queue-backed submit/status/result flow for long-running jobs. Make sure your client or gateway polls for status and waits for the final result instead of expecting an immediate response.

Frequently asked questions

Powered by Mem0

Add persistent memory to OpenClaw

Official Mem0 plugin for OpenClaw keeps context across chats and tools. Smaller prompts, lower cost, better continuity for your agents.

Read the official Mem0 guideOpen Mem0

More in Model providers

Model providers

Using Alibaba Model Studio with OpenClaw

Model providers

Using BytePlus with OpenClaw

Model providers

Using GLM (Zhipu AI) with OpenClaw

Model providers

Using Hugging Face with OpenClaw

Model providers

Using Inferrs with OpenClaw

Model providers

Using Kilocode with OpenClaw