fal Provider

기준일: 2026-07-26
난이도: 중급
공식 기준: Fal

개요

이 페이지는 OpenClaw fal provider의 인증, 모델 ref, 온보딩 플래그, 설정 키를 공식 문서 기준으로 정리합니다.

공식 요약: fal image, video, and music generation setup in OpenClaw

model ref는 보통 provider/model 형식입니다. API key·endpoint·model id는 아래 원문 값을 그대로 쓰세요. 임의로 키나 엔드포인트를 만들지 마세요.

빠른 참조

Property	Value
Provider	fal
Auth	FAL_KEY (canonical; FAL_API_KEY also works as a fallback)
API	fal model endpoints (https://fal.run; video jobs use https://queue.fal.run)
Base URL	Override with models.providers.fal.baseUrl

공식 문서 기반 상세

아래는 공식 providers/fal 문서를 Mintlify 컴포넌트만 정리하고 공통 제목을 한국어로 맞춘 내용입니다. 설정 키, env, model ref, CLI 플래그는 원문 그대로 유지합니다.

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 (https://fal.run; video jobs use https://queue.fal.run)
Base URL	Override with models.providers.fal.baseUrl

시작하기

Set the API key

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

Non-interactive setups can pass `--fal-api-key <key>` or export `FAL_KEY`.
Onboarding also sets `fal/fal-ai/flux/dev` as the default image model when
none is configured.

Set a default image model

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

이미지 생성

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
Size overrides	1024x1024, 1024x1536, 1536x1024, 1024x1792, 1792x1024
Aspect ratio	Supported everywhere except Flux image-to-image
Resolution	1K, 2K, 4K (per-model limits below)
Output format	png (default) or jpeg; Krea 2 rejects outputFormat overrides

Edit requests (reference images via the shared image / images parameters) route to a per-model edit endpoint with per-model reference limits:

Model family	Model ref after fal/	Edit endpoint	Max reference images
Flux and other fal models	fal-ai/flux/dev (default)	/image-to-image	1
GPT Image	openai/gpt-image-*	/edit	10
Grok Imagine	xai/grok-imagine-image	/edit	3
Nano Banana (legacy)	fal-ai/nano-banana	/edit	3
Nano Banana 2	fal-ai/nano-banana-*	/edit	14
Nano Banana 2 Lite	google/nano-banana-2-lite	/edit	14
Krea 2	krea/v2/{medium,large}/text-to-image	none (style refs)	10 style references

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 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 Krea 2 Medium:

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

비디오 생성

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
Timeout	20 minutes per job by default; status polled every 5 seconds

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 send only the prompt plus an optional
single reference image; other overrides are not forwarded. Seedance models
accept `aspectRatio`, `size`, `resolution`, durations of 4-15 seconds, and
an audio toggle.

Seedance 2.0 config example

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

Seedance 2.0 reference-to-video config example

```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. Audio references require
at least one image or video reference in the same request.

HeyGen video-agent config example

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

음악 생성

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 (mp3), fal-ai/ace-step/prompt-to-audio (wav), fal-ai/stable-audio-25/text-to-audio (wav)
Max duration	240 seconds
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, but not both in the same request. ACE-Step and Stable Audio are prompt-to-audio endpoints; choose them with the model override when you want those model families. ACE-Step rejects explicit lyrics; Stable Audio rejects both lyrics and instrumental mode.

The tables and accordions above cover the model families the bundled fal provider special-cases. Other fal image endpoint ids can still be selected as the image model; they are treated like Flux (generic image_size payload, one reference image via /image-to-image).

관련 문서

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.

검증 체크리스트

• openclaw models list --provider fal 로 모델이 보이는지 확인
• 기본 model alias를 agents.defaults.model.primary에 설정했는지 확인
• API key / OAuth / 로컬 런타임 인증 경로를 공식 문서와 대조했는지 확인
• failover 시 데이터가 다른 provider로 이동할 수 있는지 검토

관련

• Provider 목록 인덱스
• 로컬 모델과 Provider
• 공식: Provider directory, Model providers